1. 整体设计与选型思路1.1 隔离内网下的核心约束拆解先说清楚这个项目的边界。所谓“隔离内网”指的不是普通办公网那种能上外网、只是网速慢的环境而是物理隔离或策略隔离的网络——机器之间能互相通信但整个网段对外部互联网不可达。你在这种环境里做AI Agent会同时撞上四堵墙模型从哪来、依赖怎么装、服务怎么发现、任务怎么调度。第一堵墙是模型本身。Agent的核心是推理能力而主流的大模型API全部在公网内网根本调不通。所以你必须提前把模型文件拷贝进内网再本地起推理服务。这就牵扯出第二个问题推理引擎装在哪台机器上、用什么框架加载、显存够不够。我们当时的环境是几台双卡3090的机器网络隔离但GPU资源还算宽裕所以选型空间比较大。第二堵墙是依赖管理。Python生态的pip、Node的npm、Rust的crates.io全部需要联网拉取。内网装依赖要么提前把包下载好带进去要么在网内搭私有源。对Rust来说还有一个更隐蔽的坑cargo build时会根据平台重新编译依赖如果你携带的是源代码包而不是编译好的二进制整个过程会非常漫长而且编译期错误在内网环境下极难排查。第三堵墙是服务发现。外网环境下微服务可以用Consul、Nacos或者K8s的DNS做注册发现但内网没有这些基础设施有时候连DNS都不完整。你需要自己设计一套极简的服务发现机制比如基于UDP广播或者共享文件目录的注册表。第四堵墙是任务调度。当Agent需要同时处理多个用户的请求或者一个复杂任务要拆成多个子任务并行执行时没有外部的消息队列可用。我们最终用Rust的channel加共享状态机实现了轻量级调度不引入额外的中间件。这四个问题不是独立的它们互相纠缠。比如你选模型时就得考虑推理引擎是否支持离线加载否则模型文件拷进去了也跑不起来你设计服务发现时又得考虑Agent的ReAct循环会不会被网络抖动中断。所以整个项目的第一步不是写代码而是把这些约束全部列成一张表逐项确认解决方案。1.2 为什么选Rust而不是Python这个决定在当时引起了不小的讨论。团队里大多数人熟悉Python而且LangChain、LlamaIndex这些Agent框架的生态都在Python侧。但隔离内网的环境让我们必须重新审视语言选型。首先是运行时依赖。Python的Agent项目想跑起来至少需要Python解释器、一堆pip包、有时候还要装CUDA的Python绑定。这些依赖在内网环境下安装顺序错了就会出问题。Rust是静态编译编完就是一个可执行文件把二进制和模型文件带进内网就能跑省掉了大量环境配置工作。其次是并发性能。Agent的实际运行不是线性地调用大模型而是有一个感知-规划-行动的循环这个循环里会有大量的工具调用、上下文拼接、中间结果缓存。Python的GIL在这种场景下会成为瓶颈而Rust的async/await和channel机制能很自然地写出高并发调度器。我们在压测中对比过同样一台机器Rust版本的工具调用吞吐量大约是Python版本的3到5倍。第三是类型安全。Agent的核心逻辑是状态机等待输入、理解意图、调用工具、观察结果、生成回复。这个状态迁移过程中消息格式、工具参数、任务ID这些字段如果类型出错在Python里往往要运行时才能发现。Rust的编译期检查把这类错误提前拦截了在内网这种难以快速迭代调试的环境里这个优势被放大。当然Rust也有代价开发速度慢、生态相对薄、没有LangChain那种完整的Agent框架。所以我最终的方案不是全用Rust而是分两层——核心调度和通信用Rust模型服务的胶水逻辑和快速实验用Python。这样既保住了性能又不至于让开发进度卡死。1.3 模型选型与推理服务设计隔离内网下的模型选型核心原则只有一条必须在部署前确认模型能够完全离线工作。这个“离线”不光是说模型权重文件在本地还包括tokenizer、配置文件、采样参数这些全部不依赖外部API调用。我们对比了几个候选模型。最终选的是Qwen系列的一个可商用版本参数规模大概在7B到14B之间。选它的理由有三个中文理解能力过关工具调用指令遵循性好而且它在消费级显卡上就能跑起来不需要A100这类高端卡。如果是纯英文场景Llama系列也可以但中文环境下Qwen的指令遵循明显更稳。推理引擎选了vLLM。它支持离线批量推理也支持OpenAI兼容的HTTP接口。这里有一个关键决策虽然Agent的内核是Rust写的但模型推理服务这一层我用的是PythonvLLM两者通过HTTP通信。你不可能让Rust直接调GPU算力生态上不现实。Rust负责逻辑编排Python负责模型推理各干各擅长的部分。vLLM的配置文件里有几个参数值得单独拿出来说。max-model-len控制上下文窗口长度我们按照Agent场景设置为8192因为一个完整的ReAct循环会累积多轮工具调用记录太短的上下文会导致模型忘记一开始的目标。gpu-memory-utilization控制显存占用比例我们设置为0.85留给KV cache足够的空间。served-model-name一定要起一个固定的名字因为后续所有Agent调用都用这个名字作为请求的model字段。另外一个容易忽略的点是模型的量化格式。我们最终用了AWQ量化格式在显存占用和推理速度之间取了平衡。同样的14B模型FP16大约需要28GB显存整机就废了AWQ量化后只要14GB左右双卡3090可以同时跑两个实例一个用于生成任务一个用于分类和校验。量化确实会损失一点精度但在Agent场景里工具调用的参数抽取比文本润色更依赖指令遵循而不是生成质量实测下来AWQ完全够用。2. 离线依赖准备与基础环境落地2.1 依赖清单与版本锁定内网部署的第一步是在外网环境把依赖全部准备好。这个环节不能靠感觉要维护一份精确到小版本号的依赖清单。Rust侧需要锁定Cargo.toml里每个依赖的版本Python侧要生成requirements.txt并锁定传递依赖的版本。我先列Rust侧的依赖清单这是我们Agent内核的核心tokio异步运行时版本锁定1.38以上处理所有并发任务的执行。serde和serde_jsonJSON序列化Agent和模型服务之间的消息格式全靠它。reqwestHTTP客户端调用vLLM的API接口。uuid生成任务ID和会话ID。tracing和tracing-subscriber结构化日志内网环境下排查问题全靠日志。anyhow和thiserror错误处理Rust工程里最常用的两个错误库。Python侧依赖相对简单vllm、fastapi、uvicorn、pydantic以及transformersvLLM底层依赖它做tokenizer处理。关键在于版本必须互相兼容比如vLLM的某个版本要求CUDA版本不低于12.0而CUDA 11.8环境装新版本vLLM就会直接报错。这个坑我们踩过后面细说。依赖准备完成后在隔离内网里建议搭一个简单的私有源。Rust用cargo vendor或配置source.crates-io指向本地镜像目录Python用pip download把包全部拉到本地再内网安装。更稳妥的做法是把所有依赖的.crate文件和.whl文件都保存一份到共享存储上这样即使某台机器环境坏了也能快速重装而不用重新携带。2.2 Rust工程的离线编译与配置Rust离线编译是整个链路里最容易出问题的一环因为没有编译缓存一说任何依赖漏了都会卡死在构建阶段。我推荐的做法是用cargo vendor命令把所有的crate源码拷贝到一个vendor目录然后在.cargo/config.toml里配置[source.crates-io] replace-with vendored-sources [source.vendored-sources] directory vendor这样cargo构建时就不会去网上拉取任何东西。这里有一个实操注意点vendor目录必须和工程一起完整拷贝而且要保持相对路径不变。cargo会校验crate的checksum如果在传输过程中有任何文件损坏构建时就会报哈希不一致的错误。另外建议在构建机器上提前执行一次完整的cargo build --release把编译产物缓存住。Rust的增量编译缓存路径在target目录里如果目标机器的CPU架构和构建机相同可以直接把整个target目录也拷贝过去能省掉大量重新编译的时间。我们在实际部署时直接把构建机上的target目录打tar包搬到内网后解压再build整个构建时间从40分钟缩短到了不到10分钟。离线编译还有一个隐藏问题编译器和目标机器上的glibc版本兼容性。如果你的构建机是Ubuntu 22.04目标机器是CentOS 7静态编译时需要注意glibc的版本差异。最简单的解法是在构建机上添加nightly工具链并用-C target-featurecrt-static做全静态链接但这样生成的可执行文件会很大。另一个方案是尽量选择与目标机器相同发行版和glibc版本的构建机这比任何编译参数都可靠。2.3 模型文件与推理服务的初始化部署模型文件的传输没有捷径只能通过移动硬盘或者内部共享存储拷进隔离内网。这里有几个细节值得强调。第一模型目录结构不要随意改动。Hugging Face格式的模型目录里有config.json、tokenizer.json、tokenizer_config.json、generation_config.json以及权重文件这几个文件必须保持相对位置不变。vLLM启动时按safetensors索引文件加载权重如果你改变了目录结构或者重命名了某些文件加载过程就会失败。第二模型拷入后先做一次完整性校验。把外网下载时的SHA256校验值带到内网逐个文件核对。模型文件动辄十几GB传输过程中出现单bit翻转的概率并不为零而且这种错误通常要等到推理时才会以非常诡异的方式暴露出来——比如生成的文本里出现乱码或者单个字符重复。这种问题定位极其浪费时间提前校验是最便宜的保障。第三vLLM服务启动后做一次基准测试再接入Agent。用curl发几个最基础的请求确认响应速度和输出质量正常。我一般会准备一组测试用例脚本包含简单的问答、函数调用格式的生成、长文本生成每个用例都有预期的响应结构。这一步花不了5分钟但能在接入Agent之前发现90%的配置错误。推理服务本身建议写成一个systemd service开机自启、崩溃自动拉起。隔离内网的机器往往没有人值守进程挂了如果没被发现Agent集群就全部不可用了。vLLM服务的内存占用大启动过程也会加载几分钟才能接受请求所以健康检查的探针要设计得合理一些比如预热阶段的探针打到/health接口但允许一定时间内的失败而不是一启动就严格判定服务不可用。3. Agent内核的Rust实现细节3.1 状态机与消息协议设计Agent的本质是一个状态机而不是一个简单的“调API”的脚本。我把整个Agent的生命周期划分为五个状态Idle空闲等待、Planning意图解析与任务规划、Executing工具调用执行、Observing观察工具结果、Responding生成最终回复。每个状态之间通过事件驱动迁移事件类型包括用户消息、工具响应、超时信号、错误通知。Rust里用枚举表示状态用tokio::select!等待事件这套写法非常自然enum AgentState { Idle, Planning { session_id: String, task: TaskSpec }, Executing { session_id: String, tool_calls: VecToolCall }, Observing { session_id: String, results: VecToolResult }, Responding { session_id: String, draft: String }, } struct Agent { state: AgentState, llm_client: LlmClient, tool_registry: ArcToolRegistry, }消息协议是整个系统的骨架。Agent和用户交互、Agent之间协作、Agent和模型服务通信走的是同一个JSON协议。协议里最核心的字段是type消息类型和payload业务数据消息类型包括user_message、agent_plan、tool_call、tool_result、agent_response、error这六种。设计协议时有一个重要原则所有消息必须带有全局唯一的message_id和session_id。message_id用于追踪一条消息在整个链路中的流转session_id用于标识一次完整的任务会话。隔离内网没有现成的链路追踪系统靠日志里打印这两个ID就能重建一次任务的完整生命周期。没有这两个字段出了问题就只能靠猜。3.2 工具注册与动态加载Agent的价值体现在工具调用上。我们的工具注册表是一个trait对象集合每个工具实现统一的Tooltrait#[async_trait] trait Tool: Send Sync { fn name(self) - str; fn description(self) - str; fn parameters_schema(self) - serde_json::Value; async fn execute(self, params: serde_json::Value) - Resultserde_json::Value, ToolError; }模型决定调用什么工具时会输出一个JSON对象包含name和arguments字段。Agent内核拿到这个JSON后查注册表找到对应的tool实例执行。注册表本身用HashMapString, Arcdyn Tool实现锁是RwLock因为工具列表在运行时会动态增减。工具调用的核心坑在于参数解析。模型生成的arguments是一个JSON字符串但经常会有多余的空格、换行或者字段顺序不对。直接用serde_json::from_str解析小的参数没问题遇到复杂嵌套结构就容易失败。我建议在解析前先做一次清理把外层多余的花括号补全、修正非法的Unicode字符。更保险的做法是让每个工具的parameters_schema定义得尽量简单禁止深层嵌套否则模型生成正确参数的概率急剧下降。另一个容易被忽视的问题是工具超时。工具可能因为外部服务无响应而一直阻塞Agent的调度循环会直接卡死。我给每个工具执行都加了tokio::time::timeout封装默认超时30秒超时后返回一个固定格式的错误信息给模型“Tool execution timed out”。模型的提示词里会写明遇到这个错误时要如何处理——通常是换个参数重试一次或者放弃这个工具改用其他方案。3.3 提示词工程与上下文窗口管理隔离内网下的Agent不能像云端那样每次请求都重新构建完整的提示词因为本地推理的上下文窗口有限而且重新构建一个很长的提示词会拉长推理时间。我们设计了三级上下文结构。第一级是System Prompt包含Agent的角色定义、工具清单、输出格式要求。这一级固定不变在会话开始时就拼接好不会随对话轮次增长。第二级是会话记忆按对话轮次追加但我们做了滑动窗口——只保留最近6轮的用户消息和Agent回复更早的内容做摘要后存在会话存储里。第三级是当前任务的临时上下文包含本次任务的目标、已经执行的工具调用记录、最新一次的工具结果。这个设计的核心在于“摘要”逻辑。当会话超过6轮时用一个轻量模型或者同一个vLLM服务但用更短的max_tokens参数把旧的对话压缩成一段摘要文本替换掉原始对话记录。摘要本身又会引入一层信息丢失问题所以摘要的提示词要写得非常明确只需要保留用户意图、已经完成的任务、未完成的任务和任何用户给过的明确约束不要保留与任务无关的闲聊内容。上下文窗口还有一个容易出现的问题Token计数不一致。模型以token为粒度处理文本如果你用len(text)而不是tokenizer的计数方法来计算长度写程序时好像没问题但请求vLLM时可能直接因为超出max-model-len被拒。正确做法是用部署模型对应的tokenizer做准确的token数计算。Rust侧可以直接调用tokenizer的独立HTTP接口或者把上下文构建的职责全部交给Python胶水层Rust只传原始消息Python负责拼接后再发给vLLM。我实际项目里选的是后者省了在Rust里维护tokenizer的麻烦。3.4 并发调度与任务追踪多用户同时使用Agent时并发调度就进入了核心战场。我们用了tokio::spawn搭配mpsc::channel来实现一个简版的调度器。每个会话对应一个独立的Agent实例实例从自己的channel里接收事件处理完成后把结果发回应答channel。调度器维护一个sessions: HashMapString, SenderAgentEvent新消息进来时按session_id路由到对应实例的channel。这个设计的好处是隔离性一个会话卡住不会影响其他会话。坏处是如果有大量会话同时活跃每个会话都持有完整的上下文内存消耗不容小觑。解决办法是给长时间不活跃的会话做空闲回收——比如30分钟没有新消息的会话把它的状态存储到磁盘释放内存等新消息到达时重新加载。任务追踪是调度器里最需要细心的地方。每个任务有一个生命周期记录包含创建时间、每个阶段的开始结束时间、调用了哪些工具、每个工具耗时、最后的回复内容。这些记录统一写入本地SQLite隔离内网没有可用的APM平台SQLite加一个简单的Web查询界面就能满足日常监控需求。日志里务必带上task_id和session_id这样从日志文件里就能还原整条执行链路不用到处看分布式链路追踪系统。4. 内网通信与Agent服务编排4.1 局域网服务发现机制隔离内网没有K8s没有Consul甚至有的机器之间连主机名解析都不完整。所以服务发现必须自己写。我用了最简单可靠的方案共享目录加JSON注册文件。每台Agent节点启动时往共享存储NFS挂载的目录下写入一个agent_registry.json文件文件内容包括节点主机名、IP、服务端口、处理能力、当前负载、最近心跳时间。其他节点定期读取这个文件就能知道集群里有哪些可用节点。节点下线时写一个offline标记或者直接让注册文件过期失效。这个方案的问题在于NFS挂载偶尔会延迟而共享目录的写权限也可能冲突。我在写入时引入一个简单的激进锁机制每个节点在自己的注册记录里加了一个自增的epoch字段写入前先读取现有记录如果自己的epoch不是最新的就重新生成记录再写回去。虽然不完美但实测下来足够稳定几百行代码就搞定了服务发现模块。补充一个备选方案UDP广播。每个Agent节点启动时广播自己的存在其他节点收到广播后更新本地节点表。UDP广播在隔离内网里通常没问题因为网段内允许广播包。但有些网络环境禁用了UDP协议或者防火墙限制了广播那就只能用共享目录方案。两个方案可以同时实现启动时根据配置切换。4.2 Agent之间的消息路由与协作单个Agent解决不了复杂任务时就需要多Agent协作。在我们的架构里任务分发是“主Agent子Agent”的星型模式主Agent负责拆解任务把子任务通过内部消息协议派发给各个子Agent收集结果后做汇总。消息路由用的是纯HTTP调用。主Agent维护一个子Agent的能力列表根据子任务类型选择最合适的执行节点。这里的关键设计是请求超时与重试机制。内网虽然网络质量好但Agent节点处理任务时可能因为推理时间过长而超过预期所以发给子Agent的HTTP请求必须设置合理的超时时间比如300秒并允许重试一次。重试前要确认上一个请求没有被执行——否则子任务被重复执行两次产生脏数据。最简单的幂等方案是每个子任务带上全局唯一的subtask_id子Agent执行前先检查这个ID是否已经处理过。多Agent协作时的上下文隔离也很重要。每个子Agent只接收主Agent分配给它的任务描述和必要上下文不接收整个对话历史。这样既节省了子Agent的上下文窗口也避免了一个子Agent的错误推理影响其他子Agent。主Agent最后汇总各路结果时要在System Prompt里注明当前是“收集汇总阶段”它不应该继续调用工具而是把所有子结果组织成最终回复。4.3 核心配置管理与安全管理隔离内网的配置管理有一个特点不能用外部配置中心而配置文件又必须在多台机器间保持一致。我用的是“base配置节点覆盖”的两层配置结构。base配置是集群统一的配置JSON包含模型服务地址、默认超时、日志级别这些公共项节点覆盖配置是每台机器本地的node_override.json覆盖本机特有的参数比如本机绑定的端口、本机可用显存大小。配置合并的逻辑用Rust实现很顺手serde_json的merge操作几十行就能完成。但要注意合并顺序和深拷贝问题覆盖项必须深合并而不是替换整个对象否则公共配置里新增字段就会被覆盖掉。安全方面的配置需要额外重视。虽然隔离内网相对封闭但Agent服务之间是互相调用的如果所有Agent节点都能访问彼此的API那意味着任何一个节点被攻破都会影响整个集群。我在内部调用里加了一个简单的token机制集群初始化时生成一个共享密钥节点间的所有HTTP请求都要带X-Auth-Token头。这个token不依赖外部服务密钥文件直接从配置中心共享目录分发定期轮换。不要以为内网就安全最小权限原则在任何环境都适用。5. 常见问题与排查技巧实录5.1 CUDA与vLLM版本兼容性这个坑是我们在搭建阶段踩得最惨的。外网环境用pip安装了最新版vLLM跑到内网后一启动就报CUDA错误——错误信息指向CUDA_HOME未正确识别或者GPU驱动版本不匹配。排查了半天发现是vLLM版本更新的速度远快于CUDA Toolkit的普及速度新版本vLLM可能要求CUDA 12.x而内网机器装的是11.8。解法是锁定版本。我们在外网环境就用pip download vllm0.6.0这一类明确版本号的方式拉取依赖不要用最新版本。同时内网机器的CUDA driver版本和CUDA Toolkit版本要确认高于vLLM的官方要求。nvidia-smi能看到driver版本nvcc -V能看到Toolkit版本两个版本必须都满足要求。挖过这个坑之后我把版本兼容性验证写进了部署文档的开头每次部署前先跑一个版本检查脚本。5.2 Tokenizer加载失败与模型路径问题另一个高频问题出现在模型加载阶段vLLM提示找不到tokenizer。同样是Hugging Face格式的模型目录我们拷贝进内网时压缩解压导致某个文件大小变成0字节tokenizer_config.json损坏后vLLM就会拒绝启动。解决思路就是前文说的完整性校验。在外网下载模型后立即生成每个文件的SHA256校验值拷入内网后逐文件核对一遍。这个操作看起来费时间实际上一个14B模型也就几分钟就能校验完比启动时发现失败再排查快得多。还有一个相关问题是模型路径中的中文或特殊字符。vLLM对路径中的非ASCII字符支持不太好有时候明明路径正确就是加载失败。所以模型文件存放路径务必全英文、无空格、无特殊符号比如/data/models/qwen2-14b-awq宁可路径长一点也一定要干净。5.3 上下文溢出与超时控制的实战解法上线之后遇到最多的运行时错误就是上下文溢出。Agent运行了几轮之后上下文长度逼近8192的窗口上限vLLM返回400错误Agent直接崩溃。第一版代码里上下文截断的逻辑写得简单粗暴——直接丢弃最早的消息——结果模型开始频繁地“忘记”用户最初的需求。后来改成了“摘要滑动窗口”的混合策略。Session中超过6轮的早期对话交给模型生成摘要摘要文本单独存储。如果摘要加当前任务上下文的总长度仍然超限就把摘要再压一轮直到放得下。这个策略本身也有失败的时候摘要过程也可能因为输入太长而失败。所以我在生成摘要前先做硬截断保留任务目标字段和最近两轮消息其余内容不管多少都直接丢弃——Agent的第一目标是完成当前任务旧对话的丢失虽然遗憾但比任务失败强。超时控制方面除了工具执行超时我还给整个Agent任务加了总超时。一个任务从进入到返回结果最长允许10分钟超时后强制终止所有子任务返回部分结果和超时提示。用户看到“任务部分完成”通常能接受比一直转圈强得多。5.4 日志与可观测性的内网落地对外网项目来说可观测性有现成的全家桶方案但内网里能用的工具非常有限。我们的日志方案是本地文件加定时聚合。每台节点写结构化JSON日志到本地目录日志文件按天滚动。运维人员用一条grep | jq命令就能按task_id或session_id过滤出完整链路。日志字段我推荐固定为这套timestamp、level、node、session_id、task_id、event、duration_ms、detail。其中event字段是日志的主事件名比如llm_request_start、llm_request_success、tool_call_start、tool_call_timeout方便做统计。后期如果想做监控看板这些结构化日志直接导入Grafana也能很快出图。日志量级要控制好。vLLM的访问日志默认打印每个请求配合Agent日志会产生大量冗余。建议把vLLM的日志级别设为WARNINGAgent侧只记录关键事件。隔离内网的存储空间通常也不宽裕滚动保留7天的日志就够了重要任务的样例和分析结论单独存档。最后分享一个小技巧项目收尾阶段还能再做一两件提升工程体验的事。比如把Agent的核心二进制封装成Docker镜像时注意用alpine基础镜像跑Rust静态编译的二进制镜像体积能压到50MB以内拷进内网非常方便。再比如内网机器的GPU显存如果不能把模型整数放入单卡可以考虑用vLLM的--tensor-parallel-size参数做多卡张量并行但一定要先确认机器之间的显存互相可见——我们踩过单机双卡但PCIe带宽受限的坑张量并行的效率反而比单卡低。隔离内网做AI Agent本质上是把各种“标准答案”全部推翻重想一遍。外网五分钟搞定的事内网可能要花五小时。但正是这些限制逼着你把架构里每一层都看清、想透做完一个项目之后你对Agent全链路技术的理解深度会远超那些只调云端API的开发者。这个项目如果后续还有扩展空间我认为最值得投入的方向是让Agent具备基于本地知识库的检索增强能力毕竟内网业务数据才是最不可能出网的部分把RAG做好Agent才真正变成“自己人”。
