1. 隔离内网下 AI Agent 工程实战从零搭建到落地的完整复盘隔离内网这个词做过企业级交付的兄弟应该都不陌生。物理隔离、逻辑隔离、单向网闸各种形态我都踩过。但真正让我头疼的是在这种环境下把 AI Agent 跑起来。外网那一套 Docker 拉镜像、pip install、npm install 的丝滑体验到了内网全部失效。你面对的可能是一台连 yum 源都没有的 CentOS一个只能通过跳板机上传文件的堡垒机以及一堆不允许出网的防火墙策略。这篇文章要聊的就是在这种极端受限的环境下怎么把 AI Agent 工程从零搭起来。核心关键词包括 AI Agent、MCP、Skills、内网开发、工程实战。我会把整个链路的选型逻辑、离线包制作、依赖树梳理、MCP 协议在内网的适配、Skills 的加载机制、以及并发场景下的调优全部拆开讲。适合谁看适合那些需要在客户现场、生产内网、涉密环境中交付 AI 能力的工程师也适合想理解 AI Agent 工程化落地全貌的开发者。先说结论内网做 AI Agent难点不在模型本身而在于依赖治理和协议适配。你把这两件事想清楚了剩下的就是体力活。2. 整体架构设计与选型思路2.1 为什么不能直接照搬外网方案外网做 AI Agent典型链路是调用云端大模型 API用 LangChain 或类似框架编排工具调用走 HTTP向量库用云服务。这套方案在内网基本废掉原因有三第一模型 API 出不去第二Python 包依赖装不上第三很多内网环境连 HTTPS 证书都是自签的TLS 握手直接失败。所以内网方案的核心思路是全离线化。模型用本地部署的开源模型框架用纯 Python 实现且依赖可控的工具调用走内网 HTTP 或本地进程通信向量库用本地文件型方案。整个系统不依赖任何外部网络。我试过几种组合最后稳定下来的架构是本地推理引擎 轻量 Agent 编排层 MCP 协议做工具标准化 Skills 做能力扩展。下面逐个拆。2.2 模型选型不是越大越好内网环境通常 GPU 资源有限。我见过客户给的是两张 T416G 显存要跑一个能用的 Agent。这时候 70B 的模型想都别想量化后的 14B 或 32B 是更现实的选择。选型时重点看三个指标指令遵循能力、工具调用格式稳定性、中文支持。指令遵循决定 Agent 能不能按你的编排逻辑走工具调用格式稳定性决定 MCP 调用会不会频繁解析失败中文支持就不用说了。实测下来Qwen 系列和 DeepSeek 系列在内网场景表现比较稳。量化方案优先选 GPTQ 或 AWQ4bit 量化在 T4 上推理速度可接受。如果显存实在紧张可以考虑 CPU 推理加内存换时间但延迟会明显上升适合对实时性要求不高的场景。注意内网部署模型时务必提前确认 CUDA 版本和推理引擎的兼容性。我踩过一次坑客户机器是 CUDA 11.8我带的推理引擎编译时用的是 12.1结果加载模型直接报错现场又没有网络重装最后只能临时换方案。2.3 编排层轻量优先LangChain 功能全但依赖树太深。内网离线安装时一个 langchain 能带出几十个包版本冲突排查起来非常痛苦。我的建议是如果团队有能力直接用原生 Python 写编排逻辑或者用 LangGraph 这种相对轻量的方案。编排层的核心职责就三件事管理对话状态、调度工具调用、处理异常重试。不需要太复杂。我自己的做法是用一个状态机来管理 Agent 的执行流程每个状态对应一个动作状态转移由模型输出决定。这样逻辑清晰调试也方便。2.4 MCP 协议内网工具标准化的关键MCP 是 Model Context Protocol 的缩写简单说就是一套让模型和外部工具对话的标准协议。你可以把它理解成 USB 接口只要工具实现了 MCP 协议Agent 就能即插即用。内网环境下 MCP 的价值更大因为工具往往是定制的、异构的。有的工具是 Java 写的有的是 Python有的甚至是 shell 脚本。如果没有统一协议每接一个工具就要写一套适配代码。有了 MCP工具提供方只需要实现协议规定的接口Agent 侧统一调用。MCP 本身是软件协议不是硬件协议。它定义了工具的描述格式、调用方式、返回结构。在内网部署时MCP Server 通常以本地进程或内网 HTTP 服务的形式存在不依赖外网。2.5 Skills能力扩展的模块化方案Skills 这个概念最近很火本质上是一种可插拔的能力包。一个 Skill 包含一段提示词、一组工具定义、以及可选的示例。Agent 在运行时根据任务动态加载对应的 Skill。内网环境下 Skills 的优势在于你可以把不同业务场景的能力拆成独立的 Skill 包按需加载避免一次性把所有工具都塞给模型导致上下文爆炸。比如财务场景加载财务 Skill运维场景加载运维 Skill互不干扰。3. 离线依赖治理与包管理实操3.1 依赖树梳理先做减法内网装包最大的坑是依赖冲突。我的做法是先在外网准备一台和目标环境操作系统版本一致的机器用 pip download 把所有依赖下载下来然后用 pipdeptree 把依赖树打出来人工审查一遍。审查重点看三类包有 C 扩展的、有版本锁定的、有平台特定依赖的。有 C 扩展的包在内网编译时可能缺头文件最好直接下载对应平台的 wheel 包。版本锁定的包要确认锁定的版本是否兼容。平台特定的包比如 pywin32 这种Linux 环境直接排除。# 在外网机器上导出依赖 pip freeze requirements.txt # 下载所有依赖到本地目录 pip download -r requirements.txt -d ./offline_packages --platform manylinux2014_x86_64 --python-version 310 --only-binary:all: # 如果有些包没有 wheel需要下载源码包 pip download -r requirements.txt -d ./offline_packages --no-binary:all:3.2 离线源搭建让内网也能 pip install直接把包拷进去一个个装太原始。更好的做法是在内网搭一个本地 PyPI 源。用 devpi 或者简单的 nginx 做静态文件服务都行。我常用的是 nginx 方案把下载好的包放到一个目录nginx 配一下 autoindex然后内网机器 pip install 时指定 index-url 指向这个地址。这样后续加包也方便往目录里扔文件就行。server { listen 8080; server_name local-pypi; location /packages/ { alias /data/pypi/packages/; autoindex on; } }然后内网机器配置 pippip install --index-url http://local-pypi:8080/packages/ --trusted-host local-pypi some-package提示如果内网有多个 Python 版本建议按版本分目录存放 wheel 包避免装错版本。3.3 模型文件传输大文件怎么进内网模型文件动辄几个 G 甚至几十个 G通过跳板机上传非常痛苦。我的经验是如果内网有文件服务器优先走文件服务器。如果没有可以用分卷压缩加校验的方式分批传输。传输前一定要做完整性校验。我遇到过传输过程中文件损坏导致模型加载失败的情况排查了半天才发现是文件不完整。用 md5 或 sha256 校验传输前后对比。# 分卷压缩 tar czf - model_dir | split -b 2G - model_dir.tar.gz.part_ # 合并 cat model_dir.tar.gz.part_* | tar xzf - # 校验 sha256sum model_dir.tar.gz4. MCP 协议在内网的适配与落地4.1 MCP Server 的部署形态选择MCP Server 在内网有三种部署形态本地进程、内网 HTTP 服务、容器化部署。选哪种取决于工具的性质和调用频率。本地进程适合轻量工具比如文件读写、简单计算。启动快通信开销小但隔离性差一个工具崩溃可能影响主进程。内网 HTTP 服务适合需要独立部署的工具比如数据库查询、内部 API 调用。隔离性好但需要额外维护服务。容器化适合复杂工具但内网容器镜像的获取和更新是个麻烦事。我一般推荐 HTTP 服务形态因为内网环境通常有成熟的服务治理体系监控、日志、重启都有现成方案。4.2 工具描述文件的编写要点MCP 协议要求每个工具提供描述文件告诉模型这个工具是干什么的、参数是什么、返回什么。这个描述文件的质量直接决定模型能不能正确调用工具。写描述文件时注意几点描述要具体不要写“查询数据”要写“根据用户 ID 查询订单列表返回订单号、金额、状态”。参数说明要完整包括类型、是否必填、取值范围。返回结构要明确最好给一个示例。我见过很多工具调用失败不是模型能力问题而是描述文件写得太模糊模型根本不知道什么时候该调这个工具。4.3 内网 MCP 调用的超时与重试内网服务虽然稳定但也不是百分百可靠。MCP 调用必须设置超时和重试。超时时间根据工具性质定查询类工具 5 到 10 秒写入类工具 30 秒以上。重试策略用指数退避避免雪崩。import time import requests def call_mcp_tool(url, payload, max_retries3, base_timeout10): for attempt in range(max_retries): try: resp requests.post(url, jsonpayload, timeoutbase_timeout * (2 ** attempt)) resp.raise_for_status() return resp.json() except requests.exceptions.Timeout: if attempt max_retries - 1: raise time.sleep(2 ** attempt) except requests.exceptions.RequestException as e: if attempt max_retries - 1: raise time.sleep(2 ** attempt)注意重试只对幂等操作安全。写入类工具重试前要确认是否支持幂等否则可能产生重复数据。5. Skills 加载机制与并发调优5.1 Skills 的动态加载设计Skills 的核心是动态加载。Agent 启动时只加载基础 Skill运行时根据任务类型加载对应 Skill。这样做的目的是控制上下文长度避免把所有工具描述都塞进提示词。实现上我用一个 Skill 注册表来管理所有可用 Skill每个 Skill 有唯一的标识和触发条件。Agent 收到任务后先用一个轻量分类模型判断任务类型然后加载对应 Skill。class SkillRegistry: def __init__(self): self.skills {} def register(self, name, skill): self.skills[name] skill def load_for_task(self, task_type): return [s for s in self.skills.values() if task_type in s.tags]5.2 并发场景下的资源竞争AI Agent 扛并发难点在资源竞争。模型推理是 GPU 密集型工具调用是 IO 密集型两者要分开处理。我的做法是用一个任务队列来缓冲请求推理侧用固定数量的 worker工具调用侧用线程池。GPU 推理的并发数不要超过显存能承载的 batch size。T4 上跑 14B 4bit 模型并发 4 路基本是极限再高延迟会明显上升。工具调用侧可以适当放宽但要注意内网服务的承载能力。5.3 上下文管理与截断策略长对话场景下上下文会不断增长最终超出模型窗口。必须做上下文管理。我的策略是保留系统提示词和最近 N 轮对话中间的历史对话做摘要压缩。摘要压缩用一个轻量模型来做把多轮对话压缩成一段简短描述。这样既保留了关键信息又控制了长度。截断阈值根据模型窗口定留出 20% 的余量给工具返回结果。6. 常见问题与排查技巧实录6.1 模型加载失败排查模型加载失败最常见的原因是文件不完整和版本不兼容。排查步骤先校验文件 hash确认传输完整。再检查推理引擎版本和模型格式是否匹配。最后看 CUDA 版本和驱动版本是否满足要求。如果报错信息是显存不足尝试降低量化精度或减少并发数。如果是格式错误确认模型是否用了正确的加载器。6.2 MCP 调用超时排查MCP 调用超时先分清楚是网络问题还是服务问题。用 curl 直接调 MCP Server 的接口看是否能通。如果不通检查防火墙规则和服务状态。如果通但慢看服务日志可能是数据库查询慢或者内部依赖超时。我遇到过一次 MCP 调用超时排查半天发现是内网 DNS 解析慢每次调用都要等 DNS。后来在 hosts 文件里加了静态解析问题解决。6.3 Skills 加载冲突排查多个 Skill 同时加载时可能产生工具名冲突。排查方法是打印所有已加载 Skill 的工具列表看是否有重名。解决方法是给工具名加 Skill 前缀或者用命名空间隔离。6.4 常见问题速查表问题现象可能原因排查方法解决方案模型加载报错文件不完整校验 hash重新传输模型加载报错版本不兼容检查引擎和 CUDA 版本更换匹配版本MCP 调用超时网络不通curl 测试检查防火墙MCP 调用超时DNS 慢检查解析时间配置 hostsSkills 冲突工具重名打印工具列表加前缀隔离并发延迟高GPU 瓶颈监控显存和利用率降低并发数7. 内网 AI Agent 工程的个人体会内网做 AI Agent技术难度其实不比外网高但工程复杂度高很多。外网你遇到问题可以搜、可以试、可以换方案。内网你遇到问题可能连日志都拿不出来只能靠经验判断。我的建议是进内网之前把所有能想到的问题都预演一遍。依赖能不能装、模型能不能加载、工具能不能调通、并发能不能扛住这些都要在外网环境先验证。内网只做部署和联调不做探索性开发。另外内网环境的文档一定要写清楚。我见过太多项目交付时人走了后面接手的人连怎么启动都不知道。把部署步骤、配置说明、常见问题都写下来比什么都重要。最后分享一个小技巧内网部署时准备一个最小可用版本。就是只包含核心功能、依赖最少、配置最简单的版本。当完整版出问题时先用最小版本顶上保证业务不中断然后再慢慢排查完整版的问题。这个策略帮我救过好几次场。