尧图网页设计 
在隔离内网里把AI Agent真正跑起来是很多做政企、金融、能源项目的同学躲不掉的硬仗。我自己的亲身体会是开发机上Agent跑得风生水起一问一答行云流水结果把代码和模型一搬进生产隔离网当场傻眼——模型权重传不进去、Python依赖装不上、内部API的鉴权体系跟Agent完全不兼容光是让AI“开口说话”就折腾了三天。这篇文章主要聊我在隔离内网环境下搭建AI Agent的完整工程思路架构怎么分层、模型怎么私有化部署、依赖怎么离线迁移、Agent怎么编排内网工具、多人并发访问时怎么保证稳定不崩。适合正在做政企项目落地、或者打算把Agent能力产品化的同学参考也适合那些刚接手内网环境、对“离线部署”理解还停留在拷个wheel包阶段的新手。1. 隔离内网下的AI Agent到底难在哪1.1 先分清隔离等级再谈方案很多人一听到“隔离内网”第一反应就是“服务器没网”但实际企业环境里的隔离情况千差万别。我拿到一个新项目环境要做的事情从来不是急着装模型而是先把环境等级摸清楚。最常见的是纯生产隔离网服务器全部在私有网段里没有互联网出口用户只能通过堡垒机登录数据库、文件存储、消息队列全都在内网里任何外部资源都不可达。这种环境最狠意味着所有代码、依赖、模型权重的引入都必须通过人工拷贝或审批流程完成一步不到位就卡住。第二种是白名单隔离区留了少量合规出口比如只允许访问指定的依赖源或者模型托管站点但整体网络策略仍然不允许随意访问外部资源。这种环境会稍微舒服一点可以直接从镜像源拉包但需要网络管理员开放相应白名单走流程仍然要时间。第三种是单向导入网数据只能从受控通道让外部信息进入内网反向流出基本不可能常见于数据安全要求很高的组织。这种环境下做Agent不只要考虑模型和依赖怎么进内网还要额外想清楚微调数据、工具调用日志能不能按合规要求导出。我的建议是开工前先写一份环境调研清单服务器CPU型号、核数、GPU型号和显存、操作系统版本、Python版本、有没有Docker权限、有没有内网镜像仓库、有没有专门的离线文件拷贝通道、传输通道的带宽和审批周期是多少。很多时候项目延期不是因为Agent算法不行而是模型文件在审批流程里多走了两周。这个清单直接决定后面是“全离线交付”还是“混合离线交付”千万不要等到部署阶段才去跟网络管理员拉扯端口和访问策略。1.2 三座山模型依赖、软件依赖、工具链隔离内网做Agent首先遇到的第一座山是模型。AI Agent没有模型就是空壳而隔离环境里所有对话、规划、工具调用结果的理解都必须靠本地推理服务完成。这意味着团队必须选择能实际部署的开源模型通义千问Qwen系列、ChatGLM、DeepSeek的蒸馏版本都是常见选择同时要对硬件资源做精确预算因为大模型推理的显存占用和并发量有直接关系7B模型的FP16权重随便就超过14GB如果内网只有普通百兆传输通道拷贝整个模型目录确实会让人等到崩溃。第二座山是软件依赖。LangChain、LangGraph、FastAPI这些Python生态的包连同pydantic、openai、numpy、torch等底层库版本之间有着极其复杂的依赖关系。普通网络环境下可以边装边查但在隔离内网里没法这样做一旦某个包版本不对后面所有组件都跟着遭殃。最稳妥的办法是在一台合规的联网机器上把所有依赖打包成离线源版本锁死再一次性搬进内网安装后还要跑依赖检查把潜在冲突在运行之前就暴露出来。第三座山是工具链。Agent产品化的核心价值在于调用工具——查内网数据库、调内部平台API、写文件、跑脚本。这些内部系统往往没有统一API规范有的走HTTP有的走RPC有的只暴露底层SDK更麻烦的是权限控制很多内部接口在Agent这边根本没有专用服务账号。你不能让模型像人一样拿着密码表到处试工具层封装必须在“给Agent足够权限”和“保证安全审计”之间找到平衡。我见过不少项目死在最后一公里模型能答话但没法真正调通内部系统Agent就变成了一个高级聊天机器人失去落地价值。2. 整体架构把Agent拆成能离线落地的模块2.1 接入层、编排层、推理层、知识层怎么分工我习惯把隔离内网下的Agent架构拆成四层每层之间只通过约定好的接口通信。先看整体拓扑前端/客户端 ↓ HTTP/WebSocket/SSE FastAPI 接入层API、会话管理、鉴权、限流 ↓ LangGraph 编排层Agent状态机、工具调度、多轮上下文 ↓ LLM 推理层vLLM 部署的开源模型OpenAI兼容接口 ↓ 辅助服务Milvus/Chroma 向量库 · BGE Embedding/重排服务 · 内网工具API网关最上层是接入层负责接收用户请求、管理会话、做身份认证和限流我一般用FastAPI实现因为它的异步特性对长连接和流式输出非常友好。第二层是编排层也就是Agent的“大脑”负责理解用户意图、决定调用哪些工具、维护多轮上下文这是LangGraph这类框架的主场。第三层是推理层通过vLLM部署本地开源模型对外暴露OpenAI兼容接口隔离内网里不推荐绑死某个私有模型协议兼容接口能让上层代码完全不用关心模型厂商。第四层是知识层包括向量数据库、Embedding服务、重排服务给Agent提供外部知识检索能力。以前我们做第一版Agent时图省事把所有逻辑塞在一个Python文件里模型调用、工具调用、知识检索全部耦合在一起。结果上线后每次改动都要重新打包、重新过审批效率低到让人绝望。这次拆层以后只要接口定义不变任何一层的内部优化都不需要动其他层。隔离内网的交付特点就是一次运输、长期使用分层带来的解耦价值比公网环境大得多。你甚至可以把推理层换成不同硬件设备只要接口一致编排层完全不需要改代码。2.2 为什么我不首选Spring AI和Rust来实现主流程近一年不少团队在问能不能用Spring AI或者Rust来写Agent。我的结论是如果你的团队本来就是Java栈Spring AI确实是个可以考虑的方案它把模型调用、Prompt模板、工具调用都做了一定抽象而且Java生态在大型政企系统里天然有优势。但如果还在选型阶段我建议主流程还是用Python加LangGraph/LangChain。原因不是Python代码比Java漂亮而是Agent编排生态在Python侧最成熟遇到问题能搜到的资料也最多。隔离内网里试错成本极高团队在这上面没有反复试验的资本。Rust做Agent主流程更是如此性能再好也抵不过生态欠缺。我见过用Rust写高性能网关、把Python Agent编排放在后面的混搭架构这样确实能提升吞吐但前提是团队本身就是Rust团队而且有足够时间处理编译链路、交叉编译依赖和离线crate管理的问题。如果你只是想赶时髦用Rust劝你冷静隔离内网项目最怕的就是额外变量。对我个人来说Python负责核心逻辑Rust负责性能敏感的边角组件是比较舒服的组合。同样如果你团队全是Java工程师且不想引入新语言Spring AI也比强行让所有人学Python更合理关键还是看团队长期维护能力。3. 模型私有化部署内网Agent的地基工程3.1 开源模型怎么选显存怎么估算隔离内网里没有条件反复试模型选型必须一次到位。常见的几类模型我都实际部署过给出一份参考表格模型参数量FP16显存估算推荐硬件适用场景Qwen2.5-7B-Instruct7B14GB权重 2~4GB KV Cache单卡24GB通用对话、工具调用、RAG问答Qwen2.5-14B-Instruct14B28GB权重 4~8GB KV Cache双卡24GB/A100 40GB复杂指令、深度推理DeepSeek-R1-Distill-Qwen-7B7B14GB权重 3GB KV Cache单卡24GB推理要求高的场景GLM-4-9B-Chat9B18GB权重 4GB KV Cache单卡32GB中文能力较强的通用场景显存估算公式不复杂模型权重大概等于参数量乘2字节FP16下7B模型就是14GB左右KV Cache则取决于并发数和上下文长度上下文越长占得越多。比如拿24G显存跑7B模型FP16权重占14GB剩下10GB给KV Cache和计算开销通常能支持几十并发、4K上下文以内的对话如果把上下文拉到32K并发就得往下调。如果显存只有16G优先上INT4或AWQ量化量化后的7B模型权重只有4到5GB整体要求低不少但会有一定精度损失。推荐做法是拿典型业务Prompt做一轮基线测试观察首字时延和吞吐再决定要不要量化不要一开始就为了省显存牺牲效果。3.2 vLLM部署与OpenAI兼容接口vLLM是目前隔离内网里最值得投入的推理框架支持Continuous Batching和PagedAttention对多用户并发非常友好。部署命令通常长这样# 在GPU服务器上启动Qwen2.5-7B推理服务 vllm serve /opt/models/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8001 \ --served-model-name qwen7b \ --gpu-memory-utilization 0.9 \ --max-model-len 8192几个参数值得多说一句。--served-model-name是给上层调用时的模型别名可以随便起以后换模型不一定要改业务代码--gpu-memory-utilization控制显存利用率0.9意味着留10%给模型仓库和碎片--max-model-len限制最大上下文长度防止个别用户一次性把显存吃满。启动后可以用curl验证服务是否正常curl http://127.0.0.1:8001/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen7b,messages:[{role:user,content:你好}],stream:false}看到正常JSON返回就说明推理服务通了。这里有个细节隔离内网里的验证方式一定要提前确认好有些内网机器连curl都没有或者端口没有放通。我建议在接入层单独写一个/healthz探活接口定期检查模型服务是否可用而不是让用户等半天才发现后端已经挂了。另外vLLM启动日志里如果出现下载行为的提示一般是在尝试获取本地模型目录里的小配置文件等模型完全加载后日志会稳定下来不用太紧张。3.3 Embedding模型与重排模型也得上内网除了对话模型RAG链路还依赖Embedding模型和重排模型。这类模型规模小通常几个GB以内常见选择是BAAI/bge-large-zh-v1.5中文检索效果好重排推荐bge-reranker-v2-m3。部署方式和主模型类似打成FastAPI服务输入文本返回向量或者输入query加候选文档返回得分。这里有一个容易被忽略的点Embedding模型名称带zh表示中文优化但如果内网知识库包含大量中英文混合文档建议直接用bge-m3这类多语言模型否则英文部分的检索效果会差一截。模型就算跑在CPU上也能出结果但向量化速度会慢很多尤其是批量建库时几千个文档可能要跑几个小时。有GPU条件的话尽量给Embedding模型分配一块独立小卡比如T4或L4别和主对话模型抢显存。我踩过一个坑把Embedding服务和主模型放在同一张卡上结果建库时主模型响应突然变慢前台用户以为系统崩溃了。隔离内网里服务资源需要提前规划能分开就分开不能分开也要做好资源限制。4. 依赖与模型权重的离线迁移4.1 pip离线包准备离线环境下最痛苦的就是Python依赖管理。我的流程是先准备一套完整离线包再把它们复制进内网。准备离线包的命令如下# 在一台能联网的同架构机器上准备离线包 mkdir /work/wheels pip download -r requirements.txt -d /work/wheels \ --platform manylinux2014_x86_64 \ --implementation cp \ --python-version 311 \ --only-binary:all:参数里的--platform必须跟目标内网机器一致如果目标是arm64要换成对应的aarch64参数很多包只有源码包没有二进制包比如某些Rust扩展这时可以把--only-binary去掉让pip把源码包也拉下来但内网编译时又得准备编译工具链相当麻烦。所以我在选型时会刻意避开冷门的、强依赖C扩展的库能不用就不用。锁版本是关键中的关键。requirements.txt里全部写上版本号LangChain的版本更新很快大版本之间API差异大到离谱开发机上跑通的代码版本必须和内网安装的版本完全一致差一个小版本都可能踩坑。离线安装时用pip install --no-index --find-links/work/wheels -r requirements.txt--no-index让pip不要尝试访问任何远程源直接使用本地包。安装完以后跑一遍pip check看看有没有依赖冲突这个命令在隔离环境里特别有用可以提前把依赖三角问题暴露出来。我遇到过的情况是pydantic和langchain-core互相要求不同版本表面安装成功运行时导入直接崩溃这类问题只有尽早检查才能避免。4.2 Docker镜像离线导入如果隔离内网允许使用Docker事情会简单一些。做法是在合规联网机器上先拉取基础镜像然后导出docker pull python:3.11-slim docker save python:3.11-slim -o /work/python311slim.tar # 拷贝到内网后 docker load -i /work/python311slim.tar环境再规整一点可以在内网搭一个Harbor仓库把所有镜像打上内网地址的tag统一从Harbor分发。这里有个小教训基础镜像的版本要尽量精简且固定不要每次拉latest因为latest在不同时间含义不一样离线环境一旦固化就很难修改。还有人会在内网服务器上装Docker后直接执行docker pull结果卡半天才发现根本没网络。我建议所有Docker命令都写成脚本先检查本地镜像是否存在不存在就直接报错别让部署人员在无意义的等待里消耗时间。4.3 模型权重离线搬运模型权重是最重的货物搬运策略直接影响部署周期。先在一台联网机器上传下载模型# 方式一HuggingFace huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir /work/Qwen2.5-7B-Instruct # 方式二ModelScope国内网络更友好 modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /work/Qwen2.5-7B-Instruct拉下来之后把整个目录递归传到内网存储上例如使用scp或受控拷贝通道。有一点容易被忽视HuggingFace下载时会产生.cache目录直接把整个缓存目录里的完整文件都拷到内网反而更可靠单独拷贝容易漏掉多分片文件。传到内网后vLLM加载时直接指定本地路径不需要联网校验。如果加载时报找不到权重多半是目录里缺少model.safetensors.index.json之类的索引文件把完整目录拷全就没事了。4.4 其他语言生态的离线注意点如果团队用的是Spring AI对应要解决的是Maven依赖离线问题。可以在合规联网环境里把依赖全量拉成mvn-repo目录再放到内网作为私有仓库Rust项目则用cargo vendor把依赖源码拉下来再配置.cargo/config.toml让构建时使用本地vendor目录。这些流程都比pip离线更繁琐所以非Java或Rust强绑定团队我不建议在隔离内网里赌这些生态的成熟度。思维模式其实是一样的所有外部依赖都必须变成内网可见的静态资源然后通过工程手段固化成可复现的离线安装包。5. Agent编排与工具接入5.1 最小可运行的LangGraph编排LangGraph的核心优势是把Agent流程定义成显式状态图每个节点都是普通Python函数。先看一个最小例子from langgraph.graph import StateGraph, END from typing import TypedDict from langchain_openai import ChatOpenAI from langchain_core.tools import tool class AgentState(TypedDict): messages: list next_step: str tool def query_internal_db(sql: str): 查询内网业务库参数为完整SQL语句 # 实际实现里走内网数据库连接池 return 订单数量: 1280 llm ChatOpenAI( base_urlhttp://model-gpu:8001/v1, api_keyEMPTY, modelqwen7b, temperature0.3 ) def run_tools(state): out query_internal_db.invoke(select count(*) from orders) return {messages: state[messages] [out]} def answer(state): resp llm.invoke(state[messages]) return {messages: state[messages] [resp.content]} graph StateGraph(AgentState) graph.add_node(tools, run_tools) graph.add_node(answer, answer) graph.add_edge(tools, answer) graph.add_edge(answer, END) graph.set_entry_point(tools) app graph.compile()这只是一个示意真实项目中还会加入历史会话归档、工具执行超时、LLM调用失败重试等节点。这里想强调的点是状态图把Agent过程变成可追踪的数据流每个节点输入输出在日志里都能完整看到审计和排错比黑盒Agent舒服太多。隔离内网里这个特性尤其宝贵因为系统出问题时你不可能打开外网查日志必须靠内网日志体系就能快速定位。如果团队完全不熟悉LangGraph也可以先用原生Python写循环加工具分发等复杂度上来了再平滑迁移。让我选我倾向于用图做显式编排毕竟隔离环境里的稳定性优先于一切。5.2 内网工具封装内网工具五花八门我的原则是给每个工具一个清晰的名字和docstring。LLM是靠函数名和说明来选择工具的说明含糊模型就会瞎猜。比如query_internal_db的docstring里要写清楚参数含义、返回格式、适合什么场景如果工具执行时间长还要注明“该工具可能耗时10秒以上”这样模型规划时会更谨慎地决定调用次数。工具内部必须有超时和异常处理不能让一次数据库超时把整个Agent卡死。还有安全细节内网接口的鉴权信息不要写在Agent代码里更不要扔进模型上下文。统一放到配置中心或者环境变量工具函数启动时注入。否则模型有可能在对话中无意识地把Key打印出来这在隔离网环境里是重大安全事故。我一般会把工具调用也记入审计日志记录谁在什么时间调了哪个工具、入参是什么、出参是什么这样一旦出问题能追溯。隔离内网的安全要求通常比公网更高工具层的权限设计宁可保守也要保证不出事给Agent开的权限可以先用最小化白名单确定需要再逐步扩大。5.3 知识库RAG链路RAG链路在隔离内网里我做得比较克制文档量不大的时候直接就用Chroma单机版省去部署Milvus集群的麻烦。整体流程是文档预处理、切片、Embedding入库、检索、重排、拼Prompt、送LLM。切片参数我会结合文档内容调整常见配置是chunk_size400、chunk_overlap50如果是法规政策类文档会按章节结构切避免句子被硬生生切碎。检索阶段先取top30候选重排后取top5这一步很关键能明显提升答案相关性尤其当知识库里有大量相似内容时。Prompt模板里通常要强调“只基于检索内容回答不要编造”。这段拼接逻辑写在编排层的节点里不跟模型调用混在一起。向量库本身在隔离内网部署时也有离线依赖麻烦Chroma相对轻量pip包就能跑Milvus在高数据量场景下更合适但依赖Docker和etcd运维复杂度直线上升。所以我的原则是先让链路跑通再谈规模。内网知识库如果只有几万条文档Chroma完全够用没必要人为制造运维负担。6. 并发与稳定性Agent怎么扛住多人同时用6.1 并发瓶颈在哪很多同学问AI Agent怎么扛并发我的回答是先找出瓶颈在哪。Agent的一次对话往往不是一次LLM调用而是多轮规划和工具调用单请求可能调用三四次模型同时还要串行等待工具返回。这意味着后端Agent服务的并发能力由三块决定LLM推理服务的吞吐、外部工具调用的延迟、接入层的连接管理能力。其中LLM推理通常是主要瓶颈大模型解码是逐token生成的没有合理批处理显存利用率和GPU利用率都会很低。vLLM的Continuous Batching正是在解决这个问题它把多个请求的生成阶段动态拼在一起跑显著提高吞吐。但即便vLLM再强接入层不加保护一拥而入的请求照样能把服务打挂。我自己习惯做一个简单的容量估算假设单用户一轮对话平均触发3次LLM调用每次调用消耗8秒GPU时间如果目标是满足20个用户同时使用最粗暴的估算就是3乘20乘8等于480秒的GPU占用时间在排队。如果模型服务本身吞吐不高任何乐观估计都会在真实场景里破功。所以并发设计必须从模型服务、编排层、接入层三个维度同时下手不能只优化一个环节。6.2 异步接口与流式输出多用户在线场景下接入层必须是异步的否则长连接会占用大量进程资源。FastAPI的异步特性配合StreamingResponse可以很好支撑流式输出from fastapi import FastAPI from fastapi.responses import StreamingResponse import asyncio app FastAPI() async def event_stream(user_input: str): # 伪代码把 LLM 的流式输出转发给前端 async for chunk in agent_astream(user_input): yield fdata: {chunk}\n\n app.post(/chat) async def chat(payload: dict): return StreamingResponse( event_stream(payload[message]), media_typetext/event-stream )前端用EventSource或者fetch的ReadableStream接口就可以逐字显示回复。我在开发时发现如果不做流式输出一个十几秒的回复会让用户以为系统死了而且会加重网关超时压力流式输出让首字延迟从十几秒降低到两三秒体感完全不一样。异步接口的意义在于等待模型返回的时间段不阻塞其他请求的处理配合数据库连接池和HTTP客户端连接池单机能支撑大量长连接。6.3 限流、超时与重试多人使用时必须同时做接入层限流和编排层超时。接入层可以用Nginx的limit_req或FastAPI里加依赖项做IP/用户维度限流限制每用户每秒请求数。但比限流更重要的是超时LLM调用设置最大等待时限工具调用单独设置更短的超时超时后Agent要把异常当成一种工具结果反馈给模型让模型决定是重试还是换方案而不是直接断掉连接。还有一个坑工具调用偶尔会超时但不能无限重试。我会给整个Agent状态机加一个最大步数限制超过限制就干脆利落地返回“当前查询太复杂请简化后再试”。很多线上事故都是Agent进入静默死循环日志还在刷用户却一直等不到结果。有明确的失败出口比让模型自由发挥更重要。隔离内网里没有外部监控服务这些兜底逻辑必须写进应用代码本身不能指望靠运维事后介入。6.4 健康检查与监控隔离内网虽然不对外但监控不能省。接入层要放一个/healthz返回版本号、模型服务状态、向量库状态模型服务侧用nvidia-smi定期记录显存和GPU利用率把指标推到内网PrometheusAgent编排日志里要记录每次LLM调用的耗时、token数、工具调用是否成功。我踩过的坑是模型服务本身还活着但显存碎片化严重导致新请求排队时间越来越长表面看服务正常。所以光有健康检查不够必须监控推理队列长度超过阈值就告警。日志和监控数据属于内网资产尽量不要跟外部系统交换更不能为了方便把日志转发出去。隔离内网系统的安全边界本身很严格如果日志通道反而成了新的漏洞那就得不偿失。我个人的习惯是把监控告警也做成内网自包含方案所有组件部署在同一个可用区内用不起眼但稳定的方式把异常推送出来。7. 常见问题与排查技巧实录7.1 问题速查表下面这份表格是我在实际项目里反复遇到的情况可以直接拿来排查现象可能原因排查与解决模型服务OOM启动失败--max-model-len过大、--gpu-memory-utilization过高调低上下文长度留出10%显存余量必要时启用量化LLM调用连接拒绝base_url写错、端口未放通、模型别名不对用curl测试/v1/models确认served-model-namepip离线安装后缺依赖pip download只下了顶层包子依赖遗漏用-r requirements.txt离线后运行pip check工具调用频繁超时内部接口慢、没有超时保护工具内加时间控制限制调用次数异常转为文本SSE流式输出中断反向代理缓冲或超时关闭代理缓存开启HTTP/1.1增加SSE心跳RAG检索效果差切片切碎、Embedding语言不匹配按章节切片换中文或多语言模型增加重排模型服务排队越来越长并发过大、显存碎片限制接入并发配置vLLM并发上限增加实例表格只能帮速查下面几个坑我想单独拿出来聊因为它们都不太容易一眼定位。7.2 几个让我印象深刻的坑第一个坑是离线包平台不一致。有一次我在联网机器上准备pip离线包时忘了加平台参数结果内网arm64机器安装时直接报“is not a supported wheel on this platform”。排查下来才发现下载的包全是x86_64的白折腾了一整天。后来我把准备离线包的过程写成了CI脚本强制指定平台和Python版本并且每次发版前先在一台全新内网机器上跑一遍干净安装验证宁可慢一点也要保证可复现。第二个坑是模型服务地址写成了localhost。很多同事在接入层配置模型服务时习惯写localhost:8001开发机上没问题但接入层和模型服务不在同一台机器时localhost指向的是接入层自己自然连不上。内网环境没有外部DNS我会把模型服务地址统一配置为http://model-gpu:8001/v1然后在hosts文件里固定映射这样迁移机器时只改一处。第三个坑是LangGraph工具节点陷入死循环。有次遇到Agent在工具调用环节反复调用同一个接口日志里全是同样的SQL用户端一直转圈。原因是Prompt里没有告诉模型“如果工具返回结果和上一次一样就应该结束”。我后来在工具返回内容里加了标记比如“本结果与上次相同若问题未解决请换一种方式”并在状态机里限制同一工具最多调用两次。这个经验说明Agent工程的稳定性很多时候不是靠模型聪明而是靠流程兜底。第四个坑是RAG检索召回了一堆相似文档模型答非所问。原因是Embedding模型只有中文单语而知识库里大量英文文档没有匹配好。后来上了bge-reranker-v2-m3做第二轮筛选top5准确率明显提升。这个教训也提醒我Embedding模型选型一定要先看一眼真实语料构成不能想当然地认为中文环境就只选中文模型。最后说一点个人体会。隔离内网做AI Agent技术上并没有想象中那么炫酷它考验的是把复杂系统打包带走的能力以及对异常流程的敬畏心。我自己最大的感受是越早把离线化、可复现、可监控这几个词吃透后期返工就越少千万不要在开发机上线一时爽然后在隔离内网部署时才发现这个忘了、那个没拷贝。如果这个项目后续还要扩展我建议把离线交付物做成一套标准化目录代码包、模型目录、依赖离线源、部署脚本、配置模板整理清楚后新环境复用会非常顺畅。希望这些记录能帮你少踩几个坑也欢迎有不同实践经验的同学交流互补。 隔离内网AI Agent落地实践：模型私有化与离线迁移全攻略
在隔离内网里把AI Agent真正跑起来是很多做政企、金融、能源项目的同学躲不掉的硬仗。我自己的亲身体会是开发机上Agent跑得风生水起一问一答行云流水结果把代码和模型一搬进生产隔离网当场傻眼——模型权重传不进去、Python依赖装不上、内部API的鉴权体系跟Agent完全不兼容光是让AI“开口说话”就折腾了三天。这篇文章主要聊我在隔离内网环境下搭建AI Agent的完整工程思路架构怎么分层、模型怎么私有化部署、依赖怎么离线迁移、Agent怎么编排内网工具、多人并发访问时怎么保证稳定不崩。适合正在做政企项目落地、或者打算把Agent能力产品化的同学参考也适合那些刚接手内网环境、对“离线部署”理解还停留在拷个wheel包阶段的新手。1. 隔离内网下的AI Agent到底难在哪1.1 先分清隔离等级再谈方案很多人一听到“隔离内网”第一反应就是“服务器没网”但实际企业环境里的隔离情况千差万别。我拿到一个新项目环境要做的事情从来不是急着装模型而是先把环境等级摸清楚。最常见的是纯生产隔离网服务器全部在私有网段里没有互联网出口用户只能通过堡垒机登录数据库、文件存储、消息队列全都在内网里任何外部资源都不可达。这种环境最狠意味着所有代码、依赖、模型权重的引入都必须通过人工拷贝或审批流程完成一步不到位就卡住。第二种是白名单隔离区留了少量合规出口比如只允许访问指定的依赖源或者模型托管站点但整体网络策略仍然不允许随意访问外部资源。这种环境会稍微舒服一点可以直接从镜像源拉包但需要网络管理员开放相应白名单走流程仍然要时间。第三种是单向导入网数据只能从受控通道让外部信息进入内网反向流出基本不可能常见于数据安全要求很高的组织。这种环境下做Agent不只要考虑模型和依赖怎么进内网还要额外想清楚微调数据、工具调用日志能不能按合规要求导出。我的建议是开工前先写一份环境调研清单服务器CPU型号、核数、GPU型号和显存、操作系统版本、Python版本、有没有Docker权限、有没有内网镜像仓库、有没有专门的离线文件拷贝通道、传输通道的带宽和审批周期是多少。很多时候项目延期不是因为Agent算法不行而是模型文件在审批流程里多走了两周。这个清单直接决定后面是“全离线交付”还是“混合离线交付”千万不要等到部署阶段才去跟网络管理员拉扯端口和访问策略。1.2 三座山模型依赖、软件依赖、工具链隔离内网做Agent首先遇到的第一座山是模型。AI Agent没有模型就是空壳而隔离环境里所有对话、规划、工具调用结果的理解都必须靠本地推理服务完成。这意味着团队必须选择能实际部署的开源模型通义千问Qwen系列、ChatGLM、DeepSeek的蒸馏版本都是常见选择同时要对硬件资源做精确预算因为大模型推理的显存占用和并发量有直接关系7B模型的FP16权重随便就超过14GB如果内网只有普通百兆传输通道拷贝整个模型目录确实会让人等到崩溃。第二座山是软件依赖。LangChain、LangGraph、FastAPI这些Python生态的包连同pydantic、openai、numpy、torch等底层库版本之间有着极其复杂的依赖关系。普通网络环境下可以边装边查但在隔离内网里没法这样做一旦某个包版本不对后面所有组件都跟着遭殃。最稳妥的办法是在一台合规的联网机器上把所有依赖打包成离线源版本锁死再一次性搬进内网安装后还要跑依赖检查把潜在冲突在运行之前就暴露出来。第三座山是工具链。Agent产品化的核心价值在于调用工具——查内网数据库、调内部平台API、写文件、跑脚本。这些内部系统往往没有统一API规范有的走HTTP有的走RPC有的只暴露底层SDK更麻烦的是权限控制很多内部接口在Agent这边根本没有专用服务账号。你不能让模型像人一样拿着密码表到处试工具层封装必须在“给Agent足够权限”和“保证安全审计”之间找到平衡。我见过不少项目死在最后一公里模型能答话但没法真正调通内部系统Agent就变成了一个高级聊天机器人失去落地价值。2. 整体架构把Agent拆成能离线落地的模块2.1 接入层、编排层、推理层、知识层怎么分工我习惯把隔离内网下的Agent架构拆成四层每层之间只通过约定好的接口通信。先看整体拓扑前端/客户端 ↓ HTTP/WebSocket/SSE FastAPI 接入层API、会话管理、鉴权、限流 ↓ LangGraph 编排层Agent状态机、工具调度、多轮上下文 ↓ LLM 推理层vLLM 部署的开源模型OpenAI兼容接口 ↓ 辅助服务Milvus/Chroma 向量库 · BGE Embedding/重排服务 · 内网工具API网关最上层是接入层负责接收用户请求、管理会话、做身份认证和限流我一般用FastAPI实现因为它的异步特性对长连接和流式输出非常友好。第二层是编排层也就是Agent的“大脑”负责理解用户意图、决定调用哪些工具、维护多轮上下文这是LangGraph这类框架的主场。第三层是推理层通过vLLM部署本地开源模型对外暴露OpenAI兼容接口隔离内网里不推荐绑死某个私有模型协议兼容接口能让上层代码完全不用关心模型厂商。第四层是知识层包括向量数据库、Embedding服务、重排服务给Agent提供外部知识检索能力。以前我们做第一版Agent时图省事把所有逻辑塞在一个Python文件里模型调用、工具调用、知识检索全部耦合在一起。结果上线后每次改动都要重新打包、重新过审批效率低到让人绝望。这次拆层以后只要接口定义不变任何一层的内部优化都不需要动其他层。隔离内网的交付特点就是一次运输、长期使用分层带来的解耦价值比公网环境大得多。你甚至可以把推理层换成不同硬件设备只要接口一致编排层完全不需要改代码。2.2 为什么我不首选Spring AI和Rust来实现主流程近一年不少团队在问能不能用Spring AI或者Rust来写Agent。我的结论是如果你的团队本来就是Java栈Spring AI确实是个可以考虑的方案它把模型调用、Prompt模板、工具调用都做了一定抽象而且Java生态在大型政企系统里天然有优势。但如果还在选型阶段我建议主流程还是用Python加LangGraph/LangChain。原因不是Python代码比Java漂亮而是Agent编排生态在Python侧最成熟遇到问题能搜到的资料也最多。隔离内网里试错成本极高团队在这上面没有反复试验的资本。Rust做Agent主流程更是如此性能再好也抵不过生态欠缺。我见过用Rust写高性能网关、把Python Agent编排放在后面的混搭架构这样确实能提升吞吐但前提是团队本身就是Rust团队而且有足够时间处理编译链路、交叉编译依赖和离线crate管理的问题。如果你只是想赶时髦用Rust劝你冷静隔离内网项目最怕的就是额外变量。对我个人来说Python负责核心逻辑Rust负责性能敏感的边角组件是比较舒服的组合。同样如果你团队全是Java工程师且不想引入新语言Spring AI也比强行让所有人学Python更合理关键还是看团队长期维护能力。3. 模型私有化部署内网Agent的地基工程3.1 开源模型怎么选显存怎么估算隔离内网里没有条件反复试模型选型必须一次到位。常见的几类模型我都实际部署过给出一份参考表格模型参数量FP16显存估算推荐硬件适用场景Qwen2.5-7B-Instruct7B14GB权重 2~4GB KV Cache单卡24GB通用对话、工具调用、RAG问答Qwen2.5-14B-Instruct14B28GB权重 4~8GB KV Cache双卡24GB/A100 40GB复杂指令、深度推理DeepSeek-R1-Distill-Qwen-7B7B14GB权重 3GB KV Cache单卡24GB推理要求高的场景GLM-4-9B-Chat9B18GB权重 4GB KV Cache单卡32GB中文能力较强的通用场景显存估算公式不复杂模型权重大概等于参数量乘2字节FP16下7B模型就是14GB左右KV Cache则取决于并发数和上下文长度上下文越长占得越多。比如拿24G显存跑7B模型FP16权重占14GB剩下10GB给KV Cache和计算开销通常能支持几十并发、4K上下文以内的对话如果把上下文拉到32K并发就得往下调。如果显存只有16G优先上INT4或AWQ量化量化后的7B模型权重只有4到5GB整体要求低不少但会有一定精度损失。推荐做法是拿典型业务Prompt做一轮基线测试观察首字时延和吞吐再决定要不要量化不要一开始就为了省显存牺牲效果。3.2 vLLM部署与OpenAI兼容接口vLLM是目前隔离内网里最值得投入的推理框架支持Continuous Batching和PagedAttention对多用户并发非常友好。部署命令通常长这样# 在GPU服务器上启动Qwen2.5-7B推理服务 vllm serve /opt/models/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8001 \ --served-model-name qwen7b \ --gpu-memory-utilization 0.9 \ --max-model-len 8192几个参数值得多说一句。--served-model-name是给上层调用时的模型别名可以随便起以后换模型不一定要改业务代码--gpu-memory-utilization控制显存利用率0.9意味着留10%给模型仓库和碎片--max-model-len限制最大上下文长度防止个别用户一次性把显存吃满。启动后可以用curl验证服务是否正常curl http://127.0.0.1:8001/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen7b,messages:[{role:user,content:你好}],stream:false}看到正常JSON返回就说明推理服务通了。这里有个细节隔离内网里的验证方式一定要提前确认好有些内网机器连curl都没有或者端口没有放通。我建议在接入层单独写一个/healthz探活接口定期检查模型服务是否可用而不是让用户等半天才发现后端已经挂了。另外vLLM启动日志里如果出现下载行为的提示一般是在尝试获取本地模型目录里的小配置文件等模型完全加载后日志会稳定下来不用太紧张。3.3 Embedding模型与重排模型也得上内网除了对话模型RAG链路还依赖Embedding模型和重排模型。这类模型规模小通常几个GB以内常见选择是BAAI/bge-large-zh-v1.5中文检索效果好重排推荐bge-reranker-v2-m3。部署方式和主模型类似打成FastAPI服务输入文本返回向量或者输入query加候选文档返回得分。这里有一个容易被忽略的点Embedding模型名称带zh表示中文优化但如果内网知识库包含大量中英文混合文档建议直接用bge-m3这类多语言模型否则英文部分的检索效果会差一截。模型就算跑在CPU上也能出结果但向量化速度会慢很多尤其是批量建库时几千个文档可能要跑几个小时。有GPU条件的话尽量给Embedding模型分配一块独立小卡比如T4或L4别和主对话模型抢显存。我踩过一个坑把Embedding服务和主模型放在同一张卡上结果建库时主模型响应突然变慢前台用户以为系统崩溃了。隔离内网里服务资源需要提前规划能分开就分开不能分开也要做好资源限制。4. 依赖与模型权重的离线迁移4.1 pip离线包准备离线环境下最痛苦的就是Python依赖管理。我的流程是先准备一套完整离线包再把它们复制进内网。准备离线包的命令如下# 在一台能联网的同架构机器上准备离线包 mkdir /work/wheels pip download -r requirements.txt -d /work/wheels \ --platform manylinux2014_x86_64 \ --implementation cp \ --python-version 311 \ --only-binary:all:参数里的--platform必须跟目标内网机器一致如果目标是arm64要换成对应的aarch64参数很多包只有源码包没有二进制包比如某些Rust扩展这时可以把--only-binary去掉让pip把源码包也拉下来但内网编译时又得准备编译工具链相当麻烦。所以我在选型时会刻意避开冷门的、强依赖C扩展的库能不用就不用。锁版本是关键中的关键。requirements.txt里全部写上版本号LangChain的版本更新很快大版本之间API差异大到离谱开发机上跑通的代码版本必须和内网安装的版本完全一致差一个小版本都可能踩坑。离线安装时用pip install --no-index --find-links/work/wheels -r requirements.txt--no-index让pip不要尝试访问任何远程源直接使用本地包。安装完以后跑一遍pip check看看有没有依赖冲突这个命令在隔离环境里特别有用可以提前把依赖三角问题暴露出来。我遇到过的情况是pydantic和langchain-core互相要求不同版本表面安装成功运行时导入直接崩溃这类问题只有尽早检查才能避免。4.2 Docker镜像离线导入如果隔离内网允许使用Docker事情会简单一些。做法是在合规联网机器上先拉取基础镜像然后导出docker pull python:3.11-slim docker save python:3.11-slim -o /work/python311slim.tar # 拷贝到内网后 docker load -i /work/python311slim.tar环境再规整一点可以在内网搭一个Harbor仓库把所有镜像打上内网地址的tag统一从Harbor分发。这里有个小教训基础镜像的版本要尽量精简且固定不要每次拉latest因为latest在不同时间含义不一样离线环境一旦固化就很难修改。还有人会在内网服务器上装Docker后直接执行docker pull结果卡半天才发现根本没网络。我建议所有Docker命令都写成脚本先检查本地镜像是否存在不存在就直接报错别让部署人员在无意义的等待里消耗时间。4.3 模型权重离线搬运模型权重是最重的货物搬运策略直接影响部署周期。先在一台联网机器上传下载模型# 方式一HuggingFace huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir /work/Qwen2.5-7B-Instruct # 方式二ModelScope国内网络更友好 modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /work/Qwen2.5-7B-Instruct拉下来之后把整个目录递归传到内网存储上例如使用scp或受控拷贝通道。有一点容易被忽视HuggingFace下载时会产生.cache目录直接把整个缓存目录里的完整文件都拷到内网反而更可靠单独拷贝容易漏掉多分片文件。传到内网后vLLM加载时直接指定本地路径不需要联网校验。如果加载时报找不到权重多半是目录里缺少model.safetensors.index.json之类的索引文件把完整目录拷全就没事了。4.4 其他语言生态的离线注意点如果团队用的是Spring AI对应要解决的是Maven依赖离线问题。可以在合规联网环境里把依赖全量拉成mvn-repo目录再放到内网作为私有仓库Rust项目则用cargo vendor把依赖源码拉下来再配置.cargo/config.toml让构建时使用本地vendor目录。这些流程都比pip离线更繁琐所以非Java或Rust强绑定团队我不建议在隔离内网里赌这些生态的成熟度。思维模式其实是一样的所有外部依赖都必须变成内网可见的静态资源然后通过工程手段固化成可复现的离线安装包。5. Agent编排与工具接入5.1 最小可运行的LangGraph编排LangGraph的核心优势是把Agent流程定义成显式状态图每个节点都是普通Python函数。先看一个最小例子from langgraph.graph import StateGraph, END from typing import TypedDict from langchain_openai import ChatOpenAI from langchain_core.tools import tool class AgentState(TypedDict): messages: list next_step: str tool def query_internal_db(sql: str): 查询内网业务库参数为完整SQL语句 # 实际实现里走内网数据库连接池 return 订单数量: 1280 llm ChatOpenAI( base_urlhttp://model-gpu:8001/v1, api_keyEMPTY, modelqwen7b, temperature0.3 ) def run_tools(state): out query_internal_db.invoke(select count(*) from orders) return {messages: state[messages] [out]} def answer(state): resp llm.invoke(state[messages]) return {messages: state[messages] [resp.content]} graph StateGraph(AgentState) graph.add_node(tools, run_tools) graph.add_node(answer, answer) graph.add_edge(tools, answer) graph.add_edge(answer, END) graph.set_entry_point(tools) app graph.compile()这只是一个示意真实项目中还会加入历史会话归档、工具执行超时、LLM调用失败重试等节点。这里想强调的点是状态图把Agent过程变成可追踪的数据流每个节点输入输出在日志里都能完整看到审计和排错比黑盒Agent舒服太多。隔离内网里这个特性尤其宝贵因为系统出问题时你不可能打开外网查日志必须靠内网日志体系就能快速定位。如果团队完全不熟悉LangGraph也可以先用原生Python写循环加工具分发等复杂度上来了再平滑迁移。让我选我倾向于用图做显式编排毕竟隔离环境里的稳定性优先于一切。5.2 内网工具封装内网工具五花八门我的原则是给每个工具一个清晰的名字和docstring。LLM是靠函数名和说明来选择工具的说明含糊模型就会瞎猜。比如query_internal_db的docstring里要写清楚参数含义、返回格式、适合什么场景如果工具执行时间长还要注明“该工具可能耗时10秒以上”这样模型规划时会更谨慎地决定调用次数。工具内部必须有超时和异常处理不能让一次数据库超时把整个Agent卡死。还有安全细节内网接口的鉴权信息不要写在Agent代码里更不要扔进模型上下文。统一放到配置中心或者环境变量工具函数启动时注入。否则模型有可能在对话中无意识地把Key打印出来这在隔离网环境里是重大安全事故。我一般会把工具调用也记入审计日志记录谁在什么时间调了哪个工具、入参是什么、出参是什么这样一旦出问题能追溯。隔离内网的安全要求通常比公网更高工具层的权限设计宁可保守也要保证不出事给Agent开的权限可以先用最小化白名单确定需要再逐步扩大。5.3 知识库RAG链路RAG链路在隔离内网里我做得比较克制文档量不大的时候直接就用Chroma单机版省去部署Milvus集群的麻烦。整体流程是文档预处理、切片、Embedding入库、检索、重排、拼Prompt、送LLM。切片参数我会结合文档内容调整常见配置是chunk_size400、chunk_overlap50如果是法规政策类文档会按章节结构切避免句子被硬生生切碎。检索阶段先取top30候选重排后取top5这一步很关键能明显提升答案相关性尤其当知识库里有大量相似内容时。Prompt模板里通常要强调“只基于检索内容回答不要编造”。这段拼接逻辑写在编排层的节点里不跟模型调用混在一起。向量库本身在隔离内网部署时也有离线依赖麻烦Chroma相对轻量pip包就能跑Milvus在高数据量场景下更合适但依赖Docker和etcd运维复杂度直线上升。所以我的原则是先让链路跑通再谈规模。内网知识库如果只有几万条文档Chroma完全够用没必要人为制造运维负担。6. 并发与稳定性Agent怎么扛住多人同时用6.1 并发瓶颈在哪很多同学问AI Agent怎么扛并发我的回答是先找出瓶颈在哪。Agent的一次对话往往不是一次LLM调用而是多轮规划和工具调用单请求可能调用三四次模型同时还要串行等待工具返回。这意味着后端Agent服务的并发能力由三块决定LLM推理服务的吞吐、外部工具调用的延迟、接入层的连接管理能力。其中LLM推理通常是主要瓶颈大模型解码是逐token生成的没有合理批处理显存利用率和GPU利用率都会很低。vLLM的Continuous Batching正是在解决这个问题它把多个请求的生成阶段动态拼在一起跑显著提高吞吐。但即便vLLM再强接入层不加保护一拥而入的请求照样能把服务打挂。我自己习惯做一个简单的容量估算假设单用户一轮对话平均触发3次LLM调用每次调用消耗8秒GPU时间如果目标是满足20个用户同时使用最粗暴的估算就是3乘20乘8等于480秒的GPU占用时间在排队。如果模型服务本身吞吐不高任何乐观估计都会在真实场景里破功。所以并发设计必须从模型服务、编排层、接入层三个维度同时下手不能只优化一个环节。6.2 异步接口与流式输出多用户在线场景下接入层必须是异步的否则长连接会占用大量进程资源。FastAPI的异步特性配合StreamingResponse可以很好支撑流式输出from fastapi import FastAPI from fastapi.responses import StreamingResponse import asyncio app FastAPI() async def event_stream(user_input: str): # 伪代码把 LLM 的流式输出转发给前端 async for chunk in agent_astream(user_input): yield fdata: {chunk}\n\n app.post(/chat) async def chat(payload: dict): return StreamingResponse( event_stream(payload[message]), media_typetext/event-stream )前端用EventSource或者fetch的ReadableStream接口就可以逐字显示回复。我在开发时发现如果不做流式输出一个十几秒的回复会让用户以为系统死了而且会加重网关超时压力流式输出让首字延迟从十几秒降低到两三秒体感完全不一样。异步接口的意义在于等待模型返回的时间段不阻塞其他请求的处理配合数据库连接池和HTTP客户端连接池单机能支撑大量长连接。6.3 限流、超时与重试多人使用时必须同时做接入层限流和编排层超时。接入层可以用Nginx的limit_req或FastAPI里加依赖项做IP/用户维度限流限制每用户每秒请求数。但比限流更重要的是超时LLM调用设置最大等待时限工具调用单独设置更短的超时超时后Agent要把异常当成一种工具结果反馈给模型让模型决定是重试还是换方案而不是直接断掉连接。还有一个坑工具调用偶尔会超时但不能无限重试。我会给整个Agent状态机加一个最大步数限制超过限制就干脆利落地返回“当前查询太复杂请简化后再试”。很多线上事故都是Agent进入静默死循环日志还在刷用户却一直等不到结果。有明确的失败出口比让模型自由发挥更重要。隔离内网里没有外部监控服务这些兜底逻辑必须写进应用代码本身不能指望靠运维事后介入。6.4 健康检查与监控隔离内网虽然不对外但监控不能省。接入层要放一个/healthz返回版本号、模型服务状态、向量库状态模型服务侧用nvidia-smi定期记录显存和GPU利用率把指标推到内网PrometheusAgent编排日志里要记录每次LLM调用的耗时、token数、工具调用是否成功。我踩过的坑是模型服务本身还活着但显存碎片化严重导致新请求排队时间越来越长表面看服务正常。所以光有健康检查不够必须监控推理队列长度超过阈值就告警。日志和监控数据属于内网资产尽量不要跟外部系统交换更不能为了方便把日志转发出去。隔离内网系统的安全边界本身很严格如果日志通道反而成了新的漏洞那就得不偿失。我个人的习惯是把监控告警也做成内网自包含方案所有组件部署在同一个可用区内用不起眼但稳定的方式把异常推送出来。7. 常见问题与排查技巧实录7.1 问题速查表下面这份表格是我在实际项目里反复遇到的情况可以直接拿来排查现象可能原因排查与解决模型服务OOM启动失败--max-model-len过大、--gpu-memory-utilization过高调低上下文长度留出10%显存余量必要时启用量化LLM调用连接拒绝base_url写错、端口未放通、模型别名不对用curl测试/v1/models确认served-model-namepip离线安装后缺依赖pip download只下了顶层包子依赖遗漏用-r requirements.txt离线后运行pip check工具调用频繁超时内部接口慢、没有超时保护工具内加时间控制限制调用次数异常转为文本SSE流式输出中断反向代理缓冲或超时关闭代理缓存开启HTTP/1.1增加SSE心跳RAG检索效果差切片切碎、Embedding语言不匹配按章节切片换中文或多语言模型增加重排模型服务排队越来越长并发过大、显存碎片限制接入并发配置vLLM并发上限增加实例表格只能帮速查下面几个坑我想单独拿出来聊因为它们都不太容易一眼定位。7.2 几个让我印象深刻的坑第一个坑是离线包平台不一致。有一次我在联网机器上准备pip离线包时忘了加平台参数结果内网arm64机器安装时直接报“is not a supported wheel on this platform”。排查下来才发现下载的包全是x86_64的白折腾了一整天。后来我把准备离线包的过程写成了CI脚本强制指定平台和Python版本并且每次发版前先在一台全新内网机器上跑一遍干净安装验证宁可慢一点也要保证可复现。第二个坑是模型服务地址写成了localhost。很多同事在接入层配置模型服务时习惯写localhost:8001开发机上没问题但接入层和模型服务不在同一台机器时localhost指向的是接入层自己自然连不上。内网环境没有外部DNS我会把模型服务地址统一配置为http://model-gpu:8001/v1然后在hosts文件里固定映射这样迁移机器时只改一处。第三个坑是LangGraph工具节点陷入死循环。有次遇到Agent在工具调用环节反复调用同一个接口日志里全是同样的SQL用户端一直转圈。原因是Prompt里没有告诉模型“如果工具返回结果和上一次一样就应该结束”。我后来在工具返回内容里加了标记比如“本结果与上次相同若问题未解决请换一种方式”并在状态机里限制同一工具最多调用两次。这个经验说明Agent工程的稳定性很多时候不是靠模型聪明而是靠流程兜底。第四个坑是RAG检索召回了一堆相似文档模型答非所问。原因是Embedding模型只有中文单语而知识库里大量英文文档没有匹配好。后来上了bge-reranker-v2-m3做第二轮筛选top5准确率明显提升。这个教训也提醒我Embedding模型选型一定要先看一眼真实语料构成不能想当然地认为中文环境就只选中文模型。最后说一点个人体会。隔离内网做AI Agent技术上并没有想象中那么炫酷它考验的是把复杂系统打包带走的能力以及对异常流程的敬畏心。我自己最大的感受是越早把离线化、可复现、可监控这几个词吃透后期返工就越少千万不要在开发机上线一时爽然后在隔离内网部署时才发现这个忘了、那个没拷贝。如果这个项目后续还要扩展我建议把离线交付物做成一套标准化目录代码包、模型目录、依赖离线源、部署脚本、配置模板整理清楚后新环境复用会非常顺畅。希望这些记录能帮你少踩几个坑也欢迎有不同实践经验的同学交流互补。