很多做 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 的架构目前主流就是单 AgentAutoGPT 式和多 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 量化后大约 7GBINT4 量化后大约 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 离不开 RAGRAG 离不开向量化。隔离内网做 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 常见问题速查表现象可能原因解决方案模型加载超时磁盘 IO 太慢加载时间超过默认阈值提升超时参数模型放 NVMe 盘预加载并发高时 OOM显存预留不足单请求 token 长度过长调 max_model_len调整 gpu_memory_utilizationRAG 回答不靠谱检索质量差或切块不合理优化切块策略加查询改写加 RerankerAgent 状态错乱State 更新字段冲突区分中间结果和最终结果字段打印状态流转中文效果差Embedding 模型选型不适合中文在中文语料上重新评测选型请求排队久推理并发设置过高或过低根据响应时间实测调整并发数pip 装不上包内网源缺失或没有走代理搭建内网 PyPI 源或用离线 wheel6. 并发压测与性能报告用数据说话架构和代码写完之后性能是否达标得靠压测验证。我用了 Locust 做并发压测脚本模拟用户提交任务、等待结果、再提交下一个任务的链路。压测结果给我印象最深的是两组数据一是请求响应时间分布从 P50 到 P95 的跨度二是系统在高并发下的错误率。对比调优前和调优后的数据调优前20 并发下 P95 响应时间接近 30 秒错误率约 5%用户体感明显卡顿调优后20 并发下 P95 响应时间降到了 8 秒以内错误率控制在 0.5% 以下。优化措施主要就是前面提到的vLLM 参数调整、接口异步化、结果缓存、减少无效长文本生成。压测过程中还有一个有意思的发现缓存命中率对系统整体表现影响巨大。加了相似度缓存之后有接近四分之一的请求变成了直接返回缓存结果不走 Agent 链路系统负载一下子就降下来了。如果你对响应时间的要求比较敏感建议优先把缓存做好这比单纯加机器更经济实惠。7. 个人体会与后续扩展隔离内网下做 AI Agent成败的关键往往不在算法而在工程细节。你选的模型效果差 5%可以通过 RAG 和 prompt 调优补回来但如果你连离线依赖都没装好、模型文件都传不进内网那后面的一切都无从谈起。我个人最大的体会是在这个环境里做 Agent必须接受“有限资源、有限信息”的约束。外网那套快速迭代的打法在这里行不通每一步都要提前规划每一步都要做好记录。当你把整条链路跑通的那一刻那种成就感是外网开发完全比不了的。后续这个项目还可以继续扩展的方向一个是把 Agent 的处理能力进一步覆盖到更多内部业务系统比如接入更多的数据源和工单系统另一个是尝试更强的本地模型比如在内网部署 MoE 架构的模型但要先确认好显存和推理性能是否能支撑。还有一个比较超前的方向是用强化学习方法让 Agent 在内部任务上不断自我进化当然这只是技术预研阶段的想法真要落地还需要很长的路要走。