隔离内网环境下的AI Agent落地本质上是一场戴着镣铐跳舞的工程实践。模型不能直接调用云端API依赖装不了日志没法上传连很多开源组件都要靠人工传包进内网。但一旦跑通收益非常直接数据不出域、响应可控、业务闭环完全自主。这篇文章记录的是我在多个物理隔离网络项目中积累的完整路径从硬件算力选型、模型私有化部署、RAG知识库构建到Agent工具调用链路和排查技巧全部都是可以直接抄作业的实战经验。1. 隔离内网下AI Agent的整体设计与方案选型1.1 隔离内网场景下的核心约束做隔离内网AI Agent最先要认清的是隔离这两个字决定了你所有技术选型的边界。没有公网访问能力意味着你没法用云厂商的模型API没法在线pip install没法在HuggingFace上直接拉权重甚至连Docker镜像都要走离线包导入的流程。具体来说你会遇到这几类约束网络层面服务器之间通常是千兆或万兆局域网但对外网络是断开的尤其涉密或生产内网还会封禁USB接口和光驱写入。依赖层面Python包、系统库、模型权重、容器镜像全部需要提前在外网准备妥当再通过合规方式拷入内网。别指望现场临时下载。算力层面内网一般没有GPU集群通常是一两台单卡或双卡机器需要精打细算。权限层面Agent要调用内部系统比如OA、工单系统、数据库时往往没有现成的开放API很多是老旧系统需要靠RPA或定制接口去对接。所以架构设计的第一原则是做减法。不要在外网环境下追求大而全的架构内网环境下先保证能跑起来、能自查、能扩容功能上优先解决最高频的业务问题。1.2 方案选型与架构设计逻辑我接触过的几个隔离内网项目最终落地的架构大同小异整理成一张通用路线图就是应用层FastAPI 前端对话界面负责用户交互、会话管理。Agent调度层负责意图理解、任务规划、工具选择、上下文组装。可以用LangChain/LangGraph也可以基于LlamaIndex或自研编排框架。工具/插件层通过统一接口对接知识库检索、数据库查询、内部系统API、RPA机器人等。模型推理层私有化部署的LLM用vLLM或Ollama作为推理框架。知识库层向量数据库如Milvus、Qdrant、Chroma Embedding模型为RAG提供检索能力。安全与审计层权限控制、输入输出过滤、操作日志留痕。我为什么建议采用调度层与推理层解耦的设计因为模型会换、工具会加、业务需求会变如果你把Agent编排逻辑直接写死在模型调用里后面每换一次模型就是一次重构。解耦之后模型层只对外提供OpenAI兼容的/v1/chat/completions接口调度层只要改模型名称和base_url就能切换省掉大量重复开发。注意隔离内网环境里模型不是你最需要担心的变量工具接口才是。我在项目里遇到过最容易拖垮进度的反而是对接内部老旧系统时的协议不兼容和权限审批流程。2. 模型部署与算力评估实战2.1 离线模型选型原则隔离内网环境下选模型我用的是三条硬性标准权重能合规离线获取且推理框架有成熟的离线部署方案。显存占用在可用硬件范围内同时吞吐量能支撑目标并发。中文能力、指令遵循能力、工具调用能力满足业务要求。以我最近一个项目为例硬件是单张A100 40G部分场景是双卡4090主要业务是内部文档问答工单辅助处理。我选了7B~14B参数量级的开源模型量化后既能塞进单卡又能保证不错的回答质量。具体选型建议这样权衡模型规模显存需求FP16量化后显存适用场景1.5B~3B4G~8G2G~4G日志摘要、意图分类、轻量对话7B~9B16G~20G8G~12G文档问答、代码辅助、通用助理14B~32B28G~64G14G~32G复杂推理、长文本理解、深层次分析70B140G40G~80G重推理任务通常需要多卡并行一个很容易踩的坑是只看总参数量不看上下文长度。比如同样是7B模型上下文从8K扩到32K后KV Cache占用的显存会成倍增加实际并发会掉得很难看。我之前在一台双卡4090上跑了32K上下文的Agent任务并发只能开到4而同样的硬件跑8K上下文能开到12左右。2.2 推理服务部署细节目前私有化部署LLM推理主流还是vLLM、Ollama、SGLang这三个方向。我的经验是追求吞吐和并发、要做高并发API服务用vLLM追求快速验证、内网单机小规模使用用Ollama需要细粒度控制调度策略时再考虑SGLang。vLLM在离线环境部署时关键是把容器镜像和模型权重提前准备好。我一般在能联网的跳板机上先把镜像docker save成tar包内网再docker load导入。命令大概是这样的# 外网环境 docker pull vllm/vllm-openai:latest docker save vllm/vllm-openai:latest -o vllm-openai.tar # 内网环境 docker load -i vllm-openai.tar启动服务时有几个参数值得专门调python -m vllm.entrypoints.openai.api_server \ --model /data/models/your-model \ --served-model-name local-agent-llm \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --max-model-len 32768 \ --enforce-eager \ --host 0.0.0.0 --port 8000其中--enforce-eager是为了规避某些GPU驱动/算力架构下CUDA Graph报错内网环境经常因为驱动版本老旧出现这类问题加上这个参数能以轻微性能损失换稳定运行性价比非常高。--gpu-memory-utilization我一般留10%的余量防止显存碎片或临时KV分配导致OOM。2.3 算力评估与硬件配置建议很多人问7B模型是不是随便一张卡就能跑理论上没错但要支撑实际Agent并发就没那么简单了。Agent任务的特点是多轮工具调用、长上下文累积、高请求频次。这意味着你的算力评估不能只看单次推理延迟还得看持续负载下的吞吐。我通常用一个粗略公式估算并发能力单卡最大并发 ≈ 显存可用KV容量 / 单请求平均KV占用而单请求平均KV占用 ≈ 上下文长度 × 层数 × 头维度 × 2字节 × 2K和V。7B模型32层、32头、head_dim128的情况下一条8K上下文的请求大概占用8K × 32 × 32 × 128 × 2 × 2 ≈ 512MB如果显存里能分20G给KV Cache这个模型大概能同时支撑40个8K请求。这个估算方法能帮你在项目初期快速判断该买几张卡和该限制多少并发避免资源浪费。注意如果内网环境完全没有GPU可以考虑CPU推理走llama.cpp或者带量化版的Ollama。7B模型量化到Q4后在主流服务器CPU上大概每秒出5~12个token做知识库问答足够但复杂Agent多轮调用会比较吃力token生成速度太慢会让用户体验很差。3. RAG知识库建设与数据治理3.1 数据采集与清洗管线的设计隔离内网环境下的RAG最难的不是向量化而是数据源头非常脏。我遇到的情况通常是几十万份办公文档分散在NAS、各系统的导出Excel、老旧OA附件里格式五花八门PDF有扫描件也有文字版Word有.doc也有.docx还夹杂大量图片型表格。我的建议是效仿数据仓库的分层思路把数据管道分成四层采集层定时扫描共享目录、数据库、附件导出目录增量抓取新增文件。解析层按文件类型走不同解析器PDF用PyMuPDF、OCR引擎等Word用python-docx表格转CSV再入向量库。清洗层去页眉页脚、去重复文档、统一编码很多老文档是GBK、删除敏感水印和无关广告页。索引层切片、向量化、写入向量库并记录元数据。再补充一个细节切片策略不要只用固定长度切。我实践下来按文档结构标题、段落、表格优先切固定长度兜底效果远好于纯固定长度。因为固定长度会把完整的业务描述拦腰截断导致检索片段语义不完整。一般我设置段落阈值在300~800字之间超出部分再递归切分重叠窗口设50~100字。3.2 向量化与存储的工程细节Embedding模型要根据文档语言特点选择。中文场景我目前用得比较稳的方案是BGE系列尤其bge-large-zh-v1.5和M3E系列它们的语义匹配效果在中文本地上明显好过通用英文模型。内网部署时需要一并准备模型权重和tokenizer文件这个流程和LLM一致。向量数据库选型隔离内网场景我建议优先考虑Milvus或Qdrant两者都支持离线部署都有较好的过滤查询能力。如果数据量在百万级以下Chroma也够用部署更轻。写入MFW与检索链路我习惯的做法是from sentence_transformers import SentenceTransformer model SentenceTransformer(/data/models/bge-large-zh-v1.5) # 批量向量化控制batch_size防止显存波动 embeddings model.encode(chunks, batch_size16, normalize_embeddingsTrue) # 写入Qdrantpayload带文档ID、来源、标题、页码 client.upsert(collection_nameenterprise_kb, points[ PointStruct(ididx, vectoremb, payloadpayload) for idx, (emb, payload) in enumerate(zip(embeddings, payloads)) ])用normalize_embeddingsTrue的意义在于后面做相似度检索时可以走点积运算性能比余弦相似度更优而结果几乎一致。这个细节虽然不起眼但在数据量大了之后能明显减少检索耗时。3.3 检索质量调优方法论RAG调优是持续过程我一般按召回→排序→重写三步走召回先做向量召回Top 50再做关键词/BM25召回Top 50两路结果混合去重。如果只用纯向量检索遇到专有名词如设备型号、系统编码时效果会差很多因为Embedding本质不擅长精确词匹配。排序用Reranker模型对召回结果精排Top K取5~10。Reranker是RAG效果提升最明显的一步很多问题召回没问题但答案不对就是Top K里有用内容被埋没了。重写用户Query本身质量不高时用LLM做一次查询改写比如把口语化表述变成检索友好的关键词组合但这一步要注意别引入额外幻觉在Agent里可以做成可选开关。注意RAG的回答效果很多时候不是模型不行而是检索回来的片段根本不包含正确答案。我建议把检索内容是否包含证据做成可视化调试面板每次效果不对先看检索Top 5而不是急着换大模型。4. Agent核心链路与工具调用实现4.1 工具注册与权限边界Agent的本质是把LLM的对话能力升级为行动能力而行动落地的载体就是工具。隔离内网下工具主要分为三类内部API型比如查库存、提单、获取审批状态。数据查询型查数据库、查数据仓库、跑固定报表。操作型调用RPA机器人操作老旧系统、自动生成并分发文件。工具管理上我推荐用声明式注册 Schema校验的方式。每定义一个工具明确它的名称、描述、参数结构、权限范围、调用后果。LLM输出结构化的工具调用请求代码层做参数校验后再执行避免模型乱传参数。一个实际工具定义片段用FastAPI风格实现class QueryStockTool(BaseTool): name: str query_stock description: str 根据物料编码查询实时库存数量返回可用库存与在途数量 args_schema: Type[BaseModel] QueryStockArgs def _run(self, material_code: str) - str: # 调用内网库存服务 result call_internal_api(stock/query, {material_code: material_code}) return json.dumps(result, ensure_asciiFalse)这里的关键不是代码本身而是每个工具都要有明确的准许调用范围。我在项目中专门加了一层工具白名单由管理员在后台配置哪些角色能调用哪些工具避免Agent被诱导去执行越权操作。这是隔离内网环境尤其重要的安全底线。4.2 工作流编排与状态控制Agent任务不是一次Chat完事往往要经历理解需求→拆解步骤→选工具→调工具→看结果→再决策的多轮循环。这块我用LangGraph的场景比较多因为它的图状态机制天然适合Agent循环控制。一个简单的Agent状态流包含几个节点route意图分类、retrieve查知识库、call_tool调工具、respond生成回复。状态转移时需要重点控制两个参数最大迭代次数避免Agent陷入调工具→看到结果→继续调工具的死循环我一般设5~8次。中断策略对于有副作用的工具比如发送审批邮件、修改数据必须在执行前暂停并请求用户确认不能全自动放行。注意内网业务系统很多时候API不稳定返回超时、字段缺失是常态。每个工具调用必须做异常捕获和返回结果的结构化校验全链路加trace_id便于排查。别默认模型能处理各种异常返回——它往往会在工具报错时一本正经地编一个成功结果给你看。4.3 上下文管理与Token控制ai agent token是什么意思这类热词背后其实是很多人在问Agent的Token消耗为什么这么夸张。因为在Agent链路里每一轮工具调用结果都会拼进上下文次数一多上下文长度飙升Token费用或显存压力都跟着涨。隔离内网下Token控制的核心思路可以分成三层短期对话窗口保留最近N轮对话工具结果摘要超过阈值就做截断或滚动摘要。长期记忆外部化把用户画像、历史偏好、项目背景等信息写入独立记忆库或向量库只在需要时检索加载而不是全量拼进Prompt。这种记忆外置的策略让我在实际项目里把单会话上下文减少了40%~60%。工具结果压缩工具返回的原始内容往往很大比如SQL返回1000行结果但模型真正需要的是摘要或关键字段。我在工具执行层做一次结果裁剪只返回Top N条或关键统计值Prompt直接从8000 token降到1500 token。一个比较典型的Prompt结构会这样组织[系统指令] 你是内网业务助理只允许调用白名单工具禁止执行未授权操作。 [当前任务] 用户要求查询库存并生成补货建议 [可用工具] query_stock / check_supplier / generate_report [历史摘要] 用户已确认仓库编码WH-03 [工具结果] 物料A可用库存326件在途500件安全库存800件 [模型输出] 生成分析结论与建议这种结构化Prompt的好处是清晰分割不同信息来源模型不容易混淆用户说的和系统查到的。5. 隔离内网环境下的工程化与安全加固5.1 离线依赖与镜像管理内网环境最折磨人的问题之一就是装依赖。我的习惯是在能联网的同架构容器里做全量依赖导出再整体导入内网。具体可以这样做# 外网环境准备requirements.txt并打包安装缓存 pip download -r requirements.txt -d ./packages/ # 将packages目录拷入内网 pip install --no-index --find-links./packages/ -r requirements.txt如果用到Conda环境就用conda-pack整体打包效果更省心。Docker镜像同理尽量做全家桶镜像把CUDA驱动层、推理框架、依赖库一次性打好避免内网逐层构建因为某层拉取失败而卡住。另外强烈建议在项目启动第一天就建立内网软件物料清单SBOM。记录每个Python包的名称、版本、来源哈希每个镜像的tag。否则一旦某个依赖有安全漏洞或需要版本回溯你在内网里连查来源都费劲。5.2 日志、审计与告警体系隔离内网里的AI Agent不能是黑盒。我坚持从第一天就建立三本日志账模型调用日志请求内容、响应内容、Token消耗、延迟用于复核模型是否合规回答。工具调用日志谁在什么时间调了哪个工具、传入什么参数、返回什么结果、耗时时长。操作审计日志哪些用户登录了Agent系统、创建了什么任务、是否有越权尝试。日志采集整体走JSON结构化输出汇总到内部日志平台。告警规则按工具调用失败率超过10%模型平均延迟超过3秒Token消耗异常激增这几个指标设置。我在实际项目中遇到过Agent在凌晨自动任务中反复重试失败工具导致日志量和调用量爆炸的情况就是靠告警发现的。隔离内网不代表可以放松可观测性反而因为现场排查不方便更需要系统化日志支撑。5.3 安全防护与访问控制AI Agent的权限安全远比普通Web应用复杂因为Agent会替你做事。我的安全基线是身份认证对接内网统一身份认证OIDC/LDAP每个用户有独立身份不能用共享账号。细粒度授权工具级权限数据级权限双重控制。用户能问库存不等于能查供应商合同报价。输入输出过滤Prompt注入过滤、敏感信息脱敏。用户可能在对话中诱导模型输出内网敏感配置也可能在知识库文档中隐藏恶意指令必须有过滤器兜底。操作二次确认所有有副作用的工具写操作、发消息、修改数据默认开启人工确认。注意Prompt注入不是外网才有的风险。内网Agent如果接了企业数据库和自动化工具被诱导执行删数据发全员邮件这类恶意指令的后果更严重。务必把工具调用权限的默认策略设为最小可用而不是最大可用。5.4 关于Rust在Agent链路中的实践不少人问基于Rust语言AI Agent是否可行。我的看法是整条Agent链路全用Rust来写目前生态还不算成熟但在工具调用执行器、API网关、高并发缓冲层这些对性能和稳定性要求高的环节用Rust是非常不错的选择。我在某个业务里把工具执行器用Rust重写了一遍效果很直接原来Python实现的工具调度在并发高峰期CPU占用飙到80%换成Rust后降到20%左右单机吞吐提升了一倍多。而且Rust编译出来的静态二进制在内网部署很友好二进制一拷就能跑不需要带Python环境和依赖包。适合用Rust实现的Agent组件一般有这四类工具执行网关处理请求分发、超时控制、流量限制日志采集Agent边车模式统一抓取模型日志消息队列消费者处理异步任务如批量生成报告轻量级推理代理把模型API包一层加缓存和熔断如果你团队的强项是Python没必要为了赶潮流硬换语言但如果你需要在有限硬件上支撑高并发Agent服务用Rust做核心链路组件是一笔很划算的技术投资。6. 常见问题与排查技巧实录6.1 模型推理速度慢到无法接受这是隔离内网环境最普遍的反馈。排查顺序我建议是先看并发数是否过高导致GPU排队。压测一下单请求的time to first token如果这个值都很大就不是排队问题。再看上下文长度。很多Agent任务因为上下文膨胀实际计算量远超过你的预期。我用vllm的/metrics端点看每个请求的prompt tokens数经常能发现用户只是问一句帮我查一下刚才说的那个材料实际上上下文已经堆了1万多个token。最后看量化与精度。FP16改FP8或INT8AWQ/GPTQ量化能显著提升推理速度代价是极小幅度的质量损失。内网业务如果不是对文字质量要求极高我很推荐量化部署。6.2 RAG检索结果相关性差现象是用户明确的问题Agent答非所问引用的文档段落跟问题根本不搭边。我遇到这类问题的排查路径通常是打印检索Top 10结果看召回的是否有正确答案。如果Top 10里没有问题出在向量化或切片。检查Embedding模型的领域适配度。通用模型对专业领域术语比如参数比扭矩系数BOM树语义理解较弱这时需要收集领域语料做Embedding微调或者换用领域预训练模型。检查Query预处理。用户口语化提问和文档书面表述之间差异很大要在进入检索前做关键词扩展和查询改写。最后才是调Reranker和Top K策略。6.3 Agent陷入无限循环不结束最常见的原因是工具返回结果被模型理解成了还需要继续调下一个工具而下一个工具又返回类似结果形成循环。我处理循环有三个手段在Prompt里明确定义当已获得可直接回答的信息时立即结束工具调用。设置最大迭代次数硬上限比如6次超过后强制进入respond节点。工具结果里增加是否已解决标记字段由工具侧判断是否需要继续调用其他工具。6.4 离线导入模型权重时文件不完整模型权重动辄几十GB拷贝到内网过程中经常出现文件损坏、sha256不一致的情况而加载时模型要么直接报错要么静默出现推理乱码。解决办法是拷贝完成后先做全量哈希校验再注册到模型库sha256sum -c model_weights.sha256如果是从移动硬盘拷入的建议走两次校验拷贝机校验一次、内网服务器校验一次。另外分卷压缩时不要开多线程某些压缩工具的多线程模式在数据量大时有概率产生校验错位我已经不止一次在分卷包上吃这个亏。6.5 工具调用返回结果超时内网系统API经常因为网络波动或服务过载而慢。核心对策分三层超时分级把短超时5秒用于健康检查中超时15秒用于常规查询长超时60秒用于报表生成类任务。异步化结果生成慢的工具改为提交任务→返回任务ID→Agent轮询结果模式。熔断降级连续失败N次后熔断该工具直接向用户返回该功能暂时不可用而不是让Agent反复重试浪费时间。这四类问题覆盖了我在多个项目中踩过的绝大多数坑。如果你正打算在隔离内网里搭建Agent建议先把这些预案过一遍再动手能少走很多弯路。个人经验小结隔离内网下做AI Agent技术上其实没有想象中那么高不可攀真正的难点在于工程耐心。你需要在没有外部资源可依赖的情况下把所有环节都想清楚、准备到位从模型权重到每一个Python依赖从数据清洗到工具权限边界每一步都踏实落地。我的经验是先跑通一个最小可用闭环哪怕只是文档问答一个工具调用再逐步扩展远比一开始就设计一个庞大平台要稳妥。先把基础设施和数据治理做扎实了Agent的价值自然会慢慢体现出来。
隔离内网下AI Agent落地实战：模型部署、RAG与工具调用全解析
隔离内网环境下的AI Agent落地本质上是一场戴着镣铐跳舞的工程实践。模型不能直接调用云端API依赖装不了日志没法上传连很多开源组件都要靠人工传包进内网。但一旦跑通收益非常直接数据不出域、响应可控、业务闭环完全自主。这篇文章记录的是我在多个物理隔离网络项目中积累的完整路径从硬件算力选型、模型私有化部署、RAG知识库构建到Agent工具调用链路和排查技巧全部都是可以直接抄作业的实战经验。1. 隔离内网下AI Agent的整体设计与方案选型1.1 隔离内网场景下的核心约束做隔离内网AI Agent最先要认清的是隔离这两个字决定了你所有技术选型的边界。没有公网访问能力意味着你没法用云厂商的模型API没法在线pip install没法在HuggingFace上直接拉权重甚至连Docker镜像都要走离线包导入的流程。具体来说你会遇到这几类约束网络层面服务器之间通常是千兆或万兆局域网但对外网络是断开的尤其涉密或生产内网还会封禁USB接口和光驱写入。依赖层面Python包、系统库、模型权重、容器镜像全部需要提前在外网准备妥当再通过合规方式拷入内网。别指望现场临时下载。算力层面内网一般没有GPU集群通常是一两台单卡或双卡机器需要精打细算。权限层面Agent要调用内部系统比如OA、工单系统、数据库时往往没有现成的开放API很多是老旧系统需要靠RPA或定制接口去对接。所以架构设计的第一原则是做减法。不要在外网环境下追求大而全的架构内网环境下先保证能跑起来、能自查、能扩容功能上优先解决最高频的业务问题。1.2 方案选型与架构设计逻辑我接触过的几个隔离内网项目最终落地的架构大同小异整理成一张通用路线图就是应用层FastAPI 前端对话界面负责用户交互、会话管理。Agent调度层负责意图理解、任务规划、工具选择、上下文组装。可以用LangChain/LangGraph也可以基于LlamaIndex或自研编排框架。工具/插件层通过统一接口对接知识库检索、数据库查询、内部系统API、RPA机器人等。模型推理层私有化部署的LLM用vLLM或Ollama作为推理框架。知识库层向量数据库如Milvus、Qdrant、Chroma Embedding模型为RAG提供检索能力。安全与审计层权限控制、输入输出过滤、操作日志留痕。我为什么建议采用调度层与推理层解耦的设计因为模型会换、工具会加、业务需求会变如果你把Agent编排逻辑直接写死在模型调用里后面每换一次模型就是一次重构。解耦之后模型层只对外提供OpenAI兼容的/v1/chat/completions接口调度层只要改模型名称和base_url就能切换省掉大量重复开发。注意隔离内网环境里模型不是你最需要担心的变量工具接口才是。我在项目里遇到过最容易拖垮进度的反而是对接内部老旧系统时的协议不兼容和权限审批流程。2. 模型部署与算力评估实战2.1 离线模型选型原则隔离内网环境下选模型我用的是三条硬性标准权重能合规离线获取且推理框架有成熟的离线部署方案。显存占用在可用硬件范围内同时吞吐量能支撑目标并发。中文能力、指令遵循能力、工具调用能力满足业务要求。以我最近一个项目为例硬件是单张A100 40G部分场景是双卡4090主要业务是内部文档问答工单辅助处理。我选了7B~14B参数量级的开源模型量化后既能塞进单卡又能保证不错的回答质量。具体选型建议这样权衡模型规模显存需求FP16量化后显存适用场景1.5B~3B4G~8G2G~4G日志摘要、意图分类、轻量对话7B~9B16G~20G8G~12G文档问答、代码辅助、通用助理14B~32B28G~64G14G~32G复杂推理、长文本理解、深层次分析70B140G40G~80G重推理任务通常需要多卡并行一个很容易踩的坑是只看总参数量不看上下文长度。比如同样是7B模型上下文从8K扩到32K后KV Cache占用的显存会成倍增加实际并发会掉得很难看。我之前在一台双卡4090上跑了32K上下文的Agent任务并发只能开到4而同样的硬件跑8K上下文能开到12左右。2.2 推理服务部署细节目前私有化部署LLM推理主流还是vLLM、Ollama、SGLang这三个方向。我的经验是追求吞吐和并发、要做高并发API服务用vLLM追求快速验证、内网单机小规模使用用Ollama需要细粒度控制调度策略时再考虑SGLang。vLLM在离线环境部署时关键是把容器镜像和模型权重提前准备好。我一般在能联网的跳板机上先把镜像docker save成tar包内网再docker load导入。命令大概是这样的# 外网环境 docker pull vllm/vllm-openai:latest docker save vllm/vllm-openai:latest -o vllm-openai.tar # 内网环境 docker load -i vllm-openai.tar启动服务时有几个参数值得专门调python -m vllm.entrypoints.openai.api_server \ --model /data/models/your-model \ --served-model-name local-agent-llm \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --max-model-len 32768 \ --enforce-eager \ --host 0.0.0.0 --port 8000其中--enforce-eager是为了规避某些GPU驱动/算力架构下CUDA Graph报错内网环境经常因为驱动版本老旧出现这类问题加上这个参数能以轻微性能损失换稳定运行性价比非常高。--gpu-memory-utilization我一般留10%的余量防止显存碎片或临时KV分配导致OOM。2.3 算力评估与硬件配置建议很多人问7B模型是不是随便一张卡就能跑理论上没错但要支撑实际Agent并发就没那么简单了。Agent任务的特点是多轮工具调用、长上下文累积、高请求频次。这意味着你的算力评估不能只看单次推理延迟还得看持续负载下的吞吐。我通常用一个粗略公式估算并发能力单卡最大并发 ≈ 显存可用KV容量 / 单请求平均KV占用而单请求平均KV占用 ≈ 上下文长度 × 层数 × 头维度 × 2字节 × 2K和V。7B模型32层、32头、head_dim128的情况下一条8K上下文的请求大概占用8K × 32 × 32 × 128 × 2 × 2 ≈ 512MB如果显存里能分20G给KV Cache这个模型大概能同时支撑40个8K请求。这个估算方法能帮你在项目初期快速判断该买几张卡和该限制多少并发避免资源浪费。注意如果内网环境完全没有GPU可以考虑CPU推理走llama.cpp或者带量化版的Ollama。7B模型量化到Q4后在主流服务器CPU上大概每秒出5~12个token做知识库问答足够但复杂Agent多轮调用会比较吃力token生成速度太慢会让用户体验很差。3. RAG知识库建设与数据治理3.1 数据采集与清洗管线的设计隔离内网环境下的RAG最难的不是向量化而是数据源头非常脏。我遇到的情况通常是几十万份办公文档分散在NAS、各系统的导出Excel、老旧OA附件里格式五花八门PDF有扫描件也有文字版Word有.doc也有.docx还夹杂大量图片型表格。我的建议是效仿数据仓库的分层思路把数据管道分成四层采集层定时扫描共享目录、数据库、附件导出目录增量抓取新增文件。解析层按文件类型走不同解析器PDF用PyMuPDF、OCR引擎等Word用python-docx表格转CSV再入向量库。清洗层去页眉页脚、去重复文档、统一编码很多老文档是GBK、删除敏感水印和无关广告页。索引层切片、向量化、写入向量库并记录元数据。再补充一个细节切片策略不要只用固定长度切。我实践下来按文档结构标题、段落、表格优先切固定长度兜底效果远好于纯固定长度。因为固定长度会把完整的业务描述拦腰截断导致检索片段语义不完整。一般我设置段落阈值在300~800字之间超出部分再递归切分重叠窗口设50~100字。3.2 向量化与存储的工程细节Embedding模型要根据文档语言特点选择。中文场景我目前用得比较稳的方案是BGE系列尤其bge-large-zh-v1.5和M3E系列它们的语义匹配效果在中文本地上明显好过通用英文模型。内网部署时需要一并准备模型权重和tokenizer文件这个流程和LLM一致。向量数据库选型隔离内网场景我建议优先考虑Milvus或Qdrant两者都支持离线部署都有较好的过滤查询能力。如果数据量在百万级以下Chroma也够用部署更轻。写入MFW与检索链路我习惯的做法是from sentence_transformers import SentenceTransformer model SentenceTransformer(/data/models/bge-large-zh-v1.5) # 批量向量化控制batch_size防止显存波动 embeddings model.encode(chunks, batch_size16, normalize_embeddingsTrue) # 写入Qdrantpayload带文档ID、来源、标题、页码 client.upsert(collection_nameenterprise_kb, points[ PointStruct(ididx, vectoremb, payloadpayload) for idx, (emb, payload) in enumerate(zip(embeddings, payloads)) ])用normalize_embeddingsTrue的意义在于后面做相似度检索时可以走点积运算性能比余弦相似度更优而结果几乎一致。这个细节虽然不起眼但在数据量大了之后能明显减少检索耗时。3.3 检索质量调优方法论RAG调优是持续过程我一般按召回→排序→重写三步走召回先做向量召回Top 50再做关键词/BM25召回Top 50两路结果混合去重。如果只用纯向量检索遇到专有名词如设备型号、系统编码时效果会差很多因为Embedding本质不擅长精确词匹配。排序用Reranker模型对召回结果精排Top K取5~10。Reranker是RAG效果提升最明显的一步很多问题召回没问题但答案不对就是Top K里有用内容被埋没了。重写用户Query本身质量不高时用LLM做一次查询改写比如把口语化表述变成检索友好的关键词组合但这一步要注意别引入额外幻觉在Agent里可以做成可选开关。注意RAG的回答效果很多时候不是模型不行而是检索回来的片段根本不包含正确答案。我建议把检索内容是否包含证据做成可视化调试面板每次效果不对先看检索Top 5而不是急着换大模型。4. Agent核心链路与工具调用实现4.1 工具注册与权限边界Agent的本质是把LLM的对话能力升级为行动能力而行动落地的载体就是工具。隔离内网下工具主要分为三类内部API型比如查库存、提单、获取审批状态。数据查询型查数据库、查数据仓库、跑固定报表。操作型调用RPA机器人操作老旧系统、自动生成并分发文件。工具管理上我推荐用声明式注册 Schema校验的方式。每定义一个工具明确它的名称、描述、参数结构、权限范围、调用后果。LLM输出结构化的工具调用请求代码层做参数校验后再执行避免模型乱传参数。一个实际工具定义片段用FastAPI风格实现class QueryStockTool(BaseTool): name: str query_stock description: str 根据物料编码查询实时库存数量返回可用库存与在途数量 args_schema: Type[BaseModel] QueryStockArgs def _run(self, material_code: str) - str: # 调用内网库存服务 result call_internal_api(stock/query, {material_code: material_code}) return json.dumps(result, ensure_asciiFalse)这里的关键不是代码本身而是每个工具都要有明确的准许调用范围。我在项目中专门加了一层工具白名单由管理员在后台配置哪些角色能调用哪些工具避免Agent被诱导去执行越权操作。这是隔离内网环境尤其重要的安全底线。4.2 工作流编排与状态控制Agent任务不是一次Chat完事往往要经历理解需求→拆解步骤→选工具→调工具→看结果→再决策的多轮循环。这块我用LangGraph的场景比较多因为它的图状态机制天然适合Agent循环控制。一个简单的Agent状态流包含几个节点route意图分类、retrieve查知识库、call_tool调工具、respond生成回复。状态转移时需要重点控制两个参数最大迭代次数避免Agent陷入调工具→看到结果→继续调工具的死循环我一般设5~8次。中断策略对于有副作用的工具比如发送审批邮件、修改数据必须在执行前暂停并请求用户确认不能全自动放行。注意内网业务系统很多时候API不稳定返回超时、字段缺失是常态。每个工具调用必须做异常捕获和返回结果的结构化校验全链路加trace_id便于排查。别默认模型能处理各种异常返回——它往往会在工具报错时一本正经地编一个成功结果给你看。4.3 上下文管理与Token控制ai agent token是什么意思这类热词背后其实是很多人在问Agent的Token消耗为什么这么夸张。因为在Agent链路里每一轮工具调用结果都会拼进上下文次数一多上下文长度飙升Token费用或显存压力都跟着涨。隔离内网下Token控制的核心思路可以分成三层短期对话窗口保留最近N轮对话工具结果摘要超过阈值就做截断或滚动摘要。长期记忆外部化把用户画像、历史偏好、项目背景等信息写入独立记忆库或向量库只在需要时检索加载而不是全量拼进Prompt。这种记忆外置的策略让我在实际项目里把单会话上下文减少了40%~60%。工具结果压缩工具返回的原始内容往往很大比如SQL返回1000行结果但模型真正需要的是摘要或关键字段。我在工具执行层做一次结果裁剪只返回Top N条或关键统计值Prompt直接从8000 token降到1500 token。一个比较典型的Prompt结构会这样组织[系统指令] 你是内网业务助理只允许调用白名单工具禁止执行未授权操作。 [当前任务] 用户要求查询库存并生成补货建议 [可用工具] query_stock / check_supplier / generate_report [历史摘要] 用户已确认仓库编码WH-03 [工具结果] 物料A可用库存326件在途500件安全库存800件 [模型输出] 生成分析结论与建议这种结构化Prompt的好处是清晰分割不同信息来源模型不容易混淆用户说的和系统查到的。5. 隔离内网环境下的工程化与安全加固5.1 离线依赖与镜像管理内网环境最折磨人的问题之一就是装依赖。我的习惯是在能联网的同架构容器里做全量依赖导出再整体导入内网。具体可以这样做# 外网环境准备requirements.txt并打包安装缓存 pip download -r requirements.txt -d ./packages/ # 将packages目录拷入内网 pip install --no-index --find-links./packages/ -r requirements.txt如果用到Conda环境就用conda-pack整体打包效果更省心。Docker镜像同理尽量做全家桶镜像把CUDA驱动层、推理框架、依赖库一次性打好避免内网逐层构建因为某层拉取失败而卡住。另外强烈建议在项目启动第一天就建立内网软件物料清单SBOM。记录每个Python包的名称、版本、来源哈希每个镜像的tag。否则一旦某个依赖有安全漏洞或需要版本回溯你在内网里连查来源都费劲。5.2 日志、审计与告警体系隔离内网里的AI Agent不能是黑盒。我坚持从第一天就建立三本日志账模型调用日志请求内容、响应内容、Token消耗、延迟用于复核模型是否合规回答。工具调用日志谁在什么时间调了哪个工具、传入什么参数、返回什么结果、耗时时长。操作审计日志哪些用户登录了Agent系统、创建了什么任务、是否有越权尝试。日志采集整体走JSON结构化输出汇总到内部日志平台。告警规则按工具调用失败率超过10%模型平均延迟超过3秒Token消耗异常激增这几个指标设置。我在实际项目中遇到过Agent在凌晨自动任务中反复重试失败工具导致日志量和调用量爆炸的情况就是靠告警发现的。隔离内网不代表可以放松可观测性反而因为现场排查不方便更需要系统化日志支撑。5.3 安全防护与访问控制AI Agent的权限安全远比普通Web应用复杂因为Agent会替你做事。我的安全基线是身份认证对接内网统一身份认证OIDC/LDAP每个用户有独立身份不能用共享账号。细粒度授权工具级权限数据级权限双重控制。用户能问库存不等于能查供应商合同报价。输入输出过滤Prompt注入过滤、敏感信息脱敏。用户可能在对话中诱导模型输出内网敏感配置也可能在知识库文档中隐藏恶意指令必须有过滤器兜底。操作二次确认所有有副作用的工具写操作、发消息、修改数据默认开启人工确认。注意Prompt注入不是外网才有的风险。内网Agent如果接了企业数据库和自动化工具被诱导执行删数据发全员邮件这类恶意指令的后果更严重。务必把工具调用权限的默认策略设为最小可用而不是最大可用。5.4 关于Rust在Agent链路中的实践不少人问基于Rust语言AI Agent是否可行。我的看法是整条Agent链路全用Rust来写目前生态还不算成熟但在工具调用执行器、API网关、高并发缓冲层这些对性能和稳定性要求高的环节用Rust是非常不错的选择。我在某个业务里把工具执行器用Rust重写了一遍效果很直接原来Python实现的工具调度在并发高峰期CPU占用飙到80%换成Rust后降到20%左右单机吞吐提升了一倍多。而且Rust编译出来的静态二进制在内网部署很友好二进制一拷就能跑不需要带Python环境和依赖包。适合用Rust实现的Agent组件一般有这四类工具执行网关处理请求分发、超时控制、流量限制日志采集Agent边车模式统一抓取模型日志消息队列消费者处理异步任务如批量生成报告轻量级推理代理把模型API包一层加缓存和熔断如果你团队的强项是Python没必要为了赶潮流硬换语言但如果你需要在有限硬件上支撑高并发Agent服务用Rust做核心链路组件是一笔很划算的技术投资。6. 常见问题与排查技巧实录6.1 模型推理速度慢到无法接受这是隔离内网环境最普遍的反馈。排查顺序我建议是先看并发数是否过高导致GPU排队。压测一下单请求的time to first token如果这个值都很大就不是排队问题。再看上下文长度。很多Agent任务因为上下文膨胀实际计算量远超过你的预期。我用vllm的/metrics端点看每个请求的prompt tokens数经常能发现用户只是问一句帮我查一下刚才说的那个材料实际上上下文已经堆了1万多个token。最后看量化与精度。FP16改FP8或INT8AWQ/GPTQ量化能显著提升推理速度代价是极小幅度的质量损失。内网业务如果不是对文字质量要求极高我很推荐量化部署。6.2 RAG检索结果相关性差现象是用户明确的问题Agent答非所问引用的文档段落跟问题根本不搭边。我遇到这类问题的排查路径通常是打印检索Top 10结果看召回的是否有正确答案。如果Top 10里没有问题出在向量化或切片。检查Embedding模型的领域适配度。通用模型对专业领域术语比如参数比扭矩系数BOM树语义理解较弱这时需要收集领域语料做Embedding微调或者换用领域预训练模型。检查Query预处理。用户口语化提问和文档书面表述之间差异很大要在进入检索前做关键词扩展和查询改写。最后才是调Reranker和Top K策略。6.3 Agent陷入无限循环不结束最常见的原因是工具返回结果被模型理解成了还需要继续调下一个工具而下一个工具又返回类似结果形成循环。我处理循环有三个手段在Prompt里明确定义当已获得可直接回答的信息时立即结束工具调用。设置最大迭代次数硬上限比如6次超过后强制进入respond节点。工具结果里增加是否已解决标记字段由工具侧判断是否需要继续调用其他工具。6.4 离线导入模型权重时文件不完整模型权重动辄几十GB拷贝到内网过程中经常出现文件损坏、sha256不一致的情况而加载时模型要么直接报错要么静默出现推理乱码。解决办法是拷贝完成后先做全量哈希校验再注册到模型库sha256sum -c model_weights.sha256如果是从移动硬盘拷入的建议走两次校验拷贝机校验一次、内网服务器校验一次。另外分卷压缩时不要开多线程某些压缩工具的多线程模式在数据量大时有概率产生校验错位我已经不止一次在分卷包上吃这个亏。6.5 工具调用返回结果超时内网系统API经常因为网络波动或服务过载而慢。核心对策分三层超时分级把短超时5秒用于健康检查中超时15秒用于常规查询长超时60秒用于报表生成类任务。异步化结果生成慢的工具改为提交任务→返回任务ID→Agent轮询结果模式。熔断降级连续失败N次后熔断该工具直接向用户返回该功能暂时不可用而不是让Agent反复重试浪费时间。这四类问题覆盖了我在多个项目中踩过的绝大多数坑。如果你正打算在隔离内网里搭建Agent建议先把这些预案过一遍再动手能少走很多弯路。个人经验小结隔离内网下做AI Agent技术上其实没有想象中那么高不可攀真正的难点在于工程耐心。你需要在没有外部资源可依赖的情况下把所有环节都想清楚、准备到位从模型权重到每一个Python依赖从数据清洗到工具权限边界每一步都踏实落地。我的经验是先跑通一个最小可用闭环哪怕只是文档问答一个工具调用再逐步扩展远比一开始就设计一个庞大平台要稳妥。先把基础设施和数据治理做扎实了Agent的价值自然会慢慢体现出来。