隔离内网里做 AI Agent注定不能走“调公网大模型 API”这条捷径但恰恰是这个限制把整个技术栈逼向了更可控、更工程化的方向。这篇就围绕隔离内网下的 AI Agent 工程实战展开讲讲我如何在网络封闭、依赖离线、数据不出内网的前提下把一套可复用的 Agent 系统搭起来并跑通业务。内容偏落地适合要做内部知识问答、自动化运维巡检、内部数据分析助手的团队参考也适合正在纠结 Agent 架构的开发者拿去做蓝本。1. 隔离内网的典型场景与工程挑战1.1 什么项目必须把 Agent 放进隔离内网先摆一个常被忽略的事实很多企业不是“故意找麻烦”而是业务条件天然要求数据不出内网。比如金融行业需要拿 Agent 分析交易流水和客户画像模型既不能把数据送到外部服务也不能让中间链路把日志传到云上政务和国企内部办公系统更是直接物理隔离别说什么公网模型连源码仓库都得走内网 GitLab。另一个常见场景是工业制造生产线的设备监控数据、工艺参数都属于核心资产用 Agent 做设备异常诊断时工具调用背后都是内网的 MQTT、时序数据库和工单系统这些接口极少暴露到公网。即便是互联网公司内部也会把研发侧 Agent 放进隔离区。为什么因为 Agent 要调用内部代码库、CI 流水线、监控平台这些系统通常只有内网域名。如果 Agent 部署在公网等于给内部系统被迫开了一个外部入口安全上很难接受。所以做隔离内网 Agent本质不是为了“能跑”而是为了“让 Agent 长在业务数据旁边”。1.2 隔离环境和公网开发的本质差异公网开发 Agent 时流程基本是注册一个大模型 API、拿密钥、安装官方 SDK、写几行调用代码然后开始调 prompt。整个过程中依赖、模型、工具全部现成十有八九问题出在调 API 的细节上。到了隔离内网所有东西都要自备问题变成“我怎么把模型搞进去、怎么把依赖搞进去、怎么让 Agent 与内部系统通信”。维度公网开发隔离内网模型接入调用云厂商 API本地推理Ollama/vLLM/llama.cpp依赖获取pip 直接联网安装离线包/内部制品库工具 API多为公网开放接口内网私有服务、内部 DNS 解析监控观测云日志可直接接入自建日志、内部监控平台更新迭代模型和依赖随时升级变更需走审批、手动同步这几点差异直接把工程复杂度拉高了一个量级。最直观的是模型分发公网下载模型只要一行命令内网你得先从有网环境把权重拉下来再拷贝进内网还要处理 GB 级文件的断点续传和一致性校验。依赖同理pip install 在隔离环境几乎不可用所有第三方库得提前打成 whl 包或者在内网搭一个 PyPI 镜像源。这些表面上看是资源搬运实际上会直接影响你的整体架构不能假设运行时能动态安装东西所有组件必须提前规划好。作为技术人员最需要扭转的心态是“可用性优先于新颖性”。在隔离环境里追求超大规模的 MoE 模型或者刚发布几天的框架往往会给运维带来很大负担。我们要选的不是能力最强的而是能在内网稳定跑、依赖最少、问题最好排查的那套组合。2. 架构设计与技术选型2.1 Agent 系统的三层骨架一个可上生产的 Agent 系统不管用 LangChain、自研框架还是底层直接调用推理引擎逻辑上都分三层模型层、Agent 编排层、工具层。模型层负责把本地推理引擎包装成稳定的 LLM 服务。这层解决“模型怎么跑、怎么并发、怎么返回结果”的问题。Agent 编排层负责对话流控、任务规划、记忆管理和上下文组织。工具层则是 Agent 触达业务系统的“手”每个工具本质就是一个被封装成函数签名的内部服务接口。可以用一个生活化的类比理解模型层相当于人的大脑反应速度编排层相当于思考方法和短期记忆工具层相当于肢体动作。三层可以松散耦合也可以放在同一个进程里但在隔离内网环境下我强烈建议把三层拆开部署。原因很现实模型层是资源大户需要独立扩缩容编排层要快速迭代业务逻辑工具层往往要连接历史上沉淀很久的老系统单独部署能避免 Agent 进程频繁重启影响工具连接。2.2 模型接入选型本地推理是唯一主线隔离内网没有公网 API 可用所以模型接入只有一个主线本地推理。本地推理牵扯三个选择模型权重、推理框架、硬件资源。模型权重我建议直接从开源阵营里挑。国内能合规获取且中文能力好的有 Qwen 系列、DeepSeek 系列、ChatGLM 系列如果英语占比高LLaMA 系列的量化版本也不错。选型优先级上我会先看业务对上下文长度和工具调用的支持度。比如 Qwen2.5 系列的函数调用能力做得比较规整适合 Agent 这类需要输出 JSON 工具调用的场景。推理框架常见是 Ollama、vLLM、llama.cpp。我的经验是10B 以下的小模型、单机单卡场景Ollama 最省事它把模型格式转换、量化、Serve 都封装好了拿来当内网推理服务很顺手。20B 以上、并发请求多、需要打满 GPU 吞吐vLLM 是更好的选择它的 PagedAttention 和 continuous batching 能显著提速。llama.cpp 则是纯 CPU 或边缘设备上的保底方案别指望它跑大模型有多快但可以稳定跑起来。硬件这块想多说一句很多人以为跑 Agent 必须 A100/H100实际上很多日常 Agent 任务用消费级显卡也足够。Assistant 级应用7B~14B 的量化权重配 16GB 显存就能流畅跑再往上才是 32GB 或双卡场景。隔离内网最忌讳的是“盲目上大模型然后把显卡跑满”一方面大模型推理延迟直线上升用户等不起另一方面内网环境扩硬件要走流程提前做容量规划比事后扩容划算得多。2.3 工具调用与服务注册机制工具层是 Agent 区别于普通聊天机器人的分水岭。在公网环境工具可能是网页搜索、天气查询、地图导航这些现成接口在隔离内网工具往往是 CMDB 查询、登录堡垒机、读取工单状态、写 Java 应用日志库这类内部服务。工程上建议把这些内部服务包装成统一的“函数注册表”每个工具暴露一个 JSON Schema描述它能干什么、需要哪些参数、会返回什么结构。Agent 在编排层拿到用户请求后先用大模型判断该调用哪个工具再生成符合 Schema 的 JSON 参数最后向内部服务发起真实请求。隔离内网里的服务发现比公网简单但也更脆弱通常依赖内部 DNS 和一套自己的网关。我在项目中习惯给每个工具配置独立的超时阈值和重试策略理由很朴素内部服务经常会有诸如凌晨批量任务导致的短暂高负载如果 Agent 把这种偶发超时当成永久失败整个任务链就断了。另外工具层返回数据不要直接原样塞给模型。比如内部接口返回一个 20 字段的对象大模型在总结时很可能被无关字段带偏所以工具层要先做字段裁剪和格式化把核心信息提炼成结构化文本再交给编排层。3. 核心模块的工程化落地3.1 模型服务层封装与并发控制把本地推理引擎跑起来只是第一步真正工程化的是把推理引擎封装成标准 API 并提供可控的并发。我曾经在隔离内网部署过 Ollama它自带的 HTTP 服务已经很成熟但面向 Agent 调用我会在它前面再加一层 Thin Service主要做三件事请求鉴权、并发排队、流式响应转换。请求鉴权不用说内网不代表绝对安全Agent 服务至少要能对调用方做身份校验。并发排队是重点。本地推理引擎的并发能力远低于云 API比如 13B 量化模型在 24GB 显卡上单请求响应大概 2~5 秒并发一旦超过 4显存和等待队列都会告急。所以模型服务层要设计一个简单的令牌桶或信号量让并发请求平滑排队宁可让调用方等待也不要让模型服务直接被打崩。下面是信号量控制的示例import asyncio from fastapi import FastAPI, HTTPException app FastAPI() sem asyncio.Semaphore(4) app.post(/generate) async def generate(payload: dict): if sem.locked(): raise HTTPException(status_code429, detail模型服务繁忙请稍后重试) async with sem: result await call_local_model(payload) return result流式响应转换是配合 Agent 对话体验的。大模型生成文本通常是一段一段吐出来的Agent 编排层拿到的如果只有最终结果用户等待时会感觉“卡死”。把推理引擎的 streaming 输出转成 SSE 或 WebSocket 推给前端对体验提升非常明显。这里要注意工具调用模式下模型可能会先吐一段自然语言解释再吐一个 JSON 工具调用块不能让前端把 JSON 块直接渲染出来编排层要先做一次内容解析再转发。3.2 Agent 编排层持久化与记忆Agent 编排层的核心是对话状态管理。一个用户问“帮我查一下昨天订单量”Agent 需要先决定是否调用 BI 工具拿到结果后还要能记住用户刚才提到的时间范围并在后续追问里继续使用。这背后必须有一个持久化存储不能只把对话放在内存里因为内网服务重启、容器漂移都是常态对话记录丢了会影响整个任务链。我是把会话数据分两类存的短期上下文用 Redis长期记忆用 PostgreSQL 加向量检索。短期上下文指的是最近几轮用户输入、模型输出、工具调用结果这部分数据量小、读写频繁放 Redis 最合适。长期记忆则指那些可以跨会话复用的信息比如用户偏好、历史任务结论、内部系统 ID 映射关系用 PostgreSQL 存储结构化字段再用向量检索扩展相似度查询比如“上次那个大促订单分析”这种模糊引用就得靠向量匹配历史会话标题或摘要。记忆这一块是隔离内网 Agent 最容易做坏的地方。很多团队把“记忆”简单理解成把全部历史消息拼接进 prompt结果 token 数爆炸、模型注意力被稀释、响应质量急剧下降。更合理的做法是分层组织核心指令层、当前任务上下文、工具结果摘要、历史知识归档。只有当前任务上下文和历史知识摘要需要放进模型上下文其他部分该丢就丢。我常用一个简单的压缩策略每五轮对话后让模型把前面的关键信息总结成 200 字以内的摘要替换掉原始消息批次这样长会话也能保持稳定效果。3.3 工具层受限网络的函数调用工具层的实现细节直接决定 Agent 是否能真正完成业务闭环。我习惯把工具定义为 Pydantic 模型加执行函数然后自动生成 JSON Schema。原因有两点第一Pydantic 的字段描述能直接转化成大模型看得懂的工具说明比手写 Schema 高效第二执行函数可以用装饰器统一处理鉴权、日志、限流让每个工具只关注自己的业务逻辑。from pydantic import BaseModel, Field class QueryOrderTool(BaseModel): 查询订单工具 order_id: str Field(..., description订单编号) date_range: str Field(all, description时间范围today/yesterday/last7days) def execute_query_order(args: QueryOrderTool) - dict: # 内部系统调用逻辑 return {order_id: args.order_id, status: success}隔离内网的另一个特点是大量内部服务没有标准 REST API。我接手过一个例子Agent 要查一个老库里的历史报表库上只有 ODBC 接口网络还隔着防火墙。这种情况下硬呐喊“所有工具必须 REST 化”不现实折中方案是在工具服务里写一个适配器把 ODBC 查询包成 REST再由 Agent 编排层调用。适配器层重点处理三类异常连接超时、SQL 重试、字符集乱码。这三类在公网开发中很少遇到在内网里几乎是日常。4. 实操记录从零搭建一个可用的 Agent4.1 离线依赖准备与镜像搬运隔离内网项目启动的第一件事是把开发机上的依赖变成可静止搬运的产物。以 Python 为例正常情况下 pip install 直接装在内网就要换一个思路在有网环境用 pip download 把指定版本的依赖一次性拉下来同时锁定传递依赖版本。这里给出一个典型流程。在能联网的打包机上执行python -m pip download \ -r requirements.txt \ -d ./offline_packages \ --only-binary:all: \ --platform linux_x86_64 \ --python-version 3.10 \ -i https://pypi.org/simple注意 --platform 和 --python-version 必须和目标机匹配否则拷过去装不上。打包完成后把整个 offline_packages 目录连同 checksum 文件一起拷贝进内网再在内网目标机上执行python -m pip install --no-index \ --find-links ./offline_packages \ -r requirements.txt这套流程的核心逻辑是把“动态联网安装”变成“静态离线安装”降低对公网的依赖。如果你内网有 Nexus 或 Artifactory也可以把离线包上传作为内部 PyPI 源这样多台机器都能重复安装。初次搭这个内部源的收益很高否则每台机器都要单独拷贝一遍还容易在版本上出现漂移。4.2 模型权重迁移与加载模型权重比依赖更麻烦动辄几个 GB拷贝、校验、加载都要花时间。我个人会先用 Hugging Face 的标准目录结构把权重下载到有网环境的存储目录包括分词器、配置文件、模型权重文件然后整体打包成 tar 包拷入内网后再解压。如果内网要求更严格连模型来源都要审核那就得走企业内部的模型审批流程把开源模型许可证、安全评估报告一并提交。这不是形式主义而是为了让模型使用可追溯后续出了问题能定位到是哪个版本、哪些权重。在内网环境下我建议对模型权重做一次 SHA256 校验sha256sum -c model.sha256别小看这一步我曾经因为拷贝中断导致某个分片 shard 不完整模型加载时直接报错排查了很长时间才发现是文件损坏。提前校验能把这种坑挡在门外。加载方式上Ollama 的做法非常简单只需把 GGUF 格式模型文件放进指定目录然后在内网执行 ollama serve 启动服务。vLLM 则需要先把 Hugging Face 格式的权重目录路径配置好再指定模型名启动。两种方式我都验证过只要硬件和权重匹配稳定性和效果都有保障。4.3 最小可运行配置这里给一个我在内网实际用的最小可运行示例基于 Ollama 和 Python假设模型已经通过 ollama pull 或离线导入到内网的本地 registry。先启动模型服务ollama serve ollama run qwen2.5:7b-instruct-q4_K_M然后写一个轻量 Agent 客户端核心就三步读输入、调用模型、判断是否需要执行工具。import requests import json OLLAMA_URL http://127.0.0.1:11434/api/generate def call_llm(prompt, toolsNone): payload { model: qwen2.5:7b-instruct-q4_K_M, prompt: prompt, stream: False, options: {temperature: 0.2}, } if tools: payload[tools] tools resp requests.post(OLLAMA_URL, jsonpayload, timeout120) return resp.json()[response] def run_agent(user_input): message f用户问题{user_input}\n请直接给出回答不要输出任何额外内容。 result call_llm(message) print(Agent:, result) if __name__ __main__: run_agent(查询昨天的订单总量)这个示例刻意省略了工具执行逻辑重点展示最小闭环。真实项目里你会在这个循环中加入函数调用解析、工具执行、结果回填等步骤但核心链路已经跑通隔离内网里模型服务可用Agent 能产生自然语言响应。4.4 业务验证与效果评估Agent 部署完不能只看“回答像不像人”要设计一套业务验证脚本。我的做法是准备三组测试样例第一组是纯文本问答验证模型是否能在内网正常生成第二组是工具调用任务比如“调用 CMDB 查服务器 IP”验证函数调用 JSON 是否正确生成并被工具层执行第三组是多轮会话验证记忆和上下文是否连贯。评估指标我关注四个任务完成率、单轮响应延迟、工具调用成功率、上下文吸收率。任务完成率是最直接的业务指标单轮响应延迟决定用户体感工具调用成功率反映 Agent 的“手脚”是否灵活上下文吸收率则用来检测记忆机制是否有效。每轮测试后把失败样本存下来分析到底是模型理解出了问题、工具参数生成错了还是内部服务返回格式不符合预期。这个分析流程比模型本身更影响最终落地质量。5. 常见故障排查与性能优化5.1 典型问题速查表隔离内网环境下的故障和公网环境有很大不同很多问题都是“环境型”而不是“逻辑型”。我把实际踩过的坑整理成速查表逐条看能帮你省下大量排查时间。现象可能原因解决方案模型加载后很快 OOM量化位不够低、并发数设置过高换 Q4 量化、降低最大并发、减小上下文长度工具调用时模型返回的不是合法 JSON温度太高或函数 Schema 描述模糊把温度调到 0.1 以下、把工具描述写得像说明书内网其他机器访问不到模型服务只绑定了 127.0.0.1、防火墙没放行端口服务监听 0.0.0.0检查内网安全组规则依赖安装时找不到某些包离线包没包含指定平台 wheel重新在有网机器用相同 platform 参数下载对话超过几轮后响应质量下降上下文窗口被历史消息塞满引入摘要压缩保留核心指令和最近几轮消息Agent 调用内部服务一直超时工具层没区分连接超时和读取超时为工具设置合理的连接超时如 3s和读取超时如 30s模型返回内容夹杂乱码字符集不匹配、带 BOM 头统一 UTF-8并在协议层指定编码5.2 实测优化心得最后分享几条我在隔离内网实战里总结出的经验都是常规文档不会写的东西。第一不要给 Agent 的模型服务开过高的并发。很多人一看到 GPU 显存还有空闲就把并发调到几十结果响应时延非线性恶化。用信号量把并发控制在 4~6 是我反复验证后比较稳的区间。第二一定要给工具调用做“输出约束”。我在用 Qwen 做工具调用时发现如果温度偏高模型有时会在 JSON 前后多输出解释性文字直接导致 parse 失败。后来我在系统提示里写死“只输出 JSON不要任何前后缀”配合低温度基本能杜绝这个问题。第三隔离内网千万别忽视日志采集。因为环境封闭出了问题你连外部日志平台都查不了所以工具层和编排层要主动把日志写到本地文件或内网日志系统里。日志里至少要包含 request_id、user_input、tool_name、tool_params、model_response 这几项这样回放任务链时才不会摸黑。有一次我上线后接到反馈Agent 在某个查询任务里一直返回“没有权限”排查了半天才发现是内部服务返回的 403 状态被工具层原样透传给了模型模型就把“没有权限”当成最终结论。后来我在工具层统一增加错误码翻译把 401、403、500 分别转成“登录态失效”“访问受限”“服务异常”等语义化信息模型再判断时就准确多了。这种细节往往就是隔离内网 Agent 能不能真正落地的那道坎。我自己做下来最大的体会是隔离内网限制了资源的可获取性却也筛选掉了大量华而不实的设计逼着你把架构做扎实。如果条件允许尽量提前规划好离线包仓库、模型仓库和发布审批流程这些基建多花一周时间后面省下的可能是十倍。