1. 为什么要在隔离内网里折腾 AI Agent先把场景说清楚。所谓隔离内网就是那种物理上跟公网断开、或者只允许极少数白名单流量进出的网络环境。金融、政企、军工、大型制造业的研发网很多都是这个形态。你在这种环境里想跑一个 AI Agent第一反应通常是模型怎么放依赖怎么装工具怎么调外部 API 一个都连不上MCP 那些需要联网的 Server 全部歇菜。我前后在三个不同规模的隔离内网里落地过 Agent 工程踩的坑足够写一本小册子。核心结论先摆出来隔离内网做 Agent难点从来不是模型本身而是工程闭环。你要解决的是模型本地化、依赖离线化、工具内网化、编排可控化这四件事任何一环断了Agent 就是个只会聊天的玩具。这篇文章面向的是已经懂一点 Agent 概念、但真正要在内网里把它跑起来的人。我会把整个工程链路拆开讲从模型选型和量化到 MCP 协议在内网的适配改造再到 Skills 体系怎么设计、并发怎么扛、出问题怎么排查。所有内容都是我在真实内网环境里验证过的方案不是纸上谈兵。先给一个整体判断内网 Agent 的架构本质上是把公网 Agent 的每一个外部依赖替换成内网可自持的等价物。模型换成量化后的本地权重工具调用换成内网 MCP ServerSkills 换成内网知识库加规则引擎可观测性换成自建日志与追踪。想明白这个替换逻辑后面所有工程决策都会顺理成章。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一定要留一份完整的部署文档和故障处理手册。内网环境特殊人员流动时文档就是唯一的传承。我见过因为没文档导致系统没人敢维护的案例血的教训。