1. 隔离内网下的 AI Agent 工程到底难在哪先把场景说清楚。所谓“隔离内网”就是一台或者一批机器物理上或者策略上跟公网断开装不了在线包拉不了远程镜像连不上外部模型 API甚至连时间同步都得靠内网 NTP。很多做 AI Agent 的朋友平时在公网环境里玩得飞起pip install 一把梭MCP 服务随手一挂模型 API 填个 key 就能跑。一旦把这套东西搬进隔离内网立刻傻眼依赖装不上、模型调不通、工具链断了一大截。我前后在三个不同规模的隔离环境里落地过 AI Agent 工程最小的是一台 8 卡 A100 的离线推理机最大的是一整个内网集群配私有模型服务。踩过的坑足够写一本小册子。这篇就把“隔离内网下 AI Agent 工程实战”这件事从头到尾拆一遍讲清楚整体设计思路、核心组件怎么选、MCP 和 Skills 这类新东西在离线环境怎么落地、并发怎么扛、以及那些只有真正干过才知道的排查技巧。这篇文章适合几类人看一是要在内网环境部署 AI Agent 的工程师二是正在做企业级 Agent 中台的技术负责人三是对 MCP、Skills 这些概念感兴趣但还没在受限环境里实操过的开发者。不管你是刚接触 Agent 的新手还是已经写过几个 Demo 的老手只要你的目标环境是“没有公网”的这里面的东西都能直接抄作业。核心关键词先埋进来AI Agent、MCP、Skills、内网、工程实战。这五个词基本覆盖了整条链路——Agent 是主体MCP 是工具接入协议Skills 是能力封装方式内网是约束条件工程实战是落地方法。下面按这个逻辑一层层展开。2. 整体架构设计与方案选型思路2.1 为什么隔离内网的 Agent 架构必须“去公网依赖”公网环境下搭 Agent很多人的默认做法是Agent 框架跑在本地模型调用走云端 API工具通过 MCP 或者函数调用接进来需要什么包就 pip 装。这套架构的隐含假设是“网络永远可达”。隔离内网直接把这个假设打碎。所以第一件事是重新画架构图。隔离内网下的 Agent 系统必须做到全链路离线自持模型要私有部署依赖要提前离线打包工具服务要内网自建连 MCP 的传输层都得换成内网能跑的方式。我见过有人把公网那套架构原封不动搬进内网结果卡在“模型 API 调不通”这一步整整两天最后发现是根本没部署私有模型。架构设计的核心原则我总结成三条模型本地化、依赖预置化、通信内网化。模型本地化指的是推理服务必须在内网跑起来不管是 vLLM、TGI 还是其他推理框架依赖预置化指的是所有 Python 包、系统库、模型权重都要提前准备好离线包通信内网化指的是 Agent 跟模型、Agent 跟工具之间的所有通信都走内网地址不能有任何外网回调。2.2 模型层选型私有推理服务怎么搭模型层是整个 Agent 的心脏。隔离内网里没有云端 API 可用必须自己部署推理服务。选型上主要看三个维度模型能力、硬件资源、推理框架。模型能力方面如果内网机器有足够的显存比如 4 张 A100 80G可以上 70B 级别的模型Agent 的工具调用和复杂推理能力会好很多。如果只有单卡 24G那就老老实实上 7B 或者 14B 的量化版本别硬撑。我实测下来7B 模型做简单的工具调用和结构化输出够用但涉及多步推理和复杂规划就容易翻车。推理框架方面vLLM 是目前内网部署最省心的选择支持 OpenAI 兼容接口Agent 框架基本都能直接对接。TGI 也不错但配置稍微复杂一点。如果追求极致轻量llama.cpp 的 server 模式也能用适合资源紧张的场景。提示模型权重文件动辄几十 G一定要提前用移动硬盘或者内网文件服务器传进去别指望在内网里下载。我一般会准备两个版本一个全精度用于验证一个量化版本用于实际部署。2.3 工具层选型MCP 与 Skills 在内网的落地方式这是很多人最关心的部分。MCPModel Context Protocol本质上是一个让模型跟外部工具、数据源通信的协议标准。它解决的是“模型怎么知道有哪些工具可用、怎么调用这些工具”的问题。Skills 则是更高一层的能力封装把一个或多个工具调用组合成一个可复用的技能单元。在内网环境里MCP 的落地要注意几点。第一MCP Server 必须内网自建不能依赖任何外部服务。第二MCP 的传输方式要选内网能跑的stdio 方式最简单Agent 和 MCP Server 在同一台机器上通过标准输入输出通信完全不涉及网络。如果 Agent 和工具服务在不同机器上那就用 SSE 或者 HTTP 方式走内网地址。Skills 的落地更偏向工程组织。我的做法是把常用能力拆成独立的 Skill 模块每个 Skill 封装一组相关的工具调用逻辑比如“数据库查询 Skill”“文件处理 Skill”“报表生成 Skill”。这样 Agent 在规划时只需要选择合适的 Skill不用关心底层具体调了哪些工具。组件公网常见做法内网替代方案注意事项模型服务云端 APIvLLM/TGI 私有部署提前准备权重注意显存工具协议远程 MCP Server本地 stdio MCP 或内网 SSE传输层要内网可达能力封装在线 Skills 市场自建 Skill 仓库版本管理要跟上依赖管理pip 在线安装离线 wheel 包注意依赖树完整性2.4 并发扛不住的根因分析热词里有个问题很典型“ai agent 怎么扛并发”。隔离内网下这个问题更突出因为模型推理资源是固定的不像云端可以弹性扩容。Agent 扛并发的瓶颈通常不在 Agent 框架本身而在模型推理服务。一个请求进来Agent 要调模型做规划调工具拿数据再调模型做总结一轮下来可能调好几次模型。如果模型服务同时只能处理一个请求那并发能力就是 1。解决思路有几个方向。一是推理服务层面开并发vLLM 支持 continuous batching能同时处理多个请求这是最有效的。二是 Agent 层面做请求队列和限流避免大量请求同时打到模型服务。三是把一些确定性强的操作从模型调用里剥离出来用规则或者代码直接处理减少模型调用次数。3. 核心组件细节与实操要点3.1 离线依赖打包别等到内网才发现缺包离线依赖打包是内网部署的第一道坎。公网环境下pip install一条命令搞定的事内网里要提前把所有 wheel 包下载好还要处理依赖树。我的标准流程是这样的先在公网机器上建一个干净的虚拟环境把项目需要的所有包装一遍然后用pip download把包和依赖全部下载到本地目录。命令大概是这样pip download -r requirements.txt -d ./offline_packages --platform manylinux2014_x86_64 --python-version 310 --only-binary:all:这里有几个坑要注意。--platform和--python-version必须跟内网机器的环境完全一致否则下载的 wheel 包装不上。如果有些包没有预编译的 wheel只有源码包那就得在内网机器上现场编译这时候还要确保编译工具链齐全。注意有些包依赖系统级的库比如psycopg2依赖libpq-devlxml依赖libxml2-dev。这些系统库没法用 pip 打包必须提前在内网机器上装好。我一般会列一个系统依赖清单跟 Python 包分开管理。打包完成后把整个目录拷进内网用pip install --no-index --find-links./offline_packages -r requirements.txt安装。--no-index强制不走在线源--find-links指定本地包目录。3.2 MCP Server 的内网部署与调试MCP Server 在内网部署首选 stdio 模式。这种模式下 MCP Server 就是一个普通的可执行程序Agent 通过标准输入输出跟它通信完全不涉及网络端口也就没有防火墙和安全策略的问题。部署步骤大概是先把 MCP Server 的代码和依赖准备好确保在内网机器上能独立运行然后在 Agent 的配置里注册这个 MCP Server指定启动命令和参数最后启动 Agent它会自动拉起 MCP Server 进程并建立通信。调试 stdio 模式的 MCP Server 有个技巧可以先用命令行手动跑一下 MCP Server看看它能不能正常启动、能不能响应基本的初始化请求。很多问题其实是 MCP Server 本身启动失败而不是 Agent 配置的问题。如果 Agent 和工具服务必须分机器部署那就用 SSE 模式。SSE 模式下 MCP Server 监听一个内网端口Agent 通过 HTTP 连接过去。这时候要注意端口要开在内网可达的网段防火墙策略要放行。# MCP Server 配置示例stdio 模式 mcp_config { mcpServers: { database: { command: python, args: [/opt/mcp/db_server.py], env: { DB_HOST: 10.0.1.100, DB_PORT: 5432 } } } }3.3 Skills 的工程化组织方式Skills 在内网环境下的组织核心是“可复用”和“可维护”。我的做法是每个 Skill 一个独立目录包含 Skill 描述文件、实现代码、依赖声明和测试用例。Skill 描述文件用 YAML 或者 JSON 写说明这个 Skill 叫什么、能做什么、需要什么参数、返回什么结果。Agent 在规划时会读取这些描述决定什么时候调用哪个 Skill。# skill: query_sales_report name: query_sales_report description: 查询指定时间范围内的销售报表数据 parameters: - name: start_date type: string required: true description: 开始日期格式 YYYY-MM-DD - name: end_date type: string required: true description: 结束日期格式 YYYY-MM-DD returns: type: object description: 包含销售额、订单数、环比等字段这种组织方式的好处是新增能力只需要加一个 Skill 目录不用改动 Agent 核心逻辑。维护的时候也能快速定位到具体 Skill。3.4 内网通信与端口规划隔离内网虽然不连公网但内网内部的通信还是要规划好。我一般会预留几个端口段模型服务用一个段比如 8000-8010MCP Server 用一个段8100-8110Agent 服务用一个段8200-8210监控和日志用一个段8300-8310。端口规划的好处是排查问题的时候一目了然。看到 8001 端口不通就知道是模型服务的问题看到 8101 端口不通就知道是某个 MCP Server 的问题。内网通信还要注意 DNS 或者 hosts 配置。如果内网没有 DNS 服务那就得在每台机器的 hosts 文件里写死 IP 和主机名的映射。我一般会维护一个统一的主机名规范比如model-svc、mcp-db、agent-main然后在 hosts 里统一配置。4. 完整实操流程与关键环节实现4.1 环境准备清单与检查项动手之前先把环境准备清单过一遍。这份清单是我踩了无数次坑之后总结出来的缺一项都可能卡住。检查项具体要求验证方式操作系统与打包环境一致uname -a对比Python 版本与打包环境一致python --version系统依赖库按清单安装ldd检查动态库模型权重完整且校验通过文件大小和哈希对比离线包目录包含所有 wheelpip install --no-index试装内网连通性各服务端口可达telnet或nc测试磁盘空间模型数据日志足够df -h检查这份清单里最容易忽略的是系统依赖库和磁盘空间。系统依赖库缺失的表现是 Python 包装上了但 import 报错磁盘空间不足的表现是模型加载到一半失败。4.2 模型服务部署与验证模型服务部署是重头戏。以 vLLM 为例部署命令大概是这样python -m vllm.entrypoints.openai.api_server \ --model /opt/models/qwen-14b-chat \ --served-model-name qwen-14b \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 2 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9参数说明一下。--tensor-parallel-size 2表示用两张卡做张量并行适合模型大到单卡放不下的情况。--max-model-len 8192是最大上下文长度根据实际需求调整设太大占显存。--gpu-memory-utilization 0.9表示用 90% 的显存留一点给系统。部署完成后用 curl 验证一下curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen-14b, messages: [{role: user, content: 你好}] }能正常返回就说明模型服务 OK。如果报错先看日志常见问题是显存不足、模型路径错误、端口被占用。4.3 Agent 主程序的内网适配Agent 主程序的内网适配核心是改配置。把模型 API 地址从云端改成内网地址把 MCP Server 的启动方式改成内网可用的方式把日志和监控的输出地址改成内网地址。# Agent 配置示例 agent_config { model: { base_url: http://model-svc:8000/v1, api_key: not-needed-for-local, model_name: qwen-14b }, mcp_servers: { database: { command: python, args: [/opt/mcp/db_server.py] }, file: { command: python, args: [/opt/mcp/file_server.py] } }, skills_dir: /opt/skills, log_dir: /var/log/agent }配置改完之后先跑一个最简单的测试用例确认 Agent 能正常调模型、能正常调工具。这一步过了再上复杂场景。4.4 并发压测与调优记录并发压测是验证系统能力的关键环节。我一般用 locust 或者 wrk 做压测模拟多个用户同时发起请求。压测的时候重点看几个指标请求成功率、平均响应时间、P95 响应时间、模型服务的 GPU 利用率。如果成功率低或者响应时间长就要调优。调优的方向有几个。一是调 vLLM 的--max-num-seqs参数控制同时处理的请求数。二是调 Agent 的并发数避免一次性发太多请求。三是优化 Skill 的实现减少不必要的模型调用。我实测下来单张 A100 跑 14B 模型vLLM 开 continuous batchingAgent 并发数控制在 8-16 之间比较稳。再高的话响应时间会明显上升。提示压测的时候一定要监控 GPU 显存和利用率。显存打满会导致请求失败利用率长期 100% 说明已经到瓶颈了。5. 常见问题与排查技巧实录5.1 模型服务启动失败排查模型服务启动失败是最常见的问题。排查思路按顺序来先看日志日志里通常有明确报错再看显存nvidia-smi看是不是显存不够再看模型路径确认权重文件完整最后看端口确认没被占用。有个坑特别隐蔽模型权重文件传输过程中损坏。表现是加载到某个层的时候报错但错误信息不明确。解决办法是传输完成后做一次哈希校验跟源文件对比。5.2 MCP 连接超时与协议错误MCP 连接问题分两类一类是连不上一类是连上了但协议错误。连不上的原因通常是 MCP Server 没启动、启动命令错误、或者 stdio 模式下 Agent 找不到可执行文件。排查方法是手动跑一下 MCP Server 的启动命令看能不能正常起来。协议错误的原因通常是 MCP Server 版本跟 Agent 不兼容或者消息格式不对。排查方法是看 Agent 和 MCP Server 的日志对比消息内容。5.3 Skills 调用失败的典型原因Skills 调用失败常见原因有几个参数类型不对、依赖的服务不可达、Skill 内部逻辑报错。参数类型不对是最常见的比如 Skill 要求传日期字符串结果传了个时间戳。解决办法是在 Skill 描述文件里把参数类型写清楚Agent 规划时就会按类型传参。依赖服务不可达比如 Skill 要查数据库但数据库连不上。这种要在 Skill 实现里做好错误处理返回明确的错误信息方便排查。5.4 内网环境特有的坑内网环境有些坑是公网遇不到的。比如时间不同步导致 token 过期内网没有 NTP 服务的话机器时间可能差很多。解决办法是内网自建 NTP或者手动同步时间。还有 DNS 解析问题。内网没有 DNS 的话主机名解析不了只能用 IP。解决办法是配 hosts 文件或者内网自建 DNS。再就是文件传输问题。内网机器之间传大文件如果网络带宽不够传输会很慢。解决办法是用内网文件服务器或者用移动硬盘拷贝。问题现象可能原因排查方法解决方案模型加载失败权重损坏/显存不足看日志、nvidia-smi重新传输/减模型MCP 连不上Server 未启动手动跑启动命令修正启动配置Skill 调用报错参数类型不对看 Skill 日志修正参数类型时间不同步无 NTPdate 对比自建 NTP主机名解析失败无 DNSping 主机名配 hosts5.5 独家避坑技巧汇总分享几个我踩坑之后总结的技巧。第一个所有配置项集中管理。内网环境改配置很麻烦如果配置散落在各个文件里改一处漏一处。我一般用一个统一的配置文件所有服务都从这里读配置。第二个日志分级输出。内网排查问题主要靠日志日志太啰嗦或者太简略都不行。我一般设 INFO 级别输出到文件ERROR 级别额外输出到单独文件方便快速定位。第三个健康检查接口。每个服务都加一个健康检查接口返回服务状态和依赖状态。这样排查问题的时候先调健康检查能快速定位是哪个环节的问题。第四个版本锁定。内网环境装包麻烦所以一旦装好就别轻易动。所有依赖的版本都锁定避免因为版本变化引入新问题。6. 内网 Agent 工程的扩展方向6.1 从单机到集群的演进路径单机跑通之后下一步往往是扩展到集群。集群化的核心是服务拆分和负载均衡。模型服务可以独立部署多实例前面挂一个负载均衡Agent 服务也可以多实例部署共享同一个模型服务和工具服务。集群化之后配置管理就更重要了。我一般用配置中心统一管理所有服务的配置改一处全局生效。6.2 Agent 中台化的思考如果内网 Agent 要服务多个业务方那就需要考虑中台化。中台化的核心是能力复用和统一管理。把通用的 Skill 沉淀到中台业务方只需要关注自己的业务逻辑。中台化还要考虑权限和配额。不同业务方能用哪些 Skill、能用多少模型资源都要有管理机制。6.3 监控与可观测性建设内网环境的监控跟公网不太一样公网的监控服务内网访问不了得自建。我一般用 Prometheus Grafana 做监控日志用 ELK 或者 Loki。监控指标重点看几个模型服务的 QPS、响应时间、GPU 利用率Agent 服务的请求量、成功率、平均耗时MCP Server 的调用次数、失败率。这套监控搭起来之后排查问题效率会高很多。很多问题在用户反馈之前监控就能发现。我在实际项目里最大的体会是隔离内网的 Agent 工程难点不在 Agent 本身而在“把公网那套东西搬到内网”的适配过程。模型部署、依赖打包、MCP 适配、Skills 组织每一环都有坑。但只要把架构设计对了把依赖预置好了把排查手段备齐了内网跑 Agent 跟公网跑 Agent 的体验差距其实没那么大。最后再分享一个小技巧内网部署前先在公网环境模拟一个“断网”场景跑一遍把该暴露的问题提前暴露出来能省掉很多在内网里抓瞎的时间。