1. 为什么要在隔离内网里折腾 AI Agent先把场景说清楚。所谓“隔离内网”就是那种物理上跟公网断开、或者只允许极少数白名单流量出入的办公网、研发网、生产网。很多做金融、制造、政企项目的团队代码仓库、数据库、CI 流水线全在这张网里开发机连不上外网npm、pip、docker hub 一律不通。在这种环境下谈 AI Agent 工程化跟在公网环境里完全是两码事。我在过去一年里前后在三个不同的隔离内网环境里落地过 AI Agent 相关的工具链踩的坑足够写一本小册子。核心矛盾其实就一句话AI Agent 的生态默认你是联网的而内网默认你是断网的。模型要下载、依赖要拉取、MCP Server 要连外部服务、Skills 要从市场同步——这些在公网里一行命令搞定的事到了内网全得手动搬砖。所以这篇东西不是讲“AI Agent 是什么”而是讲当你被关在一张没有外网的内网里怎么把一套能用的 AI Agent 工程体系搭起来。涉及的关键词包括 AI Agent、MCP、Skills、内网、工程实战我会围绕这几个点把方案选型、依赖搬运、MCP 协议在内网的适配、Skills 的本地化管理、并发与资源控制这些实打实的问题拆开讲。适合谁看三类人一是在内网环境做研发、被网络限制卡住的工程师二是想把 AI Agent 引入团队但发现处处碰壁的技术负责人三是单纯好奇“断网了 AI 还能不能干活”的折腾党。不管你是哪种只要你的机器连不上外网这篇里的思路和步骤都能直接抄。先给一个整体判断内网 AI Agent 工程的核心不是模型多强而是依赖治理和协议适配。模型可以提前下好放本地但 MCP 的连接、Skills 的加载、工具链的调用这些动态行为才是真正难搞的地方。下面我按“整体设计 → 核心细节 → 实操落地 → 问题排查”的顺序展开。2. 内网 AI Agent 的整体设计与方案选型2.1 先想清楚内网 Agent 到底要解决什么问题很多人一上来就问“内网能用哪个模型”这其实是把问题想窄了。模型只是 Agent 的一个组件真正决定你能不能跑起来的是工具调用链路。一个典型的 AI Agent 工作流是这样的用户输入 → 模型推理 → 决定调用某个工具 → 工具执行 → 结果回传模型 → 生成最终回答。在内网里这条链路上每一环都可能断。我一般会先把需求拆成三层来看。第一层是推理层也就是模型本身这个相对好解决提前把模型权重下好、用本地推理框架跑起来就行。第二层是工具层包括文件操作、代码执行、数据库查询这些内网里反而比公网更安全因为不用担心数据外泄。第三层是协议层也就是 MCP 这类把模型和工具连起来的协议这一层是内网环境里最容易出问题的地方因为 MCP 的设计初衷是连接外部服务。想清楚这三层方案选型就有方向了。推理层选本地部署工具层选内网自建协议层要么改造 MCP 让它走本地要么干脆用更轻量的自定义协议替代。我见过太多团队一上来就照搬公网那套 MCP 全家桶结果卡在连接外部 Server 这一步白白浪费两周。2.2 模型选型内网里能跑什么该跑什么内网部署模型第一个约束是硬件。你得先摸清楚手上有多少张卡、显存多大。我一般按显存分档单卡 24G 以下老老实实跑 7B 到 14B 的量化模型单卡 48G 到 80G可以上 32B 级别的模型多卡集群才有资格谈 70B 以上。别信那些“消费级显卡跑 70B”的教程量化到 4bit 之后效果掉得厉害Agent 场景对指令遵循要求高掉一点就全乱套。第二个约束是模型的工具调用能力。不是所有模型都擅长 function calling。我实测下来Qwen 系列、DeepSeek 系列在工具调用上的表现比较稳指令遵循也扎实。选模型的时候一定要看它有没有专门的 tool use 微调版本这个比参数量重要得多。一个 14B 的工具调用专用模型在 Agent 场景里往往比一个 70B 的通用模型更好用。第三个约束是推理框架。内网里我推荐用 vLLM 或者 SGLang这两个对 OpenAI 兼容接口支持好Agent 框架接起来省事。如果显存实在紧张llama.cpp 也能凑合但并发能力差只适合个人用。这里有个细节推理框架的版本要和模型格式匹配我踩过一次坑模型是 GPTQ 量化的结果装了个只支持 AWQ 的框架版本折腾半天才发现。提示内网部署模型前务必在公网环境里把模型跑通、把接口调通再整体搬到内网。内网里调试模型加载问题成本是公网的十倍。2.3 MCP 协议在内网的适配思路MCP 是这两年 Agent 领域最热的东西全称是 Model Context Protocol本质是一套让模型和外部工具、数据源通信的标准协议。它的架构是 Client-Server 模式Agent 作为 Client工具作为 Server通过标准化的消息格式交互。公网环境下你可以直接连各种现成的 MCP Server比如连 Figma、连蓝湖、连各种 SaaS 服务。但内网里这套玩不转因为大部分 MCP Server 都是要连外网的。我的适配思路有三条。第一条是本地化 MCP Server把需要的 MCP Server 源码拉下来改造成连内网服务的版本比如把连外部数据库的改成连内网数据库。第二条是自建 MCP 网关在内网里起一个统一的 MCP 服务端把内网的各种工具封装成 MCP 接口Agent 只连这一个网关。第三条是降级方案如果 MCP 实在搞不定就用最原始的函数调用把工具定义直接写进 Agent 的 prompt 里。我个人最推荐第二条自建 MCP 网关。原因很简单内网的工具是有限的、可控的与其让每个 Agent 去连一堆 Server不如集中管理。网关这一层还能做权限控制、日志审计、限流这些在内网环境里都是刚需。具体怎么搭后面实操部分细讲。2.4 Skills 的本地化管理策略Skills 这个概念最近很火Claude 的 Agent Skills、Codex 的 Skills本质都是把一组相关的工具调用、提示词、知识打包成一个可复用的模块。公网环境下你可以从官方市场直接装一行命令的事。内网里没有市场只能手动管理。我的做法是建一个内网 Skills 仓库用 Git 管理。每个 Skill 是一个独立目录里面放三样东西一份skill.yaml描述元信息名称、版本、依赖、触发条件一份prompt.md放提示词模板一份tools/目录放这个 Skill 用到的工具定义或脚本。这样做的最大好处是版本可控、可审计、可回滚。内网环境最怕的就是“这个 Skill 是谁改的、改了什么”用 Git 管理一目了然。Skills 的加载策略也要设计。我一般分两级常驻 Skills和按需 Skills。常驻的比如文件操作、代码执行Agent 启动就加载按需的比如某个特定业务查询等用户提到相关关键词再动态加载。这样能控制上下文长度避免一上来就把所有 Skill 的描述塞进 prompt把模型的注意力稀释掉。3. 核心细节解析与实操要点3.1 依赖搬运内网工程的第一个拦路虎内网开发最烦的就是装依赖。pip、npm、maven、docker全都要手动搬。我总结了一套“三件套”搬运法实测下来最稳。第一件套是离线包制作。在公网机器上用pip download把依赖下成 whl 包用npm pack把 node 包下成 tgz用docker save把镜像存成 tar。这里有个关键点要下全平台的包。比如 pip 依赖如果内网机器是 ARM 架构你在 x86 上下的包可能装不上得加--platform参数指定。我踩过这个坑搬了一堆包过去发现架构不对全部重来。第二件套是私有源搭建。内网里起一个 pip 源用 devpi 或 pypiserver、一个 npm 源用 verdaccio、一个 docker registry用 registry:2。把离线包传上去内网机器直接从这个源装。这样比一个个手动装包高效得多而且能解决依赖嵌套的问题——A 依赖 BB 依赖 C手动装能把你逼疯。第三件套是依赖清单固化。用pip freeze、npm ls把最终依赖树导出成文件跟代码一起进 Git。内网环境里依赖版本漂移是灾难今天能跑的代码明天可能就跑不起来。固化清单之后任何人拿到代码都能复现出一样的环境。注意搬运依赖时一定要记录系统级依赖比如某些 Python 包需要libpq-dev、gcc这些系统库。光搬 pip 包不够系统库缺失照样装不上。我一般会写一个setup.sh把 apt 或 yum 的安装命令也列进去。3.2 MCP Server 的内网改造实操前面说了自建 MCP 网关的思路这里讲具体怎么改。假设你有一个现成的 MCP Server它原本是连外部 API 的现在要改成连内网服务。第一步是读源码找连接点。MCP Server 一般会有一个配置文件或者环境变量指定它连的目标地址。找到这个点把它改成内网地址。比如原本连https://api.example.com改成http://internal-service:8080。第二步是处理认证。公网服务的认证一般是 API Key 或者 OAuth内网服务可能是简单的 Token 或者干脆没有认证。这里要注意不要把公网的认证逻辑硬套到内网内网的安全边界不一样过度设计反而增加复杂度。第三步是测试协议兼容性。MCP 协议本身是标准化的但不同 Server 的实现可能有差异。改完之后用 MCP 官方的测试工具或者自己写个 Client 脚本把每个工具都调一遍确认返回格式正确。我一般会写一个test_mcp.py把所有工具列出来逐个测跑通了再接入 Agent。第四步是加日志和监控。内网环境出问题不好排查MCP Server 这一层一定要打详细日志记录每次调用的入参、出参、耗时。这些日志在排查 Agent 行为异常时是救命稻草。3.3 Skills 的开发规范与测试方法Skills 开发最容易犯的错是写得太随意。公网环境下Skill 写错了顶多不生效内网里可能引发连锁问题。我定了一套规范团队里强制执行。规范一每个 Skill 必须有明确的触发条件。不能写“当用户需要时触发”要写“当用户输入包含‘查询订单’且提供了订单号时触发”。触发条件越明确Agent 的决策越稳定。规范二每个 Skill 必须有输入输出契约。输入是什么格式、输出是什么格式写死在skill.yaml里。Agent 调用时按契约传参工具返回时按契约解析。这样即使模型抽风也不会传进来乱七八糟的东西。规范三每个 Skill 必须有测试用例。我一般要求至少三个用例正常输入、边界输入、异常输入。测试用例放在tests/目录用 pytest 或者 jest 跑。内网里没有 CI 的话就写个脚本手动跑但一定要跑。规范四Skill 之间不能有隐式依赖。A Skill 不能假设 B Skill 已经执行过。所有依赖都要显式声明在skill.yaml里由加载器负责按顺序加载。这个规范能避免很多“单独测没问题、一起跑就崩”的问题。3.4 并发控制Agent 扛并发的关键“AI Agent 怎么扛并发”是个高频问题。内网环境里并发问题比公网更突出因为资源是固定的没有弹性扩容这一说。我的经验是分三层控制。第一层是模型推理层用推理框架自带的并发控制。vLLM 有--max-num-seqs参数控制同时处理的请求数。这个值设太大显存爆设太小吞吐上不去。我一般按显存的 70% 来估算留 30% 余量。第二层是Agent 调度层用队列控制。所有请求先进队列Agent 从队列里取任务执行。队列长度要设上限超过就拒绝或者排队避免雪崩。这里可以用 Redis 或者简单的内存队列内网里我倾向用内存队列少一个依赖少一个故障点。第三层是工具调用层用信号量控制。每个工具能同时处理多少请求要有限制。比如数据库查询工具同时开 100 个连接肯定把数据库打挂得限制到 10 个。这一层用信号量或者连接池实现。三层控制叠加起来一个内网 Agent 服务大概能扛住几十到上百的并发具体看硬件。别指望内网 Agent 能扛几千并发那不是它的定位。4. 完整实操流程与核心环节实现4.1 环境准备从零搭建内网 Agent 运行环境假设你拿到一台全新的内网机器什么都没有怎么从零搭起来。我按顺序列一遍。第一步确认系统信息。uname -a看架构nvidia-smi看显卡df -h看磁盘free -h看内存。这些信息决定了后面所有选型。我见过有人没看架构就下包结果 x86 的包往 ARM 机器上装白忙活。第二步装基础工具。Python、Node、Git、Docker这些是标配。内网里装这些也得用离线包提前在公网下好。Python 建议用 3.10 或 3.11太新的版本有些库还不支持太老的版本 Agent 框架不兼容。第三步搭私有源。按前面说的起 pip 源、npm 源、docker registry。这一步做完后面装依赖就顺了。第四步部署模型。把提前下好的模型权重传到内网用 vLLM 起服务。启动命令大概长这样python -m vllm.entrypoints.openai.api_server \ --model /path/to/model \ --served-model-name local-agent-model \ --max-num-seqs 32 \ --gpu-memory-utilization 0.7 \ --port 8000启动之后用 curl 测一下确认接口通。第五步部署 MCP 网关。把改造好的 MCP Server 起起来配置好内网工具的连接信息。网关的配置文件我一般放在/etc/mcp-gateway/config.yaml内容包括工具列表、连接地址、认证信息、限流参数。第六步部署 Agent 框架。选一个支持本地模型和 MCP 的框架配置好模型地址和 MCP 网关地址。启动之后跑一个冒烟测试问它一个简单问题看能不能正常回答、能不能调用工具。这六步走完一个最小可用的内网 Agent 环境就搭好了。整个过程顺利的话一天不顺利的话三天主要时间花在依赖搬运和问题排查上。4.2 模型部署的参数计算与调优模型部署这块参数设置直接决定能不能跑起来、跑得好不好。我拿一个具体例子算一遍。假设你有一张 48G 显存的卡要部署一个 32B 的模型4bit 量化。模型权重大小大概是 32B × 0.5 字节 16G。KV Cache 的大小取决于上下文长度和并发数公式是KV Cache 2 × 层数 × 隐藏维度 × 上下文长度 × 并发数 × 精度字节。以 32B 模型为例层数大概 64隐藏维度 5120上下文 8192并发 16精度 2 字节fp16算下来 KV Cache 大概是 2 × 64 × 5120 × 8192 × 16 × 2 ≈ 17G。加上权重 16G总共 33G48G 显存够用还能留 15G 余量。基于这个计算--gpu-memory-utilization设 0.7 比较稳--max-num-seqs设 16 到 32 之间。如果实际跑起来发现显存不够优先降并发数而不是降上下文长度因为 Agent 场景对上下文长度要求高截断了会丢信息。调优的时候关注两个指标首 token 延迟和吞吐量。首 token 延迟影响用户体验吞吐量影响并发能力。这两个指标往往互相矛盾并发开大了首 token 延迟就高。我的经验是内网 Agent 场景优先保首 token 延迟因为用户等的是响应速度不是极限吞吐。4.3 MCP 网关的配置与工具注册MCP 网关是整个内网 Agent 的核心枢纽配置得好不好直接决定 Agent 好不好用。我拿一个实际配置举例。gateway: listen: 0.0.0.0:9000 auth: type: token tokens: - name: agent-client value: internal-token-xxx tools: - name: query_database description: 查询内网业务数据库 endpoint: http://db-service:8080/query method: POST timeout: 30 rate_limit: 10 params: - name: sql type: string required: true description: SQL 查询语句仅允许 SELECT - name: read_file description: 读取内网共享目录文件 endpoint: http://file-service:8080/read method: GET timeout: 10 rate_limit: 50 params: - name: path type: string required: true description: 文件路径必须在 /shared 目录下这个配置里每个工具都定义了名称、描述、端点、超时、限流、参数。描述很重要模型是根据描述来决定调不调这个工具的描述写得清楚模型决策就准。参数里的description也一样模型靠它来填参数。工具注册完之后要写一个工具发现接口让 Agent 能动态获取工具列表。MCP 协议里有tools/list方法网关实现这个方法返回所有工具的元信息。Agent 启动时调一次把工具列表缓存起来。提示工具描述里一定要写清楚使用场景和限制。比如“仅允许 SELECT”这种约束写在描述里模型会遵守不写模型可能给你来个 DELETE那就出大事了。4.4 Skills 的加载与执行流程Skills 的加载流程我设计成四步扫描 → 解析 → 注册 → 激活。扫描阶段遍历 Skills 仓库目录找到所有skill.yaml文件。解析阶段读取每个 yaml校验格式提取元信息。注册阶段把 Skill 的元信息注册到 Agent 的 Skill 注册表里包括名称、描述、触发条件、依赖。激活阶段根据当前对话上下文判断哪些 Skill 应该激活把激活的 Skill 的提示词和工具定义注入到 Agent 的上下文中。执行流程是Agent 决定调用某个 Skill → 从注册表里找到 Skill 定义 → 按契约准备参数 → 调用 Skill 对应的工具 → 解析返回结果 → 把结果回传给模型。这里的关键是参数校验模型给的参数不一定符合契约调用前一定要校验不符合就返回错误让模型重试。我一般会在 Skill 执行层加一个重试机制。模型第一次调用失败把错误信息回传让它重新生成参数。重试最多两次两次还不行就放弃返回错误给用户。这个机制能解决大部分参数格式问题。4.5 端到端联调从用户输入到工具执行环境搭好、模型跑起来、MCP 网关配好、Skills 加载完最后一步是端到端联调。我一般按这个顺序测。先测纯对话不涉及工具调用。问模型“你好”看它能不能正常回复。这一步确认模型推理链路通。再测单工具调用。问“帮我查一下订单表有多少条记录”看模型能不能识别出要调query_database工具能不能生成正确的 SQL能不能拿到结果并组织成自然语言回答。这一步确认 MCP 链路通。然后测多工具协作。问“读取 /shared/report.csv统计一下销售额总和”看模型能不能先调read_file再调query_database或者用代码执行工具处理 CSV能不能把多个工具的结果串起来。这一步确认 Agent 的规划能力。最后测异常处理。故意给一个不存在的文件路径看模型能不能识别错误、能不能重试、能不能给用户合理的提示。这一步确认系统的健壮性。联调过程中日志是关键。Agent 框架的日志、MCP 网关的日志、模型服务的日志三份日志对着看能快速定位问题出在哪一环。我一般会开一个终端专门 tail 日志边测边看。5. 常见问题与排查技巧实录5.1 模型加载失败显存、格式、版本三大坑模型加载失败是最常见的问题原因基本逃不出三个显存不够、格式不对、版本不匹配。显存不够的表现是加载到一半 OOM。排查方法是看加载日志确认是在加载权重阶段还是 KV Cache 阶段挂的。权重阶段挂说明模型太大得换更小的量化版本KV Cache 阶段挂说明并发或上下文设太大调小参数。格式不对的表现是加载时报“unsupported format”。排查方法是确认模型权重的量化格式是 GPTQ、AWQ 还是 GGUF然后确认推理框架支持哪种。我踩过一次坑模型是 AWQ 格式结果装了个只支持 GPTQ 的 vLLM 版本报错信息还很隐晦查了半天。版本不匹配的表现是加载成功但推理结果乱码。排查方法是确认模型和 tokenizer 的版本是否一致有时候模型更新了但 tokenizer 没更新就会出这种问题。解决方法是重新下载配套的 tokenizer。5.2 MCP 连接超时网络、认证、协议三层排查MCP 连接超时也是高频问题。我按三层排查。网络层ping一下目标地址telnet一下端口确认网络通。内网里经常是防火墙规则没开或者服务没起在预期端口上。认证层确认 Token 或证书是否正确。内网里认证信息经常是手动配的容易配错。我一般会写个脚本把认证信息单独测一遍。协议层确认 MCP 版本是否匹配。Client 和 Server 的 MCP 版本不一致会出现“连上了但握手失败”的情况。排查方法是看两边的日志对比协议版本号。5.3 Skills 不生效触发条件、加载顺序、上下文长度Skills 不生效先看触发条件。触发条件写得太宽泛模型可能忽略写得太严格模型可能匹配不上。我一般会加一个调试模式把当前激活的 Skills 列表打出来看看到底激活了没有。再看加载顺序。有依赖关系的 Skills加载顺序错了就会失败。排查方法是看加载日志确认依赖的 Skill 先加载了。最后看上下文长度。Skills 太多提示词太长超出模型的上下文窗口后面的 Skill 就被截断了。排查方法是算一下总 token 数超了就精简 Skill 描述或者改成按需加载。5.4 并发场景下的资源竞争与死锁并发一上来资源竞争和死锁就来了。我遇到过最典型的是数据库连接池耗尽。多个 Agent 同时调数据库工具连接池满了后面的请求全卡住。解决方法是给数据库工具加信号量限制同时调用的数量。还有文件锁竞争。多个 Agent 同时读写同一个文件出现读写冲突。解决方法是给文件操作加锁或者干脆让每个 Agent 操作独立的文件副本。死锁的排查比较麻烦我一般用py-spy或者gdbattach 到进程上看线程栈找到卡在哪把锁上。预防死锁的原则是统一加锁顺序所有地方都按同一个顺序获取锁就不会出现循环等待。5.5 常见问题速查表问题现象可能原因排查方法解决方案模型加载 OOM显存不足看加载日志定位阶段换小模型或调小并发推理结果乱码tokenizer 不匹配对比模型和 tokenizer 版本重新下载配套 tokenizerMCP 连接超时网络/认证/协议问题分层排查对应修复Skill 不生效触发条件/加载顺序/上下文开调试模式看激活列表调整条件或精简描述并发卡死资源竞争/死锁py-spy 看线程栈加信号量或统一锁顺序工具调用参数错误模型理解偏差看调用日志优化工具描述加重试这张表我贴在工位上出问题先对照一遍能解决八成常见故障。6. 内网 Agent 工程的几条实战心得最后分享几条踩坑踩出来的经验都是文档里不会写的。第一条内网环境里简单方案永远优于复杂方案。公网里你可以随便堆组件出问题了重启一下、扩容一下。内网里每个组件都是负担多一个组件多一个故障点。能用脚本解决的别上框架能用单机解决的别上分布式。第二条依赖版本一定要锁死。内网里没有“最新版”这个概念你装的是什么版本就一直是什么版本。所以第一次装的时候就要把版本号记下来写进依赖清单。我见过太多“上周还能跑这周就不行了”的案例全是版本漂移导致的。第三条日志要打够但别打太多。内网排查问题全靠日志但日志太多又会拖慢性能、占满磁盘。我的做法是分级打日志正常调用打 INFO异常打 ERROR调试信息打 DEBUG 且默认关闭。出问题了再开 DEBUG 复现。第四条Skills 要小而精不要大而全。一个 Skill 只干一件事干好一件事。大而全的 Skill 看起来省事实际上难维护、难测试、难复用。我一般要求单个 Skill 的代码不超过 200 行超过就拆。第五条定期做灾备演练。内网环境里机器挂了、服务崩了是常事。定期演练一下“模型服务挂了怎么办”“MCP 网关挂了怎么办”把恢复流程写成文档真出事了照着做不至于手忙脚乱。这套东西我在三个内网环境里跑下来最深的体会是内网 AI Agent 工程的难点不在 AI在工程。模型能力是现成的但把它塞进一个受限环境里稳定运行需要的是扎实的工程功底和对细节的把控。把依赖治理好、把协议适配好、把并发控制好剩下的就是水到渠成的事。