做端侧Agent的朋友大概率都经历过这个阶段功能设计文档写得漂漂亮亮工具链、编排引擎、任务队列全部就绪结果模型一部署就卡住。我第一次在Jetson Orin上跑一个满血7B模型跑是跑起来了一次工具调用要等十几秒多轮对话里模型开始“失忆”。后来我才意识到问题根本不在Agent框架而在端侧LLM部署这个环节没有做透。这篇是“深入理解端侧Agent”系列的第二篇专注端侧LLM部署。内容覆盖选型逻辑、量化策略、实测数据、Agent任务改造、并法处理等关键问题。适合已经在做或准备做端侧Agent的工程师也适合想搞明白本地部署大模型到底有哪些坑的朋友。1. 端侧Agent为什么绕不开“部署”这道坎1.1 先看清端侧Agent的三种典型形态端侧Agent不是一个抽象概念它落地之后基本就三种形态。第一种是手机上的个人助理。手机有NPU、有统一内存能跑1B到3B的模型负责日程管理、信息摘要、快捷指令执行。这类Agent对延迟最敏感用户点一下按钮模型得在几百毫秒内给出反馈多等一秒都是灾难。第二种是机器人或智能硬件比如Jetson Orin驱动的巡检机器人、RK3588驱动的商用服务终端。这类设备相对不那么在意“瞬时反应”更看重稳定性和离线能力很多场景要求断网也能干活。第三种是边缘计算盒子放到门店、工厂、医院里做本地推理跟云端服务配合只把必要的数据上行。三种形态的共性是都需要一个能本地跑、能持续运行、能被Agent框架调用的LLM。共性的背后就是端侧LLM部署这个共同难点。很多人的误区是“端侧部署就是把模型塞进设备里能出结果就行”。实际远没那么简单。模型权重只是第一步后面还有推理框架选择、量化、上下文管理、输出结构化、功能调用、并发调度每一层都可能让一个看起来能跑的Demo变成不能用的玩具。1.2 云端模型已经很成熟为什么还要端侧部署会用云端Agent API的人肯定有一个疑问既然GPT和Claude级别的模型都在云端速度又快效果又好为什么还要在开发板上折腾一个“缩水”的本地模型我觉得核心原因是三个字延迟、隐私、成本。延迟是物理层面的。无论网络多好一次云端请求的链路至少是端侧采集数据→网络传输→云端排队→模型推理→结果回传。实测下来一个中等复杂度的Agent任务云端来回至少1到2秒而在端侧如果模型和框架调得好同样的任务只需要300到500毫秒。对机器人避障、语音交互这类实时场景这个差距是决定性的。隐私不用多说。医疗、金融、工业控制这些领域数据出不了内网本地部署是硬性合规要求。我做过一个医院场景的Agent病历数据根本不允许离开院内服务器云端方案直接出局。成本则是隐性但长期存在的。每天跑几百万次云端推理调用账单会非常难堪。当Agent需要高频轮询、多轮反思、持续观察时云端推理次数会呈指数级上涨。把高频低难度的子任务放到端侧是一个很务实的省钱策略。1.3 能跑和能用之间隔着哪些实际问题“能跑”的标准很简单模型加载成功输入一句话能吐出一个回答。“能用”的标准要残酷得多连续运行一周不崩、工具调用格式100%稳定、上下文用完时知道怎么处理、并发请求时不把设备卡死。这中间的差距就是我写这篇文章想展开的内容。先说显存和内存。端侧设备的内存本就有限而LLM除了模型权重还要吃一块很大的KV Cache。7B模型Q4量化后权重约4GB但如果你给它一个8K的上下文KV Cache又要吃掉接近1GB。设备内存一旦不够系统就会走swap速度断崖式下跌。再说推理速度。模型能跑CPU推理也能出结果但端侧Agent需要的是“实时反馈”。一个Agent任务通常包含多轮推理模型先思考要调用什么工具再根据工具结果生成下一轮计划这中间可能产生5到10次推理调用。单次推理慢3秒整个Agent任务的响应就到了30秒完全不可用。还有输出稳定性。云端大模型因为参数量大、训练数据丰富生成JSON或特定格式的文本非常稳定。端侧小模型则经常出现JSON截断、字段丢失、把工具名称拼错的问题。这个坑我在后面专门用一节来拆。所以端侧LLM部署做的不是“装环境”而是对整个推理链路做系统性调优。2. 硬件与推理框架选型一次踩坑后的对比总结2.1 端侧硬件平台的真实定位这块我不讲参数表直接讲我自己的实测感受。NVIDIA Jetson Orin系列是我用下来最适合做Agent开发的平台。Orin NX 16G能跑7B模型Q4量化Orin Nano 8G跑3B非常流畅。它有CUDA生态几乎所有的推理框架都优先支持而且统一内存设计省去了显存拷贝的开销。缺点是功耗偏高开发板价格也不便宜不适合做大规模消费级产品。RK3588是国产开发板里很常用的选择8核CPU加6 TOPS的NPU跑YOLOv8这类CV模型非常快但跑LLM就得靠CPU和NPU协同。我在RK3588上部署过3B模型速度勉强能接受7B就非常吃力了。如果你的项目还需要同时跑视觉任务比如检测、识别那RK3588的NPU优势就体现出来了。手机和平板端则是另一套逻辑主要依赖高通、联发科、苹果的NPU。这个方向我接触不多但可以确认的是1.5B以下的模型在手机上表现不错再往上就需要收敛到特定芯片。下面这个表格是我个人偏好的选型参考硬件平台适合的模型规模主要优势主要限制推荐场景Jetson Orin Nano 8G1.5B-3BCUDA生态成熟框架适配好内存偏小功耗较高机器人、轻量AgentJetson Orin NX 16G4B-7B统一内存大速度稳定价格高货源紧复杂Agent、多模态项目RK35881.5B-3BNPU可跑CV模型性价比高LLM部署生态较弱视觉轻量LLM的复合任务手机/平板NPU0.5B-1.5B功耗低、成本可控框架不统一限制多端侧轻量助理2.2 主流推理框架怎么分工端侧LLM部署绕不开几个推理框架它们的定位完全不同我分别说一下。llama.cpp是绕不开的基础设施。纯C/C实现几乎支持所有主流端侧硬件包括纯CPU推理。它把模型量化成GGUF格式还率先实现了内存映射加载意思是可以把模型文件直接映射到内存不用一次性加载大幅降低了启动开销。缺点是你需要自己写胶水代码它不提供现成的HTTP API虽然现在有server示例也没有模型管理能力。Ollama本质上是基于llama.cpp做了一层工程封装。它内置模型仓库、HTTP API、模型管理、多平台安装包一行命令就能拉起一个LLM服务。我日常用它做实验和原型验证效率非常高。但要注意Ollama封装了很多细节适合快速验证生产环境定制化时还是得回到llama.cpp。阿里开源的MNN补齐了另一个方向移动端优化。它在Android和iOS上有针对NPU的深度适配能把小模型跑到很低的延迟。MLC-LLM则专注苹果生态在Apple Silicon上表现很好。还有ONNX Runtime跨平台能力强但端侧LLM的量化工具链相对繁琐。2.3 我的选型结论实验和生产分开对待我的习惯是两套方案并行。实验阶段全部用Ollama。原因很简单快。想测某个模型在设备上的速度直接ollama pull拉下来跑想调参数写一个Modelfile改温度、改上下文长度、加system prompt重载即可。Agent开发中最耗时的其实是逻辑迭代Ollama的存在让我不需要在推理细节上消耗精力。到了生产阶段我会迁移到llama.cpp或自己构建的推理服务。因为生产环境需要精确控制比如批量推理的并发排队、KV Cache的预分配策略、特定硬件的线程调度、自定义量化等。Ollama的“黑盒”在这时就变成了限制。结合上面两张表我的建议是不要一上来就追最新的框架先确认你的设备是什么、模型要跑多大、是实验还是生产再选框架。3. 部署实操从模型量化到第一个Agent请求3.1 模型规模怎么定按任务选参数不按口号选端侧Agent选模型第一原则是“任务决定参数量”。我先列一个映射关系简单意图识别、关键词抽取、格式转换1.5B就够多轮对话、指令跟随、单工具调用3B是甜点区间复杂推理、多工具编排、长文档总结需要7B或以上。这里有个很多人犯的错觉得参数越大效果越好于是不管什么任务都往7B上冲。端侧设备的算力是有限的7B模型的一次推理时间可能是3B的3倍以上。如果你的任务只是“把用户语音转成结构化的意图”3B和7B效果几乎没有区别但速度差了三倍。我自己在做Agent时通常以3B模型起步把业务逻辑跑通再评估瓶颈。如果发现工具调用经常出错、指令理解不够再上7B。如果发现速度跟不上则反过来下探到1.5B。3.2 量化档位选择Q4_K_M为什么是端侧默认模型权重的存储格式有FP16、INT8、INT4等端侧部署几乎必谈量化。量化就是在牺牲一点精度的情况下把模型压缩到更小、推理更快。GGUF格式里常见的量化档位包括Q2_K、Q3_K_S、Q4_K_M、Q5_K_M、Q8_0。我实测下来Q4_K_M是端侧最稳的平衡点体积约为FP16的1/4质量损失在可接受范围指令跟随能力和工具调用稳定性都保住了。Q2_K和Q3_K我基本不碰。不是它们不能用而是Agent任务和普通聊天不同Agent需要模型严格按格式输出、正确调用工具。权重量化越狠模型内部的推理能力衰减越明显经常出现“大概意思对但格式错了”的问题。这种问题在Agent编排里是致命的。如果设备内存较充裕比如Orin NX 16G可以试Q5_K_M甚至Q8_0。我个人在7B模型上优先用Q5_K_M在3B模型上用Q4_K_M。体积差不了太多但质量更稳。3.3 用Ollama跑通全流程下面把完整流程走一遍。这里以Jetson Orin Qwen2.5-3B为例。第一步安装Ollama。官方脚本一条命令搞定装完后跑ollama serve确认服务起来了。第二步拉取模型ollama pull qwen2.5:3b第三步写一个Modelfile调整参数。我通常会把上下文长度设大一点、温度设低一点顺便塞入Agent所需的system promptFROM qwen2.5:3b PARAMETER temperature 0.3 PARAMETER num_ctx 8192 PARAMETER top_p 0.9 PARAMETER repeat_penalty 1.1 SYSTEM 你是一个端侧Agent负责帮用户处理各类任务。 你可以调用工具但必须以JSON格式返回调用结果。 JSON字段为{tool: 工具名, args: {参数名: 参数值}}。 如果无法完成任务请返回{tool: none, args: {}}。 第四步创建并启动自定义模型ollama create my-agent -f Modelfile ollama run my-agent第五步通过HTTP API在Agent代码里调用。这是最常用的一环curl http://localhost:11434/api/generate \ -d {model: my-agent, prompt: 帮我查一下明天的天气, stream: false}返回值里的response字段就是模型输出。我记得第一次在Orin上走完这五步只花了不到半小时。Ollama的好处就在这里它把复杂的东西全藏好了让开发者能专注于Agent逻辑本身。3.4 让端侧模型学会工具调用工具调用Function Calling是Agent的核心能力但端侧小模型的工具调用能力比云端大模型弱不少。云端大模型在训练阶段就针对工具调用做了大量SFT监督微调能非常自然地输出结构化的调用参数。端侧小模型没有这层训练直接让它“自由发挥”结果往往是一坨非JSON的废话。我的做法是手动构造工具调用范本通过few-shot示例让模型“模仿”。在Modelfile的SYSTEM里除了指令再放几个完整样例用户说帮我设置明早8点的闹钟 你应该返回{tool: set_alarm, args: {time: 08:00, label: 起床}} 用户说播放周杰伦的歌 你应该返回{tool: play_music, args: {keyword: 周杰伦}}只要few-shot给得足够多、格式足够统一3B模型也能比较稳定地进行工具调用。实测下来15个左右的高质量示例就能覆盖大部分场景。示例质量差那效果就翻车所以这里别偷懒。如果模型仍然输出不稳定可以考虑换更强的模型或者用更强的约束方案。后面第5节会展开讲JSON模式兜底的做法。4. 实测数据与参数调优速度、显存、上下文的三方博弈4.1 几组实测数据附设备环境我自己的测试环境包括Jetson Orin Nano 8G和RK3588开发板跑的都是Q4_K_M量化。速度数据仅供量级参考不同固件和频率设置会有差异。先看Orin Nano 8GQwen2.5-1.5B约45-55 token/s内存占用约1.8GBQwen2.5-3B约30-40 token/s内存占用约3.2GBLlama-3.2-3B约25-32 token/s内存占用约3.5GBQwen2.5-7B约8-12 token/s内存占用约6.5GB再看RK3588Qwen2.5-1.5B约15-20 token/sQwen2.5-3B约8-12 token/s7B基本不可用单token要好几秒这里有一个很关键的结论如果你的Agent任务需要多轮工具调用单次推理速度至少要在15 token/s以上否则整体体验会非常煎熬。因为一个Agent任务可能要连续做5-10次推理每次推理生成200-300个token。按8 token/s算仅生成文本就要3-5分钟。4.2 KV Cache与上下文Agent记忆的隐形上限KV Cache是Llama这类Transformer模型在推理过程中缓存“注意力键值对”所用的内存。它的大小随着上下文长度线性增长。很多人的误区是只看模型权重的体积忽略了KV Cache也是一个大头。举个具体的例子7B模型Q4量化权重差不多4GB如果设置num_ctx为8192KV Cache额外占用大约1GB。在8G内存的设备上这已经非常紧张了。Agent场景对上下文长度的需求远高于普通聊天因为要放系统提示词、工具描述、历史对话、工具返回结果。我建议按以下规则评估MAX_CONTEXT 模型最大长度 × 0.6。留出40%的余量防止Agent在运行时上下文溢出。当上下文即将用满时有几个处理办法一是做滑动窗口只保留最近N轮对话二是做摘要压缩把过去的对话由模型“总结”成一小段再塞回去三是直接清空历史只保留最新一轮。三个办法各有利弊我的经验是摘要压缩的效果最好但会引入额外的推理开销适合对响应时间要求不那么苛刻的场景。4.3 采样参数里的坑温度、重复惩罚如何影响工具调用采样参数对Agent的影响可能比很多开发者想象的都大。先看温度。温度越高输出越随机。普通聊天场景可以设到0.8、0.9让回答更“有灵气”。但Agent场景需要确定性温度设太高会导致模型偶尔“灵感爆发”生成一个不存在的工具名。我自己的经验是Agent任务温度控制在0.2到0.4之间越高越容易出幻觉千万别学聊天场景调高。再看重复惩罚repeat_penalty。模型中如果重复惩罚设置不当容易出现两种典型问题一种是惩罚过高模型在生成JSON时频繁中断因为某个字符出现次数太多被惩罚了另一种是惩罚过低模型陷入重复循环一把梭产出无数个无意义句子。端侧模型的惩罚系数通常在1.1到1.15之间比较稳具体值需要根据模型微调。还有一个容易被忽略的参数是top_p。我习惯把它固定在0.9太低会让输出过于机械太高又增加蒸馏风险。整体原则Agent任务的采样参数要往“保守”方向调宁可输出平庸也不能输出乱来。5. Agent任务改造端侧LLM的几个硬骨头5.1 function calling不稳定JSON模式来兜底前面提过端侧模型对工具调用的“自由发挥”是不可靠的。我在实际开发中试过几种方案最终稳定下来的是一套“JSON模式兜底”的做法。核心思路是不指望模型天然生成完美JSON而是把生成过程约束在可控范围内。第一步在Modelfile里把system prompt改得非常强硬只允许输出JSONSYSTEM 你只能输出JSON不得输出任何其他内容。 JSON格式必须严格遵循{tool: ..., args: {...}} 如果你不能理解用户的请求输出{tool: none, args: {}} 不要解释不要道歉不要输出多余文字。 第二步在代码里做输出清洗和重试机制。我的Python伪代码如下import json import re def parse_agent_output(raw_text): # 提取纯JSON部分 json_match re.search(r\{.*\}, raw_text, re.DOTALL) if not json_match: return None try: data json.loads(json_match.group()) if tool not in data: return None return data except json.JSONDecodeError: return None第三步对JSON解析失败的情况设定重试策略。我通常重试两次每次都把上次的错误信息拼回提示词里让模型知道“你刚才的输出格式不对”for attempt in range(3): raw llm_generate(chat_history error_hint) result parse_agent_output(raw) if result: return result error_hint f\n上次输出不合法{raw}\n请只输出合法JSON。 return {tool: none, args: {}} # 兜底返回这套机制上线后我的Agent工具调用成功率从裸模型时的70%左右提升到了95%以上。剩余5%的不稳定基本发生在上下文过长或任务过于复杂的边界场景。5.2 记忆管理不是堆上下文是分好三类信息Agent的“记忆”是很多开发者会忽视的环节。我见过不少项目把多轮对话一股脑塞进上下文上下文一爆就卡死或“失忆”。处理记忆时可以参考大模型内部Attention机制的QKV比喻每一个记忆条目都有“Key——我是谁”、“Query——我在找什么”、“Value——我能提供什么”。管理记忆的关键是把这三类信息分开而不是一股脑堆成一个长字符串。落到实际工程上我的做法是三个独立存储区身份区固定写入Agent的角色设定、能力边界、常驻偏好。这部分永远在上下文的头部不随对话变化。工作区保存当前任务相关的数据比如当前执行到哪个步骤、哪些工具已返回结果。任务完成就清理。长期区保存跨会话的有价值信息比如用户偏好、历史结论。每次只把相关部分检索出来后拼入上下文。具体实现时可以用向量数据库做长期区的相似度检索也可以简单地用关键词过滤。数据量不大时我甚至直接用JSON文件存检索时遍历一遍也很快。关键是结构上分开避免全部塞进一个杂乱无章的“大杂烩”。这个设计还有个额外的好处上下文预算可控了。身份区固定占用一段长度工作区限制为1K token左右长期区每次只检索插入几百个token整体上下文永远不会失控。5.3 沙盒隔离让Agent不能越权Agent的能力越强权限边界就越重要。一个能调用系统工具、访问文件、执行命令的Agent如果权限不受控简直是给自己开了一扇安全后门。我在端侧Agent里强制引入“沙盒隔离”思路。不管Agent有多聪明它的所有动作都必须在预设的权限范围内执行。具体做法有三层第一层工具白名单。Agent只能调用我显式允许的工具任何未注册的工具调用一律拒绝。第二层参数校验。工具接收的参数必须是定义好的Schema比如时间参数必须是“HH:MM”格式文件路径必须限定在某个目录下。第三层敏感操作人工确认。涉及删除、覆写、外发数据等高风险动作必须返回到用户界面确认后才能执行。这个思路其实借鉴了容器隔离的理念给Agent一个受限的运行环境让它“看到的世界”是设计好的而不是整个系统。不要觉得这是多此一举很多云端的Agent框架出事都是因为权限边界没设好。5.4 并发、排队与推理调度端侧Agent扛并发的基本功很多人问端侧Agent怎么扛并发。我的答案是先看你的Agent到底需不需要“扛并发”。如果Agent是单用户交互比如个人手机助理那根本不存在高并发。但如果你的Agent跑在一个服务多用户的边缘盒子上比如酒店前台终端、家庭智能中枢就必须考虑并发请求进来了怎么办。端侧设备的算力是固定的同一时间只能跑一个推理任务或者用多个GPU/CUDA流做有限的并行。这时候就需要一个请求队列。我的实现方案很简单import queue import threading class InferenceQueue: def __init__(self, model): self.model model self.q queue.Queue() self.worker threading.Thread(targetself._run, daemonTrue) self.worker.start() def submit(self, prompt, callback): self.q.put((prompt, callback)) def _run(self): while True: prompt, callback self.q.get() result self.model.generate(prompt) callback(result)这段代码只做了一个事所有推理请求排队单线程串行推理结果通过回调返回。它避免了多线程同时调用推理接口导致的内存暴涨和线程竞争。如果你觉得串行排队太慢可以引入优先级交互性强的请求比如用户正等着回应优先级高后台批处理任务优先级低。另外把请求里最耗时的prefill阶段做成批处理也能大幅提升整体吞吐。这个思路在端侧LLM服务器里非常实用。6. 榜单分数之外的选型逻辑实测比Open LLM Leaderboard靠谱6.1 公开榜单能告诉我们什么不能告诉我们什么很多同行在选端侧模型时会先去查Open LLM Leaderboard这类公开榜单。榜单确实有参考价值比如能看出模型在通用知识、推理、数学等维度上的相对水平也能横向比较不同尺寸模型的综合能力。但榜单有三个致命盲区第一评测环境是云端的大算力设备分数不反映端侧部署后的真实速度。同一个模型在A100上的耗时和在RK3588上的耗时完全是两个世界。第二榜单评测的是通用能力不是Agent能力。一个在MMLU上拿高分的模型未必能稳定输出工具JSON。第三榜单是离线评测不涉及多轮交互、上下文衰减、长时间运行的稳定性。而这些偏偏是Agent场景最需要关注的。我有一次选了一个排行榜上分数很高的7B模型实际部署后发现工具调用格式频繁出错后来换了一个榜单分数稍低但专门针对指令跟随训练的模型效果好得多。所以榜单是起点不是终点。6.2 自建评测集从自己的Agent任务里取样我现在选端侧模型都会先跑一个自建的“Agent能力评测集”。这个评测集不复杂但完全来自我的真实业务场景。操作方法是收集过去两周内Agent实际处理过的200个用户请求人工标注出正确答案和期望的工具调用序列。然后让候选模型在同样的提示词下逐个跑打分维度包括工具选择正确率参数抽取准确率JSON格式合法率平均响应延迟上下文超长时的性能衰减这五维里延迟可以通过日志统计其他四项都是可量化的。这个评测集的价值在于它测的是“我的Agent要用的能力”而不是模型训练者想突出的能力。哪怕是同一个模型在我真实的提示词模板下表现可能和排行榜完全不同。如果时间紧最少也要做一件事把Agent里最难生成的10个提示词抽出来人工看模型输出质量。这10个提示词通常代表了最频繁、最关键的调用路径足够管中窥豹。6.3 小模型端侧大模型云端的混合兜底最后聊一个端侧Agent界行之有效的架构混合推理。不管端侧模型调得多好它在复杂推理、长文本理解、罕见问题处理上终究不如云端大模型。所以我的Agent架构是双轨的日常高频、格式固定、隐私敏感的任务走端侧小模型边缘案例、复杂推理、需要常识储备的任务自动切换到云端大模型兜底。这个切换不是玄学而是可以由规则驱动的。我常用三个触发条件端侧模型连续两次解析失败时端侧模型生成结果的置信度低于阈值时任务类型命中“复杂推理”白名单时。只要触发任何一个就把请求转给云端。这套架构的好处很明显90%的请求在端侧完成成本和延迟都维持在低位剩下10%的不走寻常路由云端最强模型兜住整体体验不输全云端方案。我建议你在开始端侧Agent项目时就把这个混合架构设计进去而不是等端侧模型“跑不出来”了再临时补。接口设计上端侧和云端使用同一套提示词模板和输出解析逻辑这样切换时对上层Agent完全透明。写到现在我最想强调的一点是端侧LLM部署不是一锤子买卖它是在持续迭代中逐步逼近“能用”状态的工程。每当我以为一个模型已经够好时跑一轮新的评测就能发现新的短板然后回到量化、采样参数、记忆管理、提示词模板上去做微调。最后再分享一个亲测好用的细节如果端侧模型在工具调用时经常输出多余的废话试着把温度调到0.2以下同时把repeat_penalty调到1.15以上并把“你只能输出JSON”这句提示词同时放在SYSTEM里和具体问题的末尾重复一次。就这三步很多时候比换一个更大的模型还管用。