1. 为什么要在隔离内网里折腾 AI Agent先把场景说清楚。所谓“隔离内网”就是那种物理上跟公网断开、或者只允许极少数白名单流量进出的网络环境。银行的核心机房、制造业的产线控制网、军工单位的研发网、医院的影像系统内网基本都是这个形态。这类环境有个共同特点能用的工具极其有限但业务对智能化的需求一点不少。我在过去一年多里先后在三个不同性质的隔离内网里落地过 AI Agent 相关的工程踩的坑比想象中多得多。公网上那些“一行命令装好”“五分钟跑通”的教程到了内网基本全部失效——因为你连 pip install 都跑不通模型权重下不下来MCP 服务连不上外部工具Skills 市场更是想都别想。所以这篇东西不是讲 AI Agent 是什么的科普而是讲在一个没有外网、没有现成生态、甚至连依赖包都要靠人工摆渡的环境里怎么把一套能真正干活的 Agent 工程搭起来。核心关键词就几个AI Agent、MCP、Skills、内网、工程实战。适合的读者是那些已经懂一点 Agent 原理、但被内网环境卡住的工程师也适合正在做内网智能化选型的技术负责人。我下面讲的所有方案都是实际跑通过的不是纸上推演。涉及具体参数和步骤的地方我会把“为什么这么选”讲透因为内网环境里一个错误的技术选型可能意味着两周的返工。2. 内网 Agent 工程的架构设计与选型逻辑2.1 先想清楚内网 Agent 到底要解决什么问题很多人一上来就问“用哪个框架”这是本末倒置。内网 Agent 的第一性问题不是框架而是能力边界。公网 Agent 可以随时调用搜索、调用外部 API、调用云模型内网 Agent 这些全都没有。所以你必须先回答三个问题模型从哪来是本地部署开源模型还是内网里已经有一台推理服务器工具怎么接Agent 要操作的文件、数据库、内部系统通过什么协议暴露给它能力怎么扩展新需求来了是改代码还是加载一个新的 Skill这三个问题的答案直接决定了你的架构。我见过太多团队上来就选了个重框架结果发现模型跑不动、工具接不上最后推倒重来。2.2 模型层本地推理是唯一现实选择隔离内网里模型只能本地部署。这里有个关键决策用多大的模型。我的经验是内网 Agent 场景下7B 到 14B 的量化模型INT4 或 INT8是性价比最高的区间。原因很直接32B 以上的模型即使量化后也需要至少 24GB 显存才能跑得动内网里的推理卡往往还要共享给其他业务7B 以下的模型工具调用的准确率会明显下降尤其是涉及多步推理和参数填充的场景错误率高到没法用14B 量化模型在 16GB 显存上能跑工具调用准确率在实测中能达到可用水平。具体到部署我推荐用vLLM 或者 Ollama 的内网离线版。vLLM 吞吐高适合多人共用Ollama 部署简单适合单机快速验证。模型权重文件通过物理介质摆渡进去校验哈希后再加载。注意内网部署模型时一定要提前确认推理卡的驱动版本和 CUDA 版本模型权重、推理框架、驱动三者版本不匹配是内网环境最常见的翻车点而且往往没有外网可以查文档。2.3 工具层MCP 是内网工具接入的最优解MCPModel Context Protocol这个东西公网上讨论很多但在内网里它的价值反而更大。为什么因为内网的工具接入天然是碎片化的——这个系统是 Java 的那个是 Python 的还有一个是 C 的老古董。如果没有统一协议每接一个工具就要写一套适配代码维护成本爆炸。MCP 的核心价值在于把“工具”抽象成一个标准接口Agent 不需要知道工具背后是什么语言、什么系统只需要知道这个工具叫什么、需要什么参数、返回什么格式。在内网里这意味着你可以把内部系统的能力一个个封装成 MCP ServerAgent 侧只需要维护一份工具清单。内网 MCP 的部署要点MCP Server 全部部署在内网走本地 socket 或内网 HTTP不依赖任何外部服务工具描述tool description要写得极其精确因为内网模型能力有限模糊的描述会导致调用失败每个 MCP Server 要有独立的健康检查内网里服务挂了没人通知你只能靠主动探测。2.4 能力层Skills 让 Agent 可扩展而不失控Skills 这个概念本质上是把“一类任务的完整处理流程”打包成一个可加载的单元。公网上的 Agent Skills 市场很热闹但内网里你只能自己造。我的做法是把内网里高频出现的任务比如“生成一份符合内部格式的周报”“从内部数据库拉数据做趋势分析”“按内部规范检查代码”各自封装成一个 Skill。每个 Skill 包含三部分触发条件、执行步骤、输出格式。Agent 加载 Skill 后遇到匹配的任务就按预设流程走而不是每次重新推理。这样做的好处是可控。内网环境最怕的就是 Agent 自由发挥因为它没有外部知识可以校正一旦跑偏就是灾难。Skills 相当于给 Agent 划定了轨道它在轨道内可以灵活但不会脱轨。2.5 整体架构三层解耦把上面几层串起来内网 Agent 的架构就是三层层级职责内网部署要点模型层提供推理能力本地量化模型vLLM/Ollama 离线部署工具层提供外部能力MCP Server 内网部署统一协议能力层提供任务编排Skills 本地加载流程固化三层之间通过标准接口通信任何一层出问题都不影响其他层。这个解耦设计在内网里特别重要因为内网的调试成本极高解耦意味着你可以单独替换某一层而不动其他部分。3. 核心细节解析与实操要点3.1 模型部署从权重摆渡到服务拉起内网模型部署的第一步是权重摆渡。这个过程听起来简单但细节很多。我的标准流程是在外网环境下载模型权重通常是 HuggingFace 格式记录每个文件的 SHA256通过物理介质拷贝到内网拷贝后重新计算哈希与记录值比对在内网推理服务器上创建独立的模型目录权限设置为只读用 vLLM 或 Ollama 加载模型指定量化参数和显存占用上限。这里有个容易忽略的点模型的分词器文件tokenizer必须和权重一起摆渡。我见过有人只拷了权重文件结果加载时报错排查了半天才发现是分词器缺失。vLLM 的启动命令大致是这样python -m vllm.entrypoints.openai.api_server \ --model /models/qwen2-14b-int4 \ --served-model-name internal-agent \ --max-model-len 8192 \ --gpu-memory-utilization 0.85 \ --port 8000参数说明max-model-len设成 8192 是因为内网 Agent 的上下文通常不需要太长设太大反而浪费显存gpu-memory-utilization设 0.85 是给系统留余量内网服务器往往还有其他进程。3.2 MCP Server 开发把内部系统包装成工具写一个内网 MCP Server核心是把内部系统的能力抽象成“函数”。以最常见的“查询内部数据库”为例一个 MCP Server 的结构大概是from mcp.server import Server from mcp.types import Tool, TextContent server Server(internal-db) server.list_tools() async def list_tools(): return [ Tool( namequery_metrics, description查询指定业务指标在指定时间范围内的数值参数为指标名和起止日期, inputSchema{ type: object, properties: { metric_name: {type: string}, start_date: {type: string}, end_date: {type: string} }, required: [metric_name, start_date, end_date] } ) ] server.call_tool() async def call_tool(name, arguments): if name query_metrics: result internal_db_query( arguments[metric_name], arguments[start_date], arguments[end_date] ) return [TextContent(typetext, textstr(result))]关键在description和inputSchema。内网模型能力有限描述必须具体到参数格式比如日期是YYYY-MM-DD还是YYYYMMDD必须写清楚。我踩过的坑是描述写得太笼统模型传了个“上周”进去结果查询直接报错。3.3 Skills 封装把流程固化成可加载单元一个 Skill 在内网里的典型结构是一个目录包含skill.yaml元信息包括名称、触发条件、依赖的工具prompt.md这个 Skill 的提示词模板steps.py可选的执行脚本用于需要确定性计算的步骤。skill.yaml的示例name: weekly_report description: 生成符合内部格式的周报 triggers: - 生成周报 - 本周总结 tools: - query_metrics - query_tasks output_format: markdownAgent 加载 Skill 后遇到“生成周报”这类请求就会按 Skill 定义的流程走先调query_metrics拉数据再调query_tasks拉任务最后按模板生成。整个过程不需要模型自由发挥稳定性大幅提升。3.4 内网调试没有外网怎么排查问题内网调试是最大的痛点。我的经验是提前建好日志体系。具体做法模型层、工具层、能力层各自输出结构化日志统一格式日志里必须包含请求 ID方便跨层追踪关键路径的日志级别设为 DEBUG非关键路径设为 INFO避免日志爆炸。排查问题时先看请求 ID 在哪一层断了再深入那一层看详细日志。这个方法论在内网里能省下大量时间因为内网没法用外部工具做链路追踪。4. 实操过程与核心环节实现4.1 环境准备从零到可运行假设你拿到一台全新的内网服务器要把它变成 Agent 运行环境。我的标准步骤是第一步确认基础环境。检查操作系统版本、Python 版本、CUDA 版本、显卡驱动版本。这四个版本必须互相兼容不兼容的话后面全是坑。第二步离线安装依赖。在外网用pip download把所有依赖包下载成 wheel 文件摆渡进内网后pip install --no-index --find-links安装。这里要注意有些包有平台相关的二进制依赖必须在外网用和目标机器相同的平台下载。第三步部署模型服务。按前面说的流程加载模型启动推理服务用 curl 测试接口是否正常。第四步部署 MCP Server。每个 MCP Server 独立进程配置好内网端口测试工具调用是否正常。第五步加载 Skills。把 Skill 目录放到指定路径Agent 启动时扫描加载。这五步做完一个最小可用的内网 Agent 环境就搭好了。整个过程如果顺利一天能搞定如果不顺利卡在依赖兼容性上两三天也正常。4.2 参数计算显存和上下文怎么定内网部署最常被问的就是“我这台机器能跑多大的模型”。给一个粗略的计算方法模型显存占用 ≈ 参数量 × 量化位数 / 8 × 1.2系数比如 14B 模型 INT4 量化14 × 4 / 8 × 1.2 ≈ 8.4GB。加上 KV Cache 和框架开销16GB 显存能跑但余量不大。如果上下文要开到 8192KV Cache 还要额外占用建议留 20% 余量。上下文长度方面内网 Agent 的典型任务工具调用、流程编排通常 4096 到 8192 足够。设太大不仅浪费显存还会让模型在长上下文里“迷失”工具调用准确率反而下降。4.3 一个完整的实操案例内网数据查询 Agent我拿一个实际做过的案例来讲。需求是内网里有个业务数据库业务人员想用自然语言查询数据比如“上个月华东区的销售额是多少”。实现路径写一个 MCP Server封装数据库查询能力工具名query_sales参数是区域、时间范围写一个 Skill触发条件是“查询”“销售额”这类词流程是先解析自然语言里的区域和时间再调query_sales模型用 14B 量化版部署在内网推理服务器Agent 主程序负责接收请求、加载 Skill、调用模型、执行工具、返回结果。关键细节自然语言里的时间解析是最容易出错的。我的做法是在 Skill 里加一个确定性的时间解析步骤用 Python 的日期库把“上个月”转成具体日期范围而不是让模型去算。模型只负责识别“上个月”这个词转换交给代码。这样准确率从 70% 提升到接近 100%。4.4 性能调优让内网 Agent 跑得更快内网 Agent 的性能瓶颈通常在模型推理。几个实测有效的优化批处理如果多个请求同时来合并成一个 batch 送进模型吞吐能提升 2 到 3 倍KV Cache 复用相同 System Prompt 的请求可以复用 KV Cache减少重复计算工具调用并行如果一次任务需要调多个工具且工具之间无依赖并行调用能显著降低延迟。这些优化在内网里尤其重要因为内网的推理资源往往比公网紧张得多。5. 常见问题与排查技巧实录5.1 模型加载失败最常见的三类原因现象可能原因排查方法加载时报文件缺失权重或分词器文件不完整比对文件清单和哈希加载时报版本不兼容框架版本与模型格式不匹配确认框架支持的模型格式加载后推理报错量化参数配置错误检查量化位数和显存设置我遇到最多的是第一类摆渡过程中文件损坏或遗漏。所以哈希校验这一步绝对不能省。5.2 工具调用失败描述问题是主因内网模型工具调用失败八成是工具描述写得不好。具体表现模型传的参数类型不对比如该传字符串传了数字模型漏传必填参数模型调用了不存在的工具。解决方法把工具描述当成给新人的说明书来写。参数类型、格式、示例、边界情况全部写清楚。我甚至会加一句“如果用户没有提供某参数请先询问用户”这样模型就不会瞎猜。5.3 Skill 加载异常路径和依赖是重点Skill 加载失败通常是两个原因路径不对或者依赖的工具没注册。排查时先确认 Skill 目录在扫描路径下再确认 Skill 声明的工具都已经在 MCP Server 里注册。提示内网里建议做一个 Skill 自检脚本启动时自动扫描所有 Skill检查依赖是否满足不满足的直接告警。这个脚本能省下大量排查时间。5.4 独家避坑技巧几个我从实际项目里总结的、文档里不会写的技巧模型服务要设超时内网推理服务器负载高时请求可能卡住必须设超时并重试MCP Server 要幂等同一个请求重复调用不能产生副作用否则 Agent 重试时会出问题Skill 要版本化每次修改 Skill 都升版本号出问题时能快速回滚日志要脱敏内网数据敏感日志里不能出现真实业务数据用占位符替代。5.5 内网 Agent 的扩展方向这套架构搭好之后扩展其实很自然。想加新能力就写个新 MCP Server想加新流程就写个新 Skill。模型层如果算力允许可以升级到更大的模型接口不变。我个人的体会是内网 Agent 工程最难的不是技术而是在没有外部资源的情况下保持工程的规范性。公网环境里你可以随时查文档、装工具、试错内网里每一步都要提前想清楚因为返工成本太高。所以前期设计多花一天后期能省一周。最后分享一个小技巧内网里做 Agent 开发建议先在公网环境用同样的架构跑通把代码和配置整理成可离线部署的包再整体摆渡进内网。这样能把大部分问题在公网阶段解决掉内网里只处理环境差异。这个流程我用了三次每次都能把内网部署时间压缩到两天以内。