1. 项目缘起为什么要在隔离内网里折腾 AI Agent先说说我遇到的实际场景。去年下半年我所在的团队接了一个企业级内部工具链的活儿客户环境是标准的物理隔离内网——没有外网出口没有公网 DNS连 pip 和 npm 都得走内部镜像源。但业务方又明确提了一个需求希望把 AI Agent 能力嵌进他们现有的研发流程里做代码审查辅助、文档自动生成、内部知识库问答这几件事。这个需求放在公网环境里说实话现在方案已经很成熟了随便挑一个框架接上模型 API配几个工具调用一两天就能跑通 demo。但一旦落到隔离内网问题就全变了模型怎么部署、Agent 框架怎么选、工具协议怎么落地、依赖怎么离线装、并发怎么扛、日志怎么排查——每一个环节都得重新想一遍。我前后花了大概六周时间从零搭了一套能在隔离内网稳定运行的 AI Agent 工程体系中间踩了不少坑也总结了一些在公网环境下根本不会遇到的工程经验。这篇文章就是把整个过程拆开来讲包括架构选型、MCP 协议在内网里的适配、Skills 机制的设计、并发处理、离线部署细节以及一堆只有真正在内网里干过才知道的注意事项。适合谁看如果你只是想在本地玩一玩 Agent这篇文章可能偏重了。但如果你面临的是企业内网、专有网络、离线环境下的 Agent 落地或者你正在做 MCP 相关的工程化适配那这些内容应该能帮你少走不少弯路。2. 整体架构设计隔离内网下的选型逻辑2.1 为什么不能直接照搬公网方案公网环境下搭 Agent大家习惯的做法是Agent 框架跑在本地或者云主机上模型走 API 调用工具通过 HTTP 请求外部服务依赖用包管理器在线拉取。这套流程在隔离内网里几乎每一步都会断掉。我一开始也想过偷懒能不能在内网里搭一个转发层把外部请求代理进来。但客户的安全策略明确禁止任何形式的内外网数据通道所以这条路直接堵死。那就只能老老实实做全离线方案模型本地部署、依赖离线打包、工具全部内网自建。这里有个关键决策点Agent 框架到底选什么。我评估了几个方向方案类型代表框架内网适配难度依赖体积可控性重型全栈框架各类一体化 Agent 平台高大低轻量编排框架主流开源 Agent 编排库中中高自研轻量调度自己写调度层低小最高最后我选的是轻量编排框架 自研调度层的组合。原因很简单重型框架在内网里依赖太多光是离线解决依赖冲突就能耗掉一周而纯自研又太费时间没必要重复造轮子。轻量框架负责 Agent 的核心循环感知-决策-执行自研层负责内网特有的模型路由、工具注册和并发控制。2.2 MCP 协议在内网里的定位MCP 这个词最近热度很高但很多人对它的理解停留在“又一个工具调用协议”。我的理解是MCP 本质上解决的是Agent 和工具之间的标准化通信问题。在公网环境里这个标准化的价值可能没那么明显因为大家习惯了自己写 function call。但在内网环境里MCP 的价值反而被放大了。为什么因为内网里的工具往往是多个团队分别维护的——有的用 Java 写有的用 Python 写有的甚至是老旧的 C 服务。如果没有一个统一协议Agent 每接一个工具就要写一套适配代码维护成本极高。MCP 提供了一套标准的描述和调用方式只要工具方按照 MCP 规范暴露接口Agent 侧就能统一接入。我在内网里部署 MCP 的方式是这样的每个工具服务作为一个独立的 MCP Server 运行在内网某台机器上通过内网 HTTP 或者 stdio 方式和 Agent 通信。这里要注意MCP 本身不强制传输层stdio 和 HTTP 都支持。在内网里我优先选 stdio因为不涉及网络端口暴露安全审计更容易过。2.3 Skills 机制的设计思路Skills 这个概念在不同框架里定义不太一样。我这里的理解是Skills 是 Agent 的可复用能力单元一个 Skill 封装了一类特定任务的完整处理逻辑包括提示词模板、工具调用序列、输出格式约束。为什么要单独设计 Skills 层因为在实际项目里我发现如果直接把所有逻辑塞进 Agent 的主循环代码会迅速膨胀到无法维护。比如“代码审查”这个任务它需要读取文件、分析语法、对比规范、生成报告这一整套流程如果每次都重新编排既浪费 token 又容易出错。把它封装成一个 Skill 之后Agent 只需要判断“当前任务适合用哪个 Skill”然后调用即可。在内网环境里Skills 还有一个额外好处可以离线版本化管理。每个 Skill 是一个独立的目录包含配置文件、提示词模板和测试用例。更新 Skill 只需要替换目录不需要重新部署整个 Agent 服务。这对内网环境特别友好因为内网部署往往审批流程长能减少部署次数就减少。3. 核心细节解析模型、依赖与工具链的内网适配3.1 模型本地部署的显存与量化取舍隔离内网里没法调外部 API模型必须本地部署。这一步的第一个问题就是选多大的模型。我的经验是先看硬件再选模型不要反过来。客户环境里可用的是两张 24G 显存的卡这个配置决定了模型规模的上限。我当时的计算逻辑是这样的推理阶段模型权重占用的显存大约是参数量 × 精度字节数FP16 精度下7B 模型约需 14G 显存13B 约需 26G已经超了如果用量化INT8 大约减半INT4 再减半最后我选的是 7B 级别的模型做 INT8 量化单卡就能跑留出显存给 KV Cache 和并发请求。这里有个坑要提醒量化会损失精度但不是所有任务都敏感。代码审查和文档生成这类任务INT8 量化的效果和 FP16 差距很小但如果是需要严格逻辑推理的任务量化后可能会出现明显的质量下降。建议在内网部署前先用一批真实任务做 A/B 测试。模型服务我用的是主流的本地推理框架支持 OpenAI 兼容接口。这一点很重要因为 Agent 框架通常默认对接 OpenAI 风格的 API本地推理框架只要兼容这个接口Agent 侧几乎不用改代码。3.2 离线依赖打包的完整流程内网部署最烦人的环节就是依赖。我的做法是在公网机器上完整模拟内网环境把所有依赖打包成离线包。具体步骤在公网机器上创建一个干净的虚拟环境Python 版本和内网目标机器保持一致安装所有依赖包括 Agent 框架、MCP SDK、模型推理客户端等用pip download把所有包下载到本地目录注意要指定平台和 Python 版本把整个目录打包拷贝进内网在内网机器上用pip install --no-index --find-links./packages离线安装这里有几个细节容易翻车平台标签要匹配。如果公网机器是 x86_64 而内网是 ARM下载的包直接不能用。必须用--platform参数指定目标平台。系统依赖也要打包。有些 Python 包依赖系统级的库比如某些图像处理库需要 libGL。这些不在 pip 的管理范围内得手动拷贝对应的 so 文件。版本锁定。内网里没法在线解决依赖冲突所以必须用pip freeze锁定所有版本确保公网和内网环境完全一致。我踩过最惨的一次坑是公网环境用的是 Python 3.10内网机器是 3.9结果好几个包编译失败。后来我养成了一个习惯在内网部署前先用 Docker 起一个和目标环境完全一致的容器做验证。3.3 MCP Server 的内网部署要点MCP Server 在内网部署和公网有几个明显区别。第一是服务发现。公网里可以用各种服务注册中心内网里往往没有这些基础设施。我的做法是用一个简单的配置文件维护 MCP Server 的地址列表Agent 启动时加载。配置文件格式用 YAML方便人工维护。第二是认证。内网虽然相对封闭但不代表不需要认证。我给每个 MCP Server 配了一个静态 tokenAgent 调用时带上。这个 token 不走网络传输加密内网环境通常有自己的链路加密但至少能防止误调用。第三是超时和重试。内网网络虽然稳定但机器负载可能波动。我给每个 MCP 调用设了 30 秒超时失败后重试两次重试间隔用指数退避。这个参数不是拍脑袋定的是根据实际工具的平均响应时间约 2-5 秒留了足够余量。3.4 Skills 的目录结构与加载机制一个 Skill 在内网里的标准目录结构是这样的skills/ code_review/ skill.yaml # 元信息名称、描述、触发条件 prompt.md # 提示词模板 tools.yaml # 依赖的 MCP 工具列表 tests/ # 测试用例 doc_generate/ ...skill.yaml里最关键的是触发条件。我用的是关键词匹配 语义相似度的组合先看用户输入是否包含特定关键词如果包含就直接触发如果不确定再用一个轻量模型算语义相似度。这样做的原因是纯语义匹配在内网小模型上准确率不够稳定加一层关键词兜底能显著提升命中率。加载机制上Agent 启动时扫描 skills 目录把所有 Skill 的元信息加载到内存。实际执行时才读取完整的提示词模板这样可以减少启动时的内存占用。4. 实操过程从零搭建到跑通第一个 Agent4.1 环境准备与基础服务启动内网机器到手后第一步是确认基础环境。我通常会跑一遍这个检查清单操作系统版本和内核参数特别是文件描述符限制Agent 并发高的时候容易撞上Python 版本和 pip 可用性GPU 驱动和显存状态内网 DNS 是否可用有些内网连内部域名解析都不稳定目标端口是否被防火墙拦截确认完环境先启动模型服务。我用的启动命令大致是这样的以主流本地推理框架为例python -m inference_server \ --model /path/to/model \ --quantization int8 \ --max-model-len 8192 \ --gpu-memory-utilization 0.85 \ --port 8000这里--gpu-memory-utilization 0.85是关键参数。设太高容易 OOM设太低浪费显存。0.85 是我在 24G 卡上跑 7B INT8 模型的经验值留了约 3.6G 给 KV Cache 和系统开销。模型服务起来后用 curl 测一下接口是否正常curl http://localhost:8000/v1/models返回模型列表就说明服务正常。4.2 Agent 主服务的配置与启动Agent 主服务的配置文件我一般分成三块模型配置、MCP 配置、Skills 配置。模型配置里指定本地推理服务的地址和模型名称。MCP 配置里列出所有可用的 MCP Server 及其地址、token、超时参数。Skills 配置里指定 skills 目录路径和加载策略。启动 Agent 服务后第一件事是验证 MCP 连接。我写了一个简单的健康检查脚本遍历所有配置的 MCP Server逐个调用其list_tools接口确认能正常返回工具列表。这一步能提前发现大部分配置错误。4.3 第一个 Skill 的完整实现我拿“代码审查”这个 Skill 举例讲一下完整实现过程。首先是skill.yamlname: code_review description: 对指定代码文件进行规范审查和问题检测 triggers: keywords: [审查, review, 检查代码] semantic_threshold: 0.75 tools: - file_reader - lint_runner - report_writer然后是prompt.md这是 Skill 的核心。我的提示词模板结构是这样的你是一个代码审查助手。请对以下代码进行审查 {code_content} 审查维度 1. 命名规范 2. 错误处理 3. 潜在性能问题 4. 安全隐患 输出格式要求 - 每个问题一行格式为 [严重程度] 行号: 问题描述 - 严重程度分为高、中、低这里有个经验提示词模板里不要写太复杂的逻辑。我见过有人把整个决策树写进提示词结果模型经常跑偏。正确做法是把复杂逻辑拆到工具调用里提示词只负责描述任务和输出格式。4.4 并发处理的实际调优过程Agent 服务上线后很快就遇到了并发问题。多个用户同时提交任务时模型服务开始出现请求排队响应时间从 2 秒飙升到 30 秒以上。排查过程是这样的先看模型服务的日志发现请求确实在排队检查 GPU 利用率发现推理时 GPU 利用率只有 40% 左右说明不是算力瓶颈检查模型服务的并发配置发现默认并发数设得很低调整方案分两步一是提高模型服务的并发请求数二是给 Agent 侧加一个请求队列控制同时提交给模型的任务数量。具体参数上我把模型服务的最大并发设为 8Agent 侧的队列长度设为 32。这个配比是根据实测得出的8 个并发请求时 GPU 利用率能到 85% 左右再高就开始出现明显的排队延迟。这里有个反直觉的点并发数不是越高越好。我试过把并发调到 16结果 GPU 利用率反而下降了因为显存不够导致频繁的 KV Cache 换入换出。所以并发数要结合显存和模型大小来定不能盲目调高。5. 常见问题与排查技巧实录5.1 模型服务启动失败的典型原因内网里模型服务起不来我遇到过这么几种情况现象原因解决方法启动时报 CUDA 错误驱动版本和推理框架不匹配确认驱动版本必要时降级框架加载模型时 OOM显存不足或量化配置错误降低 max-model-len 或改用更低精度量化服务起来但请求超时端口被防火墙拦截检查内网防火墙规则返回结果乱码模型文件损坏重新拷贝模型文件校验 MD5其中最常见的是显存问题。我的建议是部署前先用nvidia-smi确认可用显存然后按模型大小 × 1.2 的系数预留空间。5.2 MCP 工具调用失败的排查思路MCP 调用失败在内网里也很常见排查顺序我一般是这样先确认 MCP Server 进程是否存活用 curl 直接调 MCP Server 的接口排除 Agent 侧的问题检查 token 是否正确检查超时设置是否合理看 MCP Server 的日志确认请求是否到达有一次排查了很久最后发现是 MCP Server 所在机器的系统时间不对导致 token 校验失败。内网机器的时间同步往往没人管这是个容易被忽略的坑。5.3 Skills 不触发的调试方法Skills 不触发通常是触发条件设置的问题。我的调试方法是把 Agent 的决策日志打开看它实际匹配到了哪个 Skill以及匹配分数是多少。如果分数接近阈值但没触发可以适当降低阈值。如果分数很低说明提示词或者关键词需要调整。我一般会把阈值设在 0.7 到 0.8 之间太低会误触发太高会漏触发。5.4 内网环境特有的坑最后说几个内网特有的坑这些在公网环境里基本遇不到时间不同步内网机器往往没有 NTP 服务时间漂移会导致各种证书和 token 校验失败。建议在内网里自建一个时间同步服务。DNS 不稳定有些内网 DNS 解析很慢建议在 Agent 配置里直接用 IP 地址绕过 DNS。磁盘空间不足内网机器往往没有专门的运维监控磁盘满了才发现。建议给日志目录设一个大小上限定期清理。依赖版本混乱内网里没法在线升级一旦装错版本很难回退。建议每次部署前做好环境快照。6. 一些实操心得与后续扩展方向这套系统跑稳定之后我又做了一些优化。一个是给 Agent 加了请求缓存相同的任务在短时间内重复提交时直接返回缓存结果能省不少算力。另一个是把 Skills 的测试用例做成了自动化回归测试每次更新 Skill 后自动跑一遍确保没有破坏已有功能。后续如果继续扩展我觉得有几个方向值得尝试一是把 Agent 的决策过程做成可解释的方便排查问题二是支持多模型路由简单任务用小模型复杂任务用大模型进一步优化资源利用三是把 Skills 做成可组合的一个 Skill 的输出可以作为另一个 Skill 的输入形成更复杂的工作流。不过这些都是后话了。眼下最重要的还是把基础打牢内网环境下的 Agent 工程稳定性和可维护性永远比功能丰富度更重要。