1. 为什么要在隔离内网里折腾 AI Agent先把场景说清楚。所谓隔离内网就是一台或者一批机器物理上或者逻辑上跟公网断开不能直接访问外部的大模型 API不能随手 pip install 一个包就完事甚至连 GitHub 都拉不下来。很多做金融、制造、政企交付的团队日常就是在这样的环境里干活。而 AI Agent 这个东西天生又是个吃生态的玩意儿——它要调模型、要跑工具、要读文件、要连各种 MCP Server一旦断网很多现成的方案直接趴窝。我在过去一年里前前后后在三四个完全隔离的环境里落地过 AI Agent 工程踩的坑足够写一本小册子。这篇就把整套思路和实操细节摊开讲从架构选型、依赖离线化、MCP 协议在内网的适配、Skills 的组织方式一直到并发扛压和故障排查。目标读者是那些手里有一台内网服务器、想把 AI Agent 真正跑起来、而不是停留在 demo 阶段的工程师。看完你应该能照着搭出一套能用的东西而不是又一篇原理介绍。核心矛盾其实就一句话Agent 的能力来自外部生态而内网切断了这个生态。所以整套工程的核心任务就是把这个生态搬进来——模型搬进来、依赖搬进来、工具协议搬进来、技能包搬进来然后在封闭环境里让它们协同工作。下面按这个逻辑一层层拆。2. 整体架构设计与方案选型2.1 内网 Agent 的三层结构我最终稳定下来的架构是三层模型服务层、Agent 编排层、工具与技能层。这三层在内网里各自独立部署通过本地网络通信任何一层都不依赖公网。模型服务层负责把大模型跑起来对外暴露一个兼容 OpenAI 接口的 HTTP 服务。编排层是 Agent 的大脑负责理解任务、规划步骤、调用工具。工具与技能层则是 Agent 的手脚包括文件操作、数据库查询、内部 API 调用以及通过 MCP 协议挂载的各种能力。为什么这么分因为内网环境里模型往往是最重、最难动的部分把它单独抽出来做成服务编排层就可以轻量化换模型、升级模型都不影响上层逻辑。而工具层独立是为了让不同 Agent 复用同一批工具避免每个 Agent 都自带一套实现维护起来是灾难。2.2 编排框架怎么选别迷信全家桶选型这块我踩过最大的坑就是一开始想用某个特别重的框架结果它内部硬编码了一堆要联网的遥测和依赖下载逻辑在内网里根本起不来。后来我的原则变成编排层优先选依赖少、可离线、能自己掌控的。具体来说如果你团队是 Python 栈LangChain 加 LangGraph 这套组合在内网是可行的但要注意把它的遥测关掉把模型调用指向本地服务。如果是 Java 栈Spring AI 这两年成熟度上来了配合本地模型服务也能跑好处是跟企业现有的 Spring 体系融合度高。如果追求极致轻量和性能用 Rust 自己写编排核心也是很多团队的选择尤其是对并发和资源占用敏感的场景。我的建议是别一上来就上最复杂的框架。先用一个最小的编排循环接收任务、调模型、解析工具调用、执行、回填结果把链路跑通再逐步引入框架能力。很多团队死在框架还没跑通业务需求已经堆成山。2.3 MCP 协议在内网里的定位MCP 这两年火得一塌糊涂本质上是给模型和外部工具之间定了一套标准通信协议。它的价值在内网里反而更明显因为内网工具五花八门有数据库、有内部系统、有文件服务如果每个都单独写适配工作量爆炸。用 MCP 统一成 ServerAgent 侧只需要一个 MCP Client就能挂载所有工具。但要注意MCP Server 的部署在内网里要特别小心。很多现成的 MCP Server 实现默认会去连外部服务或者依赖某些在线资源。我的做法是只保留纯本地能力的 MCP Server凡是需要外网的要么改造要么自己重写。比如文件系统 MCP、数据库 MCP、内部 HTTP 接口 MCP这些都能纯本地跑是内网 Agent 的主力。2.4 Skills 的组织哲学Skills 这个词最近被用得很泛我的理解是Skill 就是一段可被 Agent 发现、理解、调用的能力封装。它可能是一个脚本、一个提示词模板、一个工具组合。在内网里Skills 的管理比公网更重要因为你没法随时从市场拉新的。我的组织方式是目录化加元数据。每个 Skill 一个目录里面放一个描述文件说明这个 Skill 干什么、需要什么参数、有什么限制加上实际实现。Agent 启动时扫描目录把描述注入到系统提示里模型就知道有哪些能力可用。这套机制的好处是新增 Skill 只需要丢一个目录进去不用改 Agent 代码。3. 依赖离线化与模型部署的实操细节3.1 把依赖搬进内网的三种姿势内网装不了包这是第一道坎。我常用的三种方式按推荐度排序第一种是在外网机器上完整构建然后整体打包搬运。用 Docker 的话直接在外网 build 好镜像导出成 tar拷进内网 load。这是最干净的因为镜像里依赖齐全内网不需要任何网络。缺点是镜像体积大搬运耗时。第二种是搭建内网私有源。把常用的 pip 包、npm 包、Maven 依赖在外网用工具批量下载下来在内网起一个私有的包索引服务。这样内网机器可以像正常一样装包只是源指向本地。适合需要频繁装包的团队前期搭建成本高但长期省事。第三种是离线 wheel 包加本地安装。把依赖的 wheel 文件全部下载拷进内网用pip install --no-index --find-links安装。适合依赖不多、变动不频繁的场景。提示不管用哪种方式一定要在外网环境里把依赖装一遍并跑通确认没有隐藏的运行时下载行为再搬运。我见过太多装的时候好好的一跑就联网的坑。3.2 本地模型服务的部署要点模型这块内网里通常有两种选择一是部署开源模型二是如果有条件用内部已有的推理集群。开源模型部署主流是用推理框架把模型权重加载起来暴露 OpenAI 兼容接口。关键参数上我一般会关注这几个上下文长度、并发数、显存占用。上下文长度决定了 Agent 能处理多复杂的任务但开太大显存吃不消。并发数直接关系到能同时服务多少个 Agent 请求。显存占用则决定了你能在一张卡上跑多大的模型。举个实际的例子一张 24G 显存的卡跑一个 7B 级别的模型量化到 4bit上下文开到 8K并发大概能撑到 8 到 16 路具体看推理框架的调度效率。如果业务需要更长上下文就得降并发或者上更大的卡。这个账一定要提前算别等上线了才发现并发一高就排队。3.3 模型接口的兼容层内网模型服务暴露的接口最好做成 OpenAI 兼容的。原因很简单生态里绝大多数 Agent 框架、MCP 工具、客户端默认都认这套接口。你只要把 base_url 指向本地服务其他代码几乎不用改。如果本地推理框架的原生接口不是 OpenAI 格式中间加一层适配服务就行。这层适配服务很薄主要做请求格式转换和流式响应处理。我一般用 FastAPI 写几十行代码搞定好处是可控出问题好排查。4. MCP 与 Skills 在内网的落地实操4.1 MCP Server 的本地化改造前面说了MCP Server 要纯本地化。具体怎么做以文件系统 MCP 为例它本身就不依赖外网直接部署即可。但像一些连接外部 SaaS 的 MCP就得改造把外部调用替换成内部接口调用把认证方式换成内网 token。改造的核心是把出网的调用全部替换成内网可达的调用。这一步没有捷径只能一个个 Server 过。我的经验是先列一个清单把所有计划使用的 MCP Server 列出来标注每个的依赖然后逐个确认哪些能直接用、哪些要改、哪些直接放弃。4.2 MCP Client 的接入与工具发现Agent 侧作为 MCP Client启动时要连接所有配置好的 MCP Server拉取它们的工具列表。这个过程在内网里要加超时和重试因为内网服务偶尔会抽风。工具发现完成后Agent 会得到一份工具清单每个工具带名称、描述、参数 schema。这份清单会被注入到模型的上下文里模型据此决定调哪个工具。这里有个细节工具太多会撑爆上下文。我一般会做一层筛选只把跟当前任务相关的工具注入或者用工具分组的方式让模型先选组再选工具。4.3 Skills 的编写与测试写 Skill 有几个原则。第一描述要写给模型看不是写给人看。模型靠描述判断什么时候用这个 Skill所以描述要清晰说明适用场景和输入输出。第二实现要健壮内网环境里参数错误、文件不存在、服务超时都是常态Skill 内部要处理好异常返回模型能理解的错误信息而不是直接抛栈。测试 Skill 我一般分两步先单独测脱离 Agent 直接调用确认功能正常再集成测让 Agent 在真实任务里调用看模型能不能正确选择和使用。很多 Skill 单独测没问题一进 Agent 就翻车往往是描述写得让模型误解了。4.4 一个完整的 Skill 示例结构假设我们要做一个查询内部订单的 Skill目录结构大概是这样skills/ query_order/ skill.yaml # 元数据名称、描述、参数 handler.py # 实际实现 README.md # 给人看的说明skill.yaml里写清楚这个 Skill 叫什么、干什么、需要哪些参数。handler.py里实现具体逻辑连内部数据库或者内部 API。Agent 启动扫描skills/目录把每个skill.yaml的描述注入上下文。模型看到查询内部订单这个能力用户问订单相关问题时就会调用它。5. 并发扛压与性能调优5.1 Agent 并发的瓶颈到底在哪很多人一上来就问AI Agent 怎么扛并发但没搞清楚瓶颈在哪。我实测下来Agent 的并发瓶颈通常不在 Agent 本身而在模型推理。Agent 编排逻辑本身很轻就是些字符串处理和 HTTP 调用真正吃资源的是模型那一侧。所以扛并发的核心是让模型服务能高效处理并发请求。这涉及推理框架的批处理能力、显存管理、请求队列调度。Agent 侧要做的是做好请求的排队和限流别把模型服务打爆。5.2 请求队列与限流设计我的做法是在 Agent 和模型服务之间加一层队列。所有模型调用请求先进队列由固定数量的 worker 消费。worker 数量根据模型服务的实际并发能力设定比如模型能扛 16 路并发就开 16 个 worker。这样做的好处是突发流量不会直接冲击模型服务而是堆在队列里慢慢消化。队列长度要设上限超了就快速失败返回系统繁忙而不是无限堆积导致雪崩。5.3 缓存能省一大半算力内网 Agent 场景里很多请求是重复的。比如同一个查询、同一段文本处理反复调用模型纯属浪费。我在编排层加了一层语义缓存请求进来先算个特征命中缓存直接返回不命中才走模型。缓存命中率在真实业务里往往能到 30% 到 50%等于省了三分之一的算力。缓存要注意失效策略内部数据变了相关缓存要清掉否则会返回过期结果。5.4 长任务的处理Agent 处理复杂任务时可能一次要跑几十步耗时几分钟甚至更久。这种长任务不能同步等得做成异步。我的方案是任务提交后立即返回任务 IDAgent 在后台跑客户端轮询或者通过内网消息推送拿结果。长任务还要考虑超时和中断。内网服务不稳定某一步卡住了整个任务就挂起。所以要给每一步设超时超时后要么重试要么降级要么明确失败别让任务永远卡在那。6. 常见问题与排查技巧实录6.1 内网 Agent 典型故障速查现象可能原因排查方向Agent 启动就报错依赖缺失或遥测联网检查启动日志关掉遥测模型调用超时模型服务过载或网络问题看模型服务负载测内网连通性工具调用失败MCP Server 未启动或配置错单独测 MCP Server模型选错工具Skill 描述不清优化描述加示例并发一高就崩无队列无限流加队列和限流结果时好时坏缓存过期或数据不一致检查缓存失效策略6.2 几个我踩过的坑第一个坑以为内网就没有网络问题。内网虽然不出公网但内部服务之间的网络照样会抖。DNS 解析慢、防火墙规则、服务发现失效这些都会导致 Agent 莫名其妙失败。我的经验是所有内网调用都要加超时和重试别假设内网一定稳。第二个坑模型上下文被工具清单撑爆。工具一多光工具描述就占了几千 token留给实际任务的空间就少了。解决办法是工具分组和动态注入只给模型看当前需要的。第三个坑Skill 描述写得太技术化。模型不是人它靠描述里的关键词匹配场景。描述里堆术语模型反而不知道啥时候用。要用人话写把什么时候用说清楚。6.3 日志与可观测性内网环境里出问题没法上网搜全靠日志。所以日志一定要打全每次模型调用的输入输出、每次工具调用的参数和结果、每步的耗时。我一般会把日志结构化方便检索。可观测性上至少要有个简单的监控面板看模型服务的 QPS、延迟、错误率看 Agent 的任务成功率、平均步数。这些指标能帮你快速定位是模型的问题还是编排的问题。7. 一些工程之外的体会搭内网 Agent 这套东西技术上其实没有特别高深的地方难的是在受限环境里把每个环节都抠扎实。公网环境里一个 pip install 能解决的事内网里可能要折腾半天。但反过来内网环境逼着你去理解每个依赖、每个调用到底在干什么这对工程能力的提升是实打实的。我现在做任何 Agent 项目都会先问三个问题模型在哪、工具怎么连、依赖怎么进。这三个问题想清楚了剩下的就是体力活。内网环境只是把这三个问题放大了逼你提前想清楚。另外一点别追求一步到位。我见过太多团队想一次性搭个完美架构结果卡在某个依赖上几个月动不了。正确的做法是先跑通最小闭环——一个模型、一个工具、一个任务然后再往上加。能跑起来的东西才有优化的价值。最后分享一个实用的小技巧在内网里调试 Agent准备一套离线测试集特别重要。把常见的任务、预期的工具调用、期望的输出整理成用例每次改动后跑一遍。内网里没法快速试错这套测试集就是你的安全网。我现在的习惯是每加一个 Skill就补几个测试用例日积月累回归测试几分钟就能跑完心里踏实。