隔离内网下 AI Agent 工程实战干了多年 AI 工程化落地我发现自己被问得最多的问题不是模型效果怎么样而是这套东西能不能在我们内网跑。能源、金融、政企类客户尤其常见机房物理隔离终端不能外联连补丁都得用光盘拷。这几年 AI Agent 应用大热但绝大多数开源项目和商业方案默认你有外网可用——模型要调 API依赖要拉镜像Embedding要联网。一旦把网络掐断原本在联网环境下半小时能搞定的事情能硬生生磨掉你一周。这篇内容就是针对这个场景来的隔离内网下AI Agent 工程落地到底要过哪些关、踩哪些坑、怎么从零搭出一套能真正干活的系统。不管你是要私有化交付给客户还是公司内部网络本身就在隔离区又或者单纯想理解 Agent 工程化的底层边界这篇都值得你花十分钟看完。我下面讲的每一条都是真实项目里验证过的方案。1. 模型权重和依赖库怎么搬进断网机房模型进不去内网后面所有 Agent 架构都是空谈。这是隔离环境里第一个、也是最脏最累的活。1.1 模型文件的离线运输与校验先别急着想着用 Ollama 拉模型。在隔离网里没有任何在线拉取的可能。常规操作是这样的在外网环境也就是你的办公网络或一台有公网访问权限的跳板机提前把需要的模型下载好。模型选型上优先考虑量化版本比如 Qwen2.5-7B-Instruct 的 AWQ 或 GPTQ 量化版。拿 7B 模型来说BF16 权重大约 14~15GBAWQ 4bit 量化后大约 6~7GB对机房 GPU 显存和拷贝耗时都友好很多。用分卷压缩加大文件切割建议单卷 4GB 左右方便通过摆渡系统、移动硬盘或光盘一次性带进去。文件拷贝完第一件事不是急着部署而是校验完整性。大文件在拷贝过程中出现的静默损坏我遇到过不止一次。模型文件如果中间有个字节错了推理时表现出的症状极其诡异——不是直接报错而是特定 prompt 下输出乱码排查到崩溃。# 在外网下载完成后生成校验文件 sha256sum qwen2.5-7b-instruct-awq.tar.gz checksums.txt # 内网拷完后逐卷校验 sha256sum -c checksums.txt1.2 推理引擎的内网部署选择模型文件到位后接着要定推理引擎。隔离内网环境下我实际用下来几类方案推理引擎适用场景显存占用备注vLLM生产级高并发较高支持 continuous batching吞吐最高Ollama单机快速验证较低部署简单但并发能力有限TensorRT-LLM极致性能优化中等需要编译优化落地周期长适合有专门优化团队的场景我个人推荐优先上 vLLM原因很简单它把 PagedAttention 和连续批处理做到了开箱即用很多 Agent 场景并发上不去瓶颈往往就在推理这一步。部署方式建议用 Docker 镜像加离线导入。# 外网环境导出镜像 docker save vllm/vllm-openai:latest -o vllm.tar # 内网环境导入 docker load -i vllm.tar # 启动 vLLM 服务 docker run --gpus all \ -v /data/models:/models \ -p 8000:8000 \ vllm/vllm-openai:latest \ --model /models/qwen2.5-7b-instruct-awq \ --quantization awq \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --trust-remote-code \ --served-model-name inner-agent-llm一句话总结模型搬运就四个字——事前校验离线分卷。我见过太多团队在这一步偷懒最后在奇怪的地方耗费好几天完全不值。1.3 依赖库与镜像源的内网化模型只是第一步Python 依赖同样要提前准备。隔离内网里没法直接 pip install所以必须在连通外网的环境把所有依赖打成离线包。# 在外网环境准备离线依赖包以 Python 3.10 为例 pip download -r requirements.txt \ -d ./offline_packages \ --platform manylinux2014_x86_64 \ --python-version 3.10 \ --only-binary:all: # 内网安装 pip install --no-index --find-links./offline_packages -r requirements.txt这里有个容易忽略的坑很多包的核心依赖是系统级 so 文件比如 pymupdf、lxml、paddleocr 这类涉及底层 C 库的库。你在外网 pip download 的时候--only-binary:all:能帮你筛选出有预编译 wheel 的包但系统的 libxml2、libjpeg、libglib 等底层库在外网机器上存在不代表内网机器也存在。因此条件允许的话尽量准备一个与内网操作系统版本一致的容器或虚拟机来打离线包顺便把系统库也一并确认好。镜像这块Python 内网源可以用 Nexus 或 Artifactory 搭一个 PyPI 代理Docker 镜像直接走 Harbor 私有仓库。Node 前端项目同理部署一套 npm verdaccio 私有源就行。2. 架构裁剪隔离环境下该留谁、该砍谁Agent 架构在外网环境下有太多现成方案比如完全依赖云端 LLM API 的编排、直接调 SaaS 工具的插件市场、以及各类 MCP 云端服务。但到了隔离内网绝大部分云端依赖都必须砍掉重来。2.1 组件裁剪清单我在实际项目中总结了一份隔离内网 Agent 架构的裁剪对照表组件类型外网常规做法隔离内网替代方案大模型服务调用云端 API本地 vLLM/Ollama 部署Embedding 模型调云端 Embedding API本地部署 bge-m3 或 m3e 系列向量数据库A 厂向量库、B 厂向量服务Milvus 内网部署 / Qdrant / Chroma工具插件云端插件市场自建工具注册中心写本地 HTTP 工具外部知识库在线文档/网页抓取内网 Wiki、内部文档解析入库MCP 服务云端 MCP本地起 stdio/HTTP MCP Server很多人在外网 demo 跑得很顺一到隔离环境就报错满天飞九成原因是没做这些裁剪。2.2 编排框架选型Python、Java 还是 Rust结合社区近期讨论热度我把主流方案按语言生态拆开看尤其是隔离内网场景更要在选型时想清楚。Python LangChain/LangGraph生态最丰富Agent 原语Tool Calling、Memory、Plan-Execute直接可用。缺点是并发场景要自己处理异步和资源控制重计算任务容易拖住 GIL。Java Spring AI如果你所在的企业是 Java 技术栈且团队没有 Python 人手Spring AI 是可行的。它抽象了 ChatClient、ToolCall 等概念能直接嵌入 Spring Boot 服务适合以业务系统为主体、Agent 只是模块的场景。RustRust 写 Agent 编排层的并发能力确实好社区也出了不少新框架适合对性能要求苛刻、且团队愿意投入 Rust 人力的情况。但坦白讲现阶段 Agent 生态里大量工具、文档、插件还是 Python 优先纯 Rust 路线在隔离内网里遇到问题时可参考的案例更少排查成本偏高。我自己的工程选择是双层拆分编排层用 Python LangGraph对外服务层用 FastAPI 做异步网关。LangGraph 负责控制流编排比如多步推理、条件分支、状态管理FastAPI 负责接收 HTTP 请求、限流和异步调度。隔离内网里没有云厂商帮你扛流量网关这层必须自己控制好。2.3 为什么一定要有网关层很多 Agent demo 项目一个 FastAPI 接口直接调 LangGraph 就完事了。隔离内网环境不行原因有两点内网系统通常有严格的认证审计要求。Agent 对外暴露的端口越少越安全网关做统一鉴权入口内部轮询外部回调都要走这里。内网流量不像公网那样有天然的多层负载均衡网关层是唯一能统一做限流、超时、熔断的地方。FastAPI 网关接 LangGraph 这套组合我称之为最小可用生产骨架FastAPI 管连接LangGraph 管流程vLLM 管推理。事实也证明这套骨架在不改动业务代码的情况下能扛住不少真实并发。3. 打通内网工具调用链路才算让 Agent 真正干活Agent 之所以是 Agent不是因为它能聊天而是因为它能调用工具、操作业务系统。在隔离内网里工具调用的链路比外网更难做——不是技术上难而是权限边界和责任边界非常敏感。3.1 工具注册与 Function Call 的本地实现我用 LangGraph 的ToolNode来注册本地工具。每个工具本质上是一个带 JSON Schema 描述的函数。关键是 Schema 写得越精细模型选参数的准确率越高。from langchain_core.tools import tool from pydantic import BaseModel, Field class QueryAssetInput(BaseModel): asset_name: str Field(description资产名称支持模糊匹配) owner: str | None Field(defaultNone, description负责人工号按精确值过滤) limit: int Field(default10, description最多返回条数1~50) tool(args_schemaQueryAssetInput) def query_internal_asset(asset_name: str, owner: str | None None, limit: int 10) - str: 查询内网资产管理系统中登记IT资产信息包括设备编号、使用人、状态。 # 这里直接调用内网资产管理系统的HTTP API # 注意所有日志要脱敏资产信息属于内部敏感数据 ...工具注册好之后要显式这三点内网系统 API 必须封装成工具不能让 LLM 直接拿到裸 URL。裸 URL 一旦被注入模型可能被诱导去请求任意内网接口。工具输入要做枚举校验。比如owner字段如果不在组织架构名单里直接报错返回不要带着脏参数进入内部系统查询。所有工具调用的入参、出参都要记录到审计日志。关键操作如修改状态、创建工单要有独立审计表谁在什么时间让 Agent 做了什么必须能回溯。3.2 Function Call 的权限边界与控制策略工具链在隔离内网环境里最容易出现事故的点是Agent 的自主权边界。我的做法是给工具分级级别工具类型执行方式L1只读查询查资产、查工单、查文档Agent 自主执行L2业务操作建工单、发通知、改状态Agent 生成请求用户审批后执行L3高权限操作删数据、改配置、批量修改默认禁止需要管理员手动操作这个分级看起来简单但能挡住大量Agent 幻觉操作。尤其是 L2 的审批环节我见过一些团队偷懒直接让 Agent 全自动执行结果模型在工具参数里编造了一个不存在的订单号把下游系统整出脏数据回过头来背锅的还是工程团队。审批环节怎么加最轻量的方式是做一个待确认任务表Agent 先落一条带参数快照的待办记录用户在内部OA/IM系统里点确认确认后才真正调用工具。3.3 和内部系统的认证对接这一步容易被新手忽视内网系统很少有对外开放的免登接口。Agent 要调用内网工具必须解决认证打通问题。常见的三类方式服务账号 OAuth 2.0 Client Credentials适合系统间调用Agent 网关用服务账号获取 token每次工具请求带上。SSO 单点登录用户触发 Agent 行为时用当前用户的 SSO 会话去授权。好处是审计对象是真实用户责任清晰。证书双向认证mTLS安全要求最高的系统直接用证书白名单方式指定哪些服务能访问。几个真正的坑位token 过期时间意外很短。有些内网系统的 token 有效期只有 5 分钟而 Agent 每一步推理可能就要花几秒遇到长链路任务很容易 token 中途失效。需要写 token 管理器做缓存和自动续期。系统调用超时设置必须合理。Agent 调用工具的耗时长会直接放大端到端延迟。把上游工具调用统一封装设置连接超时 3 秒、读超时 30 秒并给每个工具调用加整体超时熔断。内网系统返回的数据通常不是 JSON。我碰到过返回 XML、CSV、甚至直接在 HTML 里渲染的遗留系统。要在工具封装层做健壮的解析不要指望内部系统会给你标准的 REST API。4. 并发压测与稳定性内网 Agent 最容易被忽视的环节AI Agent 怎么扛并发这个热搜问题在隔离内网里显得尤其扎心。外网有弹性伸缩物理机资源受限的内网只能靠精准的架构设计来提升并发表现。4.1 先从经验看瓶颈不在编排框架在模型推理我做过一次真实压测8 张 A80080G跑 7B 量化模型vLLM 部署LangGraph 编排FastAPI 网关。结果很有趣LangGraph 编排层本身 CPU 占用很低FastAPI 异步也能同时挂很多 HTTP 长连接但整体吞吐被模型推理卡死了。vLLM 在没有设置--max-num-seqs时默认值对并发推理的限制会让大量请求排队。用 vLLM 时要重点调这俩参数--max-num-seqs 64 \ --max-parallel-loading-workers 8max-num-seqs控制同时处理的序列数受显存限制。7B AWQ 量化在 80G 显存下开 64 通常没问题。更大的并发数并不能直接提升吞吐因为 GPU 算力就那么多。还想继续压并发上语义缓存。把用户 query或经过改写后的关键子问题的 embedding 存入本地向量库相同语义的问题直接命中缓存不再走模型推理。企业内部系统的用户提问重复度其实相当高——比如上个月工单处理情况某设备现在在谁手里命中率比想象中高很多。我实测过一个运维场景缓存命中率能做到 25%~35%端到端时延从 5~8 秒降到 300 毫秒左右。4.2 网关层的限流、超时与重试隔离内网虽然没有公网流量冲击但内部系统常做批量操作比如早上 9 点全公司统一打卡后的集中查询。此时 Agent 服务会瞬时被大量请求打到。网关层建议配置一套完整策略from slowapi import Limiter from slowapi.util import get_remote_address limiter Limiter(key_funcget_remote_address) app.post(/v1/agent/chat) limiter.limit(30/minute) async def agent_chat(request: Request): ...策略明细单用户限流30 次/分钟防止单个用户刷爆推理资源。服务级信号量进程内asyncio.Semaphore(32)超过并发阈值的请求先排队不要让它全部涌进 vLLM。工具调用超时单个工具 30 秒短链路总超时 60 秒长链路 Agent 任务多步推理总超时 180 秒。失败重试策略只对网络抖动、超时、5xx做重试对模型输出的解析失败或业务侧 4xx 不做重试。重试次数最多 2 次且要带指数退避。把压测跑起来后还会发现另一个问题各种外部系统状态码的语义不统一。有的内网系统超时返回 200 空 body有的直接断开连接发请求的库会抛不同的异常。网关层一定要把所有调用封装成统一的ToolCallResult把网络异常和业务异常分开处理否则 Agent 编排层的重试逻辑很容易被各种各样的异常类型打穿。4.3 流式输出在隔离内网带来的额外压力很多 Agent 应用为了体验必须流式输出。在外网无所谓但隔离内网大量并发流式连接会带来两个隐藏问题内网网关设备防火墙、反向代理网关对连接数量和空闲连接时长有严格限制。我遇到过花 15 分钟调试一个流式接口毫无问题、上到生产环境被网关切断连接的惨案——Trace 日志显示流式响应还没传完连接就断了。SSEServer-Sent Events长连接在读取端必须做断线重连。用户切个网、断开几秒如果前端没有自动重连逻辑流式体验会变成对话框卡死。我的经验是流式输出通道和内网工具调用通道分离开聊天流走 SSE工具调用结果走内部 API。就算前端没把 SSE 收完工具逻辑也已经执行完了下次用户刷新页面重新拉上下文时状态是一致的。5. 实操复盘与避坑清单最后这部分把我在隔离内网项目里真正踩过、修过的坑做一个简单复盘。5.1 常见故障排查链路故障 A内网环境模型推理输出乱码排查链路先直接 curl 模型服务接口绕过 Agent 编排。curl 输出正常说明模型侧没问题问题在 LangGraph 的 Prompt 模板或工具结果编码上。翻日志发现工具返回的是 GBK 编码的 CSV 文件内容LangGraph 按 UTF-8 解析后出现了替换字符\ufffd喂给模型后就乱。解决工具封装层统一做编码探测和转换强制 UTF-8 输出再交回 LLM。这类故障很典型隔离内网里遗留系统用的老编码标准是 Agent 工程里一个不太起眼但极其常见的问题。故障 B一个 Agent 调用链在 200 并发下整体性雪崩排查链路压测一开始报TimeoutError以为是 vLLM 处理不过来。看 vLLM 日志发现显存只有少量占用GPU 利用率低说明请求根本没到 vLLM。原来是 FastAPI 网关用的默认 HTTP 客户端连接池太小往上溯源才发现 Gateway 的 TCP 连接数被撑爆。解决把所有上游调用改为共享httpx.AsyncClient连接池上限开到 256加上信号量限制总并发。这类网络连接数问题在外网环境通常由负载均衡扛掉了内网全靠自己排查方向很容易跑偏。5.2 值得提前规划的三件事这块算是我反复吃过后才有的心得建议第一次做隔离内网 Agent 交付的朋友提前排上日程。内网时钟同步。Agent 链路里涉及审计日志、token 有效期、缓存过期如果内网服务器之间时钟漂移超过几分钟OAuth token 校验就会随机失败缓存命中的表现也会神一块鬼一块。进内网第一件事就是确认 NTP别觉得这是基础设施该管的事Agent 这种跨多系统协作的链路对时间一致性敏感得多。离线模型升级预案。模型或者 Embedding 模型上线后不是一劳永逸的业务效果不好要换版本又得走一遍分卷拷贝、校验、部署的流程。建议从一开始就把模型目录和模型版本管理做好每一版模型的校验和、部署时间、负责人、效果评估记录都留档。等半年后要回滚旧版本时你会感谢当初的自己。统一日志 ID。隔离内网系统多链路追踪很难靠 APM 自动串起来。我会在 FastAPI 网关入口生成一个trace_id透传到 LangGraph 的 state 里再跟着工具调用头传到内部系统。只要日志里都带上这个 ID排障效率可以直接翻倍。没有统一 ID 的话模型输入、工具返回、报错信息散落在三套系统里全靠肉眼对时间那样的日子太痛苦了。隔离内网这个场景短期不一定有海量关注度但只要你做企业级交付又或者想搞一套完全自主可控的 AI 底座它都是绕不开的关卡。这套链路本身并不需要什么特别前卫的技术反而是大量工程细节的累积。补齐怎么搬模型、怎么裁剪架构、怎么管工具权限、怎么扛并发这四块拼图后隔离内网的 Agent 也就没那么吓人了。