过去大半年我大部分时间都在和隔离内网打交道做的事只有一个把AI Agent从跑通Demo变成跑在生产环境里。在公网环境里这听起来不算难——接个大模型API写两段Prompt配个工具调用就完事了。可真到了隔离内网完全不是一回事。模型权重进不来、依赖包装不上、工具服务全是外网域名连最基础的Agent框架都可能因为缺失某个底层库跑不起来。这篇文章就写写我在隔离内网里做AI Agent工程落地的完整思路和实操记录从架构设计、模型私有化部署、工具层改造到一次全链路的部署实录和排障经验全部是基于真实项目总结出来的。如果你也在政企、金融、能源这类内网环境里做Agent或者正准备把公网跑通的Agent方案迁移到隔离环境这篇文章应该能帮你少踩不少坑。1. 隔离内网做Agent到底难在哪1.1 先分清三种“隔离内网”真正在企业里说“隔离内网”不是一个统一概念。我接触过的环境大概分三种第一种是完全物理隔离设备之间没有网络连接文件进出全靠移动介质和审批流程第二种是逻辑隔离服务器和办公网在同一个物理网络上但防火墙策略只放行特定IP和端口第三种是网闸隔离通过单向网闸设备让数据只能按固定方向流动反方向只能走独立通道。不管是哪种形态落到应用开发层面就一句话外网要被当作完全不存在来设计。这跟我们在公网环境里做开发的思维惯性冲突非常大。公网环境下模型API不够用就换一家缺什么依赖就跑一遍pip installAgent需要搜索能力就接个搜索API。在隔离内网里这些动作全部没有外网服务不是不可用而是压根不在你的世界里。用一个生活化的类比公网环境下做Agent就像住在一个外卖发达的小区饿了打开App点单就行隔离内网就是你搬进一个管理森严的大院外卖和快递都进不了门所有物资必须经过门岗、安检、登记一层层送到手上。你在开发时首先要接受这个设定所有方案都按“离线优先”来做后面才会顺利一些。1.2 四道绕不开的工程坎第一道坎是模型权重怎么进内网。当前主流的中文开源模型7B级别的权重文件一般就有14GB到30GB70B级别动辄上百GB。这么大的文件在隔离内网里不是U盘一插就能用的得经过来源校验、格式转换、介质审核、杀毒、多级导入一整套流程每个环节都可能卡住。更麻烦的是内网机器通常没有外网权限模型从哪个合规渠道来、怎么保证完整性都得提前想清楚。第二道坎是软件依赖同步。一个Agent项目往往横跨Python、Node.js甚至Rust生态外网环境下pip install一把梭到内网连PyPI都访问不了。你必须在外网把所有依赖包预先拉下来再搭一个内网私服或者用离线包目录直接安装。依赖树一深就特别痛苦子依赖的依赖也要手动补漏掉一个都够你折腾半天。第三道坎是推理资源预算。内网机房买GPU不像公有云那样点点头就能扩容显卡数量有限显存总量固定。Agent场景和普通聊天不一样一次任务可能连续触发几十轮推理调用并发一上来显存直接见底。如果不在架构设计阶段就控制好上下文长度和推理频率上线后性能可能很难看。第四道坎是Agent生态里的“外网依赖症”。现在主流Agent框架默认提供的搜索、网页浏览、天气查询、地图导航这些工具在隔离内网里一个都用不上全部要做等价替换。你会发现很多团队在内网里做Agent第一个真正落地的工具往往不是花哨的网页操作而是RAG检索和内部数据查询原因很简单它们能把Agent的“搜索需求”先承接住。2. 架构设计离线环境下Agent的骨架怎么搭2.1 单Agent还是多Agent先别被概念绕晕现在Agent概念很热多智能体、角色扮演、Agent协作网络之类的宣传语满天飞。但把主流架构拆到底核心就是三条线模型层、编排层、工具层。模型层负责推理编排层负责决定“下一步干什么”工具层负责真正执行动作。所谓多智能体大多数也只是在编排层里放了多个不同身份的角色让它们互相传递消息内核还是一个循环调度机制。在内网环境里我强烈建议先把单Agent跑通再考虑多Agent。原因很实在多Agent意味着更多推理调用和更长的执行链路而内网推理资源通常不富裕另一个原因是排障复杂度一个Agent出问题都不好查多个Agent互相联动日志能把你淹了。先单后多每一步都有收益至少不会上来就被复杂链路卡住。这里顺带解答一个大家常问的问题Agent任务到底多消耗tokenAgent跑一个多步任务每一步的规划、思考、工具结果都要放回上下文里token消耗是叠着往上走的。公网场景可以按量付费内网是自建推理服务没有外面接来的配额兜底上下文窗口用完了就只能截断或者重建对话。所以你在配置推理服务时max-model-len要留足工具返回的内容也要尽量精简。2.2 编排层必须独立部署很多人做Agent的第一个版本是把逻辑直接塞进现有业务系统里比如在Django或者Spring服务里开一个Agent接口。Demo阶段看着省事一旦Agent开始跑多步任务问题就集中爆发。Agent执行时间不稳定可能几秒也可能十几分钟同步HTTP请求很容易超时Agent内部的循环如果卡住会持续吃CPU和内存直接影响主业务流程Agent一旦出错业务日志和Agent日志混在一起排查难度陡增。正确做法是把编排层做成独立服务单独部署一台机器独立账号、独立数据库、独立日志目录。业务系统对Agent的调用通过异步任务队列来做接口只负责入队和返回任务IDAgent跑完再通过回调或者轮询把结果送回去。这样Agent无论怎么翻车生产业务都不受影响。这个设计在隔离内网里尤其重要。公网环境出了故障可以随时登服务器重启内网机器恢复路径长得多涉及审批、跳板、资质每一步都在消耗时间。把Agent的故障半径缩到最小是内网架构设计的一条底线。2.3 依赖和代码怎么离线同步项目依赖的同步是整个施工阶段的重头戏。Python生态的做法是在外网用pip download把依赖的wheel包全部下载到本地目录构建好传递依赖树然后到内网执行pip install --no-index --find-links./离线包目录来安装。更省心的方案是搭一个内网PyPI私服工具用devpi或者nexus把包传上去之后内网所有机器直接按包名安装体验基本和公网一致。Node.js项目同理npm私服用verdaccio或nexus都可以。Rust项目我比较推荐cargo vendor它能把项目所有依赖的源码直接拉到一个vendor目录打包带走到内网里用cargo build --offline构建不依赖任何在线索引。Rust生态在隔离内网里还有个天生优势很多工具可以编译成单二进制文件直接把可执行文件丢进内网就能跑不依赖一堆解释器和运行时。现在也有不少Agent runtime项目在用Rust实现看重的主要是单文件分发、内存安全和可控的资源占用这些特性在弱网络环境里尤其受用。代码本身的同步反而简单企业里一般都有内网GitLab或者Gitea。外网开发分支审完后通过合规渠道把代码以全量压缩包或者patch包形式带进内网合入内网主干分支。我自己踩过的坑是每次同步只传增量结果外网分支和内网分支版本对不上Agent跑出来的行为完全不一致。后来改成每次同步都生成一个带日期和版本号的全量快照比如agent-core-20250301.tar.gz宁可文件大一点也要保证两边状态绝对一致。3. 模型获取与私有化推理的关键路径3.1 选型逻辑参数量、许可证、量化方式内网里选模型比公网做Feihu的劲爆新闻转载谨慎得多。要做三个维度的确认参数规模够不够用、许可证允许不允许商用、量化之后效果还剩多少。参数规模上通用办公问答、文档摘要、信息抽取这类场景7B到14B模型已经能扛住大部分需求。如果任务涉及复杂推理、长文本分析或者代码生成那得考虑32B以上甚至70B。但别闭着眼睛上大参数参数量每翻一倍对显存、推理延迟和机房散热的要求都水涨船高。一个10人团队的内网项目跑一个70B模型占据所有GPU资源其他业务都会受影响因为一台GPU服务器往往要承载多个团队的任务。许可证这件事很多人忽略以为开源模型随便用。实际上不同模型的开源协议差别很大有的只允许研究使用有的允许商用但有附加条款。隔离内网部署不等于自动获得商用授权该走法务审核就提前走别等上线了才补流程那样返工成本很高。量化方式直接决定你现有的显卡能不能把模型装下。我这边用得比较多的是GPTQ和AWQ的4bit量化配合vLLM做推理效果和速度比较平衡。GGUF格式配合Ollama部署更简单适合快速验证如果团队里有人对推理服务不熟悉用Ollama能省掉很多运维上的折腾。3.2 模型文件导出与离线导入的完整步骤模型文件进内网的流程我建议严格按照下面这套走每一步都不要省。第一步在合规的外网工作区把模型文件完整下载下来记录safetensors或者bin文件的SHA256校验值。第二步做格式转换和量化确认最终版本的目录结构不要下载原始文件就直接进内网不然进去之后发现格式不对又要出来重新准备一来一回审批流程特别折腾。第三步把模型目录压缩成带版本号的包命名格式类似qwen25-14b-instruct-gptq-int4-v2.tar.gz压缩包里同时放一个README说明文件和校验值文件。第四步走审批流程把压缩包通过合规介质转移进隔离内网到内网机器上先解压再重新算一遍SHA256和外部记录的校验值比对一致才算导入完成。这一套流程看起来繁琐但真的救过我。有次外网下载完直接拷进内网没做二次校验结果模型文件中途损坏Agent跑起来全是乱码输出排查了一整天才发现是模型文件本身不完整。后来我把“校验两次解压之后还要校验”这条写进了团队的操作规范类似问题基本绝迹了。3.3 推理服务化和显存估算模型文件进了内网接下来就是推理服务的搭建。我用得比较顺手的是vLLM它支持Continuous Batching可以把并发请求的KV Cache做复用非常适合Agent这种多轮短请求交错出现的场景。SGLang也是不错的备选特别是有复杂前缀缓存需求的时候两者的选择取决于你用的推理框架与量化格式的兼容性。开始写启动命令前先算显存。粗算公式是模型权重约占参数量乘以2字节FP16再按量化方式缩减然后加上KV Cache和运行时开销最后留出20%余量。拿7B模型FP16为例权重约14GB加上KV Cache和各种开销单张24GB的显卡能跑但不宽裕。14B模型权重约28GB单卡24GB就比较挤了所以我更推荐用14B的4bit量化量化后权重降到8GB上下加上KV Cache24GB单卡反而跑得挺舒服。70B级别不讨论单卡老老实实上多卡。vLLM的启动命令大概长这样vllm serve /data/models/qwen25-14b-instruct-gptq-int4 \ --served-model-name agent-llm \ --host 0.0.0.0 --port 8000 \ --max-model-len 32768 \ --gpu-memory-utilization 0.9 \ --tensor-parallel-size 1 \ --api-key sk-internal-2024几个参数我重点解释一下。--max-model-len是上下文最大长度Agent任务需要放得下整段对话历史默认值往往不够我一般给32K起步--gpu-memory-utilization是显存占用比例默认0.9如果这台机器上还跑了其他服务要手动调低--tensor-parallel-size是张量并行的卡数只有一张卡就写1多卡再往上加。--api-key是内网服务间的调用凭证别图省事不设内网不等于没有横向风险。服务起来之后vLLM会提供一个OpenAI兼容接口。Agent编排层只需要把base_url改成http://内网IP:8000/v1model名字改成agent-llm原有代码几乎不用动。这也是我一直坚持用OpenAI兼容接口的原因模型随便换接口不变团队迁移成本接近零。4. 工具层设计与安全隔离4.1 外网工具的“内网等价替换”表Agent真正干活靠的是工具。公网上搜索API、网页访问、地图、天气这些是默认能力到隔离内网全都要换。我整理过一张等价替换对照表每次新项目都会拿它来对一遍公网默认能力隔离内网等价方案备注搜索引擎内网RAG检索 企业知识库Embedding模型也要私有化部署网页浏览内网文档站全文检索定期把内部站点做成快照供Agent访问天气/地图类API内部业务数据服务数据完全依赖单位自建接口代码执行容器沙箱支持Python/Shell但无外网权限短信/消息推送内网消息中间件通过审批后走API入队这张表的底层逻辑是别试图在隔离内网里模拟公网工具而是找到内网业务里已有的数据源和服务把它们Agent化。比如内网里往往有统一认证、工单系统、监控告警平台这些系统本身就有API用Agent去调用它们比造一个“假搜索”有用得多。你在做工具层设计时先盘点手头已有的内部API和数据源再决定新造什么工具效率会高很多。4.2 MCP协议规范工具接入工具接入方式我推荐直接用MCP也就是Model Context Protocol。它的价值在于把工具调用标准化了打个比方MCP就像Agent世界的USB接口以前每个工具都要单独写驱动现在工具方按MCP标准暴露服务Agent侧实现一次协议就能发现和调用整个内网的MCP工具集。内网部署时一般会在服务网段架设若干MCP Server每个Server提供一类工具比如数据库查询MCP Server、告警查询MCP Server、日志检索MCP Server。Agent启动时先从MCP登记中心拉取工具清单根据任务需要动态挑选工具。这个过程不依赖公网因为工具的服务发现、匹配、调用全部发生在内网里。MCP Server本身不绑定特定语言我看到不少人用Python写也有用Rust写性能敏感的工具网关。内网场景下工具数量不会太多重点是格式标准化。工具描述要写清楚“这个工具是干什么的”“参数是什么”“什么时候用”因为Agent是靠工具描述来决定调不调用的。描述写得含糊模型再聪明也不知道该在什么场景下选它。4.3 权限、沙箱与审计把Agent管住隔离内网的Agent和公网相比最大的差别是它的每一个动作都可能落在真实的业务系统上出错的影响直接且不可逆。所以工具层的权限管控比模型选型还重要。我总结过三个原则。第一最小权限。Agent的数据库账号必须是只读的除非需求明确要求写入才单独申请一个可写账号并且操作范围限死在白名单表里。第二操作白名单。Agent能调用的工具全部是显式注册过的没有注册的工具模型再怎么编造也没法调用。第三全链路审计。每一次工具调用的入参、出参、耗时、调用者身份都要落地到日志最好再单独存一份到审计系统方便出问题时回溯。代码生成类工具要单独说一句。比如Agent帮人生成Django的查询代码别让它直接把代码写进生产仓库。正确的方式是Agent在沙箱容器里生成代码并跑测试输出patch文件最后由开发人员人工审查合入。让Agent直接提交代码等于在生产环境埋了一个不确定的定时炸弹内网审计环境下肯定过不了关。5. 一次完整的隔离内网Agent部署实录5.1 准备环境依赖仓库、模型文件、基础服务先交代场景。我这边是两台服务器一台GPU推理机一台应用服务机两台都在隔离网段与办公网之间有严格的审批通道。项目目标是做一个内网知识问答和告警分析的Agent。第一步搭依赖仓库。我在外网下载了项目依赖的全部wheel包同步回内网后在应用服务机上用devpi搭了一个PyPI私服CI挂载机上配置pip源指向它。Node和Rust依赖也提前打包同步Rust用cargo vendor拉进了项目的vendor目录内网构建直接--offline执行不需要额外的依赖服务。第二步是模型文件准备。按照前面说过的流程下载、量化、打包、审批、摆渡、二次校验模型最终落在/data/models/qwen25-14b-gptq-int4目录。这一步没出幺蛾子靠的就是流程严格。第三步是基础服务。应用服务机上装了Docker和containerd用于跑沙箱容器另外一台机器装了MinIO作为对象存储Agent生成的文件统一传到这里。这些基础服务看似不起眼没有它们Agent真正跑起来会到处碰壁。5.2 启动推理服务与编排服务推理服务我直接用了准备好的vLLM镜像启容器docker run -d --gpus all --shm-size16g \ -v /data/models:/models \ -v /data/logs/vllm:/logs \ -p 8000:8000 \ vllm/vllm-openai:latest \ vllm serve /models/qwen25-14b-gptq-int4 \ --served-model-name agent-llm \ --max-model-len 32768 \ --gpu-memory-utilization 0.9启动后先curl一下健康检查接口确认模型加载和请求正常再发一条OpenAI格式的请求做冒烟测试。这一步不要跳很多问题在模型服务阶段就能暴露比如量化格式不兼容、上下文配置异常等。编排服务我这边用Python生态的LangGraph搭了一个单Agent循环核心配置其实就是把模型地址指向内网推理服务。关键配置片段长这样from openai import OpenAI client OpenAI( base_urlhttp://10.20.3.15:8000/v1, api_keysk-internal-2024 )模型地址从外网配置换成内网IPAgent的模型接入就算完成了。这里建议把地址和密钥放到环境变量或配置中心管理别硬编码进代码里。内网环境多套环境切换很频繁硬编码会让你后续维护很痛苦。5.3 跑通一条完整链路检索、决策、执行、答复所有服务就绪后我做了一次完整链路测试验证Agent能不能自主完成“内网知识检索加业务数据查询加答案汇总”的闭环。测试问题是“帮我查一下本月告警平台里出现次数最多的三个系统模块并结合作业指导书说说常见的处理步骤。”这个任务在隔离内网里没有任何公网工具可用Agent必须自己规划路径。实际执行过程大致是这样Agent第一步调用MCP工具清单发现两个候选工具告警查询工具和知识库检索工具。它先调知识库检索工具去搜“告警处理作业指导书”拿到一份文档摘要再调告警查询工具带着时间范围和分组条件拉取本月告警统计最后把两部分结果拼装进对话上下文生成一段回答并且列出它引用过的工具和返回码。整个任务跑了大概3分钟中间模型推理了7次工具调用了2次。有个细节很能说明问题Agent第一次调用告警查询工具时传的参数把时间写成了“本月”工具端因为参数校验失败报了错。Agent读到报错信息后重新换成了具体日期格式的参数第二次调用才成功。这就是Agent和传统自动化脚本最大的区别它能根据报错反馈自我修正不用把逻辑写死。也正因为有这个能力工具端一定要做好参数白名单和异常返回否则它可能越试越偏。6. 常见问题与排查技巧实录6.1 高频问题速查表现象可能原因处理办法Agent响应报404或连接失败模型服务BaseURL仍是外网地址检查编排层配置改为内网IP模型加载时报OOM显存估算不足或上下文过长降低量化精度、调低max-model-lenAgent一直重复输出同一句话温度参数过高、上下文被截断调低temperature增大上下文窗口工具调用超时工具服务在内网不通或性能弱先telnet内网IP端口再优化工具接口中文检索效果差Embedding模型未选中文优化版本换中文语料训练过的Embedding模型内网证书校验失败系统时间不同步导致TLS握手异常配置内网NTP时间同步pip安装很慢或装不上私服仓库索引未更新同步索引或改用全量包目录离线安装Agent拿不到内网数据工具白名单未注册或权限不足给Agent账号授权并注册工具这张表现在我团队排查Agent问题时是第一入口。隔离内网环境有个比较隐蔽的坑报错信息可能误导人。比如连外网域名解析出来的结果是内网DNS返回的伪造地址或者证书链在断网环境下验不过如果你不先对照这张表很容易在错误方向上浪费大半天。6.2 几个印象最深的坑第一个坑是依赖地狱。最初同步Python依赖时我直接pip freeze导出版本号然后到内网按这个清单装包结果有一半装不上。原因是pip freeze只记录了顶层包版本子依赖版本没有被完整锁定。后来改成在外网用pip download加pip-tools生成lock文件把所有传递依赖的版本锁死再同步到内网一次就装通了。这个坑在隔离内网里特别致命因为内网没法临时上网补缺失的包。第二个坑是上下文长度。刚开始Agent做多步任务经常到第三步就忘了第二步的语境模型把之前的工具结果全丢了。排查下来发现是max-model-len配得太短Agent每轮对话塞的上下文早已超过限制早期内容被静默截掉。后来把上下文窗口调到32K同时要求工具返回结果只保留关键字段这个问题才算解决。工具返回结果一定要做裁剪和摘要别一股脑全塞给模型这也是内网场景下省token的实用技巧。第三个坑是时间同步。有一台内网机器系统时间比标准时间慢了十分钟导致Agent在调用内部HTTPS接口时反复报证书错误。排查了很久才发现不是接口问题而是TLS证书校验对时间敏感。内网环境如果不配NTP时间漂移会很快这个事很小但影响面很大建议每台服务器都配好统一的时间同步。最后再多说一句踩坑心得隔离内网里做Agent技术栈本身并没有多高不可攀真正考验人的是工程韧性。公网跑通的Demo放进内网至少要经历依赖搬运、模型摆渡、工具适配、权限裁剪四道工序。我的习惯是给整套离线依赖做一个全量快照命名带上日期和版本号每次摆渡之前用脚本自动做SHA256校验一旦对不上宁可重新拉取也不硬着头皮继续。这个习惯帮团队省掉了大量重复排障的时间。等快照机制跑顺了再往AgentOps的方向扩展把每一次Agent调用的模型、工具、耗时、输入输出全部留痕配合内网的审计要求这套体系才算真正闭环。