1. 为什么要在隔离内网里折腾 AI Agent先把场景说清楚。所谓“隔离内网”就是那种物理上跟公网断开、或者只允许极少数白名单流量进出的网络环境。银行核心机房、制造业的工控网、政企的办公专网、医院的 HIS 系统内网基本都是这个形态。这类环境有个共同特点数据出不去外部服务进不来。而市面上绝大多数 AI Agent 的教程、框架、工具链默认前提都是“你能随时调用云端大模型 API”。这两件事天然冲突。我在过去一年里前后在三个不同规模的隔离内网环境里落地过 AI Agent 工程踩的坑足够写一本小册子。最核心的一条经验是在内网做 Agent难点从来不是“Agent 本身”而是“把 Agent 需要的一切能力搬进一个没有外网的世界里”。模型要本地化、工具要本地化、依赖要离线打包、审批流程要重新设计、日志和审计要满足合规要求。任何一环没考虑到项目就会卡在半路。这篇内容适合三类人看第一类是被派去内网做 AI 落地的工程师手里有任务但不知道从哪下手第二类是已经在外网玩过 LangChain、MCP、各种 Agent 框架想把这套东西搬进内网的开发者第三类是技术负责人需要评估内网 Agent 工程的可行性和工作量。我会把整个工程拆成设计思路、核心细节、实操过程、问题排查四大块尽量把每一步的“为什么”讲透而不是只给一堆命令让你抄。需要提前说明的是内网环境千差万别有的允许内网自建模型服务有的连 GPU 都没有只能用 CPU 推理有的审批流程要走三层。所以下面的方案是一个可裁剪的参考框架你根据自己的环境删减。但凡涉及具体参数的地方我都会给出计算过程或者选择理由方便你按需调整。2. 内网 AI Agent 的整体架构设计思路2.1 外网方案为什么直接搬进来会翻车外网做 Agent典型链路是这样的用户输入 → 编排框架LangChain / LlamaIndex / 自研→ 调用云端 LLM API → LLM 决定调用某个工具 → 工具执行可能是搜索、可能是数据库查询、可能是某个 SaaS 接口→ 结果回填 → LLM 生成最终回答。整条链路里LLM 和工具这两块几乎都依赖公网。搬进内网第一个断点就是 LLM。云端 API 调不通你必须换成内网自部署的模型服务。第二个断点是工具。外网 Agent 最爱用的搜索、网页抓取、第三方 API在内网全部失效你得换成内网能访问的数据源。第三个断点是依赖管理。pip install、npm install 这些命令在内网直接超时所有依赖必须提前离线打包。第四个断点是可观测性。外网可以随便接 LangSmith、Langfuse 云端版内网只能自建。我见过太多团队第一步就栽在依赖上兴冲冲写了 200 行 Agent 代码结果pip install langchain卡了半小时最后发现内网 pip 源根本没配。所以架构设计的第一原则是先盘点资源再设计架构最后写代码。顺序反了返工成本极高。2.2 分层架构把“能变的”和“不能变的”分开我最终稳定下来的架构是四层从下往上依次是模型服务层、能力接入层、Agent 编排层、交互与审批层。这个分层的核心逻辑是“隔离变化”——内网环境里模型可能换、工具可能增删、审批流程可能调整分层之后每一层的改动不会污染其他层。模型服务层负责把本地大模型跑起来对外暴露一个 OpenAI 兼容的 HTTP 接口。为什么强调“OpenAI 兼容”因为这样上层的编排框架几乎不用改代码只要把 base_url 从云端地址换成内网地址就行。这一层可以用 vLLM、TGI、Ollama、Xinference 等方案选哪个取决于你的硬件和并发需求。能力接入层是内网 Agent 的灵魂对应外网语境里的 MCPModel Context Protocol和各种 tool。它的职责是把内网里所有“Agent 可能需要调用的能力”统一封装成标准接口数据库查询、文件检索、内部 API 调用、代码执行沙箱等等。这一层做得好不好直接决定 Agent 能不能真正干活。Agent 编排层是大脑负责意图理解、任务拆解、工具选择、多轮对话管理。这一层可以用现成框架也可以自研。内网环境下我倾向于“框架打底 关键逻辑自研”因为现成框架的很多默认行为比如自动联网、自动上报在内网是负担。交互与审批层是最容易被忽视但最要命的一层。内网 Agent 一旦要执行“有副作用”的操作——比如改数据库、发消息、提交工单——就必须过审批。这一层要处理权限校验、操作确认、审计留痕。2.3 关键选型模型、框架、协议怎么定模型选型上内网环境优先考虑参数量适中、中文能力强、支持工具调用function calling的模型。7B 到 14B 这个区间是甜点区再大对显存要求陡增再小工具调用准确率会明显下降。如果内网有 A100/H800 这类卡可以上 32B 甚至 72B如果只有消费级显卡或者纯 CPU那就老老实实 7B 量化版。这里有个经验值工具调用场景下模型对 JSON 格式的遵循能力比它的“聪明程度”更重要。一个 7B 但格式遵循极好的模型实际表现往往优于 14B 但经常输出多余文字的模型。框架选型上LangChain 生态最全但依赖最重离线打包最麻烦LlamaIndex 相对轻量如果团队有能力我其实推荐核心编排逻辑自研只借用少量工具库。原因很简单内网环境调试困难框架越厚出问题时你越难定位到底是框架的锅还是模型的锅。自研一个几百行的 ReAct 循环可控性远高于套一个几万行的框架。协议层面MCP 这两年被讨论得很多它的价值在于把“工具”标准化。在内网里MCP 的思路特别适用你不可能为每个 Agent 单独写一套工具调用代码但你可以让所有工具都实现同一个协议Agent 端只认协议不认具体工具。这样新增一个内网能力比如接入禅道、接入内部知识库只要实现一个 MCP server所有 Agent 立刻就能用。3. 核心细节解析与实操要点3.1 模型服务本地化从显存计算到接口暴露先算显存。以 7B 模型 FP16 为例权重占用约 14GB加上 KV Cache 和推理框架开销实际需要 18-20GB 显存。如果做 4bit 量化权重降到约 4GB8GB 显存的卡就能跑。14B FP16 约 28GB需要 A100 40G 或双卡14B 4bit 约 8GB单张 3090/4090 够用。这个计算是选型的基础先看内网有什么卡再决定上多大模型不要反过来。部署工具上vLLM 的吞吐最好适合多人并发Ollama 最省心适合单机快速验证Xinference 支持多模型管理适合需要同时跑多个模型的场景。内网部署时有个细节模型权重文件要提前下载好通过离线介质拷进去。很多团队卡在这一步因为模型动辄十几 GB传输和校验都要时间。接口暴露这块务必开启 OpenAI 兼容模式。vLLM 加--served-model-name参数Ollama 默认就兼容。暴露出来的地址类似http://内网IP:8000/v1上层代码里把openai.base_url指过去即可。这里有个坑内网如果有多台机器要注意模型服务的并发上限vLLM 默认的--max-num-seqs可能不够需要根据实际并发调大否则请求会排队甚至超时。3.2 能力接入层用 MCP 思路统一内网工具内网 Agent 能调用的工具通常有这么几类数据库查询、内部文档检索、内部 API 调用、代码执行、消息发送。每一类都要封装成标准接口。我以数据库查询为例讲一下封装要点。一个合格的数据库查询工具输入应该是自然语言或者结构化查询意图输出是查询结果。中间要处理SQL 生成、SQL 安全校验防止 DROP/DELETE、结果行数限制、超时控制。SQL 安全校验是重中之重内网 Agent 一旦误删数据后果不堪设想。我的做法是维护一个白名单只允许 SELECT且必须带 LIMIT超过行数直接截断。文档检索工具的核心是向量化 检索。内网没有云端 embedding 服务你得本地跑一个 embedding 模型比如 bge 系列。文档要先切分、向量化、存入本地向量库Milvus、Qdrant、Chroma 都行内网推荐 Chroma 因为部署最简单。检索时把用户问题向量化做相似度匹配返回 top-k 片段。内部 API 调用工具要处理鉴权和参数映射。内网 API 通常有自己的鉴权方式token、签名、证书Agent 不应该直接持有这些凭证而应该通过一个中间层代理。这个中间层负责注入鉴权信息、做参数校验、记录调用日志。代码执行工具风险最高强烈建议用容器隔离限制 CPU、内存、执行时间、网络访问。内网里跑代码执行最怕的是 Agent 生成一段死循环代码把机器拖垮。3.3 审批机制让 Agent 的“手”受控内网 Agent 和玩具 Agent 最大的区别就是它真的会动手。动手之前必须过审批。审批机制的设计要点有三个分级、可追溯、可回滚。分级是指按操作风险分等级。查询类操作可以自动放行写入类操作需要人工确认删除类、批量类操作需要二次确认甚至多人审批。这个分级要写进 Agent 的决策逻辑里不能靠事后补救。可追溯是指每一次工具调用都要留痕谁发起的、调用了什么工具、参数是什么、结果是什么、谁审批的。这些日志要存到内网数据库方便审计。可回滚是指高风险操作要有回滚方案。比如批量更新数据前先备份发消息前先存草稿。Agent 出错是常态关键是出错后能快速恢复。实操上我通常会在 Agent 编排层和工具执行层之间插一个审批网关。Agent 决定调用某个工具时请求先到网关网关根据预设规则判断是否需要审批。需要审批的挂起任务推送给审批人审批通过后网关再真正调用工具。这个网关是整个内网 Agent 工程里最不能省的一环。4. 实操过程与核心环节实现4.1 环境准备离线依赖打包的完整流程内网部署第一步永远是依赖。我的标准流程是在外网准备一台同架构、同操作系统的机器把所有依赖装好然后整体打包。Python 项目用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就得下源码包内网编译时还要保证编译工具链齐全。Node 项目用npm pack或者直接把node_modules打包。更稳妥的做法是用npm ci在离线环境重建但前提是 npm 缓存目录也一起打包。系统级依赖比如某些 C 库最麻烦建议用 Docker 镜像整体打包。把整个运行环境做成镜像导出成 tar 文件拷进内网后docker load这是最省心的方案。镜像里预装好 Python、Node、模型推理框架、向量库内网机器直接跑容器。4.2 Agent 编排核心一个可运行的最小实现下面给一个内网 Agent 的最小可运行骨架用 Python 写核心是一个 ReAct 循环。这个实现不依赖任何重型框架方便内网调试。import json import requests LLM_BASE http://内网模型服务IP:8000/v1 LLM_KEY 内网自定义key def call_llm(messages, tools): resp requests.post( f{LLM_BASE}/chat/completions, headers{Authorization: fBearer {LLM_KEY}}, json{ model: local-model, messages: messages, tools: tools, tool_choice: auto, temperature: 0.1 }, timeout60 ) return resp.json()[choices][0][message] def run_agent(user_input, tools, tool_map, max_steps8): messages [ {role: system, content: 你是内网助手只能使用提供的工具禁止编造工具。}, {role: user, content: user_input} ] for step in range(max_steps): msg call_llm(messages, tools) messages.append(msg) if not msg.get(tool_calls): return msg[content] for call in msg[tool_calls]: name call[function][name] args json.loads(call[function][arguments]) # 审批网关拦截 if need_approval(name, args): approved request_approval(name, args) if not approved: result 操作被审批人拒绝 else: result tool_map[name](**args) else: result tool_map[name](**args) messages.append({ role: tool, tool_call_id: call[id], content: str(result) }) return 达到最大步数任务未完成这段代码有几个关键点。temperature设成 0.1因为工具调用场景需要稳定输出不需要创造力。max_steps限制 8 步防止 Agent 陷入死循环。审批网关插在工具执行前这是内网场景的硬性要求。tool_choice设成 auto让模型自己决定是否调用工具。4.3 工具注册与 MCP 风格封装工具的定义要遵循 OpenAI function calling 的 schema。以数据库查询为例db_tool { type: function, function: { name: query_database, description: 查询内网业务数据库仅支持SELECT语句, parameters: { type: object, properties: { sql: {type: string, description: SELECT查询语句必须带LIMIT}, database: {type: string, enum: [order_db, user_db]} }, required: [sql, database] } } }description写得越清楚模型调用越准确。我踩过的坑是description 太模糊模型会瞎猜参数enum 不写模型会传不存在的库名。工具 schema 的严谨程度直接决定 Agent 的可靠性。如果要走 MCP 路线就把每个工具封装成一个独立的 MCP server通过 stdio 或者 SSE 通信。MCP 的好处是工具和 Agent 解耦新增工具不用改 Agent 代码。内网里我推荐用 stdio 模式因为不涉及网络端口部署更简单。4.4 审批网关的实现细节审批网关的核心是一张规则表操作类型风险等级审批方式超时处理只读查询低自动放行不适用单条写入中单人确认5分钟超时拒绝批量写入高双人确认10分钟超时拒绝删除操作极高双人确认备份15分钟超时拒绝消息发送中单人确认5分钟超时拒绝规则表要可配置因为不同内网的合规要求不一样。审批推送可以走内网 IM比如内网部署的即时通讯工具或者邮件。审批结果要写回任务上下文Agent 根据结果决定下一步。这里有个实操心得审批超时默认拒绝而不是默认通过。内网场景下宁可任务失败也不能让未审批的操作溜过去。5. 常见问题与排查技巧实录5.1 模型输出格式错乱怎么办这是内网 Agent 最高频的问题。表现是模型该输出 JSON 的时候输出一堆解释文字或者 JSON 缺字段、多字段。排查思路分三步。第一步确认模型本身是否支持 function calling。有些模型虽然能对话但没经过工具调用训练输出格式全靠 prompt 约束稳定性很差。这种情况要么换模型要么用更严格的 prompt 输出解析兜底。第二步检查 prompt 是否给了足够约束。system prompt 里要明确写“只输出 JSON”“不要输出解释”“字段必须完整”。我通常还会在 prompt 里给一个 few-shot 示例效果比纯文字描述好很多。第三步加输出解析兜底。即使模型输出格式错乱解析层也要能容错用正则提取 JSON 片段、缺字段给默认值、解析失败重试一次。永远不要假设模型输出是完美的这是内网 Agent 工程的基本心态。5.2 工具调用准确率低怎么优化工具调用准确率低通常有三个原因工具太多、描述不清、模型能力不足。工具太多是最常见的。一个 Agent 挂 20 个工具模型选择困难。解决办法是分组把工具按领域分组先让模型选组再在组内选工具。或者用路由机制根据用户意图先路由到特定工具集。描述不清是第二常见。工具的 description 要写清楚“什么时候用”“什么时候不用”“参数含义”。我见过一个工具描述只写了“查询数据”模型根本不知道查什么数据、什么时候该查。模型能力不足是硬伤。如果前两个都优化了还是不行那就是模型太小。这时候要么换大模型要么降低任务复杂度把一个大任务拆成多个小任务。5.3 内网部署的典型故障速查故障现象可能原因排查方法模型服务启动失败显存不足/权重损坏看日志检查 nvidia-smi校验权重 md5请求超时并发过高/模型太大调大 timeout降低并发换小模型依赖安装失败离线包不完整/架构不匹配检查 wheel 平台标签补下缺失包工具调用无响应网络不通/鉴权失败telnet 端口检查 token 有效期审批卡住审批人不在/推送失败检查 IM 通道设置超时兜底日志丢失磁盘满/权限不足检查磁盘确认日志目录可写这张表是我实际运维中总结的覆盖了 80% 的常见故障。建议内网部署时把这张表打印出来贴在工位上。5.4 几个只有踩过才知道的坑第一个坑内网时间不同步。模型服务、Agent 服务、数据库如果时间不一致日志对不上排查问题时会疯掉。部署前务必确认所有机器 NTP 同步。第二个坑模型服务的健康检查。内网没有云端的自动重启机制模型服务挂了没人知道。要自己写一个健康检查脚本定时探测挂了就告警。第三个坑向量库的持久化。Chroma 默认是内存模式重启数据就没了。内网部署一定要配置持久化目录否则每次重启都要重新灌数据。第四个坑审批日志的存储。审批记录是合规审计的关键证据不能只存内存。要落库且要定期备份。第五个坑模型版本管理。内网换模型不像外网那么方便换之前要评估影响面。建议模型文件按版本号命名保留旧版本方便回滚。6. 内网 Agent 工程的扩展方向跑通最小闭环之后可以往几个方向扩展。多 Agent 协作是一个方向把复杂任务拆给多个专职 Agent比如一个负责检索、一个负责分析、一个负责执行通过消息队列协调。内网里做多 Agent通信可以用 Redis 或者内网 MQ。知识库持续更新是另一个方向。内网文档会变向量库要能增量更新。可以做一个定时任务扫描文档目录发现新文件就自动切分、向量化、入库。Agent 效果评估也很重要。内网没有现成的评估平台要自己搭。我的做法是维护一个测试集每次模型或 prompt 变更后跑一遍看工具调用准确率、任务完成率、平均步数这几个指标。与内网现有系统集成是最终目标。Agent 不应该是一个孤立的玩具而要嵌入到内网的工作流里接入工单系统、接入监控告警、接入内部 IM。集成的深度决定了 Agent 的实际价值。我个人在实际操作中的体会是内网 Agent 工程 70% 的工作量在“环境适配”和“安全合规”只有 30% 在“Agent 本身”。很多团队一开始把精力全放在调模型上结果卡在依赖打包和审批流程上。先把地基打牢再盖楼这个顺序在内网环境里尤其重要。另外别追求一步到位先跑通一个只读查询的最小闭环让业务方看到价值再逐步扩展到写入和审批这样推进阻力最小。