1. 隔离内网里的 AI Agent先解决能不能跑起来再谈跑得好不好做 AI Agent 的人默认都有一大堆外网依赖调云端大模型 API、从 HuggingFace 拉权重、pip install 最新的包、git clone 刚出的开源项目。这些在公网环境下按两下回车就能解决的事一旦落到隔离内网全部变成前置审批、离线导入、手工校验、内网编译的体力活。我最近刚完成一个隔离内网里的 AI Agent 工程落地项目从模型选型、框架搭建到工具调用链路全部走离线化方案过程中踩了不少坑。这篇实战记录给同样要在企业内网做 Agent 落地的开发、运维和架构师做个参考。隔离内网通常指与公网物理隔离或逻辑隔离的企业生产网络。它不是一个“少了外网的环境”而是一个有明确安全边界的运行环境。在这个边界内数据不能随便出域外部服务不能随便访问所有软件和模型物料都必须经过可控的通路进入。AI Agent 要想在这样的环境里跑起来核心挑战不是 Agent 本身有多聪明而是你能不能把模型、依赖、工具、权限这些环节全部变成内网自己的资产。这篇文章会完整拆解我在这个项目里的选型思路、离线部署细节、核心链路设计和排障经验。适合三类人看一是要给企业内部系统做智能化改造的工程师二是负责内网基础设施的运维同学三是刚接触 Agent 工程、想避开常见坑的后端开发者。无论你是用 Python 还是 Rust无论你手里的 GPU 是强是弱只要你的目标是在隔离环境里稳定跑起一个能调用内部工具的 Agent这篇文章应该能帮你省下至少一周的调研时间。1.1 隔离内网到底“隔”住了什么先说清楚隔离内网带来的具体约束因为这些约束直接决定了后面每一步技术选型。第一模型无法在线下载。无论是开源权重还是 tokenizer 文件都必须通过离线审批流程进入内网。这意味着你不能临时换模型所有模型文件必须提前准备、提前校验。第二软件仓库无法直连。pip、npm、cargo 这些包管理工具默认走公网源在内网直接执行 install 大概率会超时或者被安全策略拦截。你得先把所有依赖包下载到中转机再导入内网的私有源或本地目录。第三外部模型 API 不可用。不能调用任何云上的推理接口模型必须本地部署。这意味着 GPU 资源配置、推理引擎选型、量化精度选择都成了必修课。第四Agent 能触达的只能是内网服务。工具调用不能指向公网地址只能对接内部工单、内部数据库、内部消息网关这类系统。Agent 的能力边界其实就是你给它注册的工具集边界。所以隔离内网做 AI Agent本质上是在一个封闭环境里重新实现一遍“模型 推理 工具 记忆”的完整闭环。公网项目里那些“先跑通再优化”的随意性在这里完全行不通。1.2 Agent 工程真正的难点在系统侧现在很多团队第一次设计内网 Agent第一版架构往往照着云端 Demo 抄前端接一个 API后端挂一个 Python 脚本模型用云端接口。到了内网一评审发现模型服务怎么部署、依赖怎么进网、工具权限怎么管控全都没有答案。以我实际落地的经验来看隔离内网里 AI Agent 工程真正的难点集中在四个系统侧问题模型供应链权重文件、分词器、配置文件怎么进网怎么保证来源可信、完整无误。依赖供应链Python 包、Rust crate、系统动态库、容器镜像全部要离线化。工具接入规范Agent 要调用哪些内部系统接口协议怎么定义权限怎么隔离。可观测与审计每一次模型输入输出、工具调用参数和结果都要留痕。这四个问题里任何一个没做好Agent 就算模型再强也上不了生产。后面所有章节都是围绕这四个问题展开的。2. 技术选型Rust 系 Agent 框架 本地推理引擎的组合2.1 主流 AI Agent 架构先对齐一下聊选型之前先对齐一下 Agent 的主流架构不然容易陷入“Agent 一个人形机器人”的误区。目前业内常见的 Agent 架构大致有四类一是单 Agent 自主循环常见实现是 ReAct即模型根据用户问题推理决定调用哪个工具观察工具返回结果后继续推理直到给出最终答案二是 Plan-and-Execute先让模型生成一个执行计划再逐项执行适合任务步骤清晰的场景三是多 Agent 协作用一个主 Agent 编排多个子 Agent子 Agent 各自负责一个领域四是工作流引擎驱动把 Agent 节点嵌入到固定业务流程里更接近传统 BPM只是节点能力由模型提供。在隔离内网环境里我强烈建议优先采用“单 Agent 工具调用”作为起步架构。原因很简单多 Agent 协作会指数级放大不确定性A Agent 的输出是 B Agent 的输入一旦某个输出格式漂移排查链路会非常痛苦。内网环境本来调试手段就受限链路越短越好。Plan-and-Execute 适合任务边界足够清晰的场景比如定时生成报表、批量处理审批。如果你的内网 Agent 一开始就是这类需求可以直接用这个模式。但如果是开放问答、知识库检索加操作业务系统混在一起ReAct 模式更稳。2.2 为什么我选了 Rust 而不是 Python我平时写 Python 不少但这次内网 Agent 的 Agent 主进程我用的是 Rust。核心原因不是“Rust 比 Python 高级”而是隔离内网的部署环境太不友好。Python 部署 Agent 虽然开发快但内网服务器往往系统版本旧Python 版本混乱缺各种系统动态库。今天缺 libssl明天缺 libffi后天 pip 装一个包编译报错光是补环境就能消耗一两天。而 Rust 可以静态编译最终产出一个单一的可执行文件glibc 兼容性处理好扔到内网 x86_64 Linux 服务器上就能跑。Rust 第二个优势是内存安全和并发能力。Agent 主进程要同时管理推理服务调用、多个工具请求、上下文缓存更新。用 Rust 的异步运行时处理这类并发很顺手不容易出现莫名其妙的内存问题。Rust 第三个优势是依赖管理链路更干净。通过cargo vendor可以把所有第三方 crate 完整拉到一个目录内网离线编译时不需要逐个处理动态库整体可复现性比 Python 环境强很多。就 Agent 生态而言Rust 社区已经有rig、genai这类框架支持工具调用、上下文管理、与主流推理服务对接。虽然生态不如 Python 丰富但做内网工具型 Agent 完全够用。这个项目的 Agent 主进程就是基于 Rust 写的。[package] name intranet-agent version 0.1.0 edition 2021 [dependencies] rig-core { version 0.5, features [rust-embeddings] } serde { version 1, features [derive] } serde_json 1 tokio { version 1, features [full] } reqwest { version 0.11, features [json] }依赖的具体版本以你内网私有源里能同步到的为准示例版本只是说明结构。关键是保持依赖锁定用 Cargo.lock 固定所有传递依赖。2.3 本地推理引擎选型对比模型要有地方跑就得选推理引擎。内网环境下我没有选云端服务只考虑开源推理方案。当前主流的四个选项llama.cpp、Ollama、vLLM、ONNX Runtime。llama.cpp 是纯 C 实现的推理引擎支持 GGUF 格式模型CPU 也能跑量化生态成熟部署就是一个二进制加一个模型文件最适合离线分发。Ollama 封装程度高支持模型管理和 API默认也走本地模型但它的模型导入流程需要手动ollama create且不少预置命令会尝试访问公网模型库在内网需要绕开。vLLM 吞吐高支持 PagedAttention适合生产级高并发但依赖较重对 GPU 和 CUDA 版本要求高离线部署工作量更大。ONNX Runtime 适合与其他 AI 组件共享中间表示缺点是部分大模型算子支持滞后。这个项目最终选了 llama.cpp 作为推理引擎。原因很直接GGUF 单文件模型便于校验和迁移llama.cpp 编译产物也是单文件放在内网服务器上几乎零依赖。如果你的环境有专用 GPU 且并发需求高再考虑 vLLM但一定要提前验证 CUDA 依赖链能否完整离线导入。3. 离线环境搭建依赖、模型和校验3.1 第一步先把离线物料清单做出来内网做 Agent最忌讳边做边想缺什么。因为每缺一个包再走一轮导入审批时间成本非常高。我建议开工第一天把下面这份物料清单列全类别物料项用途说明模型GGUF 权重文件推理引擎加载的模型主体模型tokenizer.json分词器用于精确计算 token模型配置文件模型超参、上下文长度说明PythonPython 解释器安装包内网机器没有 Python 时使用Pythonpip wheel 包Agent 工具链中 Python 脚本的依赖Rustvendor 目录离线编译 Agent 主进程系统库libgomp、libssl 等部分组件运行依赖工具jq、curl、sqlite3 二进制调试和 Agent 工具调用使用建议在隔离网外的“中转机”上先把所有物料下载好生成完整的校验文件再按审批流程导入。不要直接拷一个目录就算完每一类物料最好单独压缩包并在压缩包内附一个SHA256SUMS文件。3.2 Rust 依赖离线编译实测Rust 依赖离线编译核心就是cargo vendor。第一步在联网构建机上进入项目目录执行cargo vendor vendor它会根据 Cargo.lock 把用到的所有 crate 源码下载到本地 vendor 目录。第二步把 vendor 目录和整个项目源码一起打包导入内网。内网编译之前需要在项目根目录放一个.cargo/config.toml内容大致如下[source.crates-io] replace-with vendored-sources [source.vendored-sources] directory vendor同时设置环境变量CARGO_NET_OFFLINEtrue再执行cargo build --release。这样 Cargo 不会再尝试联网访问 crates.io全部依赖从本地 vendor 目录解析。这里有一个特别容易踩的坑如果 Cargo.toml 里直接引用了 git 仓库依赖比如某个工具库只发布在 GitHub 上cargo vendor默认也能处理但你必须锁定到具体 commit。否则在联网构建机上生成了 Cargo.lock到了内网环境解析不到目标版本就会卡在 “unable to fetch” 类错误上。任何 git 依赖都建议提前固定rev字段。3.3 模型文件校验与加载模型文件进入内网前一定要做完整性校验。不要只看文件大小对不对要用 sha256 比对。在中转机上生成校验文件sha256sum qwen2.5-7b-instruct-q4_k_m.gguf model.sha256导入内网后重新执行sha256sum -c model.sha256确认校验值完全一致。这个步骤不能省否则模型文件在拷贝过程中损坏推理时会出现奇怪的乱码或反复崩溃排查起来非常浪费时间。校验完成后启动 llama.cpp 的推理服务。这个项目里我使用的启动命令大致如下./llama-server \ -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 127.0.0.1 \ --port 8080 \ --ctx-size 8192这里--ctx-size后面会直接影响到 Agent 的上下文管理策略。我把上下文设为 8192是一个相对保守的数字。如果设成 32768虽然能容纳更长对话但推理速度和显存占用会明显上升。模型名称仅为示例具体以你们单位审批后拿到的模型为准。4. Agent 核心链路实现规划、记忆、工具调用4.1 主循环用 ReAct 模式把 Agent 跑起来Agent 主进程的逻辑用伪代码描述其实很简单接收用户问题 - 拼接系统提示词和历史上下文 - 调用本地推理模型 - 模型要么给出最终答案要么输出一个工具调用请求 - 如果是工具调用执行对应工具并把结果返回给模型 - 继续循环直到模型给出最终答案或达到最大迭代次数。这里有几个必须写死的约束。最大迭代次数我一般设为 8 次防止模型陷入反复调用同一个工具的循环。工具调用结果要完整返回给模型但也要限制单次返回的最大长度否则上下文会很快被撑爆。另外每一轮循环都要记录完整的交互日志方便问题回溯。在 Rust 里我会把主循环写成状态机enum AgentState { NeedAction, FinalAnswer(String), Timeout, } loop { let next run_agent_step(context).await?; match next { AgentState::NeedAction continue, AgentState::FinalAnswer(answer) { println!({}, answer); break; } AgentState::Timeout break, } }实际实现里run_agent_step会调用推理引擎解析返回结果判断是否需要执行工具。这一步是整个 Agent 最核心的部分也是最容易出幺蛾子的地方后面排查章节会专门说。4.2 Token 到底是什么意思为什么必须管好很多刚接触 Agent 的读者会问AI Agent token 是什么意思简单说token 是模型处理文本的最小单元。英文一个单词可能拆成几个 token中文一个汉字大约对应 1 到 2 个 token。模型的上下文窗口单位就是 token表示模型一次最多“看到”多少文本。在公网环境下很多人并不严格计算 token反正云端 API 按量计费超了再充值。但在内网环境上下文窗口是有限的本地显存资源而且窗口越长推理越慢必须先算清楚每一轮对话会消耗多少 token才能避免请求超时或内存溢出。我的做法是用离线 tokenizer 精确计算每次输入的长度。Rust 侧可以直接加载 tokenizer.jsonuse tokenizers::Tokenizer; fn count_tokens(text: str) - usize { let tokenizer Tokenizer::from_file(tokenizer.json) .expect(tokenizer file should exist); let encoding tokenizer.encode(text, true).unwrap(); encoding.get_ids().len() }注意这里的get_ids()返回的是 token id 数组数组长度就是 token 数量。在 Agent 主进程每次调用模型前先统计系统提示词、历史对话、用户输入、工具返回结果的总 token 数。如果接近窗口上限就触发截断策略优先丢弃最早的历史对话保留最近的用户意图和工具结果。这个策略比盲目加大窗口要稳妥因为历史对话里的过时信息本身对当前决策没有太大价值。4.3 内网工具集的注册与调用Agent 的价值全靠工具体现。在内网环境里工具通常是内部工单系统、数据库查询接口、消息推送网关、内部知识库检索。我建议把所有工具按统一格式注册让模型只看到 JSON Schema不感知具体实现。一个查工单的工具定义可以是这样{ name: query_work_order, description: 查询内部工单系统状态, parameters: { type: object, properties: { work_order_id: { type: string } }, required: [work_order_id] } }模型在推理时如果判断需要查询工单就会在输出中带上这个工具名和对应参数。Agent 主进程用 serde 解析这段 JSON再调用内部 HTTP 接口。调用时一定要设置超时一般工具调用超时设为 15 秒以内防止某个内部服务假死拖垮整个 Agent 循环。说到对接外部平台比如大家常提的“让小红书自动发消息”这类需求我的建议是不要由 Agent 直接操作外部账号。更稳的做法是Agent 只生成内容草稿然后投递到内部审核队列由业务系统走完合规审批后再执行发布。隔离内网环境里尤其如此Agent 的能力边界应该由权限控制系统强制约束而不是靠提示词约束。4.4 与 Django 等业务系统集成的正确姿势很多团队的应用后端是 Django。Agent 要和 Django 系统集成最干净的方式是让 Django 侧提供 REST APIAgent 侧只注册工具调用两边通过 OpenAPI 文档对齐接口。不建议让 Agent 直接连 Django 的数据库。原因有两个一是数据库结构通常不在 Agent 可控范围一旦模型生成了一条错误 SQL影响面不可控二是数据库账号权限很难审计到具体操作行为。更好的做法是让 Django 业务层封装好所有操作接口Agent 只调用接口权限在接口层控制。如果 Agent 需要主动推送消息比如定时生成报表后发给企业微信或钉钉走内部消息队列更稳。Agent 把消息写入队列消费端负责投递和重试两边解耦。5. 隔离网络环境下的部署、安全与运维5.1 部署形态单机起步别一开始就上集群内网 Agent 项目立项时总有人想把架构设计成微服务集群、GPU 池化、多副本高可用。我的经验是先单机把链路跑通再根据瓶颈横向扩展。单机部署形态下至少有三个进程一是 llama.cpp 的推理服务监听本地 8080 端口二是 Rust 写的 Agent 主进程负责对话编排和工具调用三是可选的内存缓存服务用于存储会话状态。如果暂时没有 Redis 等组件Rust 主进程内置一个 TTL 缓存也能扛过前期。为什么建议单机起步因为隔离内网的网络策略、权限管控、日志采集都涉及变更审批多一个节点就多一堆流程。先把单机上的推理、Agent、工具调用联通再考虑加节点推进节奏会顺畅很多。5.2 权限隔离与工具调用安全加固Agent 能调用工具相当于给了模型一双操作内网的“手”。权限隔离必须做到位。首要原则是 Agent 主进程绝不能用 root 运行。在 Linux 下用非特权用户跑并配合 systemd 的沙箱能力。下面是一个 systemd service 示例[Unit] DescriptionIntranet Agent Afternetwork.target [Service] Useragent Groupagent ExecStart/opt/agent/bin/intranet-agent Restarton-failure NoNewPrivilegestrue PrivateTmptrue ProtectSystemfullNoNewPrivilegestrue表示禁止进程再获得新权限ProtectSystemfull把系统目录设为只读。这两个配置对隔离内网安全审计特别有用。工具调用侧我建议统一走内部网关鉴权不要在 Agent 配置文件里塞各个系统的明文账号。Agent 只持有网关签发的短期令牌每个工具接口在网关上做权限校验。这样就算模型生成的参数有偏差最坏情况也只是某个请求被网关拒绝不会直接暴露核心系统凭据。5.3 日志审计隔离内网里留痕比功能更重要隔离内网的合规要求通常比公网项目严格得多。AI Agent 在生产环境里跑每一次交互都要能追溯。我为每个请求设计了一份结构化日志字段包括请求 ID、用户标识、时间戳、模型 ID、输入 token 数、输出 token 数、工具调用列表、每个工具的入参和出参、最终响应内容、耗时。日志以 JSON Lines 格式追加写入再通过内网日志平台采集。这里有个容易被忽视的点工具返回结果可能包含敏感的内部数据日志里必须按需脱敏。比如工单内容中的用户手机号、身份证号要提前用掩码规则处理后再落盘。审计要保留完整信息但又不能把最高敏感级明文到处放具体脱敏策略需要和合规团队一起定。5.4 模型更新与灰度发布流程模型不是部署一次就一劳永逸的。内网里更新模型不能像公网那样直接在后台切换一个 API 版本要走可控流程。我的做法是把模型文件按版本放在内网一个只读目录里通过软链切换当前生效版本。新模型导入后先在灰度环境跑一组固定的回归用例比如“查询工单状态”“汇总今日数据指标”这类典型问题。只有回归通过才切换生产流量。量化版本也要标注清楚。同一个模型Q4_K_M 和 Q8_0 的效果差异可能很明显。更新记录里要写明这个版本是哪个基座、哪个量化方式、上下文窗口多大否则过了两周没人记得当前生产模型到底是什么。6. 常见问题排查与避坑实录6.1 高频问题速查表内网 Agent 调试过程中会遇到一些极具共性的问题。我整理了一张速查表现象可能原因解决办法模型加载后推理非常慢上下文窗口开太大或量化精度过高降低--ctx-size或换更高显存的机器Agent 第一次调用工具就超时工具地址配了公网域名改成内网域名或写入/etc/hostsRust 编译报 git 依赖无法获取依赖未锁定 commit固定rev并设置CARGO_NET_OFFLINEtrue模型输出总是带 markdown 代码块工具结果提示词不够明确解析前先剥离代码块标记再提取 JSON对话超过三轮后内容错乱历史上下文进入窗口被截断调整滚动摘要策略或降低单条工具返回长度知识库检索不到结果向量模型文件未正确加载校验 embedding 模型权重与 tokenizer 一致性这张表只覆盖最前面的一层问题。真实排障中最耗时往往是环境问题而非算法问题。6.2 避坑实录这些经验是花钱买来的第一个坑先固定工具协议再调 prompt。项目开始时我为了让模型更“听话”花了很多时间精调提示词。后来换了新版本模型发现之前的提示词全要重调而工具调用格式却一直变来变去。正确的顺序是先把工具 Schema 固定死再让模型去适配 Schema最后才到提示词层面微调。工具协议稳定了换模型影响面就小得多。第二个坑不要执着于最新大模型。内网项目最看重的是可复现性。公网上可以今天用 GPT 级别模型明天换新一代模型内网换一次模型要重新走审批、校验、灰度。与其追最新参数量的模型不如选一个适合内网算力、经过充分验证的 7B 到 14B 模型深耕工具调用稳定性。第三个坑上下文越大不等于效果越好。刚开始我总觉得反正机器显存够上下文设大一点总没坏处。实际测下来上下文翻倍推理耗时可能增加三成到五成。Agent 需要的不是无限上下文而是精准的上下文。历史对话能用摘要压缩就用摘要压缩工具返回结果能只留关键字段就只留关键字段。第四个坑给每个工具定义明确的失败返回格式。模型根据工具返回结果决定下一步动作。如果工具在网络中断时直接抛异常模型看到的就是一堆堆栈根本不知道如何继续。我现在的做法是让所有工具在失败时都返回统一的 JSON 结构包含错误码、错误描述、可执行建议。模型看到错误码后才知道是重试还是换一种查询方式。第五个坑日志里一定要记录 token 消耗。虽然内网模型不按 token 计费但 token 消耗直接反映上下文使用效率。如果同样一个问题平均消耗 token 越来越多说明上下文管理策略出了问题要么历史没有及时清理要么工具返回过大。没有 token 维度日志这类问题只能靠猜。最后一件事我觉得比任何技术方案都重要隔离内网做 AI Agent看起来处处受限但当你把模型、依赖、工具、权限全部沉淀成内网标准物料之后这套系统的稳定性反而比公网 API 拼装出来的 Demo 高很多。公网模型接口偶尔抖一下、停个服你无能为力内网自己掌握模型和推理服务反而把不确定性控制在了手里。如果你也正在做类似的事我建议第一周别急着写 Agent 逻辑先把离线物料清单和部署脚本打磨好这会让你后面每一步都轻松很多。 隔离内网AI Agent落地实战：离线部署、工具调用与安全管控
1. 隔离内网里的 AI Agent先解决能不能跑起来再谈跑得好不好做 AI Agent 的人默认都有一大堆外网依赖调云端大模型 API、从 HuggingFace 拉权重、pip install 最新的包、git clone 刚出的开源项目。这些在公网环境下按两下回车就能解决的事一旦落到隔离内网全部变成前置审批、离线导入、手工校验、内网编译的体力活。我最近刚完成一个隔离内网里的 AI Agent 工程落地项目从模型选型、框架搭建到工具调用链路全部走离线化方案过程中踩了不少坑。这篇实战记录给同样要在企业内网做 Agent 落地的开发、运维和架构师做个参考。隔离内网通常指与公网物理隔离或逻辑隔离的企业生产网络。它不是一个“少了外网的环境”而是一个有明确安全边界的运行环境。在这个边界内数据不能随便出域外部服务不能随便访问所有软件和模型物料都必须经过可控的通路进入。AI Agent 要想在这样的环境里跑起来核心挑战不是 Agent 本身有多聪明而是你能不能把模型、依赖、工具、权限这些环节全部变成内网自己的资产。这篇文章会完整拆解我在这个项目里的选型思路、离线部署细节、核心链路设计和排障经验。适合三类人看一是要给企业内部系统做智能化改造的工程师二是负责内网基础设施的运维同学三是刚接触 Agent 工程、想避开常见坑的后端开发者。无论你是用 Python 还是 Rust无论你手里的 GPU 是强是弱只要你的目标是在隔离环境里稳定跑起一个能调用内部工具的 Agent这篇文章应该能帮你省下至少一周的调研时间。1.1 隔离内网到底“隔”住了什么先说清楚隔离内网带来的具体约束因为这些约束直接决定了后面每一步技术选型。第一模型无法在线下载。无论是开源权重还是 tokenizer 文件都必须通过离线审批流程进入内网。这意味着你不能临时换模型所有模型文件必须提前准备、提前校验。第二软件仓库无法直连。pip、npm、cargo 这些包管理工具默认走公网源在内网直接执行 install 大概率会超时或者被安全策略拦截。你得先把所有依赖包下载到中转机再导入内网的私有源或本地目录。第三外部模型 API 不可用。不能调用任何云上的推理接口模型必须本地部署。这意味着 GPU 资源配置、推理引擎选型、量化精度选择都成了必修课。第四Agent 能触达的只能是内网服务。工具调用不能指向公网地址只能对接内部工单、内部数据库、内部消息网关这类系统。Agent 的能力边界其实就是你给它注册的工具集边界。所以隔离内网做 AI Agent本质上是在一个封闭环境里重新实现一遍“模型 推理 工具 记忆”的完整闭环。公网项目里那些“先跑通再优化”的随意性在这里完全行不通。1.2 Agent 工程真正的难点在系统侧现在很多团队第一次设计内网 Agent第一版架构往往照着云端 Demo 抄前端接一个 API后端挂一个 Python 脚本模型用云端接口。到了内网一评审发现模型服务怎么部署、依赖怎么进网、工具权限怎么管控全都没有答案。以我实际落地的经验来看隔离内网里 AI Agent 工程真正的难点集中在四个系统侧问题模型供应链权重文件、分词器、配置文件怎么进网怎么保证来源可信、完整无误。依赖供应链Python 包、Rust crate、系统动态库、容器镜像全部要离线化。工具接入规范Agent 要调用哪些内部系统接口协议怎么定义权限怎么隔离。可观测与审计每一次模型输入输出、工具调用参数和结果都要留痕。这四个问题里任何一个没做好Agent 就算模型再强也上不了生产。后面所有章节都是围绕这四个问题展开的。2. 技术选型Rust 系 Agent 框架 本地推理引擎的组合2.1 主流 AI Agent 架构先对齐一下聊选型之前先对齐一下 Agent 的主流架构不然容易陷入“Agent 一个人形机器人”的误区。目前业内常见的 Agent 架构大致有四类一是单 Agent 自主循环常见实现是 ReAct即模型根据用户问题推理决定调用哪个工具观察工具返回结果后继续推理直到给出最终答案二是 Plan-and-Execute先让模型生成一个执行计划再逐项执行适合任务步骤清晰的场景三是多 Agent 协作用一个主 Agent 编排多个子 Agent子 Agent 各自负责一个领域四是工作流引擎驱动把 Agent 节点嵌入到固定业务流程里更接近传统 BPM只是节点能力由模型提供。在隔离内网环境里我强烈建议优先采用“单 Agent 工具调用”作为起步架构。原因很简单多 Agent 协作会指数级放大不确定性A Agent 的输出是 B Agent 的输入一旦某个输出格式漂移排查链路会非常痛苦。内网环境本来调试手段就受限链路越短越好。Plan-and-Execute 适合任务边界足够清晰的场景比如定时生成报表、批量处理审批。如果你的内网 Agent 一开始就是这类需求可以直接用这个模式。但如果是开放问答、知识库检索加操作业务系统混在一起ReAct 模式更稳。2.2 为什么我选了 Rust 而不是 Python我平时写 Python 不少但这次内网 Agent 的 Agent 主进程我用的是 Rust。核心原因不是“Rust 比 Python 高级”而是隔离内网的部署环境太不友好。Python 部署 Agent 虽然开发快但内网服务器往往系统版本旧Python 版本混乱缺各种系统动态库。今天缺 libssl明天缺 libffi后天 pip 装一个包编译报错光是补环境就能消耗一两天。而 Rust 可以静态编译最终产出一个单一的可执行文件glibc 兼容性处理好扔到内网 x86_64 Linux 服务器上就能跑。Rust 第二个优势是内存安全和并发能力。Agent 主进程要同时管理推理服务调用、多个工具请求、上下文缓存更新。用 Rust 的异步运行时处理这类并发很顺手不容易出现莫名其妙的内存问题。Rust 第三个优势是依赖管理链路更干净。通过cargo vendor可以把所有第三方 crate 完整拉到一个目录内网离线编译时不需要逐个处理动态库整体可复现性比 Python 环境强很多。就 Agent 生态而言Rust 社区已经有rig、genai这类框架支持工具调用、上下文管理、与主流推理服务对接。虽然生态不如 Python 丰富但做内网工具型 Agent 完全够用。这个项目的 Agent 主进程就是基于 Rust 写的。[package] name intranet-agent version 0.1.0 edition 2021 [dependencies] rig-core { version 0.5, features [rust-embeddings] } serde { version 1, features [derive] } serde_json 1 tokio { version 1, features [full] } reqwest { version 0.11, features [json] }依赖的具体版本以你内网私有源里能同步到的为准示例版本只是说明结构。关键是保持依赖锁定用 Cargo.lock 固定所有传递依赖。2.3 本地推理引擎选型对比模型要有地方跑就得选推理引擎。内网环境下我没有选云端服务只考虑开源推理方案。当前主流的四个选项llama.cpp、Ollama、vLLM、ONNX Runtime。llama.cpp 是纯 C 实现的推理引擎支持 GGUF 格式模型CPU 也能跑量化生态成熟部署就是一个二进制加一个模型文件最适合离线分发。Ollama 封装程度高支持模型管理和 API默认也走本地模型但它的模型导入流程需要手动ollama create且不少预置命令会尝试访问公网模型库在内网需要绕开。vLLM 吞吐高支持 PagedAttention适合生产级高并发但依赖较重对 GPU 和 CUDA 版本要求高离线部署工作量更大。ONNX Runtime 适合与其他 AI 组件共享中间表示缺点是部分大模型算子支持滞后。这个项目最终选了 llama.cpp 作为推理引擎。原因很直接GGUF 单文件模型便于校验和迁移llama.cpp 编译产物也是单文件放在内网服务器上几乎零依赖。如果你的环境有专用 GPU 且并发需求高再考虑 vLLM但一定要提前验证 CUDA 依赖链能否完整离线导入。3. 离线环境搭建依赖、模型和校验3.1 第一步先把离线物料清单做出来内网做 Agent最忌讳边做边想缺什么。因为每缺一个包再走一轮导入审批时间成本非常高。我建议开工第一天把下面这份物料清单列全类别物料项用途说明模型GGUF 权重文件推理引擎加载的模型主体模型tokenizer.json分词器用于精确计算 token模型配置文件模型超参、上下文长度说明PythonPython 解释器安装包内网机器没有 Python 时使用Pythonpip wheel 包Agent 工具链中 Python 脚本的依赖Rustvendor 目录离线编译 Agent 主进程系统库libgomp、libssl 等部分组件运行依赖工具jq、curl、sqlite3 二进制调试和 Agent 工具调用使用建议在隔离网外的“中转机”上先把所有物料下载好生成完整的校验文件再按审批流程导入。不要直接拷一个目录就算完每一类物料最好单独压缩包并在压缩包内附一个SHA256SUMS文件。3.2 Rust 依赖离线编译实测Rust 依赖离线编译核心就是cargo vendor。第一步在联网构建机上进入项目目录执行cargo vendor vendor它会根据 Cargo.lock 把用到的所有 crate 源码下载到本地 vendor 目录。第二步把 vendor 目录和整个项目源码一起打包导入内网。内网编译之前需要在项目根目录放一个.cargo/config.toml内容大致如下[source.crates-io] replace-with vendored-sources [source.vendored-sources] directory vendor同时设置环境变量CARGO_NET_OFFLINEtrue再执行cargo build --release。这样 Cargo 不会再尝试联网访问 crates.io全部依赖从本地 vendor 目录解析。这里有一个特别容易踩的坑如果 Cargo.toml 里直接引用了 git 仓库依赖比如某个工具库只发布在 GitHub 上cargo vendor默认也能处理但你必须锁定到具体 commit。否则在联网构建机上生成了 Cargo.lock到了内网环境解析不到目标版本就会卡在 “unable to fetch” 类错误上。任何 git 依赖都建议提前固定rev字段。3.3 模型文件校验与加载模型文件进入内网前一定要做完整性校验。不要只看文件大小对不对要用 sha256 比对。在中转机上生成校验文件sha256sum qwen2.5-7b-instruct-q4_k_m.gguf model.sha256导入内网后重新执行sha256sum -c model.sha256确认校验值完全一致。这个步骤不能省否则模型文件在拷贝过程中损坏推理时会出现奇怪的乱码或反复崩溃排查起来非常浪费时间。校验完成后启动 llama.cpp 的推理服务。这个项目里我使用的启动命令大致如下./llama-server \ -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 127.0.0.1 \ --port 8080 \ --ctx-size 8192这里--ctx-size后面会直接影响到 Agent 的上下文管理策略。我把上下文设为 8192是一个相对保守的数字。如果设成 32768虽然能容纳更长对话但推理速度和显存占用会明显上升。模型名称仅为示例具体以你们单位审批后拿到的模型为准。4. Agent 核心链路实现规划、记忆、工具调用4.1 主循环用 ReAct 模式把 Agent 跑起来Agent 主进程的逻辑用伪代码描述其实很简单接收用户问题 - 拼接系统提示词和历史上下文 - 调用本地推理模型 - 模型要么给出最终答案要么输出一个工具调用请求 - 如果是工具调用执行对应工具并把结果返回给模型 - 继续循环直到模型给出最终答案或达到最大迭代次数。这里有几个必须写死的约束。最大迭代次数我一般设为 8 次防止模型陷入反复调用同一个工具的循环。工具调用结果要完整返回给模型但也要限制单次返回的最大长度否则上下文会很快被撑爆。另外每一轮循环都要记录完整的交互日志方便问题回溯。在 Rust 里我会把主循环写成状态机enum AgentState { NeedAction, FinalAnswer(String), Timeout, } loop { let next run_agent_step(context).await?; match next { AgentState::NeedAction continue, AgentState::FinalAnswer(answer) { println!({}, answer); break; } AgentState::Timeout break, } }实际实现里run_agent_step会调用推理引擎解析返回结果判断是否需要执行工具。这一步是整个 Agent 最核心的部分也是最容易出幺蛾子的地方后面排查章节会专门说。4.2 Token 到底是什么意思为什么必须管好很多刚接触 Agent 的读者会问AI Agent token 是什么意思简单说token 是模型处理文本的最小单元。英文一个单词可能拆成几个 token中文一个汉字大约对应 1 到 2 个 token。模型的上下文窗口单位就是 token表示模型一次最多“看到”多少文本。在公网环境下很多人并不严格计算 token反正云端 API 按量计费超了再充值。但在内网环境上下文窗口是有限的本地显存资源而且窗口越长推理越慢必须先算清楚每一轮对话会消耗多少 token才能避免请求超时或内存溢出。我的做法是用离线 tokenizer 精确计算每次输入的长度。Rust 侧可以直接加载 tokenizer.jsonuse tokenizers::Tokenizer; fn count_tokens(text: str) - usize { let tokenizer Tokenizer::from_file(tokenizer.json) .expect(tokenizer file should exist); let encoding tokenizer.encode(text, true).unwrap(); encoding.get_ids().len() }注意这里的get_ids()返回的是 token id 数组数组长度就是 token 数量。在 Agent 主进程每次调用模型前先统计系统提示词、历史对话、用户输入、工具返回结果的总 token 数。如果接近窗口上限就触发截断策略优先丢弃最早的历史对话保留最近的用户意图和工具结果。这个策略比盲目加大窗口要稳妥因为历史对话里的过时信息本身对当前决策没有太大价值。4.3 内网工具集的注册与调用Agent 的价值全靠工具体现。在内网环境里工具通常是内部工单系统、数据库查询接口、消息推送网关、内部知识库检索。我建议把所有工具按统一格式注册让模型只看到 JSON Schema不感知具体实现。一个查工单的工具定义可以是这样{ name: query_work_order, description: 查询内部工单系统状态, parameters: { type: object, properties: { work_order_id: { type: string } }, required: [work_order_id] } }模型在推理时如果判断需要查询工单就会在输出中带上这个工具名和对应参数。Agent 主进程用 serde 解析这段 JSON再调用内部 HTTP 接口。调用时一定要设置超时一般工具调用超时设为 15 秒以内防止某个内部服务假死拖垮整个 Agent 循环。说到对接外部平台比如大家常提的“让小红书自动发消息”这类需求我的建议是不要由 Agent 直接操作外部账号。更稳的做法是Agent 只生成内容草稿然后投递到内部审核队列由业务系统走完合规审批后再执行发布。隔离内网环境里尤其如此Agent 的能力边界应该由权限控制系统强制约束而不是靠提示词约束。4.4 与 Django 等业务系统集成的正确姿势很多团队的应用后端是 Django。Agent 要和 Django 系统集成最干净的方式是让 Django 侧提供 REST APIAgent 侧只注册工具调用两边通过 OpenAPI 文档对齐接口。不建议让 Agent 直接连 Django 的数据库。原因有两个一是数据库结构通常不在 Agent 可控范围一旦模型生成了一条错误 SQL影响面不可控二是数据库账号权限很难审计到具体操作行为。更好的做法是让 Django 业务层封装好所有操作接口Agent 只调用接口权限在接口层控制。如果 Agent 需要主动推送消息比如定时生成报表后发给企业微信或钉钉走内部消息队列更稳。Agent 把消息写入队列消费端负责投递和重试两边解耦。5. 隔离网络环境下的部署、安全与运维5.1 部署形态单机起步别一开始就上集群内网 Agent 项目立项时总有人想把架构设计成微服务集群、GPU 池化、多副本高可用。我的经验是先单机把链路跑通再根据瓶颈横向扩展。单机部署形态下至少有三个进程一是 llama.cpp 的推理服务监听本地 8080 端口二是 Rust 写的 Agent 主进程负责对话编排和工具调用三是可选的内存缓存服务用于存储会话状态。如果暂时没有 Redis 等组件Rust 主进程内置一个 TTL 缓存也能扛过前期。为什么建议单机起步因为隔离内网的网络策略、权限管控、日志采集都涉及变更审批多一个节点就多一堆流程。先把单机上的推理、Agent、工具调用联通再考虑加节点推进节奏会顺畅很多。5.2 权限隔离与工具调用安全加固Agent 能调用工具相当于给了模型一双操作内网的“手”。权限隔离必须做到位。首要原则是 Agent 主进程绝不能用 root 运行。在 Linux 下用非特权用户跑并配合 systemd 的沙箱能力。下面是一个 systemd service 示例[Unit] DescriptionIntranet Agent Afternetwork.target [Service] Useragent Groupagent ExecStart/opt/agent/bin/intranet-agent Restarton-failure NoNewPrivilegestrue PrivateTmptrue ProtectSystemfullNoNewPrivilegestrue表示禁止进程再获得新权限ProtectSystemfull把系统目录设为只读。这两个配置对隔离内网安全审计特别有用。工具调用侧我建议统一走内部网关鉴权不要在 Agent 配置文件里塞各个系统的明文账号。Agent 只持有网关签发的短期令牌每个工具接口在网关上做权限校验。这样就算模型生成的参数有偏差最坏情况也只是某个请求被网关拒绝不会直接暴露核心系统凭据。5.3 日志审计隔离内网里留痕比功能更重要隔离内网的合规要求通常比公网项目严格得多。AI Agent 在生产环境里跑每一次交互都要能追溯。我为每个请求设计了一份结构化日志字段包括请求 ID、用户标识、时间戳、模型 ID、输入 token 数、输出 token 数、工具调用列表、每个工具的入参和出参、最终响应内容、耗时。日志以 JSON Lines 格式追加写入再通过内网日志平台采集。这里有个容易被忽视的点工具返回结果可能包含敏感的内部数据日志里必须按需脱敏。比如工单内容中的用户手机号、身份证号要提前用掩码规则处理后再落盘。审计要保留完整信息但又不能把最高敏感级明文到处放具体脱敏策略需要和合规团队一起定。5.4 模型更新与灰度发布流程模型不是部署一次就一劳永逸的。内网里更新模型不能像公网那样直接在后台切换一个 API 版本要走可控流程。我的做法是把模型文件按版本放在内网一个只读目录里通过软链切换当前生效版本。新模型导入后先在灰度环境跑一组固定的回归用例比如“查询工单状态”“汇总今日数据指标”这类典型问题。只有回归通过才切换生产流量。量化版本也要标注清楚。同一个模型Q4_K_M 和 Q8_0 的效果差异可能很明显。更新记录里要写明这个版本是哪个基座、哪个量化方式、上下文窗口多大否则过了两周没人记得当前生产模型到底是什么。6. 常见问题排查与避坑实录6.1 高频问题速查表内网 Agent 调试过程中会遇到一些极具共性的问题。我整理了一张速查表现象可能原因解决办法模型加载后推理非常慢上下文窗口开太大或量化精度过高降低--ctx-size或换更高显存的机器Agent 第一次调用工具就超时工具地址配了公网域名改成内网域名或写入/etc/hostsRust 编译报 git 依赖无法获取依赖未锁定 commit固定rev并设置CARGO_NET_OFFLINEtrue模型输出总是带 markdown 代码块工具结果提示词不够明确解析前先剥离代码块标记再提取 JSON对话超过三轮后内容错乱历史上下文进入窗口被截断调整滚动摘要策略或降低单条工具返回长度知识库检索不到结果向量模型文件未正确加载校验 embedding 模型权重与 tokenizer 一致性这张表只覆盖最前面的一层问题。真实排障中最耗时往往是环境问题而非算法问题。6.2 避坑实录这些经验是花钱买来的第一个坑先固定工具协议再调 prompt。项目开始时我为了让模型更“听话”花了很多时间精调提示词。后来换了新版本模型发现之前的提示词全要重调而工具调用格式却一直变来变去。正确的顺序是先把工具 Schema 固定死再让模型去适配 Schema最后才到提示词层面微调。工具协议稳定了换模型影响面就小得多。第二个坑不要执着于最新大模型。内网项目最看重的是可复现性。公网上可以今天用 GPT 级别模型明天换新一代模型内网换一次模型要重新走审批、校验、灰度。与其追最新参数量的模型不如选一个适合内网算力、经过充分验证的 7B 到 14B 模型深耕工具调用稳定性。第三个坑上下文越大不等于效果越好。刚开始我总觉得反正机器显存够上下文设大一点总没坏处。实际测下来上下文翻倍推理耗时可能增加三成到五成。Agent 需要的不是无限上下文而是精准的上下文。历史对话能用摘要压缩就用摘要压缩工具返回结果能只留关键字段就只留关键字段。第四个坑给每个工具定义明确的失败返回格式。模型根据工具返回结果决定下一步动作。如果工具在网络中断时直接抛异常模型看到的就是一堆堆栈根本不知道如何继续。我现在的做法是让所有工具在失败时都返回统一的 JSON 结构包含错误码、错误描述、可执行建议。模型看到错误码后才知道是重试还是换一种查询方式。第五个坑日志里一定要记录 token 消耗。虽然内网模型不按 token 计费但 token 消耗直接反映上下文使用效率。如果同样一个问题平均消耗 token 越来越多说明上下文管理策略出了问题要么历史没有及时清理要么工具返回过大。没有 token 维度日志这类问题只能靠猜。最后一件事我觉得比任何技术方案都重要隔离内网做 AI Agent看起来处处受限但当你把模型、依赖、工具、权限全部沉淀成内网标准物料之后这套系统的稳定性反而比公网 API 拼装出来的 Demo 高很多。公网模型接口偶尔抖一下、停个服你无能为力内网自己掌握模型和推理服务反而把不确定性控制在了手里。如果你也正在做类似的事我建议第一周别急着写 Agent 逻辑先把离线物料清单和部署脚本打磨好这会让你后面每一步都轻松很多。