做端侧Agent有个特别现实的问题你的Agent逻辑写得再完整工具定义得再清晰最后卡住性能的往往就是模型这一层。上一篇文章聊了端侧Agent的整体架构与任务编排这篇我把“端侧LLM部署”单独拆开完整走一遍从模型选型、量化、推理框架到接入Agent的路径。整篇文章基于我最近在RK3588开发板和Jetson Orin上部署Qwen系列模型的实际经验主要解决三个问题模型放本地跑到底需要什么硬件、选多大的模型才不拖Agent后腿、怎么把本地模型接到Agent的规划与工具调用流程里。内容适合两类人一类是正在做端侧Agent原型、被云端接口延迟和费用折磨的开发者另一类是手里有开发板、想跑通一套完整LLM服务的嵌入式玩家。读完你能直接照着我这套流程在自己的设备上落地一个可调用的本地LLM服务并且知道哪些坑可以提前绕开。1. Agent为什么非要在端侧跑LLM先说个我踩过的典型场景做一个基于视觉输入的智能助手Agent需要先识别用户拍的图片内容再决定调用OCR还是检索知识库最后组织语言回答。如果所有请求都走云端LLM一次完整任务要经历“录屏上传、云端推理、结果返回”三个来回实测延迟在1.5到3秒之间波动。对交互型Agent来说这个延迟会让用户感觉系统“没反应”体验非常糟糕。把LLM放在端侧之后首token延迟降到200到400毫秒整条Agent链路的响应速度才真正能用。除了延迟端侧部署还有一个容易被忽视的优势数据不出设备。我做医疗文本处理的Agent时用户的病历摘要、检查报告这类敏感数据如果走云端API即使有隐私协议客户也天然不放心。端侧LLM配合本地向量库和本地工具调用敏感信息完全不需要离开设备这个对B端项目是决定性的加分项。成本账也值得算一笔。云端大模型API按token计费一个Agent任务平均消耗3000到5000 token如果并发量做到每天一万次请求月成本轻松破万。端侧部署一次性投入硬件成本后续推理费用趋近于零对固定设备、固定场景的项目来说长期账绝对划算。不过端侧跑LLM不是没有代价。模型参数规模受限、上下文长度受限、推理吞吐量受限这三大约束决定了端侧Agent的设计思路和云端完全不一样。云端可以轻松加载70B模型处理几万token的上下文端侧通常只能在1.5B到8B的模型范围内选择上下文长度也常常需要限制在4K到8K以内。这种限制直接倒逼Agent架构做减法能本地规则解决的就不调模型能用检索解决的就不塞上下文能分步处理的就不要让模型一次消化太多信息。2. 方案选型模型、量化、框架与硬件怎么搭端侧LLM部署第一个要面对的问题就是选模型。我测试过几个主流方案实际效果差异非常明显。Qwen2.5系列是目前端侧的性价比首选。1.5B版本谦虚一点说足够做意图识别、工具调用和简单问答3B版本是综合性能和资源占用最均衡的选择能承担结构化输出和整体推理7B版本在智商上明显提升但对内存和算力的要求也水涨船高。Phi-3系列体积小巧、小模型能力突出但中文能力相比Qwen偏弱更适合英文场景。Llama 3.2系列的社区生态好但同样存在中文表现力一般的问题。我个人的建议是中文场景优先Qwen2.5英文工具类优先Phi-3或Llama 3.2。模型大小确认了接着要处理的就是量化。把FP16的模型权重压到4bit甚至更低位是端侧部署的关键一步。量化方案我推荐两个GGUF格式配合llama.cpp系列工具适合CPU和混合推理AWQ或GPTQ适合有较好GPU加速的环境。实际使用中Q4_K_M量化级别是端侧部署的甜点它能在把模型体积压到FP16的四分之一左右的同时保持相对可用的生成质量。Q8效果更好但体积接近翻倍Q2和Q3体积更小但效果下降明显我自己实测Q2级别的生成结果经常出现语义漂移用在Agent流程里非常危险。量化之后的内存预算有个粗算公式量化后模型体积 ≈ 参数量B× 0.6GB。以Q4_K_M量化为例1.5B模型约1.4GB3B模型约2.4GB7B模型约4.2GB。这还只是权重部分推理时还需要额外分配KV Cache内存。KV Cache的估算公式是2 × 层数 × 注意力头维度 × 上下文长度 × 单元素字节数。拿Qwen2.5-3B-Instruct举例它36层、40个注意力头、每头维度128上下文开2048bf16精度下KV Cache大约是2 × 36 × (128 × 40) × 2048 × 2字节算下来约720MB。所以部署3B模型的Q4版本至少准备3GB可用内存加上操作系统和Agent其他进程的开销设备的可用内存最好不低于8GB。推理框架方面我的选择逻辑很简单原型阶段用Ollama产品化阶段用llama.cpp二次封装或MLC-LLM。Ollama是llama.cpp的封装有OpenAI兼容API命令简单适合快速验证。llama.cpp本身就是底层的C实现支持GGUF、CPU/GPU混合推理可控性强适合嵌入到自己的服务进程里。MLC-LLM基于TVM编译优化支持ARM CPU、Metal、CUDA等多种后端跨平台能力强适合做移动端或嵌入式产品的正式集成。vLLM在服务端是神器但它的显存占用和调度模型是为大吞吐设计的在单机单用户的端侧场景反而笨重。最后还有一条路线是用ExecuTorch或PyTorch Mobile适合和PyTorch生态紧密绑定的项目但配置成本偏高不是首选。硬件这块我实际测试过的平台能给出直观参照。RK3588是性价比非常高的选择8核ARM 6 TOPS NPUNPU跑量化模型性能尚可但NPU工具链目前对LLM的支持还不完善多数人用它的CPU跑llama.cpp实测3B模型Q4量化后跑出7到9 token/s的生成速度对交互要求不高的Agent够用对流畅对话就差些意思。Jetson Orin Nano 8GB版本GPU算力出色配合llama.cpp的CUDA后端跑7B模型Q4量化能到25到35 token/s体验好很多但功耗和体积都大得多。苹果M系列芯片跑MLC-LLM的Metal后端小模型能达到50 token/s以上是目前端侧体验的头部水平。高通和联发科阵营更多依赖NPU和专用SDK能做但踩坑成本高除非团队有深度优化人力否则不建议一开始碰。3. 实操从零搭建一个可调用的端侧LLM服务说再多选型和原理不如直接动手过一遍完整流程。我以RK3588开发板上用Ollama部署Qwen2.5-3B为例子因为这套组合最贴合多数人手上的端侧硬件而且步骤通用性很强Jetson或者x86小主机上的操作大同小异。3.1 环境准备与Ollama安装第一步确认系统环境。我用的是Ubuntu 22.04ARM64架构。开发板内存建议8GB起步我实际测试16GB版本跑3B模型很从容。系统装好后先更新软件源然后安装curl和基础工具sudo apt update sudo apt upgrade -y sudo apt install curl git vim -y接下来安装Ollama。官方提供了一行安装脚本但开发板网络环境可能不太稳定建议先下载安装脚本看一下内容再执行curl -fsSL https://ollama.com/install.sh | sh如果官方脚本下载慢直接去Ollama的GitHub Releases页面手动下载对应架构的二进制包安装。安装完成后通过systemctl状态确认服务在跑systemctl status ollama这里有个细节Ollama默认只监听127.0.0.1如果你需要让局域网内其他设备访问这个推理服务得修改环境变量OLLAMA_HOST0.0.0.0。这个在调试Agent端到端流程时很关键因为你的Agent程序可能跑在另一台机器上。3.2 拉取量化模型并验证可用性确定模型标签非常关键。Ollama的模型仓库里同一个模型有多个tag其中带q4_K_M后缀的就是量化版本。我使用的命令是ollama pull qwen2.5:3b-instruct-q4_K_M如果仓库里tag命名有出入可以执行ollama list查看已安装模型、访问模型页面看tag列表或者直接用默认标签让Ollama自动选择。拉取完成后先做一次快速验证直接对话式测试ollama run qwen2.5:3b-instruct-q4_K_M输入“你好做一个简短的自我介绍”看响应是否流畅、中文是否准确。接着再跑一个稍微复杂的任务例如“列出5种端侧部署大模型的优势并排序”考察模型的逻辑能力。这一步别跳过很多模型表面正常、一到复杂指令就崩提前发现问题能省后面调试的力气。服务本身通过OpenAI兼容的HTTP接口提供能力。默认跑在11434端口用curl确认接口可用curl http://localhost:11434/v1/models看到模型列出来说明服务已经就绪。顺手测一个完整的对话请求curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5:3b-instruct-q4_K_M,messages:[{role:user,content:用一句话说明端侧部署的价值}]}返回JSON里带着生成文本和时间统计这个就作为后续性能对比的基线数据。3.3 用OpenAI兼容接口对接AgentOllama的OpenAI兼容接口有一个巨大的好处Agent代码里的大模型调用部分可以完全复用云端API的逻辑只需要把base_url从OpenAI的地址换成http://localhost:11434/v1即可。这意味着你之前对接ChatGPT或GPT-4写的Agent代码改动个配置就能切换到大模型端侧运行。我自己写Agent时用的是Python的openai SDK切换起来是这样from openai import OpenAI client OpenAI( base_urlhttp://localhost:11434/v1, api_keyollama # Ollama不校验key随便填 ) response client.chat.completions.create( modelqwen2.5:3b-instruct-q4_K_M, messages[ {role: system, content: 你是一个端侧设备管理助手负责调用工具完成用户指令。}, {role: user, content: 帮我查一下设备当前的内存使用情况} ], temperature0.3, max_tokens256 ) print(response.choices[0].message.content)注意temperature不要设太高我用0.2到0.3Agent任务需要确定性温度太高会导致工具参数乱变。max_tokens也根据你的任务类型灵活调整简单指令128到256足够复杂分析任务可以放宽到512。这里有个我反复踩坑的细节端侧小模型对system prompt的理解能力弱于云端大模型。同样的指令GPT-4读一遍就完全理解Qwen2.5-1.5B可能要你把指令拆成更直白的短句。我的经验是system prompt控制在一段话以内工具描述用“当用户想做什么时你应该调用哪个工具传入参数是什么”这种具体句式不要用“请根据上下文合理选择”这类模糊指导小模型真的会帮你随便选一个。3.4 让模型学会调用工具Agent和普通问答的最大区别就是工具调用。Qwen2.5系列本身支持function calling格式的微调在Ollama里可以通过tools字段实现但端侧模型对复杂工具调用的准确率还需要实测验证。我是这样测试的定义一个查询天气的模拟工具工具声明里有两个必填参数city和date用openai SDK的tools参数传入让模型自行决策是否调用tools [ { type: function, function: { name: get_weather, description: 查询城市在指定日期的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名}, date: {type: string, description: 日期格式YYYY-MM-DD} }, required: [city, date] } } } ] response client.chat.completions.create( modelqwen2.5:3b-instruct-q4_K_M, messages[{role: user, content: 看一下北京明天天气}], toolstools, tool_choiceauto, temperature0.2 )返回结果里如果带了tool_calls字段说明模型正确识别需要调用工具如果模型直接生成了一段文字回复就说明它没理解工具协议需要调整prompt或者换更大的模型。实测下来Qwen2.5-3B在单工具场景的调用准确率还行多工具、多参数场景就明显吃力。我的3B实测多工具场景准确率约70%左右1.5B则基本只能处理最简单的一参工具。如果你的Agent流程比较复杂务必以7B为优先考虑。另外还有一个技巧把多个同类型工具合并为一个工具用参数区分行为比让模型在十几个工具里选一个更可靠。比如不要设计get_weather_by_city和get_weather_by_gps两个工具合成一个get_weather内部用location_type区分。4. Agent接入LLM的上下文组织与结构化输出端侧模型上下文短如何组织Agent和模型交互时的上下文就变成了一个硬功夫。很多端侧Agent跑得慢、输出乱根本原因不是模型不行而是上下文没管理好。4.1 Context裁剪与Token预算分配端侧LLM的上下文窗口通常只有4K到8K token换算成汉字大约3000到6000字。Agent在对话过程中会积累系统提示、历史消息、工具返回结果很快就能撑爆窗口。所以我在设计端侧Agent时专门设计了一套上下文裁剪机制。预算分配上我习惯把4K窗口这样划分system prompt加工具描述占600 token当前用户问题占300 token工具返回结果最多占500 token剩余空间留给历史消息和模型输出。当历史消息超过预算时优先丢弃最旧的消息但一定要保留系统提示和最近的用户意图。这个裁剪动作不能只在消息数量层面计算要真正确切地按token数控制我直接用tiktoken或transformers的tokenizer算了再截断比凭感觉砍消息靠谱很多。def trim_history(messages, max_history_tokens1600, tokenizerNone): history [] current_tokens 0 for msg in reversed(messages[:-1]): msg_tokens len(tokenizer.encode(msg[content])) if current_tokens msg_tokens max_history_tokens: break history.insert(0, msg) current_tokens msg_tokens return history [messages[-1]]4.2 结构化输出让结果一次就能用端侧模型直接输出自由文本结果很难直接当程序里的数据用比如Agent需要模型给出“是否调用某个工具”以及“调用参数”时如果没有约束模型会答非所问。解决思路是用约束解码或者二次解析。二次解析是我常用的方案先给模型一个明确的输出模板然后用正则或JSON解析器去提取字段解析失败就重试一次。比如要模型判断用户意图我会在prompt里写“只输出JSON对象{intent: xxx, tool: xxx, params: {}}”然后代码里用json.loads解析。实测下来Qwen2.5系列对JSON格式的遵循效果在端侧模型里属于上层但偶尔还是会输出多余的解释文字。这时我会写一个小的修复函数尝试直接解析JSON失败就用正则截取从第一个{到最后}的子串再次解析再失败就调用模型重新生成。还有更彻底的做法是用llama.cpp自带的grammar约束功能直接在采样阶段限制输出只能符合指定的JSON Schema。这种方式生成的JSON几乎不会解析失败但对复杂schema的支持和模型的配合度还需要调适合在正式产品里用原型阶段用解析加重试就够了。4.3 让多个Agent任务共享一个LLM服务的并发考量端侧Agent不太可能是单个请求一个模型进程往往是多个Agent任务共享一个本地LLM服务。Ollama默认支持并发请求处理但端侧硬件性能有限同时来了多个请求每个请求都会被拖慢甚至排队。我在Jetson上实测过两个Agent同时调用7B模型每个任务的生成速度几乎减半。我的做法是在Agent调度层做请求串行化Agent框架内部用一个请求队列同一时间只向LLM服务发送一个推理请求其他请求排队等待但每个请求内部可以设置超时时间。这样做的好处是每单次推理的延迟是可控的不会因为并发导致局部卡死缺点是总体吞吐量有限。对端侧Agent来说单设备通常也就是服务于一两个用户这种串行策略完全够用。如果确实需要并发硬件方案是第一优先的Jetson Orin系列或者Mac Mini这样算力更强的端侧主机才是出路软件层调整已经很难弥补算力不足。硬件的投入在这些场景里一定要算进项目预算不要指望软件优化能无中生有。5. 端侧LLM部署的性能调优与问题排查部署只是一半运行稳定、性能达标才是另一半。这一节我把实测过程中遇到最多的问题整理成一份速查参考每一项都给出了排查思路和解决办法。5.1 推理速度不达标怎么定位瓶颈端侧LLM慢先问一句慢在“首token时间”还是“生成速度”这两者的优化方向完全不同。首token时间主要受模型加载和预填充速度影响。模型加载慢用Ollama时可以在启动后先发一个空请求把模型预热到内存里或者用ollama serve直接常驻服务。预填充阶段是Prompt长度越大就越慢这里的加速重点是缩短Prompt长度和开启flash attentionllama.cpp编译时加GGML_CUDA_FA_ATTENTION或运行时开--flash-attn。生成速度主要受每秒token数和上下文计算量影响。先做一次速度基线测试用之前整理的curl命令连续发10次请求记录耗时取平均值。如果生成速度在10到20 token/s区间Agent做简单对话没问题做复杂任务就吃力低于5 token/s基本不可用。提升生成速度的手段有限最有效的是换更小模型或者降低上下文长度另外一个容易被忽略的点是线程数设置。Ollama可以通过环境变量OLLAMA_NUM_THREADS控制使用的CPU线程数开发板默认值不一定是系统最优我测过四核A76加四核A55的RK3588跑推理时全部用上性能核比默认调度快了接近30%。另一个关键点是CPU vs GPU/NPU的负载分配。llama.cpp可以通过--main-gpu和--tensor-split把不同层分配到不同设备。我在Jetson上把大部分层放到GPU、一部分层留CPU实测比纯GPU模式内存压力小、生成速度没有明显下降。5.2 内存不足与上下文爆炸端侧部署最常见的问题是进程崩掉或者系统卡死几乎都是内存不够。排查标准流程先看模型权重占了多少再看KV Cache占多少最后看其他进程占用多少。KV Cache是上下文长度的线性函数上下文开得越大KV Cache就越大。我的建议是Agent场景先把上下文限制在2048或3072不要贪长。长上下文在端侧不仅吃内存还会拖慢预填充速度和生成速度。如果确实需要长历史对话可以引入外置记忆方案用文本摘要提取对话要点存下来而不是无限往上下文里塞。Ollama还有一个配置项OLLAMA_MAX_LOADED_MODELS默认最多同时加载多个模型。端侧设备内存有限把它设为1强制同一时间只保留一个模型在内存里避免频繁换入换出降低性能。5.3 量化损失与输出不稳定端侧模型用Q4量化后输出质量确实有损失这是绕不过去的物理规律。我的经验是不追求极端小体积Q4_K_M就是质量和体积的平衡点。如果做专业领域任务发现效果崩了先上Q8量化对比测试一把如果Q8效果达标就能接受如果Q8都不行说明模型本身能力不足以胜任任务换更大的模型是唯一出路。工具调用不稳定是量化陷阱的高发区。模型生成参数的格式不对、参数值残缺、工具名写错都会让Agent流程走不下去。我的补救方式是加一层“工具调用校验器”模型输出工具调用后先做schema校验不通过就把错误信息拼回提示词让模型重新生成一次。多数情况下第二次生成的结果能修正问题。最后给一个建议端侧模型的能力边界是真实存在的别用架构技巧去硬扛模型能力的短板。如果Agent任务的复杂度已经让模型频繁出错果断升级模型规模或硬件配置比在软件层不断打补丁靠谱得多。我自己就在一个项目里从1.5B换到7B一次切换省掉了后续无数适配问题。6. 端侧LLM部署的经典实践组合整套流程走下来其实可以提炼几套直接可用的组合方案。按项目预算和场景需求分一档参考这个表能少走不少弯路场景硬件模型量化框架预期性能入门原型验证RK3588 / 8GB内存Qwen2.5-1.5BQ4_K_MOllama10-15 token/s标准Agent产品RK3588 / 16GBQwen2.5-3BQ4_K_Mllama.cpp自封装7-10 token/s高要求Agent产品Jetson Orin 8GBQwen2.5-7BQ4_K_Mllama.cpp CUDA后端25-35 token/s高品质交互体验Mac Mini M系列Qwen2.5-7B / Llama3.2-8BQ8MLC-LLM40-60 token/s移动端嵌入手机/平板骁龙8系/天玑9系Qwen2.5-1.5BAWQML C-LLM15-30 token/s这套组合里值得多说一句的是不要把“端侧”理解成一定是移动设备或开发板桌面级小主机、MiniPC跑本地模型同样属于端侧部署的范畴。端侧的核心是私有化和低延迟不排斥相对较强的算力平台。在实际项目选型中我的判断顺序是先跑通一个基准测试明确任务需要的最低模型能力再用一个略强一点的模型跑确认性能边际收益最后按产品质量要求和硬件预算取平衡点。整个过程控制在半天内完成避免在选型上反复纠结。7. Agent与端侧LLM的协同经验总结把模型部署好之后真正的工程挑战才刚开始。Agent在使用端侧LLM时有几个协同习惯是我强烈建议养成的。端侧LLM不是万能的它适合承担明确的、局部的推理任务。复杂的规划应该在上层完成。我的Agent架构里任务规划器本身就跑在端侧LLM上但我会把任务拆分逻辑写在提示词和流程控制代码里模型只做“理解当前步骤、选择下一步动作”的工作。这样模型犯错的概率小很多任务稳定性和可调试性也好很多。任务拆分到大模型无法胜任时混合架构是务实选择。有些场景确实需要大模型能力例如复杂文档的理解、创意文本生成。我的方案是“端侧为主云端兜底”优先走端侧模型当端侧模型返回结果的置信度低或者工具调用连续两次校验失败时自动把请求转给云端API。这样做既控制了大部分请求的成本和延迟又保证了关键任务的兜底可用性。模型加载与硬件之间的调度也值得投入精力。一个端侧设备如果同时运行多个服务最好把LLM推理进程的CPU亲和性绑定到特定性能核其他任务分配到不同的核心避免相互干扰。这个在Linux开发板上用taskset命令就能实现操作成本低、收益明显。回看整个端侧LLM部署的历程最大的体会其实是端侧部署远不是“下载个模型跑起来”这么简单它是一个横跨模型选型、资源预算、推理优化、Agent协作的交叉工程。真正决定项目成败的往往是最不起眼的一个参数设置、一条上下文裁剪规则、一次量化级别的权衡。这篇内容里的方法和数据都来自我自己的实测希望能给你的端侧Agent项目节省一些试错时间。拿不准的地方按我建议的基准测试流程先跑一遍硬件和模型的匹配度很快就能看明白。