拓冰网站定制 
1. 项目全景隔离内网里做Agent到底难在哪“AI Agent能帮我们干很多活”这句话在外网环境里说起来很轻松——调OpenAI的API、装个LangChain、几分钟跑通一个带工具调用的助手很多朋友都体验过。但如果把场景换成隔离内网这套流程几乎全部失效没有公网API可用、没有pip源可连、甚至模型权重都要自己想办法搬进去。我这次做的项目就是在这样一个完全隔离的办公网络里从零搭起一套可用的AI Agent工程系统整个落地过程比预想中繁琐得多但也让我把Agent从“demo玩具”推到“生产工具”的完整链路重新梳理了一遍。先说清楚这套系统到底在解决什么问题。内网用户最大的痛点是业务系统数据密级高、不能出网但日常又有大量重复性工作比如查数据库、填报表、梳理文档、追工单。传统做法是写死脚本或表单流程灵活度太低直接上云端AI又不符合安全规定。所以最终目标很明确把大模型、Agent框架、工具调用全部装进内网让用户通过一个网页对话框就能用自然语言指挥Agent去查数、写摘要、走审批流程所有数据和模型推理都留在内网边界之内。这个项目适合谁来参考如果你正在做私有化部署的RAG问答、企业内部知识助手、工单自动处理这类事情或者你手上恰好也有一个上不了外网的环境那么这篇总结里的大部分方案和坑你大概率都会踩到。我会尽量把技术选型、部署细节、性能问题和排查思路都讲透少讲虚的多给能直接用的东西。2. 方案选型为什么是FastAPI、LangGraph和本地模型这套组合2.1 编排框架的取舍Agent的核心不是模型本身而是“让它能根据任务自主决定调用哪些工具、按什么顺序调用”。市面上主流的Agent编排方案有好几种最简单的是ReAct模式——让模型反复思考“下一步做什么、调用什么工具、观察结果”直到完成任务。但纯ReAct有个问题流程完全靠模型现场发挥内网环境下用户容忍度低一旦模型判断失误可能反复调用无用工具既拖慢响应又浪费算力。所以在选型时我更倾向于带图结构的工作流框架。LangGraph就是把Agent的思考、工具调用、状态管理做成一张有向图节点是“行动”边是“转移条件”。相比纯LangChain的链式调用它更接近真实业务流程比如“先查库存→再判断是否满足条件→满足就生成采购单→不满足就转人工审批”这种确定性逻辑用LangGraph表达非常自然。而且LangGraph支持checkpoint持久化Agent执行到一半宕机了可以从最近的节点恢复这对内网生产环境来说很有价值——用户可不想任务跑到80%突然全丢。为什么不选更简单的“函数调用循环”直接撸一个我也考虑过。如果只是做一两个固定场景自己写确实可控性最强。但项目后续要接的工具会越来越多数据库、HTTP服务、文件系统、OA接口没有一个标准化的图编排层后面每个新工具都要改主流程代码维护成本会急剧上升。LangGraph相当于把“流程编排”和“工具实现”解耦新业务场景只要新增一条子图不动主干逻辑。2.2 服务层FastAPI在内网环境里的优势Agent后端服务我用的是FastAPI。选择它并不是因为它“新潮”而是内网部署环境对它太友好了单进程就能提供异步并发能力不用额外引入沉重的应用服务器依赖极少离线打包容易自带OpenAPI文档甲方审计时要接口清单直接导出就行省了很多沟通成本。还有一个很实际的考虑内网经常有多套系统通过HTTP互相调用Agent服务需要对外提供API给前端页面、企业微信机器人或别的业务系统用。FastAPI基于Pydantic做参数校验接口契约清晰对于对接方的开发人员来说非常友好——他们看Swagger文档就能自己联调不需要我一遍遍解释“参数应该怎么传”。当然FastAPI也不是没有短板。如果Agent内部有特别耗时的长任务直接通过HTTP请求-响应模式扛着会占用连接资源。我的做法是凡是耗时的Agent任务一律走消息队列异步化FastAPI只负责“接收请求、投递任务、返回任务ID”真正的Agent执行逻辑在worker进程里跑。前端或调用方通过任务ID轮询结果这样既绕开了HTTP超时限制也让Agent任务可以后台排队执行。2.3 关于Rust、Spring AI和其他方案的讨论搜索热度里有人提到“基于Rust的AI Agent”“Spring AI Agent”我也简单说下我为啥没走这两条路。Rust写Agent的优势是性能强劲、单二进制部署极其省心但问题是生态还不够成熟——LangChain类生态的主力语言还是Python很多工具包和向量库的Python客户端最完善Rust版总慢半拍。内网项目最怕“某个功能库没人维护”我不会为了炫技把一个生产系统押在相对年轻的生态上。Spring AI更适合Java技术栈根深蒂固的团队好处是和现有Spring Boot微服务体系无缝融合。但同样的它的生态成熟度也远不如Python的Agent生态且Java写Agent时的类型约束很重做动态的工具调用不如Python灵活。说白了选Python不是因为它最好而是因为它的Agent生态最厚、遇到问题能搜到的解决方案最多——在内网环境里你没法上外网查文档一个问题的解决方案是否“已知”直接影响项目进度。2.4 模型选型与本地化部署思路模型是整个Agent的“大脑”也是隔离内网里最麻烦的一环。不能调用云端API那就只能部署开源模型。我这边兼顾生成质量、显存成本和内网机器配置最终选了中等规模的指令微调模型用vLLM或TensorRT-LLM做推理服务框架。显存在40GB以上的单卡就能跑得比较顺畅如果只有24GB就得配合量化AWQ或GPTQ来压缩显存占用。需要注意的是Agent场景里模型不仅要做对话生成还要做“工具调用决策”——也就是根据用户指令从多个可用工具里挑出正确的那个并生成参数。这个能力在通用对话模型上往往偏弱我实测下来用专门的function calling微调模型或者经过工具调用优化的指令版模型成功率会高很多。如果你手头的模型没有针对工具调用做过强化那么Agent会经常出现“选错工具”“参数瞎填”的情况这时候别急着骂框架先把模型换对。3. 实操记录从离线环境准备到Agent跑通全流程3.1 第一步把依赖“搬”进内网隔离内网最磨人的不是写代码而是装环境。由于目标机器不能上外网常规的pip install直接失效。我的做法是在一台有外网的跳板机上把项目需要的所有依赖提前下载成wheel包再用内网拷入工具转移到目标环境。这里有个关键细节不要只下载你requirements.txt里的顶层依赖必须把传递依赖一并下载。我用的是pip download命令加–resolve参数配合–platform、–python-version等参数锁定目标环境的平台信息。另外先把目标机器上Python的版本、操作系统版本确认清楚再在跳板机上下载对应平台的wheel避免出现“下载了一堆Linux包、目标机器却是Windows”的乌龙。模型权重文件的搬运是另一个大头。几十GB的模型文件通常要分批拷贝我建议在压缩打包后记录每个分片的校验值比如MD5或SHA256拷到内网后逐段验证。有一次我就是图省事没校验模型加载到一半报错排查了半天才发现是某个权重分片损坏。内网传输本身就慢来回折腾一次可能浪费一个工作日校验这步绝对不能省。依赖装完后建议用离线方式把LangChain、LangGraph等核心库的版本固定下来。隔离环境里没有“随时升级”这回事所有库的版本必须在跳板机阶段就锁定然后写进requirements.txt带进内网。否则你在内网装了一个新版库等真上线才发现某个API签名变了那是很崩溃的事情。3.2 第二步部署本地模型推理服务模型推理我用的是vLLM主要看中它的吞吐量和高并发支持。vLLM的离线部署本身不复杂把模型权重放到指定目录启动服务时指定–model路径、–served-model-name给外部调用的模型名、–port和–max-model-len等参数。但内网环境有几个额外要处理的问题。一个是显存自适应。如果模型支持多卡vLLM默认会用tensor-parallel-size来做张量并行但多卡并行会增加通信开销如果只是30人规模的内网使用单卡足以应对别盲目开多卡。另一个是量化。我实测把模型量化成AWQ 4-bit后显存占用降到原来的60%左右生成速度受影响不大内存紧张的环境可以优先考虑量化方案。向量模型也要单独部署。Agent如果要接RAG做文档问答就需要一个embedding服务。这里建议不要偷懒直接用同一个模型既做生成又做embedding效果通常都不好。我单独起了一个embedding服务专门负责把用户问题和知识库文档转成向量写入向量数据库。内网环境下向量库我选的是Milvus Lite或者单机版的Chroma足够撑起百万级文档量的场景而且部署简单不需要额外起一堆依赖组件。3.3 第三步实现Agent工作流工作流这块我用LangGraph来写。一个典型的“查数据并生成报告”的Agent流程大概长这样入口节点接收用户自然语言请求。意图识别节点让LLM判断用户想干什么输出结构化结果比如“查询订单”意图和关键参数。工具调用节点根据意图选择工具调用内网数据库接口、文件服务或审批API。结果整理节点把工具返回的数据交给模型生成最终回答。结束节点返回给用户。写LangGraph时最重要的设计理念是“减少模型自由发挥的空间”。模型能做的决策越少系统越稳定。我在设计时会把大部分判断逻辑抽到代码里比如“参数合法性校验”“工具超时处理”“结果格式标准化”这些都不该让模型操心。模型只负责两件事理解用户意图、把原始数据翻译成自然语言。另外要在每个工具节点加上超时控制。内网的接口偶尔会慢如果数据库查询卡住了Agent会一直等最终把整个请求拖死。我在工具调用层统一设置了超时时间常规工具10秒重型查询30秒超时后直接返回“工具调用失败请重试或转人工”并记录日志。这套机制上线后救了我很多次因为内网的老旧系统不稳定是常态。3.4 第四步开发API服务和前端对话页Agent核心跑通后还需要一个“壳”让用户能访问。FastAPI这边我提供两个主要接口一个用于同步执行简单Agent任务一个用于提交异步任务并查询状态。两者都做用户鉴权因为内网系统对接AD域控或自建用户体系都常见我用的是简单的JWT令牌校验避免每个请求都得查一次数据库。前端这块我做了个极简聊天页面没有用太复杂的框架一个纯静态页面加Fetch轮询就够。用户输入问题后页面调用后端API提交任务然后每隔2秒查询一次任务状态拿到结果后渲染到聊天窗口。为什么不做WebSocket推送因为Agent执行耗时长WebSocket连接要维持很久内网网关经常会把空闲连接断掉轮询反而更稳定。而且这个页面主要给内部几十个人用轮询的负载完全可以忽略。前端页面上还要考虑一个体验问题Agent执行过程中的中间状态要不要展示。我选择展示“当前执行到哪一步”比如正在查询数据库、正在生成报告这样用户不会以为系统卡死了。实现方式是后端把Agent执行状态写入Redis前端查询任务状态时一并取回。4. 并发与性能Agent怎么扛住内网业务压力4.1 同步转异步任务队列是必选项热词里有“AI Agent怎么扛并发”这是个特别现实的问题。Agent和普通API最大的区别在于“耗时不可控”一个复杂任务可能要几十秒甚至几分钟如果所有请求都同步处理每个请求占着一个worker并发一高整个服务就雪崩了。我的方案是引入任务队列。具体来说FastAPI收到请求后先把任务参数写入Redis队列立即返回任务ID给调用方后台worker进程从队列里取任务真正执行Agent工作流执行完把结果写回Redis或数据库调用方通过任务ID轮询结果。这样即使同时来了100个请求FastAPI也能瞬间全部接收真正的排队发生在worker侧。worker的数量也可以根据机器CPU核数和GPU负载灵活扩展扛不住就多起几个worker进程。4.2 线程池与信号量控制并发度如果Agent内部有很多并发调用比如同时查多个数据源直接无限制并发会把后端系统打死。内网各种系统本来就脆弱我在Agent工具层统一加了一个信号量限制同时进行的工具调用数量。比如数据库查询这类高频操作信号量控制在5也就是说同一时刻最多5个数据库查询在跑其余的在队列里等着。这样虽然单个任务变慢了但整体系统不会被打爆。生成模型这边的并发也要控制。vLLM本身支持并发请求但并发太高会让每个请求的排队时间变长。我根据业务峰值做了估算30个并发用户、每个用户平均每30秒发起一次请求QPS大约1vLLM完全扛得住。真正要盯的是Agent内部多次调用模型带来的放大效应——一个Agent任务可能要调3~5次模型所以实际模型压力是用户QPS的3~5倍。这个放大系数要提前算进去我就是靠这个公式决定用多大显存、要不要开多卡。4.3 缓存策略别让模型反复造轮子大部分用户的问题其实高度重复比如“昨天的销售额是多少”“某个项目的状态是什么”。这种查询类任务完全可以加缓存没必要每次都让Agent走一遍“推理→调工具→总结”的全流程。我的实现比较粗糙但有效以用户问题工具的哈希值作为缓存键命中缓存就直接返回历史结果。但缓存要谨慎只对“明确是查询类”的任务启用一旦用户问“帮我提交一个审批”“给我创建一个工单”绝对不缓存否则会出大事故。实现上我通过LangGraph节点的metadata给节点打标标记为read_only的节点才走缓存write操作一律绕过。4.4 连接池与超时配置细节内网环境里另一个并发隐患是连接资源。FastAPI底层用httpx调用工具接口、vLLM和数据库如果每次调用都新建连接高并发下会频繁出现端口耗尽或too many open files。我的做法是给所有HTTP客户端配置连接池复用连接数据库连接也走连接池并设置最大连接数。这一步配置看起来不起眼但我在压测时发现不配连接池的情况下100并发能把服务的文件句柄打到上千配了之后稳定在几十。5. 常见问题与排查技巧实录5.1 模型输出工具参数不规范的解法这是Agent落地时最烦人的问题LangGraph已经定义了工具模型也知道有哪些工具但生成参数时偶尔会输出非法JSON或者参数类型不对。我试过反复改提示词效果有限。最终有效的方案是在工具调用函数入口前加一个“参数修正”步骤把模型的输出用代码做一个JSON schema校验不合法就塞给LLM再修正一轮再不行就用模板默认值兜底。这个三层容错机制上线后工具调用成功率从85%左右提升到了98%。5.2 内网时间不同步引发的证书问题内网机器经常没有配置NTP时间同步时间偏差一大HTTPS证书验证、JWT签发校验这些都会挂掉。我第一次联调时发现Agent调用内网某系统接口总是报SSL错误查了半天才发现是服务器时间比实际时间快了5分钟。这个坑太隐蔽了建议在部署清单里第一步就写上“检查所有服务器时间同步”并加一个定时任务让机器自动校准时间。5.3 Agent跑着跑着就“失忆”LangGraph状态管理默认在内存里服务重启后所有正在执行的Agent任务都没了。内网环境偶尔会因为升级、监控误杀导致进程重启如果这时候有用户在跑长任务体验会很糟糕。我给LangGraph配置了checkpoint持久化到RedisAgent执行到每个节点都会保存状态进程重启后通过任务ID恢复上下文继续执行。这样虽然没法做到100%无感但至少把损失降到了最低。5.4 日志与审计内网项目逃不掉的要求内网项目尤其是涉及业务数据查询的甲方一定会要求“留痕”。我在Agent的每个工具调用节点都打了结构化日志记录了谁在什么时间、用什么问题、调用了哪个工具、传了什么参数、返回了什么结果。这些日志既要方便排查问题也要满足安全审计的要求。日志输出的位置也要规划好内网一般有统一的日志采集平台我把Agent日志单独打到一个文件按天滚动方便审计人员导出来看。6. 一点部署体会与后续扩展这个项目做下来我最深的体会有两点。第一点隔离内网做Agent真正的难点不在“Agent”而在“隔离”——依赖搬运、模型部署、环境兼容、安全审计这些才是消耗时间的大头。第二点Agent工程化不是把模型接上就完事而是要让模型在流程里只做它擅长的事理解和表达其余所有控制逻辑都交给代码。这两点想通了后面再遇到不同场景的Agent需求基本上就是换个工具集、改个流程图的事。现在这套系统支撑的业务包括工单自动分拣、合同文本摘要、业务数据问答和报表生成。后续我打算把多Agent协作加进来比如“一个Agent负责拆解任务多个子Agent并行处理不同子任务最后汇总”LangGraph的子图机制已经支持这个能力等业务需求明确后再扩展。另外也想试试把Agent的流式输出接到前端让用户能实时看到生成过程体验会更接近云端产品。如果你也在隔离内网里做Agent或者正准备给内网业务系统加一个AI助手记住一句话先跑通一条最简单的端到端流程再逐步加复杂度。不要一开始就设计一个超级大的多Agent系统内网环境里调一次试错周期太长了小步快跑才是最优解。 隔离内网部署AI Agent实战：LangGraph编排与本地模型推理
1. 项目全景隔离内网里做Agent到底难在哪“AI Agent能帮我们干很多活”这句话在外网环境里说起来很轻松——调OpenAI的API、装个LangChain、几分钟跑通一个带工具调用的助手很多朋友都体验过。但如果把场景换成隔离内网这套流程几乎全部失效没有公网API可用、没有pip源可连、甚至模型权重都要自己想办法搬进去。我这次做的项目就是在这样一个完全隔离的办公网络里从零搭起一套可用的AI Agent工程系统整个落地过程比预想中繁琐得多但也让我把Agent从“demo玩具”推到“生产工具”的完整链路重新梳理了一遍。先说清楚这套系统到底在解决什么问题。内网用户最大的痛点是业务系统数据密级高、不能出网但日常又有大量重复性工作比如查数据库、填报表、梳理文档、追工单。传统做法是写死脚本或表单流程灵活度太低直接上云端AI又不符合安全规定。所以最终目标很明确把大模型、Agent框架、工具调用全部装进内网让用户通过一个网页对话框就能用自然语言指挥Agent去查数、写摘要、走审批流程所有数据和模型推理都留在内网边界之内。这个项目适合谁来参考如果你正在做私有化部署的RAG问答、企业内部知识助手、工单自动处理这类事情或者你手上恰好也有一个上不了外网的环境那么这篇总结里的大部分方案和坑你大概率都会踩到。我会尽量把技术选型、部署细节、性能问题和排查思路都讲透少讲虚的多给能直接用的东西。2. 方案选型为什么是FastAPI、LangGraph和本地模型这套组合2.1 编排框架的取舍Agent的核心不是模型本身而是“让它能根据任务自主决定调用哪些工具、按什么顺序调用”。市面上主流的Agent编排方案有好几种最简单的是ReAct模式——让模型反复思考“下一步做什么、调用什么工具、观察结果”直到完成任务。但纯ReAct有个问题流程完全靠模型现场发挥内网环境下用户容忍度低一旦模型判断失误可能反复调用无用工具既拖慢响应又浪费算力。所以在选型时我更倾向于带图结构的工作流框架。LangGraph就是把Agent的思考、工具调用、状态管理做成一张有向图节点是“行动”边是“转移条件”。相比纯LangChain的链式调用它更接近真实业务流程比如“先查库存→再判断是否满足条件→满足就生成采购单→不满足就转人工审批”这种确定性逻辑用LangGraph表达非常自然。而且LangGraph支持checkpoint持久化Agent执行到一半宕机了可以从最近的节点恢复这对内网生产环境来说很有价值——用户可不想任务跑到80%突然全丢。为什么不选更简单的“函数调用循环”直接撸一个我也考虑过。如果只是做一两个固定场景自己写确实可控性最强。但项目后续要接的工具会越来越多数据库、HTTP服务、文件系统、OA接口没有一个标准化的图编排层后面每个新工具都要改主流程代码维护成本会急剧上升。LangGraph相当于把“流程编排”和“工具实现”解耦新业务场景只要新增一条子图不动主干逻辑。2.2 服务层FastAPI在内网环境里的优势Agent后端服务我用的是FastAPI。选择它并不是因为它“新潮”而是内网部署环境对它太友好了单进程就能提供异步并发能力不用额外引入沉重的应用服务器依赖极少离线打包容易自带OpenAPI文档甲方审计时要接口清单直接导出就行省了很多沟通成本。还有一个很实际的考虑内网经常有多套系统通过HTTP互相调用Agent服务需要对外提供API给前端页面、企业微信机器人或别的业务系统用。FastAPI基于Pydantic做参数校验接口契约清晰对于对接方的开发人员来说非常友好——他们看Swagger文档就能自己联调不需要我一遍遍解释“参数应该怎么传”。当然FastAPI也不是没有短板。如果Agent内部有特别耗时的长任务直接通过HTTP请求-响应模式扛着会占用连接资源。我的做法是凡是耗时的Agent任务一律走消息队列异步化FastAPI只负责“接收请求、投递任务、返回任务ID”真正的Agent执行逻辑在worker进程里跑。前端或调用方通过任务ID轮询结果这样既绕开了HTTP超时限制也让Agent任务可以后台排队执行。2.3 关于Rust、Spring AI和其他方案的讨论搜索热度里有人提到“基于Rust的AI Agent”“Spring AI Agent”我也简单说下我为啥没走这两条路。Rust写Agent的优势是性能强劲、单二进制部署极其省心但问题是生态还不够成熟——LangChain类生态的主力语言还是Python很多工具包和向量库的Python客户端最完善Rust版总慢半拍。内网项目最怕“某个功能库没人维护”我不会为了炫技把一个生产系统押在相对年轻的生态上。Spring AI更适合Java技术栈根深蒂固的团队好处是和现有Spring Boot微服务体系无缝融合。但同样的它的生态成熟度也远不如Python的Agent生态且Java写Agent时的类型约束很重做动态的工具调用不如Python灵活。说白了选Python不是因为它最好而是因为它的Agent生态最厚、遇到问题能搜到的解决方案最多——在内网环境里你没法上外网查文档一个问题的解决方案是否“已知”直接影响项目进度。2.4 模型选型与本地化部署思路模型是整个Agent的“大脑”也是隔离内网里最麻烦的一环。不能调用云端API那就只能部署开源模型。我这边兼顾生成质量、显存成本和内网机器配置最终选了中等规模的指令微调模型用vLLM或TensorRT-LLM做推理服务框架。显存在40GB以上的单卡就能跑得比较顺畅如果只有24GB就得配合量化AWQ或GPTQ来压缩显存占用。需要注意的是Agent场景里模型不仅要做对话生成还要做“工具调用决策”——也就是根据用户指令从多个可用工具里挑出正确的那个并生成参数。这个能力在通用对话模型上往往偏弱我实测下来用专门的function calling微调模型或者经过工具调用优化的指令版模型成功率会高很多。如果你手头的模型没有针对工具调用做过强化那么Agent会经常出现“选错工具”“参数瞎填”的情况这时候别急着骂框架先把模型换对。3. 实操记录从离线环境准备到Agent跑通全流程3.1 第一步把依赖“搬”进内网隔离内网最磨人的不是写代码而是装环境。由于目标机器不能上外网常规的pip install直接失效。我的做法是在一台有外网的跳板机上把项目需要的所有依赖提前下载成wheel包再用内网拷入工具转移到目标环境。这里有个关键细节不要只下载你requirements.txt里的顶层依赖必须把传递依赖一并下载。我用的是pip download命令加–resolve参数配合–platform、–python-version等参数锁定目标环境的平台信息。另外先把目标机器上Python的版本、操作系统版本确认清楚再在跳板机上下载对应平台的wheel避免出现“下载了一堆Linux包、目标机器却是Windows”的乌龙。模型权重文件的搬运是另一个大头。几十GB的模型文件通常要分批拷贝我建议在压缩打包后记录每个分片的校验值比如MD5或SHA256拷到内网后逐段验证。有一次我就是图省事没校验模型加载到一半报错排查了半天才发现是某个权重分片损坏。内网传输本身就慢来回折腾一次可能浪费一个工作日校验这步绝对不能省。依赖装完后建议用离线方式把LangChain、LangGraph等核心库的版本固定下来。隔离环境里没有“随时升级”这回事所有库的版本必须在跳板机阶段就锁定然后写进requirements.txt带进内网。否则你在内网装了一个新版库等真上线才发现某个API签名变了那是很崩溃的事情。3.2 第二步部署本地模型推理服务模型推理我用的是vLLM主要看中它的吞吐量和高并发支持。vLLM的离线部署本身不复杂把模型权重放到指定目录启动服务时指定–model路径、–served-model-name给外部调用的模型名、–port和–max-model-len等参数。但内网环境有几个额外要处理的问题。一个是显存自适应。如果模型支持多卡vLLM默认会用tensor-parallel-size来做张量并行但多卡并行会增加通信开销如果只是30人规模的内网使用单卡足以应对别盲目开多卡。另一个是量化。我实测把模型量化成AWQ 4-bit后显存占用降到原来的60%左右生成速度受影响不大内存紧张的环境可以优先考虑量化方案。向量模型也要单独部署。Agent如果要接RAG做文档问答就需要一个embedding服务。这里建议不要偷懒直接用同一个模型既做生成又做embedding效果通常都不好。我单独起了一个embedding服务专门负责把用户问题和知识库文档转成向量写入向量数据库。内网环境下向量库我选的是Milvus Lite或者单机版的Chroma足够撑起百万级文档量的场景而且部署简单不需要额外起一堆依赖组件。3.3 第三步实现Agent工作流工作流这块我用LangGraph来写。一个典型的“查数据并生成报告”的Agent流程大概长这样入口节点接收用户自然语言请求。意图识别节点让LLM判断用户想干什么输出结构化结果比如“查询订单”意图和关键参数。工具调用节点根据意图选择工具调用内网数据库接口、文件服务或审批API。结果整理节点把工具返回的数据交给模型生成最终回答。结束节点返回给用户。写LangGraph时最重要的设计理念是“减少模型自由发挥的空间”。模型能做的决策越少系统越稳定。我在设计时会把大部分判断逻辑抽到代码里比如“参数合法性校验”“工具超时处理”“结果格式标准化”这些都不该让模型操心。模型只负责两件事理解用户意图、把原始数据翻译成自然语言。另外要在每个工具节点加上超时控制。内网的接口偶尔会慢如果数据库查询卡住了Agent会一直等最终把整个请求拖死。我在工具调用层统一设置了超时时间常规工具10秒重型查询30秒超时后直接返回“工具调用失败请重试或转人工”并记录日志。这套机制上线后救了我很多次因为内网的老旧系统不稳定是常态。3.4 第四步开发API服务和前端对话页Agent核心跑通后还需要一个“壳”让用户能访问。FastAPI这边我提供两个主要接口一个用于同步执行简单Agent任务一个用于提交异步任务并查询状态。两者都做用户鉴权因为内网系统对接AD域控或自建用户体系都常见我用的是简单的JWT令牌校验避免每个请求都得查一次数据库。前端这块我做了个极简聊天页面没有用太复杂的框架一个纯静态页面加Fetch轮询就够。用户输入问题后页面调用后端API提交任务然后每隔2秒查询一次任务状态拿到结果后渲染到聊天窗口。为什么不做WebSocket推送因为Agent执行耗时长WebSocket连接要维持很久内网网关经常会把空闲连接断掉轮询反而更稳定。而且这个页面主要给内部几十个人用轮询的负载完全可以忽略。前端页面上还要考虑一个体验问题Agent执行过程中的中间状态要不要展示。我选择展示“当前执行到哪一步”比如正在查询数据库、正在生成报告这样用户不会以为系统卡死了。实现方式是后端把Agent执行状态写入Redis前端查询任务状态时一并取回。4. 并发与性能Agent怎么扛住内网业务压力4.1 同步转异步任务队列是必选项热词里有“AI Agent怎么扛并发”这是个特别现实的问题。Agent和普通API最大的区别在于“耗时不可控”一个复杂任务可能要几十秒甚至几分钟如果所有请求都同步处理每个请求占着一个worker并发一高整个服务就雪崩了。我的方案是引入任务队列。具体来说FastAPI收到请求后先把任务参数写入Redis队列立即返回任务ID给调用方后台worker进程从队列里取任务真正执行Agent工作流执行完把结果写回Redis或数据库调用方通过任务ID轮询结果。这样即使同时来了100个请求FastAPI也能瞬间全部接收真正的排队发生在worker侧。worker的数量也可以根据机器CPU核数和GPU负载灵活扩展扛不住就多起几个worker进程。4.2 线程池与信号量控制并发度如果Agent内部有很多并发调用比如同时查多个数据源直接无限制并发会把后端系统打死。内网各种系统本来就脆弱我在Agent工具层统一加了一个信号量限制同时进行的工具调用数量。比如数据库查询这类高频操作信号量控制在5也就是说同一时刻最多5个数据库查询在跑其余的在队列里等着。这样虽然单个任务变慢了但整体系统不会被打爆。生成模型这边的并发也要控制。vLLM本身支持并发请求但并发太高会让每个请求的排队时间变长。我根据业务峰值做了估算30个并发用户、每个用户平均每30秒发起一次请求QPS大约1vLLM完全扛得住。真正要盯的是Agent内部多次调用模型带来的放大效应——一个Agent任务可能要调3~5次模型所以实际模型压力是用户QPS的3~5倍。这个放大系数要提前算进去我就是靠这个公式决定用多大显存、要不要开多卡。4.3 缓存策略别让模型反复造轮子大部分用户的问题其实高度重复比如“昨天的销售额是多少”“某个项目的状态是什么”。这种查询类任务完全可以加缓存没必要每次都让Agent走一遍“推理→调工具→总结”的全流程。我的实现比较粗糙但有效以用户问题工具的哈希值作为缓存键命中缓存就直接返回历史结果。但缓存要谨慎只对“明确是查询类”的任务启用一旦用户问“帮我提交一个审批”“给我创建一个工单”绝对不缓存否则会出大事故。实现上我通过LangGraph节点的metadata给节点打标标记为read_only的节点才走缓存write操作一律绕过。4.4 连接池与超时配置细节内网环境里另一个并发隐患是连接资源。FastAPI底层用httpx调用工具接口、vLLM和数据库如果每次调用都新建连接高并发下会频繁出现端口耗尽或too many open files。我的做法是给所有HTTP客户端配置连接池复用连接数据库连接也走连接池并设置最大连接数。这一步配置看起来不起眼但我在压测时发现不配连接池的情况下100并发能把服务的文件句柄打到上千配了之后稳定在几十。5. 常见问题与排查技巧实录5.1 模型输出工具参数不规范的解法这是Agent落地时最烦人的问题LangGraph已经定义了工具模型也知道有哪些工具但生成参数时偶尔会输出非法JSON或者参数类型不对。我试过反复改提示词效果有限。最终有效的方案是在工具调用函数入口前加一个“参数修正”步骤把模型的输出用代码做一个JSON schema校验不合法就塞给LLM再修正一轮再不行就用模板默认值兜底。这个三层容错机制上线后工具调用成功率从85%左右提升到了98%。5.2 内网时间不同步引发的证书问题内网机器经常没有配置NTP时间同步时间偏差一大HTTPS证书验证、JWT签发校验这些都会挂掉。我第一次联调时发现Agent调用内网某系统接口总是报SSL错误查了半天才发现是服务器时间比实际时间快了5分钟。这个坑太隐蔽了建议在部署清单里第一步就写上“检查所有服务器时间同步”并加一个定时任务让机器自动校准时间。5.3 Agent跑着跑着就“失忆”LangGraph状态管理默认在内存里服务重启后所有正在执行的Agent任务都没了。内网环境偶尔会因为升级、监控误杀导致进程重启如果这时候有用户在跑长任务体验会很糟糕。我给LangGraph配置了checkpoint持久化到RedisAgent执行到每个节点都会保存状态进程重启后通过任务ID恢复上下文继续执行。这样虽然没法做到100%无感但至少把损失降到了最低。5.4 日志与审计内网项目逃不掉的要求内网项目尤其是涉及业务数据查询的甲方一定会要求“留痕”。我在Agent的每个工具调用节点都打了结构化日志记录了谁在什么时间、用什么问题、调用了哪个工具、传了什么参数、返回了什么结果。这些日志既要方便排查问题也要满足安全审计的要求。日志输出的位置也要规划好内网一般有统一的日志采集平台我把Agent日志单独打到一个文件按天滚动方便审计人员导出来看。6. 一点部署体会与后续扩展这个项目做下来我最深的体会有两点。第一点隔离内网做Agent真正的难点不在“Agent”而在“隔离”——依赖搬运、模型部署、环境兼容、安全审计这些才是消耗时间的大头。第二点Agent工程化不是把模型接上就完事而是要让模型在流程里只做它擅长的事理解和表达其余所有控制逻辑都交给代码。这两点想通了后面再遇到不同场景的Agent需求基本上就是换个工具集、改个流程图的事。现在这套系统支撑的业务包括工单自动分拣、合同文本摘要、业务数据问答和报表生成。后续我打算把多Agent协作加进来比如“一个Agent负责拆解任务多个子Agent并行处理不同子任务最后汇总”LangGraph的子图机制已经支持这个能力等业务需求明确后再扩展。另外也想试试把Agent的流式输出接到前端让用户能实时看到生成过程体验会更接近云端产品。如果你也在隔离内网里做Agent或者正准备给内网业务系统加一个AI助手记住一句话先跑通一条最简单的端到端流程再逐步加复杂度。不要一开始就设计一个超级大的多Agent系统内网环境里调一次试错周期太长了小步快跑才是最优解。