1. 为什么“隔离内网 AI Agent”是个真问题先把场景说清楚。所谓隔离内网就是那种物理上跟公网断开、或者只允许单向数据流入的办公网、生产网、研发网。很多做金融、制造、能源、政企交付的团队日常干活的环境就是这样能上外网的那台机器和真正跑业务的机器中间隔着一道墙。而 AI Agent 这套东西从诞生第一天起就是“联网优先”的——模型要调 API、工具要拉依赖、MCP Server 要连外部服务、Skills 要从市场下载。这两件事天然打架。我自己第一次在内网里搭 Agent 的时候踩的坑现在想起来还挺好笑在外网机器上跑得好好的一个流程搬到内网直接全线报错因为pip install拉不到包、模型 endpoint 连不上、MCP 的 stdio 子进程找不到可执行文件。折腾了整整两天才把链路打通。所以这篇东西不是讲“AI Agent 是什么”而是讲当你的运行环境没有公网时怎么把一套完整的 Agent 工程落地。适合谁看三类人一是要在客户内网做交付的工程师二是公司研发网本身就不通外网的开发者三是想在自己机器上搭一套“离线可用”Agent 环境的折腾党。核心关键词就几个AI Agent、MCP、Skills、内网、工程实战。下面我按“整体设计 → 核心细节 → 实操落地 → 问题排查”这条线把整套东西拆开讲。2. 整体架构设计与方案选型2.1 内网 Agent 的三层结构内网环境下的 Agent 工程跟公网环境最大的区别在于所有外部依赖都必须提前“搬进来”。所以架构上我会把它拆成三层每一层的职责和边界都很清楚。第一层是模型层。内网不可能调公网大模型 API所以要么用本地部署的开源模型比如通过推理框架在内网 GPU 机器上跑要么用公司内部已经部署好的模型网关。这一层的关键是提供一个稳定的、OpenAI 兼容的 HTTP endpoint让上层 Agent 框架无感切换。第二层是编排层也就是 Agent 的大脑。这一层负责对话管理、工具调用、任务规划。常见的选择有基于 LangChain/LangGraph 的自研编排、Spring AIJava 技术栈团队常用、以及各种 Agent 框架。这一层跑在内网应用服务器上通过内网地址访问模型层。第三层是工具与能力层也就是 MCP Server 和 Skills 所在的地方。MCPModel Context Protocol本质上是软件协议不是硬件协议——它规定了模型和外部工具之间怎么通信你可以类比成“AI 世界的 USB 接口标准”。Skills 则是更高一层的封装把一组工具调用、提示词、执行逻辑打包成一个可复用的能力单元。三层之间的数据流是这样的用户请求 → 编排层解析意图 → 通过 MCP 协议调用工具层 → 工具层执行查数据库、读文件、调内部 API→ 结果回传编排层 → 编排层组织语言 → 模型层生成最终回复。整条链路全部在内网闭环不碰公网。2.2 为什么选 MCP 而不是自己写函数调用很多人会问我直接写 function calling 不就行了为什么要引入 MCP 这层协议这个问题我在项目里认真权衡过结论是单机小项目确实可以不引入但只要涉及多工具、多团队协作MCP 的收益就非常明显。自己写 function calling 的问题是每个工具的参数格式、错误处理、鉴权方式都不一样工具一多就变成一团乱麻。MCP 把这些标准化了工具怎么声明、参数怎么传、结果怎么返回、错误怎么报全都有统一规范。更关键的是MCP Server 可以独立部署、独立升级编排层不需要跟着改。在内网交付场景里这一点特别重要——客户的内网环境往往不允许你频繁重新部署整个应用但单独更新一个 MCP Server 是可以接受的。至于 Skills我的理解是它站在 MCP 之上。MCP 解决的是“怎么调工具”Skills 解决的是“怎么把一组工具和知识打包成一个能干活的角色”。比如一个“内网代码审查 Skill”它内部可能调用了读文件、跑静态检查、查规范文档三个 MCP 工具还带了一套提示词模板。对编排层来说它只需要调用这个 Skill不用关心里面怎么组合。2.3 内网穿透工具的定位与边界热词里出现了不少内网穿透相关的内容这里必须说清楚内网穿透工具在 Agent 工程里的定位是“开发调试期的临时通道”不是生产方案。它的典型用途是你在内网机器上跑了一个 MCP Server想在外网机器上调试编排逻辑这时候用穿透工具把内网端口临时映射出来方便联调。但生产环境绝对不能用穿透。原因很简单安全边界被打破了。正确的生产做法是所有组件都部署在内网通过内网地址互相访问如果确实需要跨网段走公司统一的网关和鉴权体系。我在项目里定的规矩是穿透工具只允许在开发阶段用上线前必须全部撤掉代码里不允许出现任何穿透相关的配置。3. 核心细节解析与实操要点3.1 模型层的离线部署要点内网模型部署第一个要决定的是模型规格。不是越大越好要看你的内网硬件。我的经验是如果只有单张消费级显卡比如 24G 显存跑 7B 到 14B 的量化模型比较现实如果有 A100 这类卡可以考虑 32B 甚至更大的模型。量化方式上GPTQ 和 AWQ 是比较成熟的选择4bit 量化能把显存占用压到原来的四分之一左右精度损失在可接受范围内。部署框架我一般用 vLLM 或者类似的推理服务原因是它原生提供 OpenAI 兼容接口上层 Agent 框架几乎不用改代码就能接。启动命令大概长这样python -m vllm.entrypoints.openai.api_server \ --model /models/Qwen2.5-14B-Instruct-AWQ \ --served-model-name internal-agent-model \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9这里有几个参数值得说。--max-model-len控制上下文长度内网 Agent 经常要处理长文档但设太大显存扛不住8192 是个比较平衡的值。--gpu-memory-utilization 0.9表示用 90% 显存留一点给系统。--served-model-name起个别名上层配置里用这个名字将来换模型不用改上层代码。注意内网部署模型前一定要把模型权重文件完整下载并校验哈希值再通过合规的介质导入内网。导入后先跑一个简单的推理测试确认模型能正常加载再接入 Agent。3.2 MCP Server 的内网适配MCP Server 有两种常见的通信方式stdio标准输入输出和 SSE/HTTP。在内网环境里我的建议是优先用 HTTP 方式原因是 stdio 方式要求 MCP Server 和编排层在同一台机器上部署灵活性差HTTP 方式可以独立部署通过内网地址访问更符合工程化要求。写一个内网 MCP Server核心是把工具声明清楚。下面是一个简化的 Python 示例展示一个“查询内部知识库”的工具from mcp.server import Server from mcp.server.models import Tool server Server(internal-kb) server.tool() async def search_knowledge(query: str, top_k: int 5) - str: 在内网知识库中检索相关内容。 Args: query: 检索关键词 top_k: 返回结果数量默认5条 # 这里接内网的向量库或全文检索服务 results internal_search(query, top_k) return format_results(results)关键点在于工具的 docstring 会被模型读取用来判断什么时候调用这个工具。所以 docstring 要写得清楚、准确参数说明要完整。我见过很多工具调用失败最后发现是 docstring 写得太模糊模型根本不知道这个工具是干嘛的。内网 MCP Server 的依赖管理是个大坑。因为不能pip install所有依赖必须提前打包。我的做法是用pip download在外网机器上把依赖下载成 wheel 包一起导入内网然后用pip install --no-index --find-links./wheels离线安装。这个流程要写进部署文档不然每次换机器都要重新折腾。3.3 Skills 的组织与复用Skills 这块我的核心观点是不要追求大而全要追求小而可组合。一个 Skill 只干一件事干好。比如“读文件”是一个 Skill“代码格式化”是另一个 Skill需要的时候组合起来用。一个 Skill 通常包含三部分提示词模板、工具依赖声明、执行逻辑。在内网环境里Skills 的存储我建议用本地文件系统或者内网 Git 仓库不要依赖任何外部市场。目录结构可以这样组织skills/ ├── code_review/ │ ├── skill.yaml # 元信息名称、描述、依赖的工具 │ ├── prompt.md # 提示词模板 │ └── handler.py # 执行逻辑 ├── doc_summary/ │ ├── skill.yaml │ ├── prompt.md │ └── handler.pyskill.yaml里声明这个 Skill 依赖哪些 MCP 工具编排层加载时先检查依赖是否满足不满足就报错避免运行到一半才发现工具缺失。这个“启动时校验”的机制能省掉大量运行时排查的时间。提示Skills 的提示词模板里尽量用内网环境里真实存在的路径、服务名、字段名做示例。模型看到具体的例子调用准确率会明显提升。4. 完整实操流程与关键环节4.1 环境准备把依赖“搬”进内网这一步是整个工程里最枯燥但最关键的。我的标准流程是在外网准备一台“打包机”配置和内网目标机器尽量一致操作系统版本、Python 版本、架构然后在打包机上把所有依赖下载好。具体操作分三步。第一步收集依赖清单。把编排层、MCP Server、Skills 用到的所有 Python 包、系统库、模型文件列出来。第二步下载。Python 包用pip download -r requirements.txt -d ./wheels系统库用对应的包管理器下载离线包。第三步校验和导入。所有文件算一遍哈希记录在清单里导入内网后逐一校验。这里有个细节注意平台差异。如果打包机是 x86 而内网机器是 ARM下载的 wheel 包可能不兼容。所以打包机的架构必须和目标机一致。我吃过这个亏下载了一堆 x86 的包到 ARM 机器上全废了只能重来。4.2 编排层配置让 Agent 认识内网编排层的配置核心是两件事模型 endpoint 指向内网模型服务工具列表指向内网 MCP Server。以常见的配置方式为例model: provider: openai_compatible base_url: http://10.0.1.20:8000/v1 model_name: internal-agent-model api_key: internal-dummy-key mcp_servers: - name: internal-kb url: http://10.0.1.21:9000/sse - name: code-tools url: http://10.0.1.22:9001/sse skills_dir: /opt/agent/skillsapi_key这里填个占位符就行内网模型服务一般不校验但有些框架要求这个字段非空。base_url用内网 IP不要用域名避免 DNS 解析问题。配置好之后先做一次“连通性自检”编排层能不能连上模型服务、能不能连上每个 MCP Server、Skills 目录能不能读到。我一般会写一个自检脚本启动时自动跑一遍任何一项失败就明确报错。这个习惯能省掉大量“启动成功但一调用就挂”的问题。4.3 端到端联调从一句话到一次工具调用联调阶段我建议从最简单的场景开始逐步加复杂度。第一步只测模型对话确认模型能正常回复。第二步加一个最简单的 MCP 工具比如“获取当前时间”确认工具调用链路通。第三步加一个真实业务工具比如“查询订单”确认参数传递和结果解析正确。第四步加 Skill确认 Skill 能正确组合多个工具。每一步都要看日志。Agent 工程的日志要打得足够细模型请求和响应、工具调用的入参和出参、Skill 的执行步骤全都要记录。内网环境排查问题本来就难日志是你唯一的眼睛。我一般会把日志级别调到 DEBUG联调通过后再调回 INFO。联调时有个常见现象模型“幻觉”出一个不存在的工具名。这通常是因为工具描述不够清晰或者工具太多导致模型混淆。解决办法是精简工具列表把不常用的工具收起来只暴露当前任务需要的。工具不是越多越好这一点在内网小模型上尤其明显。4.4 性能与并发内网 Agent 怎么扛住压力热词里有人问“AI Agent 怎么扛并发”这个问题在内网环境里更尖锐因为内网硬件资源通常有限。我的经验是瓶颈几乎永远在模型推理这一层不在编排层。扛并发的核心手段有三个。第一是请求队列 限流编排层不要无限制地把请求打到模型服务要有个队列超过处理能力的请求排队等待。第二是模型服务批处理vLLM 这类框架支持 continuous batching能把多个请求合并成一批推理吞吐量能提升好几倍。第三是结果缓存对于重复性高的查询比如“查某个固定配置”把结果缓存起来直接返回。具体参数上我会根据模型服务的实际吞吐来设置编排层的并发上限。比如实测模型服务每秒能处理 5 个请求那编排层并发就设 5 到 8留一点缓冲。设太高只会让请求堆积响应时间反而更长。注意内网 Agent 的并发测试一定要用真实业务请求压不要用“你好”这种简单请求。简单请求和复杂请求的推理耗时可能差十倍用简单请求测出来的并发数没有参考价值。5. 常见问题与排查技巧实录5.1 依赖缺失类问题速查内网环境最高频的问题就是依赖缺失。下面这张表是我整理的高频问题和排查方法现象可能原因排查方法解决方式启动报 ModuleNotFoundErrorPython 包没装全对比 requirements 和已装列表补装缺失的 wheel 包报找不到 .so 文件系统库缺失ldd检查动态链接导入对应系统库模型加载失败权重文件损坏或版本不匹配校验哈希、看加载日志重新导入权重MCP 连接超时内网地址或端口不通curl测端口连通性检查防火墙和监听地址工具调用报参数错误工具声明和实现不一致对比 schema 和函数签名修正声明这张表里的每一条我都在实际项目里遇到过。特别是“找不到 .so 文件”这条最容易被忽略因为报错信息往往很隐晦得用ldd一层层查依赖。5.2 模型行为类问题排查模型层面的问题更微妙因为它不是“报错”而是“行为不符合预期”。常见的几种模型不调用工具、调用错误的工具、参数填错、回复格式不对。排查这类问题我的方法论是先看提示词再看工具描述最后看模型能力。提示词里有没有明确告诉模型“你有这些工具可用”工具描述够不够清楚如果前两个都没问题那可能是模型本身能力不够考虑换更大的模型或者做微调。有个实用技巧把模型的完整输入包括系统提示词、工具列表、对话历史打印出来人工读一遍。很多时候问题一眼就能看出来——比如工具列表里有个工具的描述写错了或者系统提示词里有个矛盾的指令。这个“人工读输入”的习惯帮我解决过至少一半的模型行为问题。5.3 内网特有的坑与避坑经验内网环境有几个特有的坑公网开发时根本遇不到。第一个是时间同步。内网机器如果时间不同步会导致 token 过期、日志时间错乱、缓存失效。上线前一定要确认所有机器都配了内网 NTP 服务。第二个是磁盘空间。模型文件动辄几十 G日志文件也会快速增长内网机器磁盘满了之后各种诡异问题都会出现。我的做法是给模型和日志单独挂盘设置日志轮转定期清理。第三个是网络策略变更。内网的防火墙策略经常由网络团队统一管理你今天调通的端口明天可能就被封了。所以关键服务的端口要提前报备写进网络策略文档不要用临时端口。第四个是证书问题。如果内网服务用了自签证书Agent 框架默认会校验失败。要么把自签 CA 导入信任链要么在框架配置里显式指定 CA 路径。不要图省事直接关校验那是个安全隐患。5.4 上线前的检查清单交付前我会跑一遍这个清单每一项都确认过才敢上线所有依赖已离线安装pip check无报错模型服务、MCP Server、编排层三者连通性自检通过所有 Skills 的依赖工具都存在且可用日志级别正确日志轮转已配置并发限流参数已按实测吞吐设置所有配置里没有公网地址、没有穿透工具残留时间同步、磁盘空间、证书信任链已确认关键端口已报备网络策略文档已更新这个清单看起来啰嗦但每一条背后都有一次真实的翻车经历。内网交付最怕的就是“上线后才发现”因为排查成本比开发阶段高得多。6. 一些个人体会做内网 Agent 工程这几年我最大的感受是难点从来不在 AI 本身而在工程。模型能力再强依赖装不上、端口不通、配置写错一样跑不起来。所以内网 Agent 工程师的核心竞争力其实是扎实的工程功底——会打包、懂网络、能排查、写得清文档。另一个体会是内网环境逼着你把每一层都理解透。公网开发时很多问题可以“换个库”“加个代理”绕过去内网里绕不过去你必须搞清楚这个依赖为什么缺、这个端口为什么不通、这个模型为什么这么回复。这种“被迫深入”的过程反而让我对 Agent 工程的理解比在公网环境里更扎实。最后分享一个小技巧在内网里维护一个“踩坑记录”文档每次遇到问题、解决之后把现象、原因、解决方法记下来。内网环境的问题往往有重复性今天踩的坑下个项目很可能再踩一次。这个文档积累到几十条之后就成了团队最值钱的资产。我现在带新人第一件事就是让他读这份文档比任何教程都管用。