隔离内网下 AI Agent 工程实战很多人一听说“隔离内网里跑 AI Agent”第一反应是——这不扯吗大模型不都得调云端 API 吗但真正在金融、能源、政务这类行业落过地的人都知道数据不出域是底线业务智能化又是刚需两头一夹反而逼出了一套跟“拿 API Key 调 OpenAI”完全不同的工程方法论。这篇文章我想把隔离内网下 AI Agent 工程实战的完整思路梳理一遍包括架构怎么拆、模型怎么私有化部署、Agent 编排层怎么做、知识库怎么离线搭以及那些你翻文档也翻不到的经验坑。不管你是刚接触 AI Agent 搭建还是已经在自己内网里折腾过一轮这篇都值得花十分钟读完。我最初接手这类项目时最深的感受是隔离环境并不只是“没有外网”这么简单它意味着你无法依赖任何云端组件从模型权重、向量库、Embedding 模型到 Agent 框架本身全得自己想办法搬进去。这既是一个工程约束其实也是一次很好的架构训练。下面我从头讲起每一步都附上我实测过的方案和细节。1. 隔离内网的第一性约束与整体架构设计在动手之前我们必须先搞清楚隔离内网到底“隔离”了什么。很多团队犯的第一个错误就是拿公网架构图直接往里套结果到了部署阶段寸步难行。我建议先做个环境约束检查表逐项确认。1.1 先认清隔离环境到底卡住你什么隔离内网里的约束通常分四层每层都会影响 Agent 的技术选型。第一层是模型服务层。公网的大模型 API 无法访问意味着所有推理必须落在内网物理机或私有云上你得自己搞定模型权重、推理框架、GPU 资源。这一层最直接也是最容易预算失控的地方。第二层是工具与插件层。Agent 的核心能力是调用工具而大多数现成插件搜索、天气、地图、网页解析都强依赖公网服务。在隔离环境里你必须把工具能力“内置化”改成调用内网已有的 API 网关、数据库、运维平台或文件服务。第三层是数据与知识层。Agent 的问答质量非常依赖 RAG检索增强生成而 Embedding 模型、向量数据库、基础文档解析服务又是一堆组件全都得离线部署。更麻烦的是内网文档格式五花八门PDF、Word、Excel、扫描件混杂解析链路比公网环境更折腾。第四层是发布与运维层。你没法随便 pip install 公网包也没法直接 docker pull 镜像。所有依赖都得通过离线包导入镜像要导出再导入环境版本一旦不兼容排查起来相当痛苦。我把这四层约束画成一个“约束-应对”对照表你在做方案评审时可以直接参考约束层级典型限制应对方案模型服务无法访问云端 LLM API私有化部署 7B~14B 量级开源模型工具调用无法调用公网搜索/网页插件接入内网 API 网关、数据库、运维平台知识库无法使用在线 Embedding 与向量服务离线部署向量库与本地 Embedding 模型软件供应链无法在线拉取依赖与容器镜像建立离线源、打包镜像、校验版本1.2 整体架构分层的思路隔离内网 Agent 架构我建议从上到下拆成四层接入层、Agent 编排层、模型服务层、工具与数据层。这个分层不是拍脑袋定的而是为了在出问题时能快速定位——是用户请求没进来还是 Agent 决策错了还是模型推理慢了还是工具调用超时了。接入层负责统一接收业务系统的请求对外暴露一个 OpenAI 兼容接口。这样做的好处是上层业务系统可以无缝替换原来的模型供应商甚至保留流式输出的体验。Agent 编排层是整个架构的核心负责“理解用户意图 → 规划任务步骤 → 调用工具 → 汇总结果”。这一层我推荐用 LangGraph 或自研的状态机来实现里面会用到 ReAct 模式。模型服务层推荐使用 vLLM 或 Ollama 作为推理服务部署 Qwen2.5-14B 这类中文能力强的模型。工具与数据层是最能体现“隔离内网特色”的部分包括知识库检索、数据库查询、文件读写、流程审批等能力。这些工具必须通过一套白名单机制暴露给 Agent避免模型乱调接口。这个分层架构的核心逻辑是把“模型”和“业务”解耦。模型只负责生成决策与文本业务能力通过标准工具接口注入这样以后替换模型或者扩展工具都不用改整条链路。2. 大模型私有化部署Agent 的“发动机”不能掉链子Agent 的推理质量直接取决于底座模型选得好不好。在隔离内网里我们不能选几百 B 的巨无霸硬件成本和推理延迟都扛不住。我个人实测下来7B~14B 是一个黄金区间兼顾效果、显存、并发。2.1 模型选型与量化策略中文场景下我首选 Qwen2.5-14B-Instruct 和 Llama-3.1-8B-Instruct。Qwen 的中文指令跟随能力稳定做工具调用时 JSON 输出格式不容易乱Llama 的优势是英文逻辑推理更强如果业务文档偏英文可以优先考虑。显存估算有个简单公式模型显存 ≈ 参数量 × 量化位数以字节计。以 Qwen2.5-14B 为例——FP16 下约 28GBAWQ 4bit 量化后约 8GB再加上 KV Cache 和推理中间态单卡 24GB 比较宽裕单卡 16GB 就得开量化。如果你只有消费级显卡我建议用 4bit 量化。虽然会有轻微的效果损失但换取的是可以上生产。2.2 推理框架选型vLLM 还是 Ollama模型有了接下来是推理框架。这里最容易踩坑很多人图省事直接用 Ollama 起服务结果并发一高就重启。我的建议是分场景来Ollama适合原型验证、个人电脑、低并发场景。一条命令就能拉模型、起服务非常省心。vLLM适合生产环境、并发要求高、需要 PagedAttention 和 Continuous Batching 的场景。虽然配置复杂一点但吞吐量翻几倍。我在生产环境用 vLLM 部署 Qwen2.5-14B启动命令参考如下vllm serve /models/Qwen2.5-14B-Instruct \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --max-model-len 8192 \ --served-model-name agent-llm \ --host 0.0.0.0 \ --port 8000启动后用 curl 验证一下服务是否正常curl -s http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: agent-llm, messages: [{role: user, content: 你好请简单介绍一下你自己}], max_tokens: 128 }如果返回带 content 的 JSON说明模型服务已通。2.3 离线依赖迁移的补全方案内网能不能把 vLLM 跑起来最关键的其实是 Python 依赖。我的做法是在一台可以联网的 Ubuntu 20.04 机器上用同样的 Python 版本和 CUDA 版本装好 vLLM然后 pip download 打包所有 wheel再把整个 Python 虚拟环境压缩带进内网解压。这个办法虽然土但实测最稳。如果内网有 Docker 环境更推荐直接把 vLLM 的镜像打包转移# 外网机器上 docker pull vllm/vllm-openai:latest docker save vllm/vllm-openai:latest | gzip vllm-image.tar.gz # 进入内网后 gunzip -c vllm-image.tar.gz | docker load注意镜像版本和宿主机 GPU 驱动要匹配。VLLM 官方镜像一般要求 CUDA 11.8 以上进去之前先跑 nvidia-smi 查驱动版本。这里有一个容易被忽略的细节vLLM 在首次启动时会做 CUDA graph 捕获如果显卡型号太老或者显存太小可能报错。建议启动前设置环境变量 VLLM_NO_DEPRECATION_WARNING1并预留 10% 显存给运行时状态。3. Agent 编排层从“单轮问答”到“工具闭环”模型服务就绪之后真正的重头戏才刚开始把模型包装成一个能干活的 Agent。隔离内网场景里大部分爆点问题都出现在这一层。大家拿到的开源框架很漂亮但一接入内网的真实数据便开始状况百出。3.1 主流 Agent 框架对比与 Rust 生态观察Agent 编排层的主流架构目前可以分成三派。第一派是 LangGraph / LangChain。LangGraph 把 Agent 的思考、行动、观察抽象成一张图节点和边可以灵活编排非常适合“带状态”的工作流。缺点是概念多、版本迭代快一旦升级源码要跟上节奏。第二派是自动化平台类比如 Dify。它提供可视化的工作流编排和 RAG 管道对运维人员很友好企业落地时可以显著缩短开发周期。但自定义工具逻辑时受平台约束多一些。第三派是偏底层的自研调度器用代码直接控制模型循环调用工具。好处是规则透明、可控性极强、可完全离线封装坏处是全部轮子都要自己造。这里提一下热搜里“基于 Rust 语言 AI Agent”的方向。业界确实出现了比如 rig、llm-chain 这类 Rust 库。Rust 的优势是静态编译后产出一个二进制文件扔到内网直接跑不用解决 Python 环境依赖问题性能也高。但 Rust 生态的整体成熟度还比不上 Python自定义工具链需要写较多样板代码适合底层推理调度、Gateway 组件不适合快速的业务功能迭代。如果团队有 Rust 功底可以考虑 C/Rust 重写工具调用预校验服务就像给 Python Agent 加一个安全外脑但对多数团队我建议不必强行 Rust先把 Python 主链路跑通更重要。3.2 核心流程实现ReAct 循环隔离内网 Agent 的核心流程建议直接采用 ReAct 模式Reason Act。它的核心思路是模型先“推理”下一步该做什么然后“调用工具”获得事实再基于工具返回结果继续推理如此循环直到最终回答。下面我给出一个简化的 Python 实现思路import json from llm import LocalLLMClient SYSTEM_PROMPT 你是一个运行在隔离内网环境的智能助手。你可以通过以下工具访问内网资源 - search_kb(query): 检索内部知识库 - query_sql(sql): 执行只读 SQL 查询 - get_order_status(order_id): 查询订单状态 请严格按以下 JSON 格式输出你的行动 {thought: ..., action: 工具名, action_input: {参数: 值}} 当所有信息收集完成后请输出最终答案 {final_answer: ...} def run_agent(user_query: str, max_steps: int 5): messages [{role: system, content: SYSTEM_PROMPT}, {role: user, content: user_query}] for step in range(max_steps): response LocalLLMClient.chat(messages) content response[choices][0][message][content] parsed parse_json(content) if final_answer in parsed: return parsed[final_answer] if action in parsed: tool_result call_tool(parsed[action], parsed[action_input]) messages.append({role: assistant, content: content}) messages.append({role: tool, content: json.dumps(tool_result, ensure_asciiFalse)}) else: return Agent 输出格式异常%s % content return 超过最大步数终止这个实现虽然简单但已经是生产级 Agent 的雏形。真正要投入使用还有很多细节要补result 的截断策略、重试机制、JSON 解析失败的兜底、多轮工具调用的状态一致性等。3.3 工具定义与安全边界隔离内网里工具调用的安全与合规优先级甚至高于效果。模型是不可百分百信任的如果让 Agent 直接执行任意 SQL 或运维命令风险极大。我建议所有工具接口都遵循“最小权限白名单只读优先”三原则。最小权限工具只用到的表、只读查询不要给 DDL 权限。白名单机制限定可调用的参数范围数据库层再补一层防火墙规则。参数强校验无论模型生成什么参数执行前都校验格式和边界。举一个真实的例子。某内网知识库检索工具最初是让 Agent 自己生成 SQL 查询结果模型无意生成了一条扫全表的语句数据库差点被拖垮。后来我们把工具改为只暴露全文检索接口并强制 LIMIT 50问题立刻消失。4. 知识库离线搭建RAG 是隔离环境的刚需你可以把 RAG 理解为“给模型外接一个长期记忆仓库”。在隔离内网里这个仓库往往是企业内部多年沉淀的运维文档、规章制度、项目记录价值极高。同时由于模型无法上网更新知识RAG 几乎是消除“模型知识滞后”的唯一手段。4.1 离线向量数据库选型隔离内网里常见的向量库选择有三个Milvus、Chroma、Elasticsearch。我分别说一下适配场景。Milvus 是分布式向量数据库适合千万级向量、高并发检索但部署组件多需要 etcd、MinIO 等依赖偏重。Chroma 是轻量级向量库单机运行、零依赖几百 GB 知识量级下足够用适合中小型项目快速落地。Elasticsearch 如果你内网已经有 ES 集群可以直接复用。向量检索性能稍逊于专业向量库但胜在不需要新增组件、运维熟悉。我个人建议先有数据和规模再选组件。第一版用 Chroma 是性价比最高的选择等向量量级突破百万再上 Milvus。4.2 文档解析与切分细节很多内网知识库项目的失败不是检索框架不行而是文档根本切得稀碎。隔行如隔山内网文档往往包含版式复杂的 PDF、带密级标识的扫描件、格式混乱的 Excel。这里我推荐一套流程用 PyMuPDF 抽取 PDF 文本和目录结构扫描件接入 OCR 服务如果内网有优先用统一 OCR API按章节标题和段落切分不是按固定字符数硬切每段保留文档来源、标题、页码等元数据。切分长度建议控制在 300~500 个中文字符之间重叠 50~80 字符。切太过语义会被拦腰截断切太长检索命中噪音大。4.3 Embedding 模型本地化部署与离线下载RAG 的检索质量高度依赖 Embedding 模型。中文场景我用的是 BAAI/bge-large-zh-v1.5它 1024 维输出检索效果稳定压缩包 1GB 出头搬运进内网即可。离线下载思路在外网机器上用 huggingface-cli 下载模型到指定目录export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download BAAI/bge-large-zh-v1.5 --local-dir /models/bge-large-zh-v1.5然后把整个目录拷进内网。加载时直接指定本地路径from sentence_transformers import SentenceTransformer embedder SentenceTransformer(/models/bge-large-zh-v1.5)这里有个常见的坑bge 系列模型建议在检索时给 query 加上指令前缀“为这个句子生成表示以用于检索相关文章”否则检索分数会偏低。不加前缀的检索大概率找不到最高相关文档。5. 常见问题与排查技巧实录隔离内网环境下排查问题的复杂度比公网环境高一个数量级。因为没有现成的日志平台可以查没有线上文档可以搜很多时候全靠经验和耐心。这里把我踩过的坑列成速查表供你直接对照。问题现象可能原因排查与解决模型响应超时严重GPU 显存不足导致 swap 到内存降低并发数、开启量化、缩小 max-model-lenAgent 反复输出 JSON 异常模型强指令跟随能力不足切换更大模型或改为 Function Calling 协议工具调用 SQL 慢模型生成的 SQL 没有索引或全表范围大在工具层强制正则校验和 LIMIT知识库检不到内容Embedding 没加指令前缀按 bge 官方要求加 query 前缀并检查切分质量vLLM 启动报 CUDA OOM显存利用率设置过高调低 gpu-memory-utilization 到 0.85 再试内网启动依赖包报错Python 版本或 CUDA 驱动不一致用虚拟环境打包彻底重装环境5.1 日志追踪设计Agent 的调试比普通接口难因为它是一串“思考→行动→观察”的动态过程。我强烈建议给每一步都落一条带 trace_id 的日志内容包含模型生成的原始 JSON、工具入参、工具返回截断、用户最终接收的消息。我在生产环境里采用一个非常朴素但好用的办法把每一步追加到同一个 JSON 文件里再配合 filebeat 接入内网 ELK。这样一旦用户反馈“答案不对”可以直接把 trace_id 捞出来还原完整的决策链。5.2 状态持久化与并发控制Agent 在运行过程中可能会损坏或丢失工具状态。比如第二步拿到订单号第三步调用支付状态接口时进程被调度重启了整个会话上下文就断了。生产环境我建议把 Agent 的 messages 和中间产物存储到 Redis 或 PostgreSQL 中轮询请求时通过 session_id 恢复上下文。并发控制同样关键。内网 GPU 资源是有限资源如果不做并发限制10 个用户同时调用推理队列瞬间被占满。我在 nginx 层做了单用户并发数为 1、全局并发数为 8 的限制其余请求缓冲排队这样能有效避免单用户触发雪崩。5.3 经验分享最后分享几个私货级的心得。配置内网大模型推理服务时务必先把 max-model-len 调小再调大。一开始设置 8192后面线上发现吞吐跟不上改成 4096 之后并发直接翻倍。很多任务不需要那么长上下文不必盲目追撑窗口。工具返回长文本之前必须做摘要截断。否则你会看到模型把大段日志原封不动地拼到答案里既浪费 token 又让用户困惑。我的做法是超过 800 字符的工具结果先用“前 200 字摘要 后 200 字尾部 中间省略说明”拼成压缩文本。多轮对话治理也要提前规划。隔离内网业务场景中用户一次会话常在 5 轮以上messages 塞得越来越长。如果不做历史摘要压缩很快上下文就被耗尽且模型会“忘记”初始指令。我每过 3 轮就会将早期对话压缩成一句概括并重新注入系统提示词。写在后面这一类项目真正的难点在哪我做了几个隔离内网 Agent 项目之后最大的体会是模型和框架反而都不是最难的最难的是环境工程和数据治理。你能把一个 14B 模型放进内网、跑通 ReAct 循环、搭好知识库这只是一小半真正让 Agent 在业务里稳定跑上三个月不让人操心才见功力。这中间拼的就是一系列不起眼但极其重要的工程细节离线依赖怎么导、工具边界怎么划、并发超限怎么办、日志怎么追踪、上下文怎么压缩。把这篇里的每一项都当成一回事去认真对待你就能少走我走过的那些弯路。如果你也在隔离内网里折腾 Agent欢迎分享你的踩坑记录一起把这套离线工程方法打磨得更完整。