1. 为什么要在隔离内网里折腾 AI Agent
先把场景说清楚。所谓隔离内网，就是那种物理上跟公网断开、或者只允许极少数白名单流量进出的网络环境。金融、政企、军工、大型制造业的研发网，很多都是这个形态。你在这种环境里想跑一个 AI Agent，第一反应通常是：模型怎么放？依赖怎么装？工具怎么调？外部 API 一个都连不上，MCP 那些需要联网的 Server 全部歇菜。
我前后在三个不同规模的隔离内网里落地过 Agent 工程，踩的坑足够写一本小册子。核心结论先摆出来：隔离内网做 Agent，难点从来不是模型本身，而是"工程闭环"。你要解决的是模型本地化、依赖离线化、工具内网化、编排可控化这四件事，任何一环断了，Agent 就是个只会聊天的玩具。
这篇文章面向的是已经懂一点 Agent 概念、但真正要在内网里把它跑起来的人。我会把整个工程链路拆开讲：从模型选型和量化，到 MCP 协议在内网的适配改造，再到 Skills 体系怎么设计、并发怎么扛、出问题怎么排查。所有内容都是我在真实内网环境里验证过的方案，不是纸上谈兵。
先给一个整体判断：内网 Agent 的架构，本质上是把公网 Agent 的每一个外部依赖，替换成内网可自持的等价物。模型换成量化后的本地权重，工具调用换成内网 MCP Server，Skills 换成内网知识库加规则引擎，可观测性换成自建日志与追踪。想明白这个替换逻辑，后面所有工程决策都会顺理成章。
2. 内网 Agent 的整体架构设计与选型逻辑
2.1 四层架构：把公网依赖逐个替换掉
我在内网里最终稳定下来的架构是四层，从上到下依次是交互层、编排层、能力层、模型层。这个分层不是为了好看，而是为了让每一层的替换边界足够清晰，方便你在资源受限时逐层降级。
交互层负责接收用户输入、展示结果，通常是一个内网 Web 应用或者对接内部 IM。编排层是 Agent 的大脑，负责意图识别、任务规划、工具调度，这一层我用过 LangGraph 风格的状态机，也用过更轻量的自研调度器。能力层就是各种工具和 Skills，包括 MCP Server、内网 API 封装、知识库检索。模型层是本地部署的推理服务，可能是量化后的开源模型，也可能是内网已有的推理集群。
为什么这么分？因为内网资源是稀缺的。你可能只有两台带 GPU 的服务器，模型层必须独占；编排层和交互层可以挤在一台 CPU 机器上；能力层按需分布。分层之后，每一层可以独立扩容、独立降级，不会因为一个工具挂了拖垮整个 Agent。
2.2 模型选型：不是越大越好，是越稳越好
内网选模型，第一个要放弃的执念就是"追最新最强"。你要考虑的是显存、量化损失、推理延迟、以及最关键的——工具调用能力。一个 70B 但不会调工具的模型，不如一个 14B 但 function calling 稳定的模型。
我的经验是分档处理。如果内网有 A100 或同级别显卡，可以上 32B 到 70B 的量化版本，用 4bit 量化基本能压进单卡或双卡。如果只有消费级显卡，14B 是甜点区，7B 适合做意图路由和简单任务。量化方案上，GPTQ 和 AWQ 我都用过，AWQ 在工具调用场景下的稳定性略好，但差距不大，关键是量化后一定要重新测一遍 function calling 的准确率，不能想当然。
提示：量化后的模型，工具调用的 JSON 格式出错率会明显上升。务必在编排层加一层 JSON 修复和重试逻辑，不要指望模型一次吐对。
2.3 MCP 协议在内网的适配改造
MCP 是 Anthropic 推的工具调用协议，本质是让模型通过标准化接口调用外部能力。公网环境下 MCP Server 通常是独立进程，通过 stdio 或 HTTP 通信。内网里这套逻辑要改。
首先，MCP Server 必须全部内网自持，不能有任何外部依赖。我通常把 MCP Server 做成内网微服务，用 HTTP + SSE 的方式暴露，编排层通过内网地址调用。其次，MCP 的鉴权要简化，内网本身有网络隔离，再加一层 token 校验即可，不用搞复杂的 OAuth。
还有一个坑：MCP 协议里有些 Server 会去拉外部资源，比如查天气、查网页。内网里这些必须全部替换成内网数据源，或者直接禁用。我一般会在 MCP 注册中心加一个"内网可用性"标记，编排层只加载标记为可用的 Server。
2.4 Skills 体系：内网 Agent 的差异化能力
Skills 这个词最近很热，但很多人理解偏了。在内网语境下，Skills 不是简单的提示词模板，而是封装了内网业务逻辑的可复用能力单元。比如"查询工单状态"是一个 Skill，"生成合规报告"是一个 Skill，"调用内网审批流"也是一个 Skill。
我设计 Skills 体系时遵循三个原则：一是每个 Skill 有明确的输入输出契约，用 JSON Schema 定义；二是 Skill 内部可以调用 MCP 工具，但对外只暴露一个统一接口；三是 Skill 要可测试，每个 Skill 都有独立的测试用例，不依赖完整 Agent 链路。
这样设计的好处是，当内网业务变化时，你只需要改对应的 Skill，不用动编排层。而且 Skills 可以按部门、按角色做权限隔离，这在政企内网里是刚需。
3. 核心细节解析与实操要点
3.1 离线依赖：把 pip 和 npm 变成内网仓库
内网装依赖是第一个拦路虎。公网pip install一行命令的事，内网里要提前把所有 wheel 包下载好，传到内网，搭一个私有 PyPI 源。我一般用devpi或者简单的pypiserver，把依赖包按版本归档。
具体操作上，先在公网机器上用pip download把整个依赖树拉下来，注意要指定平台和 Python 版本，否则下到的包在内网装不上。命令大概是这样：
pip download -r requirements.txt -d ./packages --platform manylinux2014_x86_64 --python-version 310 --only-binary=:all:下完之后把packages目录整体拷进内网，用pip install --no-index --find-links=./packages -r requirements.txt安装。npm 同理，用npm pack或者搭一个verdaccio私有源。
注意：有些包在安装时会动态下载资源，比如某些模型的 tokenizer 文件。这类包必须提前把资源文件也打包进去，否则内网安装时会卡住。
3.2 模型部署：推理服务的稳定性设计
内网模型部署我推荐用 vLLM 或者 TGI，两者都支持连续批处理和 PagedAttention，吞吐比裸 transformers 高一个数量级。部署时要关注几个参数：max_model_len决定上下文长度，gpu_memory_utilization控制显存占用，max_num_seqs影响并发能力。
我的经验是，gpu_memory_utilization不要设到 0.95 以上，留一点余量给 KV Cache 的动态增长，否则高并发时会 OOM。max_num_seqs根据显存和模型大小调，14B 模型在 24G 显存上大概能跑到 32 到 64。
还有一个内网特有的问题：模型文件怎么传进去。几十 G 的权重文件，用移动硬盘拷贝是最稳的，网络传输容易断。拷进去之后要做一次完整性校验，用 sha256 比对，避免传输损坏导致加载失败。
3.3 MCP Server 的内网实现细节
MCP Server 在内网里我一般用 Python 或 Go 写，Python 生态好但性能一般，Go 性能好但 MCP 的 SDK 成熟度稍差。如果并发要求不高，Python 足够；如果要扛高并发，Go 更合适。
一个典型的 MCP Server 结构是这样的：启动时注册工具列表，每个工具对应一个处理函数，收到请求后解析参数、执行逻辑、返回结果。内网里我通常加一层缓存，把频繁调用的工具结果缓存起来，减少后端压力。
工具注册的 schema 要写清楚，参数类型、是否必填、默认值都要标明。模型是根据 schema 来决定怎么调用的，schema 写得模糊，模型就容易调错。我见过因为参数描述不清导致模型反复传错格式的案例，排查了半天才发现是 schema 的问题。
3.4 Skills 的封装与测试
Skills 的封装我建议用类或者函数加装饰器的方式，每个 Skill 是一个独立的模块。装饰器负责注册 Skill、校验输入、记录日志、处理异常。这样业务代码只需要关注核心逻辑，工程细节由框架处理。
测试方面，每个 Skill 至少要有三类用例：正常输入、边界输入、异常输入。正常输入验证功能正确，边界输入验证鲁棒性，异常输入验证错误处理。我一般用 pytest 写，配合 mock 把外部依赖隔离掉，保证测试可以在没有完整环境的情况下跑。
提示：Skills 的版本管理很重要。内网里业务规则经常变，每个 Skill 要带版本号，编排层调用时指定版本，避免升级一个 Skill 影响其他流程。
4. 实操过程与核心环节实现
4.1 从零搭建内网 Agent 的完整流程
我把整个搭建过程拆成七个阶段，每个阶段都有明确的交付物和验收标准。
第一阶段是环境勘察。确认内网的网络拓扑、可用服务器、GPU 资源、存储空间、以及允许的软件安装方式。这一步不能省，我见过太多人上来就装环境，结果发现内网根本不允许装 Docker，白忙一场。
第二阶段是模型落地。把选定的模型权重和推理框架传进内网，部署推理服务，用一组标准问题验证模型的基本能力和工具调用能力。验收标准是：模型能稳定输出符合 schema 的 JSON。
第三阶段是依赖仓库搭建。把 Python、Node 的私有源搭好，确保后续所有组件都能在内网安装依赖。这一步做完，后面就是纯内网操作了。
第四阶段是 MCP Server 开发。根据业务需求，把需要的能力封装成 MCP 工具，逐个开发和测试。每个工具都要有独立的测试用例。
第五阶段是 Skills 封装。把业务逻辑封装成 Skill，定义好输入输出契约，写好测试。
第六阶段是编排层开发。实现意图识别、任务规划、工具调度、结果聚合。这一层是 Agent 的核心，也是最容易出问题的地方。
第七阶段是联调和压测。把整个链路跑通，用真实业务场景测试，然后做并发压测，找出瓶颈。
4.2 并发扛压：内网 Agent 的性能优化
"AI Agent 怎么扛并发"是热词里高频出现的问题。内网的并发压力通常来自两个方面：一是多个用户同时使用，二是单个复杂任务触发了大量工具调用。
我的优化思路是分层处理。模型层用连续批处理提升吞吐，vLLM 天然支持，关键是调好max_num_seqs和max_num_batched_tokens。编排层用异步 IO，工具调用并行化，不要让 Agent 串行等待。能力层用缓存和连接池，减少重复计算和连接开销。
实测下来，一个 14B 模型在单张 24G 显卡上，配合合理的批处理参数，能支撑 20 到 30 个并发会话。如果不够，就加卡做张量并行，或者部署多个实例做负载均衡。
还有一个容易被忽略的点：超时控制。内网里某个工具卡住，如果不设超时，整个 Agent 就挂在那里。我给每个工具调用都设了超时，超时后返回降级结果或者报错，让 Agent 能继续往下走。
4.3 内网穿透的替代方案
热词里出现了"内网穿透"相关的词，这里要澄清一下：隔离内网的核心诉求就是不穿透。如果你的内网需要穿透才能用，那说明架构设计有问题。正确的做法是把所有依赖都内网化，而不是想办法打通内外。
如果确实有跨网段访问的需求，比如办公网访问生产内网的 Agent，那应该用内网已有的安全通道，比如堡垒机、跳板机，而不是自己搭穿透工具。这一点在合规要求高的环境里尤其重要，自己搭的穿透通道往往是安全审计的重点对象。
4.4 可观测性：内网 Agent 的日志与追踪
内网里没有现成的 APM 工具，可观测性要自己搭。我一般用三个层次：日志、指标、追踪。
日志用结构化日志，每个请求带 trace_id，方便串联。指标用 Prometheus 加 Grafana，监控 QPS、延迟、错误率、显存占用。追踪用 OpenTelemetry，记录每个工具调用的耗时和结果。
这套东西搭起来不复杂，但对排查问题帮助巨大。Agent 出问题时，你能快速定位是模型的问题、工具的问题、还是编排逻辑的问题。
5. 常见问题与排查技巧实录
5.1 内网 Agent 高频问题速查表
| 问题现象 | 可能原因 | 排查方向 | 解决方法 |
|---|---|---|---|
| 模型加载失败 | 权重文件损坏或版本不匹配 | 校验 sha256，检查框架版本 | 重新传输权重，对齐框架版本 |
| 工具调用格式错误 | 模型量化后 JSON 能力下降 | 查看原始输出 | 加 JSON 修复层，或换量化方案 |
| 并发时 OOM | 显存预留不足 | 监控显存曲线 | 降低 gpu_memory_utilization |
| 工具调用超时 | 后端服务慢或网络问题 | 查看工具耗时分布 | 加超时和降级，优化后端 |
| Skill 执行异常 | 输入不符合契约 | 查看 Skill 日志 | 加强输入校验，完善测试 |
| 依赖安装失败 | 缺少离线包或平台不匹配 | 查看 pip 报错 | 补下对应平台的 wheel 包 |
5.2 踩坑记录：那些文档里不会写的事
第一个坑是模型量化后的工具调用退化。我一开始用 4bit 量化，模型聊天没问题，但工具调用经常吐出不完整的 JSON。后来换成 8bit，问题缓解但显存吃紧。最终方案是 4bit 量化加编排层的 JSON 修复，兼顾显存和稳定性。
第二个坑是MCP Server 的并发瓶颈。Python 写的 MCP Server 在并发高时 GIL 成为瓶颈，工具调用排队严重。后来把核心工具用 Go 重写，性能提升明显。如果不想换语言，用多进程加负载均衡也能缓解。
第三个坑是Skills 的版本混乱。早期没做版本管理，改了一个 Skill 导致其他流程出错。后来引入版本号，编排层显式指定版本，问题才解决。
第四个坑是日志把磁盘写满。Agent 的日志量很大，尤其是调试阶段。内网磁盘空间有限，日志写满会导致服务崩溃。后来加了日志轮转和级别控制，生产环境只记关键日志。
5.3 独家避坑技巧
技巧一：模型预热。服务启动后先用一组标准请求预热，让 KV Cache 和显存分配稳定下来，再对外提供服务。否则第一批请求延迟会很高。
技巧二：工具分级。把工具按重要性和耗时分级，核心工具优先保障，非核心工具可以降级或异步。这样在资源紧张时，Agent 的核心功能不受影响。
技巧三：灰度发布。内网里改 Agent 逻辑风险很高，我一般用灰度发布，先让一小部分流量走新逻辑，观察没问题再全量。内网没有成熟的灰度工具，用配置中心加开关就能实现。
技巧四：定期演练。内网环境相对稳定，但故障总会发生。定期做故障演练，比如手动停掉一个 MCP Server，看 Agent 能不能优雅降级。演练过的系统，真出问题时心里有底。
6. 内网 Agent 工程的扩展方向
6.1 从单 Agent 到多 Agent 协作
单 Agent 能力有限，复杂任务需要多 Agent 协作。内网里做多 Agent，关键是通信机制。我一般用消息队列做 Agent 间的通信，每个 Agent 是一个独立的服务，通过队列传递任务和结果。
多 Agent 的挑战在于协调和一致性。任务怎么拆分、结果怎么合并、冲突怎么解决，这些都需要设计。我的经验是，先从简单的流水线模式开始，一个 Agent 的输出是另一个的输入，跑通了再考虑更复杂的协作模式。
6.2 与内网现有系统的集成
Agent 不是孤岛，要跟内网现有的系统集成。常见的集成点包括：统一认证、工单系统、知识库、审批流。集成时要注意接口的稳定性和幂等性，内网系统往往比较老旧，接口不规范，要做好适配层。
我一般会为每个外部系统写一个适配器，把外部接口转换成 Agent 能理解的统一格式。适配器要处理超时、重试、降级，保证外部系统的问题不会拖垮 Agent。
6.3 持续迭代与效果评估
Agent 上线不是终点，是起点。要持续收集用户反馈，评估 Agent 的效果，迭代优化。评估指标包括：任务完成率、工具调用准确率、用户满意度、平均响应时间。
内网里收集反馈比较麻烦，我一般用两种方式：一是 Agent 交互日志分析，看哪些任务失败、哪些工具调用出错；二是定期找用户访谈，了解真实使用体验。数据加访谈，才能全面评估效果。
我个人在实际操作中的体会是，内网 Agent 工程最考验的不是技术深度，而是工程耐心。每一个依赖都要自己搞定，每一个问题都要自己排查，没有现成的云服务可以依赖。但正是这种约束，逼着你把每一个环节都想清楚、做扎实。当 Agent 在内网里稳定跑起来，支撑起真实业务的时候，那种成就感是公网环境里体会不到的。
最后分享一个小技巧：内网里做 Agent，一定要留一份完整的部署文档和故障处理手册。内网环境特殊，人员流动时，文档就是唯一的传承。我见过因为没文档导致系统没人敢维护的案例，血的教训。
