这事儿我从去年开始就一直在琢磨。公司要求做AI赋能但数据不能出内网模型不能上云所有东西都得在自己的机房里跑。一开始我也天真地以为把开源模型一拉装个Python环境调用几个库一个智能体不就出来了真做起来才发现坑比想象的多得多。而且市面上能找到的资料几乎全是围绕国外那套技术栈写的什么OpenAI的API、HuggingFace的模型库、向量数据库默认你有个能轻松访问外网、还能随便下载依赖的环境。可真到了企业内网尤其是国产化环境里一切都变了。这篇文章就是我从零开始在国产化硬件和操作系统上搭建Agent应用的全过程记录。没有高大上的理论全是实打实的选型、部署、调优和踩坑。如果你也在企业内网环境里做AI应用尤其是需要私有化部署的这篇文章应该能让你少走很多弯路。1. 项目概述怎么理解“国产化环境下的Agent”1.1 先给Agent画个像在开始动手之前我们得先统一一下认知Agent到底是个什么东西按照我的理解Agent就是一个能自己动脑子的程序。你给它一个目标它能自己拆解任务、调用工具、检查结果直到把目标完成。它不是简单的聊天机器人也不是一个固定的工作流而是介于两者之间的一种存在。用大白话说你在对话框里让它“帮我分析这份财务报告把异常点列出来再画个图表”它不只是把你输入的文本接住再吐出来。它会先读文件然后调用代码解释器做计算再调用绘图工具生成图表。这个过程里模型自己在规划步骤自己决定该用什么工具这就是Agent。这个“自己决定”的能力依赖于大模型的推理能力和函数调用Function Calling能力。我们后面要搭的整个系统本质上就是围绕这个核心能力展开的。1.2 “国产化环境”到底特指什么说到“国产化环境”很多人会下意识觉得就是“用不了外网”。但在我实际做项目的过程中我发现这里面的约束是多维度的一层一层叠加起来远比“不能联网”要复杂得多。第一层是硬件层。你用的可能是华为昇腾、寒武纪、海光DCU或者天数智芯这些国产AI加速卡而不是英伟达的GPU。这就意味着CUDA没法用了你得用各家的专用计算框架比如CANN昇腾、BANG寒武纪等等。这对很多做AI出身的人来说几乎是第一道看不懂的门槛。第二层是系统层。操作系统可能是麒麟、统信UOS、欧拉而不是Ubuntu或者CentOS。这虽然不至于让你寸步难行但很多软件在这些系统上确实没有现成的安装包你得学会自己编译学会换源学会处理各种依赖问题。第三层是网络层。内网环境意味着你不能随意pip install也不能从Docker Hub拉镜像所有东西都需要离线部署。提前准备好轮子文件、离线安装包这些都成了基本功。第四层是生态层。内网里没有HuggingFace没有各种odoo的现成组件也没有GitHub上随时可以克隆的代码库。你需要的很多工具都得靠自己用代码去拼凑或者在内网的GitLab里重新建立一套内部依赖体系。我列这些不是想劝退你而是想在第一篇就让你对“国产化”这三个字有一个清醒的认识它就是一套完全不同的生态需要用完全不同的打法来应对。你不能用老旧的习惯去生搬硬套必须换一套思路。2. 方案选型我为什么最终选了这套技术栈做个Agent应用方案其实非常多。就拿模型来说你可以用开源模型也可以买商业API拿框架来说有LangChain有Semantic Kernel还有各种国产框架。这么多组合怎么选才是真正适合私有化环境的下面我把我的选型过程复盘一下。2.1 模型底座Qwen2.5-7B-Instruct是性价比之选模型是整个Agent系统的大脑也是我最早确定的组件。选择开源模型的原因很直接商业API调用链路太长数据安全不可控而开源模型可以完全部署在内网数据静态加密在本地动态传输也在内网不会出任何边界。在国内开源模型里我优先考虑的是Qwen系列。当时在手头能接触到的模型里Qwen2.5-7B-Instruct的综合实力和中文能力是让我最满意的。尤其是它的工具调用能力对Function Calling支持得相当好这点对Agent应用来说至关重要。因为我们后面的所有工具调度都依赖于模型能不能准确输出结构化的调用意图。7B这个参数量是我反复权衡后砍掉更大模型的选择。130亿以上的模型在推理效果上确实会好一点但在国产加速卡上的部署成本会迅速上升。我的经验是在单卡16GB甚至8GB显存的环境下量化后的7B模型是体验和部署难度最平衡的选择。当然如果你们的算力资源更充足也可以选择Qwen2.5-14B甚至更大参数量的模型。但无论如何我建议你在模型选型这一块一定要预留出足够的测试时间。不要光看跑分一定要把你们业务里最典型的几个任务拿出来实测看效果、看延迟、看并发表现。2.2 推理引擎vLLM是生产环境的首选模型定下来之后接下来的选择就是推理引擎。市面上能用的推理框架不少FastChat、TGI、vLLM都能跑。我在一开始图省事用了FastChat因为它是早期标杆文档相对全面部署也确实快。但用着用着我就不太满意了。它的并发能力和吞吐量在真实业务压力下撑不住。我压测了一下并发一上来响应延迟就开始抖动显存也没有得到充分利用。后来我换成了vLLM这个选择让整个系统的性能有了质的提升。vLLM之所以强核心在于PagedAttention技术。它可以像操作系统管理内存一样管理KV Cache减少了显存碎片把显存利用率提了上来。这样在同样的硬件条件下我能跑的并发请求数量就多得多。我用一个简单场景对比过在同样的昇腾卡上跑Qwen2.5-7BFastChat大概只能支持个位数的并发而vLLM能支撑住二三十个并发请求延迟还更平稳。在昇腾的环境下vLLM的适配版本是华为官方基于CANN框架改造过的vllm-ascend在GitHub上可以找到源码。别直接用原版vLLM去跑昇腾那样会报各种算子不支持的错误。这也是我在选型过程中一个重要心得翻译过来就是“什么土壤种什么庄稼”。2.3 应用开发框架放弃LangChain自己搭胶水层现在说到应用开发框架这也是我踩坑比较多的地方。一开始我很自然地去看了LangChain毕竟它名气大、社区活跃网上资料也多。但实际用它的时候我发现了一些不太好处理的点。LangChain的抽象层级特别多每个环节都有好几种不同概念比如Chain、Tool、Agent、Memory、Retriever这些概念又互相套娃。一旦出了什么问题排查起来非常头疼。尤其在国产化环境里很多依赖的库版本并不兼容经常装了A组件B组件就崩了改来改去时间全耗在依赖地狱里。传统开发模式是一种方式但当你把LangChain的代码一跑起来发现环境的坑比业务本身的坑还多。从那时起我就决定不用这种重框架直接用vLLM暴露出来的OpenAI兼容API加自己写的一层薄薄的调度逻辑。这个调度逻辑就叫它“胶水层”。它的职责非常纯粹接收用户的请求把用户的意图、历史消息和工具定义拼好发给大模型模型返回结构化调用指令后再从工具注册表里找到对应的函数去执行把执行结果交还给模型直到生成最终答案。你别小看这层胶水它就是Agent的核心灵魂。LangChain也是在干这些事只是它把这套逻辑做成了通用框架这回过头来反而成了负担。你自己写可以完全把控自由度也能在出现问题时快速定位定位。具体来说我的想法是维护一个工具注册表里面放好一系列函数每个函数配好名称和描述。模型如果决定要调用某个工具它会输出一个结构化的JSON。这层调度逻辑读到JSON后执行对应的函数把结果拼接进上下文再返回给模型让模型继续推理。整个过程都可以用很普通的Python代码完成。2.4 向量数据库和工具链的选型Agent应用中还有一个很重要的组件是记忆和知识库。要让Agent能回答私有知识相关的问题必须能够快速从文档库里检索相关信息。这就用到了向量数据库。这个环节我选的是Milvus。原因很简单企业级应用对数据的可靠性和检索性能有很高要求。Milvus本身就是云原生架构可以分布式部署稳定性也相对更好不像一些轻量级方案那样用着用着就出问题。Milvus对国产化环境的适配也做得不错在ARM架构下也能编译部署。当然除了Milvus如果你们的场景更简单数据量也不大也可以用轻量级的方案比如Chroma或LC的本地向量库。但如果要考虑长期扩展我的建议是宁可前期麻烦一点直接上Milvus。后来随着业务规模上来你会发现这些投入都是值得的。在工具链方面我除了基础的函数调用还集成了一个代码解释器沙箱环境这样Agent可以动态生成Python代码来做数据分析而不是光靠嘴说。这个功能对偏Office、财务、运营方向的Agent特别有用能让分析结果更硬核也更可控。3. 环境准备把地基打牢方案定了之后接下来的工作就是真正动工。这一步我打算先把环境准备好。按照我踩过的坑经验环境准备阶段宁可慢慢来多花点时间也不能急于求成。一旦后面运行起来了才发现地基不稳回头的成本会特别高。3.1 操作系统和基础软件的安装我这边测试环境用的是麒麟V10 SP1这个版本内核是4.19架构是x86。这个系统在国产化环境里算是比较有代表性的社区文档相对多一些坑也相对好搜一些。如果你的环境是统信UOS这类系统操作思路是类似的只是个别命令和包管理方式会有点差异。系统装好之后有一系列基础软件要装Python、Docker、Git、以及后面会用到的一些工具库。这里我还是建议优先使用系统的包管理器去安装只有在确实找不到包的情况下才去源码编译。一个很重要的提醒在国产化系统上Python的版本可能会偏低一些。比如麒麟V10自带的是Python 3.7而我们要跑的很多应用可能需要3.10以上。这时候千万不要去动系统自带的Python很容易把系统的yum/dnf这些包管理器搞跪我早期就干过这种事最后只能重装系统。正确做法是用源码编译一个独立版本的Python通过软链接的方式使用或者使用conda管理虚拟环境这样不影响系统本身的运行。Docker的安装如果没有现成包可以选择用二进制包systemd脚本来手动安装。Git、GCC、Make这些工具也一样。打包好之后的离线安装包要为后续的生产环境部署做好准备。3.2 昇腾环境的准备和驱动安装我这边的环境准备最头疼的部分其实是昇腾卡的驱动和固件安装。昇腾卡不像英伟达GPU那样装个驱动就完事儿。它需要装好几个组件驱动、固件、CANN工具包还有后面用vLLM时要装的torch_npu插件。关于这些组件的版本我在这里强烈建议不要自己发挥一定要严格按照华为官方文档推荐的版本组合来。我第一次装的时候想着只要版本大方向没错就行结果卡在了一个算子不兼容的问题上。当时那个程序跑起来老是提示算子不支持我排查了好久最后才发现是CANN和torch_npu的版本不匹配。后来我养成了一个习惯把所有组件的版本号都记下来每次部署前先对照官方文档检查版本矩阵。昇腾环境下的版本矩阵是真实存在的不同版本的Ascend驱动、CANN工具包和PyTorch适配层是彼此隔离的组合错一对就会出各种神鬼莫测的问题。装好之后记得验证一下环境是否正常。可以用Python脚本来检查torch_npu是否成功加载显卡是否被正确识别。这一步虽然无聊但非常必要。3.3 离线依赖库的准备在能上网的机器上提前把后面会用到的Python包全部下载好。比如transformers、accelerate、safetensors、sentencepiece、numpy这些都要用pip download的方式存成离线wheel文件。然后把这些wheel文件连同它们的依赖一起拷贝到内网环境里再用pip install --no-index --find-linkswhl_dir 来安装。这个过程我一开始吃过亏。我就光下载了明确列出来的包结果安装的时候发现少了一堆传递依赖一会儿缺XXX一会儿缺YYY装了好久才搞定。后来我学会了一个更花哨的打法用pip download -r requirements.txt -d whl_dir它就会把requirements里所有包的依赖一起拉下来虽然体积会大一些但是省心太多。还有一点镜像源的设置也很重要。在内网环境里你要确保pip不会去连外网不然每次安装都要等超时提示白白浪费时间。可以在pip.conf里设置index-url指向内部镜像源或者干脆加--no-index参数强制本地安装。4. 模型部署与推理优化让大脑先转起来环境准备好之后终于可以进入最核心的一步把模型跑起来。这一步我会结合昇腾卡的实际环境详细记录部署过程和推理优化的经验。4.1 模型下载与转换Qwen2.5-7B-Instruct在HuggingFace上有官方权重但内网环境里显然不能直接下载。常规做法是在能上网的电脑上先把模型下载下来然后转成我们推理引擎需要的格式再拷贝进内网。这里我要补充一个我后期一直在用的小技巧。下载模型时如果网络情况只是普通不建议直接在大模型仓库页面逐个点击下载因为文件很大断点续传也不太行。我通常是用modelscope或者hf_transfer这类工具来下载支持多线程、断点续传速度能快好几倍。模型下载下来之后如果是准备用vLLM跑那权重文件其实已经可以直接用了safe tensors格式基本通用。但如果你的环境里只能用TensorRT-LLM这类引擎那就要额外做模型转换生成TensorRT的引擎文件。这一步会比较耗时也会吃很大的显存建议一次性规划好。昇腾环境下的模型存放路径建议放在一块高速SSD里不要放在机械硬盘上否则加载模型能等得人心态爆炸。4.2 vLLM启动服务与关键参数调优在昇腾环境下启动vLLM服务逻辑跟GPU版类似但有一些独特的参数需要注意。先说我用的一次经典启动命令这里摘出来给你参考python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen/Qwen2.5-7B-Instruct/ \ --served-model-name qwen7b \ --tensor-parallel-size 1 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --trust-remote-code \ --port 8000 \ --host 0.0.0.0 \ --dtype bfloat16简单说明一下这些参数的含义。tensor-parallel-size这个参数在多卡环境里尤其重要希望并行推理时设置为卡数。如果你的卡显存不是特别大可以设置small一些。max-model-len指的是模型能处理的最大上下文长度如果开太大显存占用会飙升所以一般都是结合显存大小来定。我这边就是8K足够覆盖绝大多数业务场景。gpu-memory-utilization是让vLLM尽量用满显存的比例我设成0.9预留一点安全余量防止OOM。有一点必须注意昇腾环境下要确保CANN自带的环境变量正确加载比如source /usr/local/Ascend/ascend-toolkit/set_env.sh这种。然后运行的时候Python解释器要能import torch_npu否则vLLM是没法真正调用昇腾卡的。服务启动之后可以用一个简单的curl命令验证curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d {model: qwen7b, messages: [{role: user, content: 你好做个自我介绍}]}。如果这个请求能正常返回结果说明模型已经跑起来了。这一步我建议先用一个简单的对话测试再用Function Calling的请求测试看看模型能不能按预期的JSON格式返回工具调用指令。4.3 推理性能调优心得模型跑起来只是第一步性能好不好直接决定了上线之后用户体验怎么样。在昇腾环境里有几个调优的心得我觉得非常值得分享。第一个是关于并发和吞吐。vLLM的continuous batching机制天然处理得还算不错但前提是你得把max-num-seqs这类参数调好。并发用户多的话这个值可以适当调大不过我经验里也不能过猛调太高的并发调度反而会增加调度开销拖慢单请求延迟。具体还要靠压测数据说话。第二个是KV Cache和显存的比例。gpu-memory-utilization设成0.9之后并不意味着模型会把所有显存都用于KV Cache。实际生产里如果你还想留点显存放其他的小模型或者做别的任务可以适当降下来改成0.8甚至0.75。第三个是关于dtype的选择。昇腾环境里bfloat16的支持情况会比常规CUDA差一些需要一定版本才能支持。如果是早期不支持的话可以用float16不过精度会略低一点点问题不大。我压测用的工具是简单的Locust脚本模拟几十个用户同时提问监控请求延迟和吞吐量。通过这些数据我再反过来调整并发参数直到达到一个相对稳定的平衡点。模型推理是整个系统里最容易被压垮的瓶颈这一步多花点时间是值得的。5. Agent应用开发把大脑接上手脚模型能跑起来算是有了“大脑”。接下来要做的事情就是给这个大脑接上“手脚”——也就是围绕它构建一整套Agent应用。5.1 设计工具注册与Function Calling我构建的第一个核心模块就是工具注册与Function Calling。这个设计可以理解成把Agent能做的事情都登记在一个“菜单”上模型根据用户的问题从菜单里挑选合适的“菜品”来“点单”。具体实现上我维护了一个名为ToolRegistry的类。每个工具都由一个名称、一段自然语言描述、以及一个具体的执行函数组成。工具描述写得越具体模型就越容易在合适的场景下选中它。我一开始写的工具描述太简略导致模型经常选错工具后来我把描述扩写详细加上了使用场景和参数说明效果马上就好了很多。当模型决定调用某个工具时它会按照我定义好的输出格式返回一个包含工具名称和参数的JSON。于是我的执行逻辑就开始工作读取JSON从注册表里找到对应的函数把参数传进去执行然后把结果拼成一条新的消息连同用户的原始问题一起再发给模型继续推理。这里有个需要注意的细节工具返回的结果最好不要太大。如果返回的是一个超大JSON或者特别长的日志模型很难从中抽取出关键信息还会白白消耗上下文窗口。解决办法是在工具执行完成后做一次结果摘要只保留核心的关键结论再交给模型。这个细节在实际使用中能显著提升Agent的表现。5.2 记忆与上下文管理机制Agent的第二个重要模块是记忆。如果没有记忆Agent每次对话都是“失忆”状态用户之前说过什么它一概不知。这样很多多轮任务就完不成。我的方案是把记忆分成两层。一层是短期记忆对应的是对话历史。使用vLLM的上下文窗口把所有历史消息都塞进去。当然这些消息往往超过上下文窗口因此还要做个整理比如只保留最近几轮对话把更早的内容总结成一段摘要再放进去。另一层是长期记忆关系到知识库。把私有文档灌进Milvus用户提问时从Milvus里检索与问题最相关的片段再拼到上下文里让模型参考这些片段去回答。这些片段相当于模型的记忆碎片每次丢进去几个相关的不用太多否则也会造成干扰。Milvus的检索需要用到Embedding模型我选了bge-m3这个模型在国内开源Embedding模型里综合表现靠前主要是中文能力和泛化能力都不错。部署Embedding模型可以单独起一个小服务不需要很高的显卡配置CPU推理也能用速度慢一点但也能接受。5.3 沙箱代码解释器这一节我要重点说说代码解释器Code Interpreter。这个东西太重要了。如果没有它Agent只能做一些文本处理一旦需要计算、数据分析、生成图表它就完全没辙。有了代码解释器Agent可以在沙箱里生成并运行Python代码完成各种数据处理任务。我采用的是Docker沙箱方案。为每个用户的执行请求创建一个一次性容器容器里预装好Python主流的数据分析库pandas、numpy、matplotlib等。这样即便模型的代码生成得有些脏东西它也只是在一个干净隔离的容器里运行不会影响主服务的安全。这块有一个重要细节安全。你不能让模型在宿主机上直接执行代码万一它生成了一段恶意代码或者执行了危险操就会非常麻烦。所以容器必须做资源限制CPU、内存、超时时间都得设上限。我这边是把超时控制在30秒内超过就会杀掉容器并返回一个超时错误。代码执行完之后沙箱会把stdout输出、运行状态码以及可能生成的图表文件返回。如果生成了图表我让Agent把它转换成base64编码最后在前端展示给用户。这个功能无论是做数据报表还是做运维分析都特别实用。5.4 对话前端与API封装前端界面我走的是极简路线没有用很复杂的框架直接用Gradio搭了一个聊天平台。Gradio最大的优点是上手快写十几行代码就能出一个带聊天界面的WebApp。它还自带WebSocket机制可以实现打字机式的流式输出。对话流程核心是Streaming输出。模型在vLLM返回的是一个流式的token序列我通过FastAPI WebSocket将这些token片段逐字分发给前端。这样做的好处是用户不用干等下一条消息提交之后就能看到正在生成的文字体验会好很多。后端API我统一封装成OpenAI兼容的格式。这样设计的好处是之后如果需要切换模型或者把能力开放给第三方系统只要客户端支持OpenAI协议就能直接对接不至于把整个接口层重写一遍。6. 上线与运维从能用到好用开发完成之后系统还只是“能跑”。距离“好用”和“稳定”中间还要经历上线和运维的考验。这一章我会分享我在实际部署运维过程中积累的经验尤其是企业环境下很看重的稳定性、性能和安全性问题。6.1 Docker化部署与容器编排为了让整个系统能在不同环境里平滑迁移我把所有组件都打成了Docker镜像。模型服务、后端API、向量数据库、前端每个组件都有独立的镜像通过docker-compose统一编排在一台机器上。这里有一个小建议镜像的标签一定要具体加上版本号比如agent-backend:v1.2.0。不要图省事用latest否则几个月后再去看都不知道线上跑的是哪一版代码。这个习惯能省掉很多“事故还原”的麻烦。在昇腾环境的容器化部署里有几个特殊点要处理。一是让容器能访问到昇腾的设备节点。你需要把/dev/davinci*挂载进容器再把CANN的驱动和库文件也挂进去否则容器里是没法识别卡的。二是一些系统环境变量比如ASCEND_VISIBLE_DEVICES也要在容器启动时设置好。编排层面推荐用Docker Compose管理单机多容器。如果将来要跨多台机器做高可用集群再考虑Kubernetes。对于大多数中小规模企业应用Docker Compose完全够用没必要一上来就上K8s运维成本会陡增。6.2 性能监控与日志采集系统上线后性能监控和日志采集是保障稳定性的基石。我的做法是后端每一个关键步骤都打点记录时间戳用户请求进入时间、工具调用耗时、模型推理耗时、输出返回时间。这样定位问题的时候我们就知道瓶颈到底出在哪一个环节。日志方面我采用结构化打印每条日志都是JSON格式包含时间、级别、模块、请求ID和具体消息。这样后续接入ELKElasticsearch、Logstash、Kibana的时候特别方便。请求ID特别重要每个请求都带上这样当用户报问题我们通过请求ID就能把所有日志串起来还原现场。监控面板我用的是PrometheusGrafana。后端服务会暴露一个/metrics端点把请求量、延迟分布、错误率、显存占用这些指标都采集进去。Grafana画几个核心Dashboard比如并发数趋势、P95延迟、工具调用失败率等。每次版本迭代之后盯着Dashboard看几天基本就能判断发布是否健康。6.3 国产化环境下的兼容性坑国产化环境里最大的敌人就是“差一点”的兼容性。我发现了很多莫名其妙的坑这里简单列举。比如某些基础镜像里的glibc版本偏低跑Python应用时落到某个二进制的库就调用不了报错信息还不直观只能靠大家搜索经验。这个情况其实是兜底方案必须下到合适的基础镜像才能解决。再比如一些内置的加密算法在不同系统底层库里的支持不一致某些国产操作系统对国际主流加密套件的支持并不全面导致我们用某些开源库的时候出现异常。以及不同Linux发行版对systemd支持的路子各有偏差不同系统的service管理方式也各有区别。这些坑很难提前预知我几乎都是靠一步步排查搞定的。养成一个习惯部署完每个组件后先单独验证它的基本功能确认没问题后再集成进系统这样定位问题会快很多。一旦系统整体建立一个再出问题排查范围就会很大很容易拖延上线时间。6.4 安全加固与权限管控安全是企业应用的生命线。我在上线前做了一轮安全加固总结了几个重点。首先服务层面所有对外暴露的接口全部走HTTPS证书使用企业内部的CA签发的证书。账号系统接入企业的统一身份认证单点登录不用简单的账号密码。要给AI应用单独设置Key通过API Key管理后台给不同部门分配不同的调用额度。其次针对Prompt注入攻击要做防护。恶意用户可能通过输入特定的提示词试图让Agent绕过约束执行未授权的操作。针对于此我会设计一套系统级提示词把这些系统规则插入到上下文的最前面同时也可以在后端API层过滤掉一部分敏感指令。另外只要用户输入中出现“忽略上述所有指令”之类的危险句型我会和像“防火墙”一样拦截掉。最后是数据安全。支持对话数据落库同时对敏感字段做脱敏处理。由于部署在内网很多企业可能低估了数据安全风险但我建议还是按照等保三级的标准去设计规范尽量做到“谁的对话谁能看”。这一块对Agent类应用尤其重要因为它可能接触到大量的内部文档和用户数据权限设计一旦不到位后果会很严重。7. 效果验证与体验优化系统部署完之后整个架构基本完整了。但从“能跑”到“好用”还需要对效果做细致的验证和体验优化。这一章我想分享一些实际测试的结果和方法给你一些参考。7.1 真实业务场景效果验证完成基本开发后我用一个比较贴近业务实际的场景专门做了一次效果验证知识库问答加数据图表分析。具体来说我向Agent上传了一份销售数据报表咨询它“上个季度的销量趋势如何哪个地区增长最快帮我画一张图”。Agent的执行步骤非常清晰。它先解析我的意图确认需要调用代码解释器接着在沙箱里读取CSV文件计算出各地区的销量统计和环比增长率生成了一张柱状图。最后它借助上下文里的数据组织了一段总结文字把“哪个地区增长最快”答得明明白白。整个过程大概花了20秒模型推理的时间占了80%以上工具的调用基本上是在秒级完成的。从结果来看这份报告已经接近一个初级数据分析师的工作产出这对我的这套系统来说已经是一个合格的开局了。让我更惊喜的是Agent的多轮协作能力。它能记住我前面上传的是销售报表当我继续追问“那华东区呢”的时候它不需要我提供文件自动结合上下文和数据结果给出了华东区的详细分析。多轮交互的能力让这个系统可用性大幅提升用户真的觉得它在“记住我”、“理解我”。7.2 延迟优化和体验提升在效果有保障的基础上我考虑优化整个交互的体感。最明显的痛点是首次响应延迟和模型首字生成速度。vLLM的流式返回机制解决了一部分问题因为第一个token返回之后用户就开始看到文字主观等待时间缩短不少。为了进一步压这个指标我做了几个调整。一个是在后端加了缓存。对于一些高频的、结果相同的请求比如介绍类问题、固定格式的报表查询我们可以配置语义缓存把用户的请求文本做Embedding在向量数据库里查一下如果和之前的某条请求相似度很高就直接用缓存结果回答。这样可以显著降低模型压力也能让响应时间从秒级降到毫秒级。另外就是模型本身的选择。对于一些简单的意图识别和路由我用上一个轻量级的文本匹配模型可以直接判断用户是闲聊还是需要工具调用这样可以省去大模型的大部分无谓计算。主模型则只处理真正需要推理的任务整体资源利用率就上来了。8. 踩坑记录那些让你怀疑人生的瞬间写到这里我觉得有必要单独开一章记下我在这个过程中遇到的几个最典型的坑。它们不是技术难点可能就是你上网搜了很久也搜不到的那种问题但往往会卡住你很久。8.1 vLLM启动报错的“祖师爷级”问题我刚装好vLLM环境时运行启动命令立刻报出一大堆错有些看都看不懂。我总结了几个最常见的原因。第一种是torch_npu和CANN的版本不匹配这个是非常大概率的事情。解决方案就是严格按照官方文档的版本矩阵重新安装不要自以为是。第二种是环境变量没设置完全。昇腾环境需要一堆环境变量比如ASCEND_HOME、ASCEND_TOOLKIT_HOME还有LD_LIBRARY_PATH里要包含CANN的lib目录。这些变量一旦少了vLLM启动时就会报找不到库文件或无法识别设备的错误。第三种是Python版本问题。昇腾的CANN工具包对Python版本有严格限制一般支持3.7、3.8、3.9。如果系统自带的Python版本太高或太低都会有很奇怪的报错。建议创建虚拟环境把Python版本调整到CANN适配范围内。8.2 pip依赖地狱国产化环境里没有网对pip依赖的处理要格外谨慎。我第一次离线部署时只下载了requirements文件里一个个列出的包结果安装到一半报错说缺少某个传递依赖。于是又开始“单点补包”下载一个装一个装一个再报错一个来来回回十几轮人都麻了。最稳妥的做法是用pip download加-r requirements.txt把整个依赖树一次性下载下来。同时要求开发环境和部署环境的Python版本、操作系统架构要一致。否则你在这台机器上打包的依赖到另一台机器上可能装不了因为有些编译后的包是绑定平台架构的。8.3 向量数据库的Embedding模型选型第一次用向量数据库时我的Embedding模型选择的是一个小语种的多语言模型实际效果却不理想。原因是模型对中文支持不好中文检索的召回率特别低几乎等于没法用。后来换了bge-m3之后效果就立马上来了。这里我的经验是面向中文场景一定优先考虑中文表现好的Embedding模型比如bge系列、m3e系列等。另外做Embedding的时候给文本加一个合适的指令前缀比如“为这个句子生成向量以用于检索相关文章”能明显提升检索效果这是个被很多人忽略的细节。9. 写在最后的优化建议整个项目从前期环境考量到模型部署再到Agent应用的开发和改造最后走到运维上线过程中的每一步都有很多值得复盘的细节。我最后想说的是国产化环境下的Agent开发门槛更多是在于对整个环境的熟悉程度而不是模型技术本身的深度。9.1 先在小规模业务场景里验证我建议第一次做这类项目先选择一个小而具体的业务场景。比如做一个部门级的知识库问答机器人或者一个自动化报表分析助手。这样覆盖的范围不大数据量不大对硬件的要求也相对较低试错成本可控。做一个全功能的大而全的智能体会让开始的难度成倍提升。你可能会陷入“什么都在做什么都没做好”的糟糕境地。9.2 重视结构化数据的价值在项目迭代的过程中我发现一个很值得注意的经验Agent能力提升的重要源泉不只是模型的参数还包括数据的结构化和工具的质量。很多企业内部大量的数据和文档都是杂乱无章的PDF、Word、Excel如果直接丢给模型做RAG检索增强生成效果往往不太好。这时候可以投入精力去做数据清洗、数据抽取和结构化。比如把PDF转成Markdown把Excel转成易于检索的CSV格式再配合合理的索引设计知识库的查询质量和回答准确率会上升一个层次。这件事虽然琐碎且不性感但带来的效果提升幅度远比换一个大模型来得快。9.3 持续跟进开源社区和版本迭代国产化AI生态还有很大的迭代空间昇腾、寒武纪这些厂商适配的框架和模型都在快速更新。建议每隔一段时间关注一下你用的那几个核心组件有没有新的版本有没有新的优化。升级之前一定要仔细阅读官方文档中的版本变更日志和兼容性说明先做好充分的测试再上生产。我的经验是多花一点点时间在环境维护和技术更新上比一直“守着老版本不动”要安全得多。老版本太老会累积很多已知的问题版本太新可能踩不兼容的坑新的生态里这个问题格外明显。最后我还是想强调一遍那句话国产化环境不是“降级”环境而是一套有着自己玩法的生态。耐心、细心、好心态这三样东西比任何技术技巧都重要。希望我的这些经验能成为你的垫脚石让你少走几段弯路。 国产化环境下企业级Agent应用搭建实战指南
这事儿我从去年开始就一直在琢磨。公司要求做AI赋能但数据不能出内网模型不能上云所有东西都得在自己的机房里跑。一开始我也天真地以为把开源模型一拉装个Python环境调用几个库一个智能体不就出来了真做起来才发现坑比想象的多得多。而且市面上能找到的资料几乎全是围绕国外那套技术栈写的什么OpenAI的API、HuggingFace的模型库、向量数据库默认你有个能轻松访问外网、还能随便下载依赖的环境。可真到了企业内网尤其是国产化环境里一切都变了。这篇文章就是我从零开始在国产化硬件和操作系统上搭建Agent应用的全过程记录。没有高大上的理论全是实打实的选型、部署、调优和踩坑。如果你也在企业内网环境里做AI应用尤其是需要私有化部署的这篇文章应该能让你少走很多弯路。1. 项目概述怎么理解“国产化环境下的Agent”1.1 先给Agent画个像在开始动手之前我们得先统一一下认知Agent到底是个什么东西按照我的理解Agent就是一个能自己动脑子的程序。你给它一个目标它能自己拆解任务、调用工具、检查结果直到把目标完成。它不是简单的聊天机器人也不是一个固定的工作流而是介于两者之间的一种存在。用大白话说你在对话框里让它“帮我分析这份财务报告把异常点列出来再画个图表”它不只是把你输入的文本接住再吐出来。它会先读文件然后调用代码解释器做计算再调用绘图工具生成图表。这个过程里模型自己在规划步骤自己决定该用什么工具这就是Agent。这个“自己决定”的能力依赖于大模型的推理能力和函数调用Function Calling能力。我们后面要搭的整个系统本质上就是围绕这个核心能力展开的。1.2 “国产化环境”到底特指什么说到“国产化环境”很多人会下意识觉得就是“用不了外网”。但在我实际做项目的过程中我发现这里面的约束是多维度的一层一层叠加起来远比“不能联网”要复杂得多。第一层是硬件层。你用的可能是华为昇腾、寒武纪、海光DCU或者天数智芯这些国产AI加速卡而不是英伟达的GPU。这就意味着CUDA没法用了你得用各家的专用计算框架比如CANN昇腾、BANG寒武纪等等。这对很多做AI出身的人来说几乎是第一道看不懂的门槛。第二层是系统层。操作系统可能是麒麟、统信UOS、欧拉而不是Ubuntu或者CentOS。这虽然不至于让你寸步难行但很多软件在这些系统上确实没有现成的安装包你得学会自己编译学会换源学会处理各种依赖问题。第三层是网络层。内网环境意味着你不能随意pip install也不能从Docker Hub拉镜像所有东西都需要离线部署。提前准备好轮子文件、离线安装包这些都成了基本功。第四层是生态层。内网里没有HuggingFace没有各种odoo的现成组件也没有GitHub上随时可以克隆的代码库。你需要的很多工具都得靠自己用代码去拼凑或者在内网的GitLab里重新建立一套内部依赖体系。我列这些不是想劝退你而是想在第一篇就让你对“国产化”这三个字有一个清醒的认识它就是一套完全不同的生态需要用完全不同的打法来应对。你不能用老旧的习惯去生搬硬套必须换一套思路。2. 方案选型我为什么最终选了这套技术栈做个Agent应用方案其实非常多。就拿模型来说你可以用开源模型也可以买商业API拿框架来说有LangChain有Semantic Kernel还有各种国产框架。这么多组合怎么选才是真正适合私有化环境的下面我把我的选型过程复盘一下。2.1 模型底座Qwen2.5-7B-Instruct是性价比之选模型是整个Agent系统的大脑也是我最早确定的组件。选择开源模型的原因很直接商业API调用链路太长数据安全不可控而开源模型可以完全部署在内网数据静态加密在本地动态传输也在内网不会出任何边界。在国内开源模型里我优先考虑的是Qwen系列。当时在手头能接触到的模型里Qwen2.5-7B-Instruct的综合实力和中文能力是让我最满意的。尤其是它的工具调用能力对Function Calling支持得相当好这点对Agent应用来说至关重要。因为我们后面的所有工具调度都依赖于模型能不能准确输出结构化的调用意图。7B这个参数量是我反复权衡后砍掉更大模型的选择。130亿以上的模型在推理效果上确实会好一点但在国产加速卡上的部署成本会迅速上升。我的经验是在单卡16GB甚至8GB显存的环境下量化后的7B模型是体验和部署难度最平衡的选择。当然如果你们的算力资源更充足也可以选择Qwen2.5-14B甚至更大参数量的模型。但无论如何我建议你在模型选型这一块一定要预留出足够的测试时间。不要光看跑分一定要把你们业务里最典型的几个任务拿出来实测看效果、看延迟、看并发表现。2.2 推理引擎vLLM是生产环境的首选模型定下来之后接下来的选择就是推理引擎。市面上能用的推理框架不少FastChat、TGI、vLLM都能跑。我在一开始图省事用了FastChat因为它是早期标杆文档相对全面部署也确实快。但用着用着我就不太满意了。它的并发能力和吞吐量在真实业务压力下撑不住。我压测了一下并发一上来响应延迟就开始抖动显存也没有得到充分利用。后来我换成了vLLM这个选择让整个系统的性能有了质的提升。vLLM之所以强核心在于PagedAttention技术。它可以像操作系统管理内存一样管理KV Cache减少了显存碎片把显存利用率提了上来。这样在同样的硬件条件下我能跑的并发请求数量就多得多。我用一个简单场景对比过在同样的昇腾卡上跑Qwen2.5-7BFastChat大概只能支持个位数的并发而vLLM能支撑住二三十个并发请求延迟还更平稳。在昇腾的环境下vLLM的适配版本是华为官方基于CANN框架改造过的vllm-ascend在GitHub上可以找到源码。别直接用原版vLLM去跑昇腾那样会报各种算子不支持的错误。这也是我在选型过程中一个重要心得翻译过来就是“什么土壤种什么庄稼”。2.3 应用开发框架放弃LangChain自己搭胶水层现在说到应用开发框架这也是我踩坑比较多的地方。一开始我很自然地去看了LangChain毕竟它名气大、社区活跃网上资料也多。但实际用它的时候我发现了一些不太好处理的点。LangChain的抽象层级特别多每个环节都有好几种不同概念比如Chain、Tool、Agent、Memory、Retriever这些概念又互相套娃。一旦出了什么问题排查起来非常头疼。尤其在国产化环境里很多依赖的库版本并不兼容经常装了A组件B组件就崩了改来改去时间全耗在依赖地狱里。传统开发模式是一种方式但当你把LangChain的代码一跑起来发现环境的坑比业务本身的坑还多。从那时起我就决定不用这种重框架直接用vLLM暴露出来的OpenAI兼容API加自己写的一层薄薄的调度逻辑。这个调度逻辑就叫它“胶水层”。它的职责非常纯粹接收用户的请求把用户的意图、历史消息和工具定义拼好发给大模型模型返回结构化调用指令后再从工具注册表里找到对应的函数去执行把执行结果交还给模型直到生成最终答案。你别小看这层胶水它就是Agent的核心灵魂。LangChain也是在干这些事只是它把这套逻辑做成了通用框架这回过头来反而成了负担。你自己写可以完全把控自由度也能在出现问题时快速定位定位。具体来说我的想法是维护一个工具注册表里面放好一系列函数每个函数配好名称和描述。模型如果决定要调用某个工具它会输出一个结构化的JSON。这层调度逻辑读到JSON后执行对应的函数把结果拼接进上下文再返回给模型让模型继续推理。整个过程都可以用很普通的Python代码完成。2.4 向量数据库和工具链的选型Agent应用中还有一个很重要的组件是记忆和知识库。要让Agent能回答私有知识相关的问题必须能够快速从文档库里检索相关信息。这就用到了向量数据库。这个环节我选的是Milvus。原因很简单企业级应用对数据的可靠性和检索性能有很高要求。Milvus本身就是云原生架构可以分布式部署稳定性也相对更好不像一些轻量级方案那样用着用着就出问题。Milvus对国产化环境的适配也做得不错在ARM架构下也能编译部署。当然除了Milvus如果你们的场景更简单数据量也不大也可以用轻量级的方案比如Chroma或LC的本地向量库。但如果要考虑长期扩展我的建议是宁可前期麻烦一点直接上Milvus。后来随着业务规模上来你会发现这些投入都是值得的。在工具链方面我除了基础的函数调用还集成了一个代码解释器沙箱环境这样Agent可以动态生成Python代码来做数据分析而不是光靠嘴说。这个功能对偏Office、财务、运营方向的Agent特别有用能让分析结果更硬核也更可控。3. 环境准备把地基打牢方案定了之后接下来的工作就是真正动工。这一步我打算先把环境准备好。按照我踩过的坑经验环境准备阶段宁可慢慢来多花点时间也不能急于求成。一旦后面运行起来了才发现地基不稳回头的成本会特别高。3.1 操作系统和基础软件的安装我这边测试环境用的是麒麟V10 SP1这个版本内核是4.19架构是x86。这个系统在国产化环境里算是比较有代表性的社区文档相对多一些坑也相对好搜一些。如果你的环境是统信UOS这类系统操作思路是类似的只是个别命令和包管理方式会有点差异。系统装好之后有一系列基础软件要装Python、Docker、Git、以及后面会用到的一些工具库。这里我还是建议优先使用系统的包管理器去安装只有在确实找不到包的情况下才去源码编译。一个很重要的提醒在国产化系统上Python的版本可能会偏低一些。比如麒麟V10自带的是Python 3.7而我们要跑的很多应用可能需要3.10以上。这时候千万不要去动系统自带的Python很容易把系统的yum/dnf这些包管理器搞跪我早期就干过这种事最后只能重装系统。正确做法是用源码编译一个独立版本的Python通过软链接的方式使用或者使用conda管理虚拟环境这样不影响系统本身的运行。Docker的安装如果没有现成包可以选择用二进制包systemd脚本来手动安装。Git、GCC、Make这些工具也一样。打包好之后的离线安装包要为后续的生产环境部署做好准备。3.2 昇腾环境的准备和驱动安装我这边的环境准备最头疼的部分其实是昇腾卡的驱动和固件安装。昇腾卡不像英伟达GPU那样装个驱动就完事儿。它需要装好几个组件驱动、固件、CANN工具包还有后面用vLLM时要装的torch_npu插件。关于这些组件的版本我在这里强烈建议不要自己发挥一定要严格按照华为官方文档推荐的版本组合来。我第一次装的时候想着只要版本大方向没错就行结果卡在了一个算子不兼容的问题上。当时那个程序跑起来老是提示算子不支持我排查了好久最后才发现是CANN和torch_npu的版本不匹配。后来我养成了一个习惯把所有组件的版本号都记下来每次部署前先对照官方文档检查版本矩阵。昇腾环境下的版本矩阵是真实存在的不同版本的Ascend驱动、CANN工具包和PyTorch适配层是彼此隔离的组合错一对就会出各种神鬼莫测的问题。装好之后记得验证一下环境是否正常。可以用Python脚本来检查torch_npu是否成功加载显卡是否被正确识别。这一步虽然无聊但非常必要。3.3 离线依赖库的准备在能上网的机器上提前把后面会用到的Python包全部下载好。比如transformers、accelerate、safetensors、sentencepiece、numpy这些都要用pip download的方式存成离线wheel文件。然后把这些wheel文件连同它们的依赖一起拷贝到内网环境里再用pip install --no-index --find-linkswhl_dir 来安装。这个过程我一开始吃过亏。我就光下载了明确列出来的包结果安装的时候发现少了一堆传递依赖一会儿缺XXX一会儿缺YYY装了好久才搞定。后来我学会了一个更花哨的打法用pip download -r requirements.txt -d whl_dir它就会把requirements里所有包的依赖一起拉下来虽然体积会大一些但是省心太多。还有一点镜像源的设置也很重要。在内网环境里你要确保pip不会去连外网不然每次安装都要等超时提示白白浪费时间。可以在pip.conf里设置index-url指向内部镜像源或者干脆加--no-index参数强制本地安装。4. 模型部署与推理优化让大脑先转起来环境准备好之后终于可以进入最核心的一步把模型跑起来。这一步我会结合昇腾卡的实际环境详细记录部署过程和推理优化的经验。4.1 模型下载与转换Qwen2.5-7B-Instruct在HuggingFace上有官方权重但内网环境里显然不能直接下载。常规做法是在能上网的电脑上先把模型下载下来然后转成我们推理引擎需要的格式再拷贝进内网。这里我要补充一个我后期一直在用的小技巧。下载模型时如果网络情况只是普通不建议直接在大模型仓库页面逐个点击下载因为文件很大断点续传也不太行。我通常是用modelscope或者hf_transfer这类工具来下载支持多线程、断点续传速度能快好几倍。模型下载下来之后如果是准备用vLLM跑那权重文件其实已经可以直接用了safe tensors格式基本通用。但如果你的环境里只能用TensorRT-LLM这类引擎那就要额外做模型转换生成TensorRT的引擎文件。这一步会比较耗时也会吃很大的显存建议一次性规划好。昇腾环境下的模型存放路径建议放在一块高速SSD里不要放在机械硬盘上否则加载模型能等得人心态爆炸。4.2 vLLM启动服务与关键参数调优在昇腾环境下启动vLLM服务逻辑跟GPU版类似但有一些独特的参数需要注意。先说我用的一次经典启动命令这里摘出来给你参考python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen/Qwen2.5-7B-Instruct/ \ --served-model-name qwen7b \ --tensor-parallel-size 1 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --trust-remote-code \ --port 8000 \ --host 0.0.0.0 \ --dtype bfloat16简单说明一下这些参数的含义。tensor-parallel-size这个参数在多卡环境里尤其重要希望并行推理时设置为卡数。如果你的卡显存不是特别大可以设置small一些。max-model-len指的是模型能处理的最大上下文长度如果开太大显存占用会飙升所以一般都是结合显存大小来定。我这边就是8K足够覆盖绝大多数业务场景。gpu-memory-utilization是让vLLM尽量用满显存的比例我设成0.9预留一点安全余量防止OOM。有一点必须注意昇腾环境下要确保CANN自带的环境变量正确加载比如source /usr/local/Ascend/ascend-toolkit/set_env.sh这种。然后运行的时候Python解释器要能import torch_npu否则vLLM是没法真正调用昇腾卡的。服务启动之后可以用一个简单的curl命令验证curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d {model: qwen7b, messages: [{role: user, content: 你好做个自我介绍}]}。如果这个请求能正常返回结果说明模型已经跑起来了。这一步我建议先用一个简单的对话测试再用Function Calling的请求测试看看模型能不能按预期的JSON格式返回工具调用指令。4.3 推理性能调优心得模型跑起来只是第一步性能好不好直接决定了上线之后用户体验怎么样。在昇腾环境里有几个调优的心得我觉得非常值得分享。第一个是关于并发和吞吐。vLLM的continuous batching机制天然处理得还算不错但前提是你得把max-num-seqs这类参数调好。并发用户多的话这个值可以适当调大不过我经验里也不能过猛调太高的并发调度反而会增加调度开销拖慢单请求延迟。具体还要靠压测数据说话。第二个是KV Cache和显存的比例。gpu-memory-utilization设成0.9之后并不意味着模型会把所有显存都用于KV Cache。实际生产里如果你还想留点显存放其他的小模型或者做别的任务可以适当降下来改成0.8甚至0.75。第三个是关于dtype的选择。昇腾环境里bfloat16的支持情况会比常规CUDA差一些需要一定版本才能支持。如果是早期不支持的话可以用float16不过精度会略低一点点问题不大。我压测用的工具是简单的Locust脚本模拟几十个用户同时提问监控请求延迟和吞吐量。通过这些数据我再反过来调整并发参数直到达到一个相对稳定的平衡点。模型推理是整个系统里最容易被压垮的瓶颈这一步多花点时间是值得的。5. Agent应用开发把大脑接上手脚模型能跑起来算是有了“大脑”。接下来要做的事情就是给这个大脑接上“手脚”——也就是围绕它构建一整套Agent应用。5.1 设计工具注册与Function Calling我构建的第一个核心模块就是工具注册与Function Calling。这个设计可以理解成把Agent能做的事情都登记在一个“菜单”上模型根据用户的问题从菜单里挑选合适的“菜品”来“点单”。具体实现上我维护了一个名为ToolRegistry的类。每个工具都由一个名称、一段自然语言描述、以及一个具体的执行函数组成。工具描述写得越具体模型就越容易在合适的场景下选中它。我一开始写的工具描述太简略导致模型经常选错工具后来我把描述扩写详细加上了使用场景和参数说明效果马上就好了很多。当模型决定调用某个工具时它会按照我定义好的输出格式返回一个包含工具名称和参数的JSON。于是我的执行逻辑就开始工作读取JSON从注册表里找到对应的函数把参数传进去执行然后把结果拼成一条新的消息连同用户的原始问题一起再发给模型继续推理。这里有个需要注意的细节工具返回的结果最好不要太大。如果返回的是一个超大JSON或者特别长的日志模型很难从中抽取出关键信息还会白白消耗上下文窗口。解决办法是在工具执行完成后做一次结果摘要只保留核心的关键结论再交给模型。这个细节在实际使用中能显著提升Agent的表现。5.2 记忆与上下文管理机制Agent的第二个重要模块是记忆。如果没有记忆Agent每次对话都是“失忆”状态用户之前说过什么它一概不知。这样很多多轮任务就完不成。我的方案是把记忆分成两层。一层是短期记忆对应的是对话历史。使用vLLM的上下文窗口把所有历史消息都塞进去。当然这些消息往往超过上下文窗口因此还要做个整理比如只保留最近几轮对话把更早的内容总结成一段摘要再放进去。另一层是长期记忆关系到知识库。把私有文档灌进Milvus用户提问时从Milvus里检索与问题最相关的片段再拼到上下文里让模型参考这些片段去回答。这些片段相当于模型的记忆碎片每次丢进去几个相关的不用太多否则也会造成干扰。Milvus的检索需要用到Embedding模型我选了bge-m3这个模型在国内开源Embedding模型里综合表现靠前主要是中文能力和泛化能力都不错。部署Embedding模型可以单独起一个小服务不需要很高的显卡配置CPU推理也能用速度慢一点但也能接受。5.3 沙箱代码解释器这一节我要重点说说代码解释器Code Interpreter。这个东西太重要了。如果没有它Agent只能做一些文本处理一旦需要计算、数据分析、生成图表它就完全没辙。有了代码解释器Agent可以在沙箱里生成并运行Python代码完成各种数据处理任务。我采用的是Docker沙箱方案。为每个用户的执行请求创建一个一次性容器容器里预装好Python主流的数据分析库pandas、numpy、matplotlib等。这样即便模型的代码生成得有些脏东西它也只是在一个干净隔离的容器里运行不会影响主服务的安全。这块有一个重要细节安全。你不能让模型在宿主机上直接执行代码万一它生成了一段恶意代码或者执行了危险操就会非常麻烦。所以容器必须做资源限制CPU、内存、超时时间都得设上限。我这边是把超时控制在30秒内超过就会杀掉容器并返回一个超时错误。代码执行完之后沙箱会把stdout输出、运行状态码以及可能生成的图表文件返回。如果生成了图表我让Agent把它转换成base64编码最后在前端展示给用户。这个功能无论是做数据报表还是做运维分析都特别实用。5.4 对话前端与API封装前端界面我走的是极简路线没有用很复杂的框架直接用Gradio搭了一个聊天平台。Gradio最大的优点是上手快写十几行代码就能出一个带聊天界面的WebApp。它还自带WebSocket机制可以实现打字机式的流式输出。对话流程核心是Streaming输出。模型在vLLM返回的是一个流式的token序列我通过FastAPI WebSocket将这些token片段逐字分发给前端。这样做的好处是用户不用干等下一条消息提交之后就能看到正在生成的文字体验会好很多。后端API我统一封装成OpenAI兼容的格式。这样设计的好处是之后如果需要切换模型或者把能力开放给第三方系统只要客户端支持OpenAI协议就能直接对接不至于把整个接口层重写一遍。6. 上线与运维从能用到好用开发完成之后系统还只是“能跑”。距离“好用”和“稳定”中间还要经历上线和运维的考验。这一章我会分享我在实际部署运维过程中积累的经验尤其是企业环境下很看重的稳定性、性能和安全性问题。6.1 Docker化部署与容器编排为了让整个系统能在不同环境里平滑迁移我把所有组件都打成了Docker镜像。模型服务、后端API、向量数据库、前端每个组件都有独立的镜像通过docker-compose统一编排在一台机器上。这里有一个小建议镜像的标签一定要具体加上版本号比如agent-backend:v1.2.0。不要图省事用latest否则几个月后再去看都不知道线上跑的是哪一版代码。这个习惯能省掉很多“事故还原”的麻烦。在昇腾环境的容器化部署里有几个特殊点要处理。一是让容器能访问到昇腾的设备节点。你需要把/dev/davinci*挂载进容器再把CANN的驱动和库文件也挂进去否则容器里是没法识别卡的。二是一些系统环境变量比如ASCEND_VISIBLE_DEVICES也要在容器启动时设置好。编排层面推荐用Docker Compose管理单机多容器。如果将来要跨多台机器做高可用集群再考虑Kubernetes。对于大多数中小规模企业应用Docker Compose完全够用没必要一上来就上K8s运维成本会陡增。6.2 性能监控与日志采集系统上线后性能监控和日志采集是保障稳定性的基石。我的做法是后端每一个关键步骤都打点记录时间戳用户请求进入时间、工具调用耗时、模型推理耗时、输出返回时间。这样定位问题的时候我们就知道瓶颈到底出在哪一个环节。日志方面我采用结构化打印每条日志都是JSON格式包含时间、级别、模块、请求ID和具体消息。这样后续接入ELKElasticsearch、Logstash、Kibana的时候特别方便。请求ID特别重要每个请求都带上这样当用户报问题我们通过请求ID就能把所有日志串起来还原现场。监控面板我用的是PrometheusGrafana。后端服务会暴露一个/metrics端点把请求量、延迟分布、错误率、显存占用这些指标都采集进去。Grafana画几个核心Dashboard比如并发数趋势、P95延迟、工具调用失败率等。每次版本迭代之后盯着Dashboard看几天基本就能判断发布是否健康。6.3 国产化环境下的兼容性坑国产化环境里最大的敌人就是“差一点”的兼容性。我发现了很多莫名其妙的坑这里简单列举。比如某些基础镜像里的glibc版本偏低跑Python应用时落到某个二进制的库就调用不了报错信息还不直观只能靠大家搜索经验。这个情况其实是兜底方案必须下到合适的基础镜像才能解决。再比如一些内置的加密算法在不同系统底层库里的支持不一致某些国产操作系统对国际主流加密套件的支持并不全面导致我们用某些开源库的时候出现异常。以及不同Linux发行版对systemd支持的路子各有偏差不同系统的service管理方式也各有区别。这些坑很难提前预知我几乎都是靠一步步排查搞定的。养成一个习惯部署完每个组件后先单独验证它的基本功能确认没问题后再集成进系统这样定位问题会快很多。一旦系统整体建立一个再出问题排查范围就会很大很容易拖延上线时间。6.4 安全加固与权限管控安全是企业应用的生命线。我在上线前做了一轮安全加固总结了几个重点。首先服务层面所有对外暴露的接口全部走HTTPS证书使用企业内部的CA签发的证书。账号系统接入企业的统一身份认证单点登录不用简单的账号密码。要给AI应用单独设置Key通过API Key管理后台给不同部门分配不同的调用额度。其次针对Prompt注入攻击要做防护。恶意用户可能通过输入特定的提示词试图让Agent绕过约束执行未授权的操作。针对于此我会设计一套系统级提示词把这些系统规则插入到上下文的最前面同时也可以在后端API层过滤掉一部分敏感指令。另外只要用户输入中出现“忽略上述所有指令”之类的危险句型我会和像“防火墙”一样拦截掉。最后是数据安全。支持对话数据落库同时对敏感字段做脱敏处理。由于部署在内网很多企业可能低估了数据安全风险但我建议还是按照等保三级的标准去设计规范尽量做到“谁的对话谁能看”。这一块对Agent类应用尤其重要因为它可能接触到大量的内部文档和用户数据权限设计一旦不到位后果会很严重。7. 效果验证与体验优化系统部署完之后整个架构基本完整了。但从“能跑”到“好用”还需要对效果做细致的验证和体验优化。这一章我想分享一些实际测试的结果和方法给你一些参考。7.1 真实业务场景效果验证完成基本开发后我用一个比较贴近业务实际的场景专门做了一次效果验证知识库问答加数据图表分析。具体来说我向Agent上传了一份销售数据报表咨询它“上个季度的销量趋势如何哪个地区增长最快帮我画一张图”。Agent的执行步骤非常清晰。它先解析我的意图确认需要调用代码解释器接着在沙箱里读取CSV文件计算出各地区的销量统计和环比增长率生成了一张柱状图。最后它借助上下文里的数据组织了一段总结文字把“哪个地区增长最快”答得明明白白。整个过程大概花了20秒模型推理的时间占了80%以上工具的调用基本上是在秒级完成的。从结果来看这份报告已经接近一个初级数据分析师的工作产出这对我的这套系统来说已经是一个合格的开局了。让我更惊喜的是Agent的多轮协作能力。它能记住我前面上传的是销售报表当我继续追问“那华东区呢”的时候它不需要我提供文件自动结合上下文和数据结果给出了华东区的详细分析。多轮交互的能力让这个系统可用性大幅提升用户真的觉得它在“记住我”、“理解我”。7.2 延迟优化和体验提升在效果有保障的基础上我考虑优化整个交互的体感。最明显的痛点是首次响应延迟和模型首字生成速度。vLLM的流式返回机制解决了一部分问题因为第一个token返回之后用户就开始看到文字主观等待时间缩短不少。为了进一步压这个指标我做了几个调整。一个是在后端加了缓存。对于一些高频的、结果相同的请求比如介绍类问题、固定格式的报表查询我们可以配置语义缓存把用户的请求文本做Embedding在向量数据库里查一下如果和之前的某条请求相似度很高就直接用缓存结果回答。这样可以显著降低模型压力也能让响应时间从秒级降到毫秒级。另外就是模型本身的选择。对于一些简单的意图识别和路由我用上一个轻量级的文本匹配模型可以直接判断用户是闲聊还是需要工具调用这样可以省去大模型的大部分无谓计算。主模型则只处理真正需要推理的任务整体资源利用率就上来了。8. 踩坑记录那些让你怀疑人生的瞬间写到这里我觉得有必要单独开一章记下我在这个过程中遇到的几个最典型的坑。它们不是技术难点可能就是你上网搜了很久也搜不到的那种问题但往往会卡住你很久。8.1 vLLM启动报错的“祖师爷级”问题我刚装好vLLM环境时运行启动命令立刻报出一大堆错有些看都看不懂。我总结了几个最常见的原因。第一种是torch_npu和CANN的版本不匹配这个是非常大概率的事情。解决方案就是严格按照官方文档的版本矩阵重新安装不要自以为是。第二种是环境变量没设置完全。昇腾环境需要一堆环境变量比如ASCEND_HOME、ASCEND_TOOLKIT_HOME还有LD_LIBRARY_PATH里要包含CANN的lib目录。这些变量一旦少了vLLM启动时就会报找不到库文件或无法识别设备的错误。第三种是Python版本问题。昇腾的CANN工具包对Python版本有严格限制一般支持3.7、3.8、3.9。如果系统自带的Python版本太高或太低都会有很奇怪的报错。建议创建虚拟环境把Python版本调整到CANN适配范围内。8.2 pip依赖地狱国产化环境里没有网对pip依赖的处理要格外谨慎。我第一次离线部署时只下载了requirements文件里一个个列出的包结果安装到一半报错说缺少某个传递依赖。于是又开始“单点补包”下载一个装一个装一个再报错一个来来回回十几轮人都麻了。最稳妥的做法是用pip download加-r requirements.txt把整个依赖树一次性下载下来。同时要求开发环境和部署环境的Python版本、操作系统架构要一致。否则你在这台机器上打包的依赖到另一台机器上可能装不了因为有些编译后的包是绑定平台架构的。8.3 向量数据库的Embedding模型选型第一次用向量数据库时我的Embedding模型选择的是一个小语种的多语言模型实际效果却不理想。原因是模型对中文支持不好中文检索的召回率特别低几乎等于没法用。后来换了bge-m3之后效果就立马上来了。这里我的经验是面向中文场景一定优先考虑中文表现好的Embedding模型比如bge系列、m3e系列等。另外做Embedding的时候给文本加一个合适的指令前缀比如“为这个句子生成向量以用于检索相关文章”能明显提升检索效果这是个被很多人忽略的细节。9. 写在最后的优化建议整个项目从前期环境考量到模型部署再到Agent应用的开发和改造最后走到运维上线过程中的每一步都有很多值得复盘的细节。我最后想说的是国产化环境下的Agent开发门槛更多是在于对整个环境的熟悉程度而不是模型技术本身的深度。9.1 先在小规模业务场景里验证我建议第一次做这类项目先选择一个小而具体的业务场景。比如做一个部门级的知识库问答机器人或者一个自动化报表分析助手。这样覆盖的范围不大数据量不大对硬件的要求也相对较低试错成本可控。做一个全功能的大而全的智能体会让开始的难度成倍提升。你可能会陷入“什么都在做什么都没做好”的糟糕境地。9.2 重视结构化数据的价值在项目迭代的过程中我发现一个很值得注意的经验Agent能力提升的重要源泉不只是模型的参数还包括数据的结构化和工具的质量。很多企业内部大量的数据和文档都是杂乱无章的PDF、Word、Excel如果直接丢给模型做RAG检索增强生成效果往往不太好。这时候可以投入精力去做数据清洗、数据抽取和结构化。比如把PDF转成Markdown把Excel转成易于检索的CSV格式再配合合理的索引设计知识库的查询质量和回答准确率会上升一个层次。这件事虽然琐碎且不性感但带来的效果提升幅度远比换一个大模型来得快。9.3 持续跟进开源社区和版本迭代国产化AI生态还有很大的迭代空间昇腾、寒武纪这些厂商适配的框架和模型都在快速更新。建议每隔一段时间关注一下你用的那几个核心组件有没有新的版本有没有新的优化。升级之前一定要仔细阅读官方文档中的版本变更日志和兼容性说明先做好充分的测试再上生产。我的经验是多花一点点时间在环境维护和技术更新上比一直“守着老版本不动”要安全得多。老版本太老会累积很多已知的问题版本太新可能踩不兼容的坑新的生态里这个问题格外明显。最后我还是想强调一遍那句话国产化环境不是“降级”环境而是一套有着自己玩法的生态。耐心、细心、好心态这三样东西比任何技术技巧都重要。希望我的这些经验能成为你的垫脚石让你少走几段弯路。