1. 隔离内网下 AI Agent 工程实战从零搭建到落地的完整复盘隔离内网这四个字做过企业级交付的人看到都会头皮一紧。没有公网、没有外部镜像源、没有在线大模型接口连 pip install 都得先想想包从哪来。偏偏这两年 AI Agent 又成了刚需业务方不管你的网络环境只看你能不能把活干出来。我在过去大半年里前后在三个完全物理隔离的内网环境里落地过 AI Agent 工程踩的坑从依赖打包一直延伸到模型推理服务的并发瓶颈今天把整套思路和实操细节完整拆一遍。先说清楚这篇文章适合谁看。如果你所在的环境是金融、能源、制造、政务这类内网隔离场景需要把 AI Agent 真正跑起来而不是停留在 demo 阶段那这篇内容基本可以当施工手册用。如果你只是在自己笔记本上玩 Agent网络畅通无阻那这篇里关于离线依赖、内网模型服务、MCP 协议适配的部分可能对你参考价值有限但工程化思路依然值得一看。核心关键词就几个AI Agent、MCP、Skills、内网、工程实战全文围绕这五个词展开不跑题。我先把结论性的判断放在前面隔离内网下做 AI Agent难点从来不是 Agent 本身而是依赖供应链、模型推理服务、协议适配层这三座大山。Agent 框架的代码逻辑反而是最简单的部分。很多人一上来就研究 LangChain、LangGraph 怎么编排结果卡在第一步——内网装不上包。这个顺序搞反了会浪费大量时间。2. 内网 AI Agent 的整体架构设计与选型逻辑2.1 为什么不能照搬公网那套方案公网环境下搭 AI Agent大家习惯的路径是pip 装框架、调云端大模型 API、用现成的 MCP 服务、Skills 直接从市场拉。这套流程在内网里每一步都会断。pip 装不上是因为没有 PyPI 源云端 API 调不通是因为没有出口MCP 服务拉不下来是因为没有外部网络Skills 市场更是想都别想。所以内网方案的核心思路必须转变把所有外部依赖变成内部资产。具体来说就是三件事——依赖包全部离线化、模型推理全部本地化、协议服务全部自建化。这三件事听起来简单但每一件都有大量细节。我见过太多团队在内网里硬套公网架构结果搭了两周还在解决依赖冲突。正确的做法是先盘点内网已有的资源有没有 GPU 服务器、有没有内部 PyPI 镜像、有没有容器仓库、有没有内部文件服务。这些资源决定了你的架构上限。2.2 三层架构的划分方式我最终稳定下来的架构是三层基础设施层、能力层、编排层。基础设施层负责提供算力和依赖包括 GPU 推理服务器、内部包管理服务、容器镜像仓库、对象存储。这一层是地基地基不稳后面全白搭。能力层是 AI Agent 的“手脚”包括本地大模型推理服务、MCP 协议服务、Skills 执行引擎、工具调用网关。编排层是“大脑”负责 Agent 的决策逻辑、任务规划、上下文管理。这么分层的好处是每层可以独立演进。比如模型换了只动能力层的推理服务Agent 逻辑改了只动编排层。内网环境下变更成本高分层能大幅降低维护难度。2.3 模型选型的现实考量内网里选模型不能只看 benchmark 分数。我总结下来要看四个维度显存占用、推理速度、中文能力、工具调用稳定性。显存占用直接决定你能跑多大的模型。一张 24G 显存的卡7B 模型量化后能跑14B 勉强32B 就得量化到 4bit 甚至更低。推理速度决定用户体验内网里没有云端那种弹性扩容速度不够就是不够。中文能力对国内业务场景是硬指标很多英文强的模型中文一塌糊涂。工具调用稳定性是 Agent 场景特有的模型能不能稳定输出结构化的工具调用请求直接决定 Agent 能不能用。我实测下来在内网 24G 显存的环境里7B 到 14B 的量化模型是比较务实的选择。再大就得考虑多卡或者更激进的量化但量化太狠会显著影响工具调用的准确率这个 trade-off 要自己权衡。2.4 MCP 协议在内网里的定位MCP 这两年热度很高但很多人没搞清楚它在内网里的实际价值。MCP 本质是一套标准化的工具调用协议让 Agent 能用统一的方式访问各种外部能力。在内网里MCP 的价值在于解耦——Agent 不需要知道每个工具的具体实现只需要按 MCP 协议调用就行。但内网里用 MCP 有个前提你得自己实现 MCP Server。公网上那些现成的 MCP 服务在内网里一个都用不了。所以实际工作量是定义工具接口、实现 MCP Server、部署到内网、让 Agent 通过 MCP Client 连接。这套流程走下来比直接硬编码工具调用要重但长期维护性更好。3. 离线依赖供应链的搭建与避坑3.1 依赖打包的正确姿势内网装包这件事我踩过的坑能写一本书。最开始的笨办法是在公网机器上 pip download 一堆 whl 文件拷进内网 pip install。这个方法在依赖简单的时候能用一旦遇到有 C 扩展的包就崩——因为 pip download 默认只下当前平台的 whl内网机器架构不一样就装不上。正确的做法是用pip download加上平台参数把所有可能的平台都下下来。命令大概是这样pip download -r requirements.txt \ --platform manylinux2014_x86_64 \ --python-version 310 \ --only-binary:all: \ -d ./offline_packages但这里有个坑--platform和--only-binary一起用的时候如果某个包没有对应平台的 whl会直接报错。这时候要么找替代包要么就得下源码包在内网编译。源码编译在内网里是噩梦因为编译依赖往往又是一堆包。我的经验是优先选纯 Python 实现的包避开有 C 扩展的。比如向量库能用纯 Python 的就别用需要编译的。实在避不开的提前在公网把编译好的 whl 准备好。3.2 内部 PyPI 镜像的搭建依赖包多了以后靠拷贝 whl 文件管理会失控。这时候需要搭一个内部 PyPI 镜像。可选方案有 devpi、pypiserver、Nexus 等。我推荐 devpi因为它支持缓存代理和本地包上传功能比较全。搭好之后内网机器的 pip 配置指向内部镜像装包就跟公网一样顺畅。但要注意devpi 本身也需要在内网部署它的依赖也得提前准备好。这是个鸡生蛋的问题第一次部署会麻烦一点之后就一劳永逸。提示内部镜像一定要做好权限控制别让所有人都能往上传包。我见过有人误传了一个同名但版本不同的包导致整个团队的构建全部失败排查了大半天。3.3 容器镜像的离线搬运如果 Agent 用容器部署镜像搬运是另一个大坑。公网拉镜像、save 成 tar、拷进内网、load 进去这套流程本身没问题但镜像层数多、体积大的时候tar 文件能到几个 G拷贝和加载都很慢。优化思路是减小镜像体积。用多阶段构建把编译依赖和运行时依赖分开用 alpine 或者 slim 基础镜像清理不必要的缓存文件。我做过一个对比优化前后镜像从 3.2G 降到 800M加载时间从几分钟降到几十秒。另外内网如果有 Harbor 之类的镜像仓库把镜像 push 进去其他机器直接 pull比每台机器都 load tar 文件高效得多。3.4 依赖版本锁定的重要性内网环境最怕的就是“在我机器上能跑”。因为内网装包麻烦大家往往装完就不动了结果不同机器上的依赖版本不一致同一个 Agent 在不同机器上行为不同。解决办法是严格锁定版本。用 pip freeze 生成精确的 requirements.txt所有版本号都写死。更进一步可以用 pip-tools 或者 poetry 管理依赖生成 lock 文件。内网部署时严格按照 lock 文件安装确保环境一致。这个习惯在公网可能觉得无所谓内网里是刚需。我吃过亏一个 Agent 在测试环境好好的上到生产环境就报错最后发现是某个依赖的小版本差异导致的。4. 本地模型推理服务的部署与调优4.1 推理框架的选择内网部署本地模型推理框架的选择直接影响性能和稳定性。主流的有 vLLM、TGI、Ollama、llama.cpp 等。选哪个要看场景。vLLM 吞吐量高适合并发请求多的场景但显存占用相对大。TGI 是 HuggingFace 出的生态好部署简单。Ollama 最省心一条命令就能跑但性能和并发能力一般。llama.cpp 最省资源CPU 也能跑但速度慢。我的建议是有 GPU 且并发要求高用 vLLM快速验证和单机使用用 Ollama资源极度受限用 llama.cpp。内网环境往往资源紧张Ollama 的性价比其实很高。4.2 模型量化的取舍量化是内网部署绕不开的话题。FP16 精度最高但显存占用大INT8 折中INT4 最省显存但精度损失明显。我做过一组对比测试同一个 7B 模型FP16 需要约 14G 显存INT8 约 7GINT4 约 4G。推理速度上INT4 最快FP16 最慢。但工具调用的准确率FP16 和 INT8 差距不大INT4 明显下降。对于 Agent 场景工具调用的准确率是生命线。所以我一般推荐INT8 量化在显存和精度之间取得平衡。如果显存实在不够INT4 也能用但要接受一定的准确率损失并且在 prompt 设计上做补偿。4.3 并发能力的实测与瓶颈“AI Agent 怎么扛并发”是热词里高频出现的问题。内网里并发瓶颈往往不在模型本身而在推理服务的配置。vLLM 有个关键参数--max-num-seqs控制同时处理的请求数。设太小并发上不去设太大显存爆掉。这个值要根据显存和模型大小算。经验公式是可用显存除以单个请求的 KV Cache 占用。7B 模型 INT8 量化24G 显存--max-num-seqs设 16 到 32 比较稳。另一个瓶颈是 Agent 本身的编排逻辑。如果 Agent 串行调用工具那并发再高也没用。要把能并行的工具调用并行化这需要在编排层做设计。我实测过一个场景单张 24G 卡跑 7B INT8 模型--max-num-seqs设 24QPS 能到 8 到 10 左右。再往上加并发延迟会明显上升。这个数据供参考具体要看模型和硬件。4.4 推理服务的健康检查与降级内网环境没有云端的自动运维推理服务挂了得自己发现。所以健康检查机制必须做。我的做法是推理服务暴露一个/health接口Agent 调用前先检查。如果服务不可用走降级逻辑——要么返回缓存结果要么提示用户稍后重试要么切换到备用模型。备用模型这个策略在内网里很实用。主模型用大的备用模型用小的主模型挂了自动切到小的虽然效果差一点但至少能用。这个切换逻辑要在 Agent 编排层实现。5. MCP 协议与 Skills 体系的内网落地5.1 MCP Server 的自建流程内网里用 MCP第一步是自建 MCP Server。MCP 协议本身不复杂核心就是定义工具的描述和调用接口。一个最小的 MCP Server 大概长这样from mcp.server import Server from mcp.types import Tool, TextContent server Server(internal-tools) server.list_tools() async def list_tools(): return [ Tool( namequery_database, description查询内部数据库, inputSchema{ type: object, properties: { sql: {type: string, description: SQL 查询语句} }, required: [sql] } ) ] server.call_tool() async def call_tool(name: str, arguments: dict): if name query_database: result execute_sql(arguments[sql]) return [TextContent(typetext, textstr(result))]这个 Server 部署在内网Agent 通过 MCP Client 连接。关键点是工具的描述要写清楚模型靠这个描述来决定调不调用、怎么调用。描述写得含糊模型就会乱调。5.2 Skills 的设计原则Skills 这个概念这两年很火但内网里落地 Skills 要务实。Skills 本质是封装好的能力单元Agent 按需加载。设计 Skills 有几个原则。粒度要适中。太细了 Agent 要加载一堆太粗了复用性差。我的经验是按业务动作划分比如“查询订单”“生成报表”“发送通知”各是一个 Skill。接口要稳定。Skills 一旦被 Agent 依赖改动成本很高。所以接口设计要预留扩展空间参数用对象而不是散列方便后续加字段。要有降级方案。内网里某个 Skill 依赖的服务挂了不能让整个 Agent 崩掉。每个 Skill 要有超时和降级逻辑。5.3 Skills 的测试方法Skills 测试在内网里容易被忽视但很重要。我一般分三层测单元测试测 Skill 本身的逻辑集成测试测 Skill 和依赖服务的交互端到端测试测 Agent 调用 Skill 的完整链路。端到端测试最容易被跳过但恰恰最能发现问题。我遇到过一个 caseSkill 单独测都正常但 Agent 调用时因为上下文太长导致模型输出格式错乱Skill 解析失败。这种问题只有端到端测才能发现。测试数据要覆盖边界情况空输入、超长输入、特殊字符、并发调用。内网环境数据敏感测试数据要脱敏但结构要真实。5.4 MCP 与 Skills 的协同MCP 和 Skills 不是二选一而是协同关系。MCP 解决的是“怎么调用”的问题Skills 解决的是“调用什么”的问题。一个 Skill 可以封装成 MCP Server 暴露出去Agent 通过 MCP 协议调用。这种分层的好处是Skill 的实现可以独立演进只要 MCP 接口不变Agent 就不用改。内网里变更成本高这种解耦能省很多事。6. 常见问题与排查技巧实录6.1 依赖相关问题的排查内网依赖问题排查核心是定位是哪个包出的问题。pip 报错信息往往很长关键信息在前面几行。我一般先看报错类型是找不到包还是版本冲突还是编译失败。找不到包检查内部镜像里有没有这个包版本对不对。版本冲突用pip check看冲突详情然后手动调整版本。编译失败看缺什么系统库在内网里找对应的 rpm 或 deb 包装上。有个技巧是用虚拟环境隔离。不同 Agent 用不同的 venv避免依赖互相污染。内网里重建环境成本高隔离能减少很多麻烦。6.2 模型推理异常的排查模型推理异常表现可能是输出乱码、格式错误、速度极慢、服务崩溃。排查思路是从输入到输出逐段检查。先看输入prompt 是不是太长是不是有特殊字符。再看模型加载显存够不够量化配置对不对。然后看推理过程日志里有没有报错。最后看输出格式符不符合预期。速度慢的问题先看是不是首次加载慢正常再看是不是并发太高降--max-num-seqs最后看是不是显存不足导致频繁 swap减模型大小或量化。6.3 MCP 连接问题的排查MCP 连接问题常见的是连不上、超时、返回格式错误。连不上先检查网络和端口内网防火墙规则要确认。超时看服务端处理时间可能是工具执行太慢。返回格式错误看 MCP Server 的实现是不是符合协议。我遇到过一个坑MCP Server 返回的 JSON 里有 NaN 值Agent 解析直接崩。这种问题要在 Server 端做数据清洗确保返回的都是合法 JSON。6.4 常见问题速查表问题现象可能原因排查方向解决思路pip 装包失败内部镜像无此包检查镜像包列表上传缺失的包依赖版本冲突版本锁定不严pip check严格锁定版本模型输出乱码量化过度或 prompt 问题检查量化配置和 prompt提高量化精度或优化 prompt推理速度慢并发过高或显存不足看 GPU 利用率和 swap降并发或减模型MCP 连不上网络或端口问题检查防火墙和端口开放端口或换端口MCP 返回格式错Server 实现问题看 Server 日志修复 Server 数据清洗Agent 工具调用失败模型工具调用能力弱看模型输出格式换模型或优化 prompt并发上不去编排层串行看 Agent 调用链路并行化工具调用6.5 独家避坑经验最后分享几个我踩过的坑都是文档里不会写的。坑一内网时间不同步。内网机器时间如果不同步会导致 token 过期、日志时间错乱、缓存失效。部署前一定要配好 NTP哪怕内网没有外部 NTP也要有个内部时间源。坑二磁盘空间不足。模型文件、日志、缓存都很占空间。内网扩容麻烦部署前要算好磁盘需求留足余量。我见过模型跑到一半磁盘满了服务直接挂掉。坑三GPU 驱动版本不匹配。推理框架对 GPU 驱动版本有要求内网升级驱动很麻烦。部署前确认驱动版本选兼容的推理框架版本。坑四日志级别设太高。内网排查问题全靠日志日志级别设太高会丢关键信息。生产环境用 INFO排查问题时临时调 DEBUG。坑五没有监控。内网里服务挂了没人知道。至少要有个简单的监控看服务存活、GPU 利用率、请求延迟。Prometheus 加 Grafana 是标配内网部署也不复杂。7. 工程化落地的几点个人体会内网 AI Agent 工程化说到底是个平衡的艺术。效果和资源要平衡开发效率和维护成本要平衡功能完整和稳定可靠要平衡。公网环境下可以堆资源解决问题内网里资源有限必须精打细算。我个人的经验是先把最小可用链路跑通再逐步加能力。不要一上来就追求大而全内网里每加一个组件都是成本。先让 Agent 能调用一两个核心工具跑通端到端然后再扩展 Skills 和 MCP 服务。另外文档和自动化脚本要跟上。内网环境重建成本高好的文档和脚本能让重建变得简单。我每个项目都会写一份部署文档和一套自动化脚本虽然前期费时间但后期省的事更多。最后说个实际的内网里做 AI Agent别追求最新最炫的技术。稳定压倒一切。选成熟的框架、成熟的模型、成熟的方案把精力放在业务适配和工程优化上。新技术在内网里试错成本太高等公网验证成熟了再引入也不迟。