隔离内网AI Agent落地全攻略：模型部署、RAG检索与并发优化实战

很多做 AI 应用的人，一开始想的都是“调个 API 就完事”。但真到了政企、军工、金融内网这类环境里，你会发现事情完全不是这样。外网的大模型接口调不通，HuggingFace 上不去，pip 源也连不上，甚至连 Docker Hub 都拉不了镜像。我最早接手隔离内网下的 AI Agent 项目时，光环境准备就折腾了一周。这篇文章就把我在隔离内网环境里落地 AI Agent 的完整过程、踩过的坑、以及最终跑通并发和 RAG 检索的工程方案，原原本本分享出来。

内容会涉及几个部分：隔离内网下 AI Agent 的架构怎么选、模型怎么部署、向量化与知识库怎么做、并发和 Token 限制怎么处理，以及我实际遇到的一些诡异问题和排查过程。无论你是刚接触 AI Agent 的新手，还是已经在公网环境做过 Agent 开发、正准备往内网迁移的老手，这篇文章都能给你一些实在的参考。

1. 隔离内网里的 AI Agent，难点到底在哪——先拆清楚再动手

1.1 网络断了，Agent 的“手脚”和“大脑”都不好使

很多人对 AI Agent 的理解是“一个对话机器人”，实际上 Agent 是一套能够自主决策、调用工具、分步完成任务的程序。一个典型的 Agent 工作链路是这样的：接收用户请求，解析意图，规划步骤，调用工具（比如搜索、查数据库、发消息），把中间结果交给大模型，最后生成回复。这个过程依赖两个关键外部资源——大模型推理接口，以及可能用到的各类工具服务。

到了隔离内网，这两个依赖都会出问题。没有外网访问权限，就意味着：

• 云端大模型 API 无法调用。比如公网上的各种大模型接口，在内网环境完全不可用，你必须在内网部署一套推理服务。
• 模型文件下载困难。HuggingFace、ModelScope 这些模型仓库全被掐断，你需要通过离线包、光盘拷贝、甚至审批流程才能把模型文件送进内网。
• 依赖包安装受阻。pip、npm、apt 源全部访问不了，你只能搭建内网私有源，或者用离线 wheel 包手动安装。
• 工具服务的替代方案。Agent 调用的搜索、地图、天气这类在线工具，在内网基本都不可用，你需要自建替代方案，或者调整 Agent 的能力范围。

所以，在隔离内网里做 AI Agent，本质上是在有限的资源、有限的信息、有限的外部能力条件下，重新搭建一整套完整系统。这已经不是“调用别人服务”的开发模式，而是“自己承担全部链路”的工程模式。

1.2 隔离内网的三种常见形态，决定你要不要动架构

先别急着写代码。隔离内网也不是铁板一块，我遇到过三种典型形态，对应的工程复杂度差异巨大。

第一阶段：物理隔离，机器完全不联网。这种最常见于涉密程度高的单位。你需要做的准备工作最多，所有软件、模型、数据都得通过安全审批的方式导入。这种环境下，你甚至要提前规划好模型文件的落盘位置和硬盘空间。

第二阶段：逻辑隔离，可以访问内网服务器但不能出公网。这种环境通常有内部源、内部的模型服务。相比物理隔离，工作会轻松不少，至少不用为装一个 Python 包跑断腿。

第三阶段：白名单代理，只能访问特定域名。这种环境甚至可以直接使用某些云端服务，前提是完成安全备案。需要注意的是，很多云厂商提供专线或私有化部署方案，这种情况下“隔离内网”的约束反而没那么硬。

判断清楚自己的网络形态，决定了你后续要花多少时间在环境准备上，也决定了 Agent 架构可以做多复杂。比如，物理隔离环境下，你基本只能选择本地部署的小模型；而白名单代理环境下，你可能还能用上更大参数的云端模型。

2. 工程架构怎么选：RAG、任务编排、模型入口的设计思路

2.1 单 Agent 还是多 Agent，别为了时髦乱上

关于 AI Agent 的架构，目前主流就是单 Agent（AutoGPT 式）和多 Agent（多角色协作式）两种组织方式。我见过不少团队一上来就搞复杂的多 Agent 编排，结果效果没见多好，排错却要崩溃。我的建议是：能单 Agent 解决，绝不上多 Agent。

单 Agent 的典型代表是 LangChain 的 AgentExecutor，或者直接基于大模型写一个 while 循环，让模型自己决定下一步调用什么工具。这种模式实现简单，调试直观，从用户意图输入到最终结果返回，只有一条链路。缺点是模型一旦在某个环节反复出错，整个任务就可能卡死。

多 Agent 类似一个团队协作机制，有规划 Agent、执行 Agent、审查 Agent 等角色。典型实现是 LangGraph 的 StateGraph，把每个 Agent 定义成一个节点，节点之间有显式的状态流转关系。这种模式在处理复杂任务时表现更好，但工程成本会明显增加。

我在实战中的选型标准很简单：任务链路清晰、工具数量少于五个、单轮能完成的任务，一律用单 Agent。只有任务确实需要多步分解、需要用到多个工具而且步骤之间存在依赖关系的时候，才考虑上 LangGraph 做多 Agent 编排。

举个例子，我手上有个需求是让 Agent 根据用户的一句话，自动查询内部系统的订单数据、判断异常、生成报告并发送到企业微信群。这个链路涉及查库、规则判断、报告生成、消息推送四个工具，而且顺序固定，用 LangGraph 的节点编排就非常合适。每个节点是一个独立函数，节点之间的数据通过共享状态传递，模型只负责在关键节点做决策，这比让一个 Agent 自由发挥要稳定得多。

2.2 LangGraph 编排任务，其实是在给 Agent 画流程图

LangGraph 这个名字听起来很高深，说白了就是一个让你用“图”的方式组织 Agent 流转的框架。它的核心概念有三个：State（状态）、Node（节点）、Edge（边）。

State 就是一个贯穿全程的数据结构。用户输入、中间结果、最终输出都放在 State 里。在 LangGraph 里，State 通常用 TypedDict 定义，比如包含 query、history、result、messages 这些字段。Node 是具体的处理函数，接收当前 State，返回更新后的 State。Edge 则定义了节点之间的跳转方向，可以是固定跳转，也可以是条件跳转。

我实际项目中的做法是：把整个 Agent 流程拆成五个节点——意图识别、参数抽取、数据查询、结果分析、报告生成。前两个节点用大模型做语义解析，数据查询节点是写死的函数（因为不可能让模型自己去拼 SQL，那样太危险），结果分析节点再次调用大模型对查询结果做判断，报告生成节点用模板填充数据。通过条件边，如果意图识别阶段判断用户只是想闲聊，就直接短路走结束节点，不触发后续的数据库查询。

用 LangGraph 的一个重要好处是可观测性强。因为是图结构，每一步的状态都可以单独打印出来，排查问题的时候，你能清楚地看到数据是在哪个节点丢失的、模型是在哪一步产生了幻觉。这对隔离内网环境下做问题排查特别有用，因为这种环境没有外网那些调试工具可用，一切只能靠自己。

2.3 模型入口封装：别让业务代码绑死大模型

在隔离内网做 Agent 开发，有一个很容易被忽视的坑：模型入口直接硬编码在业务代码里。等到后面换模型、换推理服务的时候，你就会发现要改的地方散落得到处都是。

我的做法是在业务代码和大模型推理之间加一层模型网关，屏蔽底层细节。无论你调的是 vLLM、Ollama、TGI，还是内部封装的服务，业务侧只需要通过一个统一的接口传入 prompt 和参数，拿到生成结果就行。这一层网关内部封装了协议适配、字符编码处理、超时重试、token 计数这些事情。

为什么强调这个？因为在隔离内网的模型服务选型，很可能会经历一个从“先跑通”到“追求性能”的过程。你可能最开始用 Ollama 快速验证，后来发现并发不够，换成 vLLM；或者发现模型效果不好，从 7B 换成 13B。如果没有网关层，每次切换都要修改业务代码，这种重复劳动会浪费大量时间。项目初期多花半天时间做好这层封装，后面会省下几天的返工时间。

3. 动手落地：模型部署、向量化、RAG 检索这些环节怎么做

3.1 本地模型怎么选：量化、显存、推理速度这三个指标怎么权衡

在隔离内网部署模型，通常只能选开源模型，因为商业模型的私有化部署普遍不开放或者价格非常高。模型选型要考虑三个核心指标：推理效果（看评测分数和业务适配度）、显存占用（硬件条件是否跑得动）、推理速度（会不会影响用户体验）。

以 LLM 为例，我的经验是，如果业务场景相对简单，比如文本分类、信息抽取、格式化输出，7B 到 14B 的模型已经够用。如果任务需要较强的推理能力和复杂指令跟随，尽量选 32B 以上的模型，但要确认你的 GPU 显存是否扛得住。

显存估算有个简易公式：模型显存占用大约等于参数数量乘以每个参数占用的字节数。以 7B 模型为例，FP16 精度下大约需要 14GB 显存，INT8 量化后大约 7GB，INT4 量化后大约 3.5GB。但这里要提醒一下，这只是模型权重占用的显存，实际推理过程中，KV Cache、中间激活值、临时缓冲区还会额外占用显存，通常要在这个基础上再留出 20% 到 50% 的余量。所以 7B FP16 模型，单张 24GB 的显卡跑起来问题不大；但如果你还想同时加载 Embedding 模型、向量数据库索引，就要精打细算了。

我这边的实际配置是两张 32GB 的显卡。一张跑主模型，用的量化版本是 INT8 的 14B 模型，显存占用约 15GB 左右，剩下的显存留给 KV Cache。另一张卡跑 Embedding 模型和后续我要提到的重排序（Reranker）模型。推理框架选择了 vLLM，实测的并发能力和吞吐量比用 Ollama 高不少。

Ollama 的优势是部署简单、上手快，适合开发自测。但到了生产环境，并发请求稍微一多，Ollama 的吞吐量和排队表现会明显下滑。vLLM 的优势在于显存管理更高效、支持连续批处理（Continuous Batching），我是直接把生产环境的推理服务换成 vLLM，效果提升肉眼可见。

3.2 向量化与知识库构建，隔离环境里最容易翻车的一步

Agent 离不开 RAG，RAG 离不开向量化。隔离内网做 RAG 的坑，我踩过太多次了。

第一步，Embedding 模型的选择。不要用外网默认的开源 Embedding 模型，一定要在中文语料上测试效果。我当时测试过几个常见的开源中文 Embedding 模型，用的测试方法是搞一个小规模的中文检索数据集（几百条知识问答对），对照测试不同模型的召回准确率。选型结果最终锁定了一个中文效果明显更好的模型，参数不大，300MB 左右，但检索效果差距明显。

第二步，切块策略。这块直接影响 RAG 效果。我刚开始图省事，直接按固定长度每 500 字切一块，结果用户提问跨越两块的边界时，检索效果差得离谱。后来改成按语义段落切分，先识别文本中的标题、段落分隔符，尽量保持语义完整。切块长度设置在 300 到 800 字之间，同时设置 50 到 100 字的 overlap（重叠区域），这样前后文的衔接不会断裂。

第三步，图谱和向量混合检索。纯向量检索在关键词匹配上经常失灵。举例来说，用户问“上月采购金额是多少”，如果你的知识库文本里写的是“2024 年 6 月采购总额”，向量检索可能没问题；但如果写的是“六月份花钱总数”，向量检索可能就抓瞎了。我后期做了一个折中方案：同时建向量索引和 BM25 关键词索引，检索时两路召回，融合后交给大模型。这个方案已经能覆盖绝大多数实用场景，而且不依赖外网服务。

这里特别提醒一句：不要迷信复杂的 RAG 方案。很多营销号说的 GraphRAG、Self-RAG，虽然有各自的适用场景，但在内网环境、算力有限、时间有限的前提下，最靠谱的永远是“向量检索 + 关键词检索 + 重排序”这条最稳的路。

重排序（Reranker）这一步也别省。初召回结果往往有几十条，直接全部塞给大模型会导致 prompt 超长、噪声太大。加上一个 Reranker 模型，对初召回结果做精排，只把 Top 3 到 Top 5 给到大模型，效果提升非常明显。

4. 并发与性能：Token 限制、排队、缓存这些坑怎么填

4.1 Token 到底怎么算，为什么长上下文化任务特别烧资源

搜索热词里有个很常见的疑问：“AI Agent token 是什么意思”。简单说，Token 是大模型处理文本的最小单位，中文场景下，一个字大约对应 1 到 2 个 Token，英文场景下，一个单词大约对应 1 到 2 个 Token。模型的价格、上下文窗口限制、性能瓶颈，全部围绕 Token 展开。

Agent 场景有一个特点：每次交互都要带历史上下文。用户问一句，Agent 内部可能已经和模型来回交互了五次，每次交互都把前期的对话历史全部带上，Token 消耗就会成倍增加。一个简单问答，用户可能只输入 20 个字，但 Agent 内部处理的 Token 总量可能已经超过 2000。

Token 限制带来的直接问题，是生成大量文本时模型直接报错，比如超过上下文窗口长度。解决办法有几个：

• 做对话历史的滑动窗口，只保留最近 N 轮的内容。
• 做关键信息的摘要替代，把历史对话压缩成一条摘要塞进 prompt。
• 控制工具返回结果的长度，查询数据库之后，不把全量记录塞给模型，只给摘要统计。

另一个隐藏问题是速度。生成 1000 个 Token 的耗时远高于生成 100 个 Token，如果 Agent 的某个环节让模型生成长文本，整个链路的时间会明显拉长。我做性能优化时，把所有非必要长文本生成环节都改成了短输出模式，比如“只输出结果的关键字段”或“用表格形式简要回答”，实测链路耗时能下降 30% 以上。

4.2 并发控制：内网环境经常忽略的工程问题

“AI Agent 怎么扛并发”是热门搜索词，说明这是所有人都会遇到的瓶颈。内网环境的并发量通常没有互联网应用那么夸张，但内部用户一旦集中在上午或某个时间点发起请求，冲击力依然不小。

我当时的方案分三层：

第一层，推理服务的并发控制。vLLM 支持设置 max_num_seqs 和 max_parallel_sequences，控制同时处理的请求数量。并不是并发越高越好，并发太高会导致每个请求的响应时间急剧拉长。我实测下来，对 14B 量化模型，把并发控制在 8 到 16 之间比较合适，响应时间保持稳定的同时吞吐率也能接受。

第二层，接口层做排队。使用 FastAPI 的 BackgroundTasks 或 Celery 把 Agent 任务转为异步执行，前端提交任务后立即返回一个任务 ID，用户通过轮询或 WebSocket 获取结果。这样即使后端处理不过来，前端也不会一直转圈等待。

第三层，结果缓存。高频重复的问题，直接缓存答案。我甚至做了一个简单的相似度缓存，如果用户的提问和之前某个提问的向量相似度超过阈值，就直接把当时的答案返回，不重新走一遍 Agent 链路。这个策略让系统的整体负载下降非常明显。

4.3 模型并发时的显存调度，别等 OOM 了再找原因

并发模型推理最容易出现的问题就是显存溢出。vLLM 默认会做 PagedAttention 和 KV Cache 管理，但如果你用其他框架，就得自己关注显存分配。

我遇到的情况是，当并发数从 4 提升到 8 时，整个推理服务开始频繁报错，有时甚至直接 OOM 崩溃。排查之后发现原因有两个：一是模型权重本身占了太多显存，留给 KV Cache 的空间不够；二是并发请求的输入长度差异巨大，一个长 prompt 的请求就可能吃光剩余显存。

解决办法是设置 vLLM 的 max_model_len 参数，把单请求的最大 Token 长度限制在合理的范围内。对于大部分 Agent 场景，设置成 8192 足够用了。同时把 vLLM 的 gpu_memory_utilization 设置为 0.85 到 0.90 之间，给推理预留足够空间的同时，保住 KV Cache 的可用量。调整完之后，并发提升到 12 都没有再出现 OOM。

5. 常见问题排查实录：这些坑踩过才知道

5.1 生成的回答不靠谱，先别怪模型，查检索

Agent 的最终输出质量，一半以上由检索质量决定。我在内网做知识库问答时遇到过一种情况：模型生成的回答看起来很有道理，但关键数据是错的。一开始以为是模型幻觉，折腾了半天的 prompt 调优，效果不大。后来把中间过程的检索结果打印出来才发现，RAG 检索到的知识片段和用户的问题完全不相关，模型是在拿错误的信息做“一本正经的胡说八道”。

排查思路很简单：先看知识库能不能检索到正确内容，再看 Reranker 精排结果是否正确，最后才考虑模型的能力问题。如果检索本身就不行，你就算把 prompt 写得天花乱坠也没用。

后来我通过加强查询改写和检索召回率来解决这个问题。在送入 Embedding 模型之前，先用大模型对用户提问做一个改写，把口语化的表达转化为正式的知识库检索式表达，比如“上季度公司总共花了多少钱”，改写成“上季度公司总支出金额”，检索准确率提升了接近三成。

5.2 部署之后模型加载一直超时，那段时间我差点怀疑人生

隔离内网部署模型时，最让我崩溃的一次经历是：模型文件明明已经下载下来、文件完整性也校验过了，但每次加载模型都报错超时。后来才发现，内网的磁盘 IO 速度非常慢，而模型文件又大，加载时间超过了框架默认的超时阈值。

这个问题的解决方法是调整模型加载的超时参数，以及把模型文件放到本地 NVMe 盘上，不要放在共享存储或网络磁盘上。还有一个小技巧：把模型文件先做一个内存映射（mmap），后续加载速度会有明显提升。另外，尽量选择同一批次的模型文件夹整个拷贝，不要用网盘、U盘逐个拷贝文件，那样很容易出现文件缺失或大小写不一致的问题。

5.3 多 Agent 协作时的状态错乱，原来是我自己埋的雷

有一版用 LangGraph 做多 Agent 协作，出现了状态错乱的问题：上一步生成的结果，在下一个节点展示时变成了别的内容。一开始以为框架有 Bug，后来仔细检查发现，是 State 更新逻辑写错了。LangGraph 的 State 更新有几种合并策略，如果多个节点向同一个字段写入数据，后来的节点会覆盖先前节点的数据。我把中间结果和最终结果全写在了同一个字段里，自然就互相覆盖了。

排查过程花了很长时间，因为状态错乱的现象只在特定输入下出现，而且报错信息不够直观。后来我在每个节点入口都打印了一份当前 State 的核心字段变化，才把问题定位清楚。经验就是：Agent 项目的排查能力，本质上取决于你对自己系统可观测性的设计有多完善。从项目开始就做好日志埋点和状态追踪，比事后绞尽脑汁去猜要好得多。

5.4 常见问题速查表

6. 并发压测与性能报告，用数据说话

架构和代码写完之后，性能是否达标得靠压测验证。我用了 Locust 做并发压测，脚本模拟用户提交任务、等待结果、再提交下一个任务的链路。压测结果给我印象最深的是两组数据：一是请求响应时间分布从 P50 到 P95 的跨度；二是系统在高并发下的错误率。

对比调优前和调优后的数据：调优前，20 并发下 P95 响应时间接近 30 秒，错误率约 5%，用户体感明显卡顿；调优后，20 并发下 P95 响应时间降到了 8 秒以内，错误率控制在 0.5% 以下。优化措施主要就是前面提到的：vLLM 参数调整、接口异步化、结果缓存、减少无效长文本生成。

压测过程中还有一个有意思的发现：缓存命中率对系统整体表现影响巨大。加了相似度缓存之后，有接近四分之一的请求变成了直接返回缓存结果，不走 Agent 链路，系统负载一下子就降下来了。如果你对响应时间的要求比较敏感，建议优先把缓存做好，这比单纯加机器更经济实惠。

7. 个人体会与后续扩展

隔离内网下做 AI Agent，成败的关键往往不在算法，而在工程细节。你选的模型效果差 5%，可以通过 RAG 和 prompt 调优补回来；但如果你连离线依赖都没装好、模型文件都传不进内网，那后面的一切都无从谈起。

我个人最大的体会是：在这个环境里做 Agent，必须接受“有限资源、有限信息”的约束。外网那套快速迭代的打法在这里行不通，每一步都要提前规划，每一步都要做好记录。当你把整条链路跑通的那一刻，那种成就感是外网开发完全比不了的。

后续这个项目还可以继续扩展的方向，一个是把 Agent 的处理能力进一步覆盖到更多内部业务系统，比如接入更多的数据源和工单系统；另一个是尝试更强的本地模型，比如在内网部署 MoE 架构的模型，但要先确认好显存和推理性能是否能支撑。还有一个比较超前的方向，是用强化学习方法让 Agent 在内部任务上不断自我进化，当然这只是技术预研阶段的想法，真要落地还需要很长的路要走。