隔离内网AI Agent部署实战：架构选型、离线依赖与并发调优

1. 写在前面为什么要把 AI Agent 塞进隔离内网干这行这么多年我见过太多项目在公网跑得飞起一进隔离内网就“见光死”。不是模型不行不是代码有问题而是整个技术栈的假设全变了——不能联网、装不了包、拉不了镜像、调不了外部 API甚至连基础软件源都是个问题。今年接了一个电力行业的项目客户机房严格物理隔离要求把一个基于大模型的 AI Agent 部署进去处理内部工单、知识问答和流程调度。做完这一趟踩坑无数也沉淀出一套可以复用的打法。这篇就聊聊隔离内网下做 AI Agent 工程实战的那些事从架构选型、模型部署、依赖离线化到并发调优一次讲透。为什么非要在这个场景里做 Agent因为隔离内网意味着高价值数据不能出域但业务又确实需要智能化的对话、理解、编排能力。比如客服工单自动分诊、运维故障初判、规章制度问答这些场景如果全靠人工成本高、响应慢而传统规则引擎又处理不了自然语言的模糊表达。AI Agent 的核心价值在于它不是一个简单的问答机器人而是能拆解任务、调用工具、分步执行、最终返回结果的智能化体。放到隔离内网里还要额外解决模型、数据、权限、审计、并发等一系列工程问题。这篇内容适合谁如果你正在做企业内部 AI 平台、正在把大模型能力产品化、或者正准备在私有化环境里部署 Agent 应用那这篇文章可以帮你少走很多弯路。我会把我踩过的坑、实测有效的方案、以及那些文档里不会写的细节全部摊开来讲。2. 方案整体设计与技术选型2.1 场景约束决定架构而不是技术时髦度很多人一上来就选最火的框架、最重的模型但在隔离内网里场景约束是第一位的。我们当时面对的现实条件是这样的物理隔离机房只有内网服务器GPU 是两张 A800操作系统是麒麟 V10网络完全不通外网。业务需求是工单分诊、知识问答、设备告警分析还要求所有操作可审计、模型可替换、流程可配置。这些约束直接决定了几个选型方向模型方面必须用开源可私有化部署的底座我们最终选了 Qwen 系列因为中文能力和授权协议都更适合企业场景编排框架方面我们用的是 LangGraph它能把复杂的 Agent 流程建模成状态图比串行链式调用清晰得多后面扩展新功能也方便服务层方面用 FastAPI 作为统一网关层做鉴权、并发控制、协议转换。架构上分四层最底层是模型服务层负责大模型推理和向量化中间是 Agent 编排层承载节点状态机、工具调度和记忆管理再往上是服务接入层使用 FastAPI 暴露接口做并发控制和权限校验最上面是应用层包括工单系统、前端页面、管理后台。这样分层的好处是每一层都可以独立替换模型可以换、工具可以加、接口可以拆不会牵一发动全身。2.2 LangGraph 还是纯 LangChain生产环境选型的真实考量热词里有个“AI Agent 主流架构”现实中我看到的主流就两条路线一条是 LangChain 的 AgentExecutor简单直接适合 demo 和轻量场景另一条是 LangGraph把 Agent 流程变成有向状态图适合复杂生产和流程可控性要求高的场景。我这次选了 LangGraph说白了就是因为 LangChain 的 AgentExecutor 在复杂任务下控制力不够你想中途插手、想加人工审核节点、想记录每步状态它对原生回调用得别扭而 LangGraph 天然就是状态机每个节点做什么、怎么跳转、容错逻辑全在图上写清楚。这里多说一句选框架别只看 GitHub star要看它在你们团队手里能不能驾驭。LangGraph 的调试体验在早期版本里不算友好Graph 一旦大了可视化排查要靠 LangSmith但隔离内网里 LangSmith 是连不上的这就意味着你要自己写状态日志和追踪逻辑。所以我们设计了一个轻量的 trace 模块把每个节点的输入输出、耗时、token 消耗、出错信息和重试次数全部落库。后面排查问题时这套自研 trace 比什么框架自带的调试工具都好用。工具调用这块我们借鉴了 Tool Calling 的标准范式但做了内网化的改造工具注册表是统一的 schema工具执行是独立的线程池工具鉴权由服务层下发 token工具运行结果统一走回调不回传原始敏感字段。比如查工单详情的工具Agent 拿到的是脱敏后的工单标题和状态具体内容要前端再按权限调详情接口Agent 本身碰不到敏感原文安全边界清晰。2.3 FastAPI 作为编排层暴露接口并发模型怎么设计FastAPI 这个选型我基本没有犹豫因为它的 async 特性太适合做编排层的 IO 密集型任务。你可能会有疑问Agent 的推理过程本身是阻塞的API 层再 async 有什么用实际场景里一次 Agent 调用包含多个步骤——大模型推理、工具调用、再推理、结果生成其中模型推理占总耗时大头但工具调用和内部 HTTP 通信是真正的 IO 等待。用 async 接口承接请求后可以做到外部并发请求进来时FastAPI 不阻塞线程等模型推理结果返回后再写回响应整体吞吐明显提升。服务化之后还要解决一个问题GPU 只有两张模型推理并发一高就 OOM或者排队越来越长。我们的做法是把“API 并发”和“模型并发”分开治理。API 层可以承受高并发请求但每个请求进入后立即被投递到一个有界队列里队列长度超过阈值直接返回 503提示用户稍后重试。模型服务层用 vLLM 部署设置最大并发数超过这个数的请求会自动排队。这样整条链路从“来者不拒”变成了“有损保护”高峰期不会拖垮节点低峰期资源又不浪费。3. 隔离内网下的模型部署与运行环境构建3.1 模型离线安装与量化取舍能跑起来比指标好看更重要隔离内网里最难受的一步是把模型从外网搬到内网。虽然不能跟你们讲怎么绕过网络限制这个红线必须守住但可以说一套合规的队伍做法通过移动介质拷贝授权范围内的模型文件和应用依赖这完全符合机房管理规定。我们这次是把 Qwen2.5-14B-Instruct 和 Qwen2.5-7B-Instruct 两个型号的权重文件加一个 bge-m3 embedding 模型全部打包后一次性拷入内网。模型选型上14B 做主力推理7B 做轻量任务降级embedding 模型负责知识库向量化。这里有个量化选型的教训一开始我图省事直接上了 AWQ 4bit 量化版跑是能跑但工具调用的指令遵循能力肉眼可见地下降了Agent 经常把工具参数格式写错。后来换成 GPTQ 8bit 量化指令遵循能力恢复得很好显存占用虽然比 4bit 多了十几个 G但两张 A800 完全扛得住。所以量化不是越低越好要看你的实际任务类型。对 Agent 来说工具调用的参数格式要求极高太低比特的量化会明显破坏格式稳定性和逻辑连贯性省那点显存不值当。模型服务统一用 vLLM 起这里有两个关键参数值得讲一下。一个是max-model-len不能设太小否则长多轮对话的 prompt 会被截断Agent 上下文信息丢失也不能设太大否则显存预分配过多并发上不去。我们最终设的是 32768配合显存池化实测可以支撑 8 个并发推理而不 OOM。另一个是gpu-memory-utilization设到 0.9 时吞吐最高但连续跑几天后有小概率触发显存碎片问题后来收到 0.85 求稳。3.2 Python 依赖与模型仓库离线化构建内网 pip 源与镜像同步这是最脏最累的活儿但也是决定项目能不能落地的一步。先说一下现实内网机器上 Python 环境是干净的你想装 fastapi、langgraph、vllm 这些包直接 pip install 是不行的因为外网源不通。合规的做法是从外网服务器上下载好 whl 包和依赖树拷贝进内网后自建一个本地 pip 源。我建议你按这个步骤来做能省一半时间先在一台有外网的机器上用相同的 Python 版本和操作系统创建虚拟环境然后pip download把项目所有依赖包括传递依赖拉成一个目录。这里要注意pip download有个--platform参数可以指定平台但最稳的方法还是直接在同样架构的机器上执行pip freeze后整份下载避免某些包带 C 扩展的兼容问题。内网搭源我用的是 devpi比简单的本地目录方式好管理支持多索引、版本覆盖、权限控制。配置好之后内网机器只需指定-i http://内网地址:3141/root/pypi/simple/ --trusted-host 内网地址就能正常装包。另一个大头是模型仓库。HuggingFace 上的模型文件没法直接拉进内网我们把需要的模型在公网机器上先执行snapshot_download拉全然后连同整个.cache/huggingface目录结构一起拷贝进内网。机智的一点是内网机器的 HF_HOME 环境变量直接指到拷贝目录这样 huggingface 代码在加载模型时不会再去检查外网缓存整个流程顺滑。3.3 知识库构建与向量化embedding 本地化部署知识库问答是这次 Agent 的一个核心能力而知识库的关键就是 embedding 模型能不能在内网稳定服务。我们没有用外部 API全部走本地部署。bge-m3 这个模型很合适支持中文和英文维度 1024在检索精度上表现也不错。向量库选的是 Milvus 2.x 版本做成了独立服务。这里要提一个注意点Milvus 对内存和 CPU 的要求不低如果服务器资源紧张可以用轻量的 Chroma 或者 Qdrant 替代。我们当时为了将来数据量增长还是选了 Milvus 集群版但如果你只是内部知识库几百兆数据建议用 Qdrant 单机就够了部署和维护成本低很多。文档处理环节也是个大坑。原始资料有 PDF、Word、Excel、PPT还有扫描件我们需要做版面解析、OCR 识别、标题层级切分然后把长文本切成固定长度的 chunk。我们切分策略是优先按标题结构切其次是段落最后是滑窗补充。每个 chunk 控制在 400-600 token前后重叠 50 token保证上下文衔接。这一步直接决定了 RAG 的召回质量很多团队把精力全放在模型上结果检索一团糟问题就出在切分这块没做好。切完的 chunk 要过一遍清洗规则去掉页眉页脚、去掉重复的空行、修正 OCR 产生的错别字、统一全角半角。清洗这一步很多人忽略但它对后续 embedding 质量的影响非常大。比如“登录”和“登 录”这两个文本向量化后距离很远但业务上它们是同一个词不清洗的话召回会漏。4. Agent 核心逻辑与工具调用实战4.1 状态图拆解把 Agent 从“黑盒”变成“白盒”LangGraph 的最大优点是可观测、可干预。我们把 Agent 流程拆成了这几个节点入口路由、意图识别、工具规划、工具执行、上下文整理、结果生成、人工审核按需、最终响应。每个节点都是一个独立的 Python 函数输入是当前状态输出是更新后的状态。状态用一个 TypedDict 定义字段包括messages、tool_calls、tool_results、current_step、retry_count、user_id、session_id等。这里贴一段核心的状态图定义逻辑看完你就明白为什么我说 LangGraph 比链式调用清晰from langgraph.graph import StateGraph, END from typing import TypedDict, List, Any class AgentState(TypedDict): messages: List[dict] tool_calls: List[dict] tool_results: List[dict] current_step: str retry_count: int user_id: str session_id: str def route_after_plan(state: AgentState) - str: # 如果规划中要求调用工具进入工具执行节点否则直接生成结果 if state[tool_calls]: return execute_tools return generate_answer def build_graph(): g StateGraph(AgentState) g.add_node(intent_recognition, recognize_intent) g.add_node(tool_planning, plan_tools) g.add_node(execute_tools, execute_tools) g.add_node(generate_answer, generate_answer) g.add_node(human_approval, human_approval) g.set_entry_point(intent_recognition) g.add_edge(intent_recognition, tool_planning) g.add_conditional_edges(tool_planning, route_after_plan) g.add_edge(execute_tools, generate_answer) g.add_conditional_edges(generate_answer, lambda s: human_approval if s.get(need_approval) else END) g.add_edge(human_approval, END) return g.compile()可千万别小看这个人工审核节点。在金融、电力这类行业Agent 不能完全自主执行有风险的操作——比如发送指令、修改配置、删除数据。我们设置了工具风险等级低风险工具查日历、查天气、搜文档由 Agent 直接执行高风险工具改配置、发命令、删文件必须走人工审核节点前端弹窗给操作员确认后才放行。这在业务侧有非常好的口碑因为业务方不用担心“AI 乱操作”导致事故。4.2 工具注册与安全边界Agent 的权限不能比人还大工具调用是 Agent 的核心能力但也是最容易出安全事故的地方。围绕这个我总结出三个必须坚持的原则全是实操中犯错后悟出来的第一工具 schema 必须严格定义参数。我给每个工具都写了一个 Pydantic 模型参数名、类型、是否必填、取值范围、描述信息全部结构化定义。这么做有两个好处一是模型生成调用参数时可以按照 schema 来减少格式错误二是服务层可以按 schema 做校验非法参数直接拒绝不进入执行层。比如“发送工单”这个工具参数必须是ticket_id字符串和action枚举值如果模型传了个不存在的 enum 值直接拦截不给底层造成脏数据。第二工具返回结果要做脱敏和裁剪。Agent 在执行完工具后拿到的结果应当控制在一个合理范围。比如查用户信息的工具返回给模型的字段只有“姓名脱敏后的名字、部门、岗位”涉及身份证号、手机号、住址这些敏感字段直接在工具层就过滤掉模型根本看不到。这样即使 prompt 被恶意注入也拿不到敏感信息。第三工具列表本身要按用户角色动态下发给模型。什么意思呢就是同一个模型实例面对普通员工和管理员时可见的工具集合是不同的。普通员工看不到“导出全部用户数据”这种工具管理员也只在特定场景下才看到。这个实现起来很简单请求进来后根据用户的 role 过滤工具注册表再把过滤后的工具 schema 塞进 system prompt。成本极低但安全性提升一个量级。4.3 Prompt 与上下文管理内网场景下容易被低估的细节很多人以为 Agent 效果不好就是模型不行其实很多问题是出在 prompt 和上下文管理上。这次我们沉淀了一套 prompt 编写规范核心就三条system prompt 明确角色边界、few-shot 示例跟真实业务贴合、输出格式强约束。角色边界这条要展开讲。因为内网场景涉及大量内部系统Agent 经常会“不懂装懂”编造一个工单号或者虚构一个操作结果。我在 system prompt 里加了一句这样的话你只能基于工具返回结果回答如果工具返回为空或错误必须明确告诉用户“目前没有查询到相关信息”并建议用户联系人工客服。就这么一句简单的约束幻觉率肉眼可见地下降了。few-shot 示例我建议不要用通用的例子一定要用真实的业务语料。比如工单分诊你给模型看三个真实工单脱敏后是如何被分诊到不同部门的模型在线上表现会明显好于用“苹果好吃吗”这种通用例子。诀窍是正面例子放两个放一个反例一个工单被错误分诊的案例这样模型能学到边界在哪里。输出格式强约束这块我建议直接在 prompt 里要求 JSON 输出然后服务层做 schema 校验。LangGraph 的一些模型输出解析方法在隔离内网也能用但要求模型“只输出 JSON”往往不靠谱尤其在工具调用场景下。后来的做法是让模型先把分析过程写在thinking字段里再输出结构化结果。这样就算 JSON 有格式问题我们也能从 thinking 里看出模型的推理过程方便排查。5. 并发处理与服务性能调优5.1 大模型并发三个“拦路虎”显存、队列、超时既然热词里出现了“AI Agent 怎么扛并发”这一节就必须重点讲讲并发因为我们在这上面的教训太深刻了。一开始模型服务直接裸奔FastAPI 收到用户请求后直接调 vLLM 接口结果用户一多GPU 显存被打满部分请求直接 OOM 崩溃更麻烦的是崩溃后 vLLM 要重新加载模型恢复时间超过三分钟。后来我们做了一个三级防护体系效果很稳。第一级是 API 入口限流FastAPI 层用令牌桶算法每秒只能进 20 个 Agent 请求超过的请求立即返回“系统繁忙请稍后重试”。第二级是有界队列令牌桶放行后请求进入一个长度 200 的队列排队时间超过 30 秒就超时返回。第三级是模型服务并发数限制vLLM 的--max-num-seqs参数设置成 8超过这个数的新推理请求在模型层继续排队。这一套下来实测效果是高峰 50 个并发请求时200 队列不会积压太久平均响应时间从原来的 120 秒压到 40 秒左右超时率从 15% 降到了 1% 以内。核心心法就一条不要让用户的请求直接打到模型上中间必须有一层缓冲和熔断。5.2 流式输出让用户等待体验下降一半Agent 场景比纯对话场景更耗时因为中间有多轮工具调用和推理动辄几十秒。如果不做流式输出用户盯着一个 loading 转圈一分钟体感极其糟糕。我们这次给所有面向用户的接口都加了 SSE 流式响应。实现不复杂FastAPI 原生支持 StreamingResponse。但有几个细节要注意第一流式输出时如果某个工具调用耗时太长你需要在流里定时发一个“心跳事件”否则前端以为链接断了直接超时。第二工具调用的中间状态也要流式推送比如“正在查询工单系统…”、“正在分析告警数据…”用户能看到 Agent 正在干什么体感完全不同。我试过把工具状态做成动态的步骤条用户体验反馈非常好。第三流式输出不等于放弃超时控制总时长超过 60 秒必须强制断开否则后端线程池容易被慢请求占满。5.3 缓存策略同问同答不重复烧钱烧算力内网部署模型不花 API 钱但 GPU 算力是有限的。我们加了一层语义缓存针对高频的、确定性较高的问答做缓存。做法是用 embedding 模型把用户问题向量化去 Milvus 里做相似度检索相似度超过 0.95 的直接返回历史答案不再走 Agent 流程。这个设计的坑在于“相似”如何定义。一开始我用 0.98 的阈值缓存命中率太低降到 0.93 又出现答非所问的情况。后来改成了“双阈值”0.97 以上直接命中0.93 到 0.97 之间返回“你可能想问的是XXX”的确认卡片由用户点选确认后复用缓存。这样既保证了准确率又提高了命中率。超时阈值和缓存策略的最终参数我整理成了一个小表方便直接参考配置项取值说明API 入口限流20 req/s令牌桶超出直接返回 503有界队列长度200排队超 30 秒返回超时vLLM 最大并发序列8超出后模型层排队流式输出心跳间隔5 秒防止连接被断开单请求总超时60 秒强制断开慢请求语义缓存高阈值0.97直接命中复用答案语义缓存确认阈值0.93返回确认卡片让用户点选6. 常见问题与排查技巧实录6.1 模型服务偶发 OOM 与显存碎片问题这个问题在长稳运行后暴露得最明显。现象是白天运行正常跑了两三天后某次并发一高vLLM 直接崩掉日志里出现 CUDA out of memory。一开始我以为是max-model-len设太大调小之后还是有偶发崩溃。后来把gpu-memory-utilization从 0.9 降到 0.85并且每次推理结束后主动执行显存碎片整理vLLM 配置里启用--enforce-eager终于稳定了。要提醒的是--enforce-eager会牺牲一点首次推理延迟但换来的是长期稳定性。内网项目里“稳定”比“性能好看”重要得多。6.2 工具调用参数幻觉模型编造参数怎么办这是 Agent 场景里最头疼的问题之一。比如模型生成调用“查询工单”工具时传入了一个根本不存在的工单号。排查发现问题往往不在模型而在工具 schema 描述不够具体。我在工具的description字段里补上了“工单号的典型格式为 WO 开头加 8 位数字如 WO20240001”模型就很少再编造格式了。另一个办法是在工具执行结果里返回标准错误码比如“TICKET_NOT_FOUND”然后 Agent 拿到后能自动给用户解释。这里要做一个重试机制工具执行失败后把错误信息返回给模型让模型重新规划重试次数上限 2 次超出后进入兜底话术。6.3 离线环境调试利器自研 trace 与日志回放隔离内网不能连 LangSmithAgent 的推理过程难以追溯。我们从第一天就坚持写本地日志整个 trace 链路包含完整 prompt、完整响应、工具调用记录、每一步的耗时、token 消耗、最终回答。后来遇到线上问题直接根据 session_id 把整个 trace 拉出来一步一步回放比什么可视化工具都好用。日志存储选的是 ClickHouse因为要支持按 session_id 查历史轨迹、按时间范围扫描、按错误类型聚合这套查询在 ClickHouse 里性能非常好。日志还有一个隐藏价值可以用来做回归测试。每次修改 prompt 或工具逻辑后我们把一批固定的历史问题重新跑一遍用 text similarity 对比新旧答案偏差大的就人工复核。这个机制帮我避免过很多次“改好了 A 问题、带崩了 B 问题”的尴尬情况。6.4 知识库漏召回与坏数据识别知识库上线初期经常出现用户明明问的是“报销流程”Agent 却答非所问地返回了“请假制度”。排查发现两个原因一是 chunk 切分时不包含标题上下文导致一段被切出来的文字丢了“所属文档标题”这个语境信息。我后来在切分时给每个 chunk 的 content 前自动拼接了“所属文档报销管理制度2024版章节第二章 报销标准”召回质量立刻改善。二是 embedding 模型对模糊缩写不敏感比如“OA 系统”和“办公自动化系统”在向量空间里距离较远。我的解决方案是加了一个同义词映射表在文档预处理阶段把缩写统一替换或者把同义词作为扩展查询词一起喂给向量检索。6.5 流式输出中断、前端显示异常等问题排查前端收到不完整的 SSE 数据流是另一个高发问题。最常见的是 Nginx 层缓冲导致数据不能实时推送我一开始在 Nginx 配置里关掉 proxy_buffering 才解决。另外FastAPI 的 StreamingResponse 如果中途产生异常默认连接会直接断开前端只能捕获 error 事件。后来我在生成器里包了一层 try-except异常时先推送一个错误事件再断开前端就能弹窗提示“Agent 暂时开小差了”体验好很多。7. 最后分享一点实践心得隔离内网下的 AI Agent 工程本质上不是算法问题而是系统工程问题。模型选型重要但更重要的是依赖闭环、服务治理、安全边界和可观测性。我最大的体会是不要把注意力全放在“模型聪明不聪明”上要多花时间在设计可靠的工程链路上。Agent 的每一次工具调用、每一次状态转移、每一次并发排队都可能成为故障点只有把每个节点都治理清楚了Agent 才能“下地干活”。另外一个小技巧在做隔离内网部署前先花一周把全链路的离线依赖清单理清楚包括 Python 包、模型文件、向量库安装包、前端静态资源、系统动态库全部列成清单并验证版本兼容。这个动作越早做越好因为一旦进了内网再想补包费时费力还不一定合规。最后再给个建议内网 Agent 项目上线后一定要留一台用于测试的“仿真机器”型号、驱动、依赖都和生产保持一致很多问题在这台机器上能提前暴露出来。踩过这次坑之后我自己的结论是越是在受限环境里越要认真对待工程细节。地面上的菜园子谁都会种温室里种出好菜才是真功夫。