聊起 AI Agent大部分讨论开场都是 ReAct、Plan-and-Execute、多智能体协作这些概念但只要生产环境换到隔离内网第一刀就砍在这上面没有公网大模型 API没有模型在线下载没有包仓库连一个很基础的第三方服务都调不出来。隔离内网里的 AI Agent 工程实战玩儿的不是花哨的框架而是把模型、依赖、工具、记忆、可观测性全部改造成离线可闭环的状态并确保真能被业务用起来。这篇文章写的是我在隔离内网环境中落地一个 Agent 助手的全过程。团队里有前后端研发没有专门做大模型工程的同事很多方案是边踩坑边调整出来的。我会尽量把选型逻辑、部署细节、显存计算、工具调用设计这些关键环节讲清楚适合那些已经跑通 Demo、正准备在受控网络或离线生产环境里把 AI Agent 推向真实业务场景的开发者看。如果你恰好要在一个连外网都接触不到的机房或私有云里交付 Agent这篇文章应该能帮你省下好几天的排查时间。1. 隔离内网里的 AI Agent难点到底在哪1.1 隔离环境下 Agent 的核心矛盾先说结论隔离内网里做 AI Agent真正的难点不在“模型能力”而在“环境闭环”。一个 Agent 要和模型交互模型要推理工具要被调用记忆要存取知识库要检索。在公网环境下这些环节可以用现成的 SaaS 串起来一旦切到隔离内网每个环节都得找到本地替代品模型跑在哪、推理服务怎么起、Python 依赖从哪来、向量库连不上外网怎么办、工具系统要不要做成审批制全部变成实打实的工程问题。我见过不少团队在 Demo 阶段跑得很顺畅一到内网部署就卡住因为潜意识里还是把 Agent 当成“调 API 的脚本”。实际在隔离环境里Agent 更像一条流水线模型是发动机工具是机械臂知识库是图纸内网服务是传送带。任何一环断掉整条线就停摆。所以工程化的第一步是先把这条流水线的每一个环节拆出来分别确认离线可用。1.2 一次内网上线暴露出的四类问题我们第一次尝试把 Agent 部署到隔离环境时问题集中爆发在四个层面模型服务层是最先出问题的。本来想直接从外部模型仓库拉一个开源模型进来结果网络直接超时下载进度卡在 10% 就再也不动。后来改成内网文件服务器分发才把模型文件传进去。依赖环境层同样被低估。Agent 代码里用到了 Python 的一些常见库还有向量库客户端、解析 PDF 的库这些在公网 pip 一条命令就能装但隔离网里没有源报错信息一片红。最后只能把 wheel 包统一拷进去搭建私有源。工具调用层也翻车了。Agent 内部有一个函数用来查询工单系统但在隔离环境里工单系统的接口域名解析失败而且测试环境与正式环境的网络策略还不一致。我们最初根本没把“内网域名解析”当回事结果 Agent 频繁报“工具调用失败”。最后是知识库检索。原本计划用外网的模型服务生成 embedding断网之后这条路直接断了只能在内网单独部署 embedding 模型。加上文档格式五花八门PDF 扫描件、Word 表格、Excel 导出数据全都有离线解析和切分的成本一下子上来了。这四个问题让我意识到隔离内网下的 Agent 工程不是“算法问题”而是一整套围绕离线环境的系统工程。后面做的所有事其实就是在回答一个问题怎样让 Agent 在没有任何外部依赖的情况下稳定、可控、可维护地跑完一个业务闭环。2. 架构设计与模块选型先拆到能离线部署为止2.1 Agent 的五层模块怎么切我习惯把 Agent 拆成五个层模型服务层、模型网关层、Agent 运行时层、工具执行层、记忆与知识层。每个层在隔离环境里都有对应的替代方案下面这张表是我们最终落地时用的配置分层核心职责隔离内网推荐形态选型要点模型服务层提供推理能力vLLM、Ollama、llama.cpp 等本地推理服务与显存、并发量强相关优先考虑可量化的服务模型网关层统一模型接口做路由和降级自研 OpenAI 兼容网关或已有 API 网关改造避免 Agent 绑定单个推理引擎Agent 运行时层负责规划、调用工具、维护会话自研编排或 LangGraph、Dify 等可私有化方案必须支持离线部署不依赖云厂商托管服务工具执行层执行 Agent 选择的工具白名单脚本、内部 HTTP API、受限 SQL 查询必须收敛在受控范围内不能放一个万能接口记忆与知识层存储历史、提供检索增强Redis 做短记忆PostgreSQL 做长期记录向量库做知识检索embedding 模型也要内网部署没有捷径这里有一个容易忽略的点Agent 运行时层不一定要用很重的框架。业务规则如果简单用几段 Python 编排就够了但如果涉及复杂的工具切换、条件分支、用户多轮确认就需要一个可图形化或可配置的运行时。我们在隔离环境里最终选择了轻量自研方案配合少量 LangGraph 的离线逻辑主要原因是可控性更高也方便在团队内做代码评审。2.2 为什么一定要加模型网关我强烈建议在 Agent 和本地推理服务之间加一层模型网关。原因不复杂本地推理引擎本身是存在差异的vLLM 和 Ollama 的并发行为不同不同模型的工具调用能力也不同。如果 Agent 代码直接连某个推理服务后续换模型或调整推理引擎时改动会牵一发动全身。模型网关的核心作用是统一暴露一个 OpenAI 兼容接口Agent 只对接这一个地址由网关负责把请求转发到后端多个推理实例。这样即使某个推理服务挂了网关可以自动降级到备份模型业务侧无感。下面是一个简化配置示例model_gateway: default_model: qwen2.5-14b-instruct backends: - name: vllm-main type: vllm base_url: http://10.20.0.11:8000/v1 api_key: internal-key models: - qwen2.5-14b-instruct - name: ollama-backup type: ollama base_url: http://10.20.0.12:11434/v1 models: - qwen2.5-7b-chat fallback: - ollama-backup实际使用下来这个网关最少帮我解决了三个问题切换模型时 Prompt 模板不用动推理服务重启期间有降级通道可以走还能在网关层统一做超时、重试、限流和 Token 消耗审计。对于隔离内网这样“出现问题不好热修复”的环境多一层抽象带来的稳定性收益远大于成本。2.3 Rust 写的 Agent 运行时为什么适配离线场景这里单独想聊一下“基于 Rust 语言 AI Agent”这个方向。我们在调研时发现部分用 Rust 写的 Agent 运行时可以直接编译成静态二进制部署时不需要安装 Python 环境也没有复杂的依赖链非常适合离线交付。我记得当时在目标机器上只放了一个二进制文件加一个配置文件跑起来很干净。不过 Rust 生态里的 Agent 框架成熟度不如 Python。我的建议是如果团队本身就是 Python 技术栈不必强行换成 Rust但如果你要交付到运维管控严格、基础环境非常受限的机器上把 Agent 的轻量运行时用 Rust 封装一层是可以考虑的。尤其在隔离内网场景里依赖越少出问题的概率越低这个原则永远不会错。3. 离线工具链搭建模型分发、依赖锁定与推理服务3.1 模型文件的分发与校验在隔离内网里模型没法在线下载只能先通过受控方式导入。最传统也最可靠的方式是在一台可以访问外网的构建机上把模型文件预先下载好然后通过文件服务器或移动介质导入内网如果存在跨网传输建议用文件服务器分发的模式避免移动介质一天拷好几个小时。模型文件通常很大不建议只靠cp或手动拷贝。我们用的是这样一套流程在构建机下载模型原始文件保持 Hugging Face Transformers 或 GGUF 格式不变。对每个模型文件生成 SHA256 校验值记录到MANIFEST.json中。通过内部文件服务器分发到内网目标机器。目标机器下载后重新计算 SHA256和MANIFEST.json比对不一致则重新下载。# 构建机生成校验 sha256sum qwen2.5-7b-instruct-q4_k_m.gguf SHA256SUMS # 内网机器校验 sha256sum -c SHA256SUMS为什么校验这么重要因为模型文件在跨网传输过程中可能损坏而此类损坏往往不是通过运行时报错暴露的——它很可能导致模型推理结果偶发异常排查起来非常痛苦。我们之前就遇到过模型权重文件被截断导致 Agent 在处理某段中文文本时出现重复输出花了很长时间才发现是文件不完整。有了校验环节这类问题等于被挡在第一步之外。还有一个实操细节如果内网带宽有限链接较长优先使用支持断点续传的工具比如wget -c或aria2c。同时模型分卷大小控制在 1GB 到 4GB 之间方便中途失败后重传。如果真的需要反复搬运可以在文件服务器上保持目录结构新拷贝时尽量增量同步。3.2 模型量化档位与显存估算模型能不能在目标机器上跑起来主要看显存。我之前踩过的坑是看到 7B 模型就觉得“不大”结果直接把一张 16GB 显卡跑爆了。下面这段计算可以帮你提前做评估。以 FP16 精度的 7B 模型为例权重显存大约是参数量乘以 2 字节所以约需要 14GB 显存。但这还没结束推理过程中还要分配 KV Cache 和临时激活显存。以 Qwen2.5-7B 为例模型有 32 层假设 KV heads 为 4head dim 为 128那么每个 Token 的 KV Cache 约为2K 和 V 各一份× 32层数× 4KV heads× 128head dim× 2FP16 一个数占 2 字节等于每 Token 约 64KB。如果上下文窗口开到 32K理论上 KV Cache 就需要约 2GB。再加上权重 14GB 和推理时的激活显存16GB 显卡显然不够安全。所以我们在内网部署时优先选择了 4bit 量化模型。同样是 7B量化后权重显存降到 5GB 左右加上 KV Cache 和激活显存一张 16GB 或 24GB 的卡都能比较从容地跑起来。常见量化档位参考如下量化档位权重显存估算适用场景FP16约 14GB7B 模型追求精度显存充足INT8约 8GB精度损失较小显存中等INT4如 Q4_K_M约 5GB优先保证可运行适合内网环境需要注意量化不是没有代价。工具调用对模型稳定性要求较高过度量化可能导致模型输出不稳定尤其体现在 function calling 的参数格式上。我们在一个项目中对比过4bit 量化模型在线程简单任务上表现正常但涉及多参数、嵌套 JSON 的工具调用时偶尔会出现参数漏传。因此量化后必须增加对应的回归测试不能只看推理能不能跑通。3.3 Python 依赖、Node 依赖与容器镜像的离线闭环AI Agent 工程在国内通常离不开 Python而离线装依赖是很多团队绕不过去的坎。如果目标机器完全隔离最靠谱的方式是在能访问外网的构建机上提前下载所有依赖再导入内网私有源。比如 Python 侧可以使用如下方式# 在构建机上执行 pip download -r requirements.txt -d offline_packages/ -i https://pypi.org/simple --no-deps # 将 offline_packages 目录同步到内网私有源服务器 # 内网目标机器配置 pip 指向本地源 pip install --no-index --find-links./offline_packages -r requirements.txt这里有个容易坑人的点--no-deps参数只下载当前依赖不会下载传递依赖。如果不想太费心可以直接不携带--no-deps让它把整个依赖树都下载下来但要注意做这一步必须在一台和最终环境相同 Python 版本的机器上执行否则很多二进制的 wheel 包会不兼容。Node.js 生态同理常见做法是搭建内网 npm 私有库常见工具是 Verdaccio。构建机上执行npm pack或者从公网 registry 下载 tgz 文件再发布到内网私有库。容器镜像的离线分发更简单直接把需要用到的镜像从外部镜像仓库拉下来再通过docker save导出为 tar 包进入内网后docker load导入到本地 Registry业务节点从本地 Registry 拉取即可。需要注意一点如果业务节点没有外网必须提前配置好 Registry 的信任关系和证书否则镜像拉取会失败。3.4 本地推理服务的选择vLLM 还是 Ollama隔离内网里的推理服务选型我建议根据并发需求分两层来看。如果业务并发很低比如只有几个内部用户轮流传唤 AgentOllama 通常够用。Ollama 的优势是部署简单一条命令就能启动服务而且自带 OpenAPI 兼容接口用来跑内网原型非常方便。但它的缺点是并发处理能力较弱高并发下可能排队导致响应时间变大。如果 Agent 会被多个业务系统同步调用或者存在周期性批量任务我倾向于用 vLLM。vLLM 对并发请求的处理做得更到位吞吐量和 GPU 利用率通常更好同时通过 OpenAI 兼容接口对外提供服务Agent 侧对接起来差异不大。内存方面 vLLM 对 KV Cache 的管理更灵活可以通过配置限制模型上下文长度来保护显存。最终怎么选还是看你的并发模型和硬件条件。我们内网环境里用 vLLM 作为主推理服务Ollama 保留一个备份模型作为降级通道这样在升级或维护 vLLM 实例时Agent 还能继续工作。4. Agent 工作流落地工具调用、知识库、记忆的全内网化4.1 Function Calling 的 Schema 设计决定稳定性隔离内网里的工具调用往往是对内部系统的操作。有一次我们的 Agent 需要从工单系统里查数据工具定义写得很随意描述模棱两可结果模型经常把参数命名搞错甚至把两个工具混淆。后来我们把所有工具定义都收敛成严格的 JSON Schema并把每个参数的业务约束写清楚。下面是一个好的工具定义示例{ name: query_alert_by_host, description: 按主机名查询内网监控告警列表, parameters: { type: object, properties: { hostname: { type: string, description: 内网主机名如 mon-01 }, hours: { type: integer, description: 查询最近多少小时范围 1 到 168, minimum: 1, maximum: 168 } }, required: [hostname] } }这里的关键细节是工具名简洁准确描述要包含“何时使用”“何时不使用”参数严格用类型和枚举收敛范围。模型本身就是概率输出如果不给它清晰约束它就会自由发挥。还有一点强烈建议工具执行前在 Agent 运行时层做参数白名单校验。模型生成的hostname未必真实存在hours数值可能越界运行时需要再解析一次 JSON做业务侧校验然后再真正调用内部接口。这既是为了稳定性更是为了安全性。4.2 内部知识库检索向量库、ES 与 Rerank在隔离内网做知识库核心问题有两个文档怎么解析检索怎么做。文档解析方面PDF、Word、Excel 都需要对应的离线解析库扫描版 PDF 还需要 OCR而 OCR 模型也得内网部署。之前我们图省事直接用基础解析结果大量表格内容被拆得稀碎检索召回质量很差。后来才加上表格结构识别和版面分析的离线模块检索效果才基本可用。检索架构上我推荐“向量检索 关键词检索 Rerank”三段式。只用向量库的话一些带特定编号、型号的查询经常召回不准只用 ES 关键词的话语义检索又不足。实际方案是把两者结果合并再用 Rerank 模型统一重排效果比单一检索稳定很多。隔离内网里向量数据库可以选 Milvus 或 Qdrant它们都有社区版能够在单机或内网集群部署。ES 如果你们已经在用那也可以直接承担关键词检索任务。Embedding 模型建议选择参数较小、中文效果稳定的模型比如 BGE-M3 系列部署成本低而且支持长文本和多语言足够应付大部分内部文档场景。4.3 记忆与上下文管理Token 预算必须明确接入 Agent 之后我发现团队最容易高估模型的上下文窗口。内网模型通常不是以最大上下文部署的因为更长上下文意味着更大的 KV Cache 和更高的显存占用。业务侧如果无脑把历史对话全塞进去很快就把窗口塞满模型输出质量反而下降。我们做了一个简单的 Token 预算表每次请求前先计算各部分耗用组成部分Token 预算说明系统 Prompt800固定角色与工具说明不随用户变化本轮用户输入500超出部分截断或摘要检索知识点1500检索结果经重排后只取 Top 3对话历史1200滑动窗口保留最近 10 轮预留输出1000保证工具调用和回答有足够空间这个预算算好之后我们在代码里显式控制历史轮数和检索片段长度。对话历史超过预算就对更早的内容做摘要把摘要作为“长期记忆”存到 Redis 或 PostgreSQL短期记忆则直接放在会话状态里。有人可能会问为什么不用更大的上下文窗口因为更大的窗口意味着推理延迟和显存占用直线上升。在隔离内网这种资源通常偏紧的环境里单靠“加大窗口”并不是最优解主动做记忆裁剪和摘要反而能让 Agent 更稳定。5. 内网实战避坑超时、并发、安全与排查实录5.1 线上案例模型服务偶发无响应根因是并发和超时这里分享一个我们亲身经历过的故障。某天早上Agent 后台突然收到大量超时告警用户反馈对话特别慢有些请求直接失败。一开始我们怀疑是模型文件有问题重启了 vLLM 服务结果只好了十几分钟问题继续出现。排查过程分为四步。第一步复现问题用 curl 直接请求模型网关观察延迟和返回内容第二步看网关日志发现大量请求堆积在同一个模型实例上第三步看推理服务日志发现 GPU 显存占用接近临界但还没有 OOM第三步看监控面板发现并发请求峰值超过了模型服务的生产配置。根因其实不复杂Agent 在一次多轮对话里可能会触发多次工具调用每次工具调用都要重新请求模型多个用户同时操作时请求量成倍增长。模型服务只是被大量请求打到响应变慢慢的响应又触发客户端超时和重试重试再次增加请求量系统进入恶性循环。最后我们做了三件事来稳定系统模型网关设置最大并发数超出立刻返回 429 错误码而不是无脑排队所有模型请求设置显式超时默认 30 秒超过就降级到备份模型工具执行与模型请求解耦工具调用使用异步任务不再阻塞主对话。这个案例给我的最大启发是隔离内网里的 Agent 排障不能只看模型本身要把“模型推理”“工具调用”“客户端超时”“网关降级”全部串起来看。缺少任何一环生产环境都会给你颜色看。5.2 工具执行的安全收敛与审计Agent 一旦能调用内部工具就不能把“万能执行器”暴露给它。隔离内网不代表一定安全反而因为内外管控边界复杂内部越权路径往往更多。我们在工具层做了三类收敛工具强制白名单只能调用预先注册的脚本或内部接口参数做业务层校验SQL 优先用预编译模板避免动态拼接操作分成“只读”和“高风险”两种高风险操作直接插入人工审批环节。日志方面不要把所有内容都堆进去。Agent 对话涉及的数据可能包含敏感信息我们做了字段脱敏必要的日志才写审计表且设定保留周期。这样既能定位问题又能满足最小化留存原则。5.3 隔离内网问题速查表现象常见原因处理思路模型下载中断网络带宽受限或传输工具不支持断点续传改用aria2c多线程下载或通过文件服务器分卷同步Agent 启动报缺少依赖离线环境未配置私有源提前在构建机下载依赖内网目标机配置本地源推理响应很慢并发过高或模型上下文太长限制网关并发、缩短上下文窗口、升级推理服务工具调用频繁失败工具 Schema 不清晰或参数校验过严优化工具描述、增加容错解析、放宽不必要的校验知识库检索召回不准文档解析粗糙或检索方式单一增加 OCR 和表格解析采用向量与关键词混合检索显存不足导致 OOM模型精度太高或并发量过大换量化模型限制 KV Cache 或并行请求数Agent 偶发输出异常模型文件损坏或量化过度校验 SHA256用低量化模型做回归测试不知道 Agent 在做什么链路没有日志和追踪在网关层和工具层埋点输出结构化审计日志这张表是我们团队在多次上线中积累出来的。你在隔离内网里部署 Agent 时稍微留心一下这些现象很多问题其实在正式上线前就能提前暴露。最后分享一个我的个人习惯隔离内网里的 Agent 上线前一定要先做“最小闭环冒烟测试”。假设所有外部能力都不可用只靠内网模型、内网工具和基础依赖把“用户提问 → 模型推理 → 工具调用 → 返回结果”整条链路跑通才算初步成功。我见过太多项目在演示环境一切正常一到隔离网就翻车就是因为没有提前做这种链路级的自检。另外尽量把“失败”设计成 Agent 的正常能力。模型推不动时返回让用户稍后再试工具调不到时给出明确原因知识库没查到内容时主动提示缺少文档。把这些边界情况处理好了隔离内网里的 AI Agent 才能真正站得住。
