把开源模型塞进手机跑通一个能聊天的Demo现在网上教程一大把门槛已经很低了。可同样的模型一旦要变成真正能“帮你查一下周二下午的会议时间、重新排到周三上午、再顺手把所有参会人通知一遍”的端侧Agent事情就完全变了味。模型推理只是地基里的钢筋而Agent工程化才是这栋楼的水电、墙体、门窗和消防系统。本文是“深入理解端侧 Agent”系列的第三篇主题是Agent工程化上篇我们把视野从模型推理拉高到整个工程链路重点拆解四个绕不开的话题端侧Agent到底解决什么问题、模型底座怎么选型和抠性能、端云边界怎么划、以及工具调用在手机上怎么安全落地。这篇内容的定位是给已经能用端侧模型做出原型、但还没做到产品稳定交付的工程师看的。如果你正卡在“Demo什么都好、一接真实场景就崩”这个阶段读这篇应该能少踩不少坑。考虑到工程化的面太广这篇先把“底座”讲透记忆管理、评测体系、更新兜底这些偏运维和体验的话题我们留到下篇。1. 端侧Agent工程化先搞清楚“凭什么在端上”这个前提很多人一上来就扎进模型量化、推理加速、工具调用结果方向搞反了。端侧Agent工程化最难的不是“怎么把东西塞进手机”而是“哪些东西应该塞进手机”。这个边界划错了后面所有的性能优化都是在给错误方案擦屁股。1.1 云端Agent和端侧Agent的根本差异不是模型大小很多团队做端侧Agent的思路是先做一个云端Agent然后把模型换小、量化照搬架构部署到手机上。这个思路坑很大。端侧Agent和云端Agent的差异根本不是“模型小一点”的线性缩放而是整个系统的非功能约束发生了质变。我整理了一个对比直接看这张表就明白维度云端Agent端侧Agent推理延迟依网络状况2~5秒波动大300~800ms稳定可预期数据隐私数据需上传合规成本高数据不出设备天然私密算力预算几乎无限可动态扩容固定内存和功耗墙极其吝啬上下文容量可挂超大窗口128K受DRAM约束往往只有几K可用网络依赖必须在线离线即死离线可用在线增强边际成本每次调用按Token计费一次性硬件成本无Token费更新频率服务端随时热更新受应用商店和包体限制更新重这里最容易被低估的是延迟和隐私。我做过的端侧语音助手场景里用户对“说完指令到开始动作”的容忍上限大约在1.2秒左右超过就明显觉得卡。云端方案在广州到上海机房约30ms RTT的前提下光网络往返加排队已经吃掉700~800ms再加上模型TTFT经常逼近甚至超过阈值。端侧推理稳定在400ms左右省掉两次网络往返体验是质的提升。同样被低估的还有隐私这个卖点。端侧Agent最性感的地方在于模型直接驻留在设备里通讯录、日历、相册这些数据可以本地检索本地推理完全不需要上传。这不仅仅是合规优势它在产品设计上带来的自由度非常大——你可以让Agent去吃本地数据而不用写十几页的数据安全说明文档。1.2 工程化的本质在物理约束里做“四则运算”端侧Agent的工程化说白了就是在一条特别窄的物理约束缝隙里塞进规划、记忆、工具调用这一整套胶水逻辑。这里的物理约束通常包括内存预算App能拿到的运行内存一般在2~4GB抠到模型侧往往只剩1.5GB左右。Android上系统吃得多连大模型带Agent运行时内存一超就容易被LMKLow Memory Killer杀掉。功耗预算持续推理时的电流通常得控制在几百mA级不然iPhone瞬间发烫降频Android直接弹温控警告。这就是为什么端侧推理很少持续跑大模型而是用“突发推理快速待机”的模式。包体预算移动端App包体动不动就被应用商店限制在200MB以内你塞一个2B模型量化后还有1.2GB搞不定就需要动态下载模型这又引出加载时间和存储空间的管理。性能预算首Token时间要压到500ms以内推理吞吐要扛住连续多轮对话同时不能让系统卡顿掉帧。这些约束叠加起来就逼着你把一个云端Agent的“所有模块常驻内存”模式改成“按需加载、用完即走、能省则省”的资源管理模式。代码层面要做的东西和在服务器上写业务逻辑完全不一样。举个最简单的例子云端Agent的上下文随手塞进Redis几毫秒就能读出来端侧Agent的上下文就压在手机那点内存里你得分层缓存、按需清除稍不留神就是OOM。所以工程化的第一步是接受一个事实端侧Agent不可能做到云端Agent的百分之百能力目标是覆盖高频刚需场景的百分之八十体验同时保持可接受的资源开销。这点共识不建立后面全是内耗。2. 模型底座选型推理引擎、量化方案与上下文内存博弈底座选错了后面再怎么调都是事倍功半。我见过不少团队用云端跑的同一套ONNX模型直接怼到手机上结果算子不支持、性能惨不忍睹回头又怪框架不行。端侧模型的选型和部署有自己的独立逻辑。2.1 推理引擎选型不能只看跑分要看生态闭环端侧推理引擎主流就那么几个但每个的适配场景差别很大。先看对比引擎核心优势短板适合场景llama.cpp纯CGGUF量化支持极好Metal/Vulkan后端齐全算子覆盖偏LLM通用模型支持弱端侧纯LLM推理CPU/GPU混合跑MNN算子覆盖广移动端优化深入静态图性能稳LLM动态shape支持不如llama.cpp顺滑多模态、工具类小模型Android为主ONNX Runtime生态最全前后端统一标准包体积偏大移动端裁剪要花功夫已有ONNX资产跨端统一部署NCNN体积小依赖极简LLM支持偏弱偏视觉模型IoT、嵌入式极小模型场景MLXApple生态原生Metal加速内存统一架构优化好仅限Apple平台出不了生态墙纯Apple端产品重视内存带宽利用选型时最容易被忽视的是“社区活力和维护节奏”。llama.cpp在LLM时代几乎是社区更新的风向标GGUF格式已经成为开源LLM在端侧的准标准如果你要跑的模型是LLaMA、Qwen、Mistral这些主流开源LLMllama.cpp基本是最省心的底座。反过来如果Agent里还要跑CLIP做图像理解、跑一个小分类器做意图识别那MNN和ONNX Runtime在算子覆盖上优势更明显因为llama.cpp对非LLM模型的支持不够顺手。还有一个很现实的判断维度你的模型转换链路过不过得去。选引擎不是看谁跑分高而是看你的模型能不能从PyTorch/HuggingFace顺利转成它要的格式、中间会不会卡在某个不支持的算子。我建议选型时开盘先花半天时间拿你们真实要跑的模型不是测试模型把“导出一转换一量化一端侧推理”全流程跑通一遍哪个引擎卡最少就用哪个。2.2 量化方案端侧Agent的“能用”标准要重新定义量化的本质是用精度换体积和速度。端侧Agent的量化选型比纯聊天场景更微妙因为Agent要频繁做结构化输出JSON、工具参数对格式和语义的敏感度比生成自然语言高得多。现在的主流方案分几档FP16基本不损失精度但7B模型FP16要占14GB手机直接出局。现在端侧几乎不考虑FP16做权重存储只用于计算过程中的激活值。INT8W8A8权重和激活都量化精度损失很小7B模型约4GB还是比较胖。适合设备内存宽裕的旗舰机或者在IPhone这种可用的统一内存比较大的设备上跑3B以下模型。INT4W4A16权重INT4、激活FP16这是目前端侧的最优选。7B模型压缩到4GB左右2B模型约1.2GB内存预算能接受。代价是需要做混合精度推理底层要处理好反量化。2-bit/3-bitW2/W3压得很狠1B模型能压到600MB但量化损失开始影响工具调用的可靠性。我的实测里3-bit下模型写JSON偶尔会出现key名拼错、括号不闭合这类低级错误这在一个“要真正执行动作”的Agent里是致命的。这里给出一个具体的取舍建议如果你跑的是1B~3B小模型冲INT4完全可行如果你跑的是4B~7B中大型模型INT4几乎是唯一选项同时要配合LoRA微调来补偿量化损失。网上经常有人说“INT4和FP16差不多”这话在聊天场景部分成立在Agent场景要打折扣——特别是Function Calling这种需要精准输出参数的任务INT4模型的整体成功率可能掉3~8个百分点必须用评测数据说话别拍脑袋。我在实际项目里踩过一个大坑量化后模型看起来聊天还挺流畅但连续调用工具时经常出现幻觉参数比如把“周二下午3点”写成“3day pm”。后来排查调优了很久发现根因就是量化粒度太大导致的数字精度损失。解决办法是把包含时间、ID、金额这类敏感数字的层单独保留为INT8其余层压INT4也就是所谓的混合精度敏感层保护一下就把工具调用的参数错误率压下去了。2.3 KV Cache端侧Agent的隐形内存杀手端侧Agent部署还有一个特别容易被忽视的硬骨头——KV Cache。很多人在云端跑模型时完全不关心KV Cache反正显存够大。到了端侧KV Cache就是那个悄悄蚕食DRAM的隐形毒瘤。先说原理。Transformer每生成一个Token都要缓存这一层的K矩阵和V矩阵用来算注意力。这个缓存占用的内存大致是内存占用 2K/V两个矩阵 × 层数 × KV头数 × 每头维度 × 序列长度 × 每个元素的字节数不用记公式记住结论就行KV Cache大小基本和序列长度线性相关。一个7B模型32层、8个KV头、每头128维序列长度4096时缓存开销大约是2×32×8×128×4096×2字节≈512MB。这已经是一个相当奢侈的数字了——因为你模型权重才4GB聊天聊到4000多个字额外又吃512MB很多手机直接受不了。更麻烦的是Agent场景天然会产生长对话。用户一个任务可能要经过“理解意图—拆解计划—多次调用工具—汇总结果”多个轮次上下文很容易膨胀。我跑过一个测试一个包含4次工具调用的任务仅仅是因为每次都把工具返回结果拼进对话历史最终的上下文长度比普通聊天话题高出3倍以上。如果不做干预几轮对话后KV Cache就把内存吃干榨净然后系统触发LMK把App杀掉。所以端侧Agent的内存优化真正的胜负手在KV Cache管理而不是单纯压模型权重。常用的三板斧滑窗截断只保留最近的N轮对话比如保留最近2048 Token更早的历史做摘要后以固定长度摘要Token替代。这是最朴素的方案副作用是Agent可能忘掉前面规划过的步骤。KV Cache量化把K、V矩阵从FP16压到INT8能省一半缓存空间精度损失通常很小。这个方案在端侧性价比极高因为缓存是动态增长的压缩它等于给整场对话延长“寿命”。工具结果的瘦身工具返回的冗长JSON别原样塞进上下文。先做字段裁剪只保留摘要或关键信息再把完整结果存到外部存储等需要时按ID取回。这个属于工程层面的“治本”比压缩物理缓存更该先做。我自己的项目组合是滑窗截断保存最近8轮 KV Cache量化INT8 工具结果结构化瘦身。这套组合下来同样的7B模型可用上下文长度从1200个Token提升到接近3500个Token内存开销几乎持平。工程化说到根上就是这种“一分一厘抠出来”的打磨。3. 端云协同把算力放在正确的“位置”纯端侧Agent在很长一段时间内能力都追不上云端大模型。但产品又需要随时可用、保护隐私、控制成本——所以大多数实际落地的端侧Agent不是“纯端”而是“端云协同”。工程化的一半功夫要花在这个边界怎么划上。3.1 分流决策不是所有请求都要在端上跑端云协同的第一步是定义“哪个请求走端、哪个请求上云”。这个分流维度一般有四个延迟敏感度语音交互、实时控制类的指令必须在端上完成因为等不起网络往返。隐私敏感度涉及通讯录、相册、邮件正文、位置等个人数据的推理坚决本地执行。数据一旦离开设备商业信任和合规成本就完全变了。任务复杂度复杂推理、长文总结、深层逻辑问答本地小模型搞不定上云大模型更稳。上下文长度请求加上相关知识已经超出了端侧能扛的窗口直接上云避免本地做暴力截断导致断章取义。落地上一般做个分流规则引擎按优先级判断识别到隐私数据 → 端侧执行同时禁用上行延迟关键路径如涉及硬件操作→ 端侧执行预估任务复杂度超过阈值如多跳推理、需要外部知识→ 上云其余情况 → 默认端侧端侧模型低置信度时再升级云端特别要留意第4条的“置信度升级”设计。纯规则分流很容易漏判一个看起来简单的“帮我预约周四的会议室”端侧模型可能理解不了周四的“会议室A在装修”这个隐含前提。合理的策略是让端侧模型同时输出一个置信度分数可以用logprob归一化近似低于某个阈值时就自动把请求升级到云端。这个策略我用下来非常有效能把整体任务成功率提升十几个点而云端的请求量只增加不到两成——因为你只在真正拿不准的时候才上云。3.2 降级策略网络总在最不该断的时候断端云协同如果只有分流没有降级那是一个不完整的工程方案。移动端最残酷的真相是——网络层永远不稳定。电梯里、地下车库、地铁隧道断网是常态而不是例外。降级设计要分成三档强联网态正常分流端云协同跑满。弱网态RTT 1.5s或丢包率5%敏感任务本地优先云端任务可接受更慢响应但必须有明确的超时兜底不能无限等待。离线态云端全部不可用Agent降级为“端侧小模型规则引擎”的组合只支持预先定义的受限任务集比如本地闹钟、便签、系统设置。关键是要把降级当成第一公民功能来设计而不是事后补丁。我在项目里是这么做的所有上云请求都包一层“超时熔断”默认RTT阈值1.2秒超了就直接调端侧模型顶上同时把端侧模型做成永远可用的“最后防线”云端返回失败时端侧立即接管并给用户一个合理但稍简化的答复。这个设计在产品上的意义是巨大的用户绝大多数时候感受不到云端的参与但也不会因为网络波动就彻底无法使用。稳定性的口碑远胜于单一场景的智能程度。3.3 缓存别让同一个请求反复烧Token工程化到一定阶段你会发现Agent的请求有一大批是重复的。用户每天问的“今天有什么安排”“明天天气怎么样”语义几乎一致。这种情况下无脑让端侧模型重新跑一遍纯属浪费浪费的不只是算力还有用户的时间。我建议做两层缓存语义缓存对用户输入做Embedding相似度超过0.92的直接命中历史结果。这一层注意别只存最终答案要连同当时调用的工具结果一起存而且设置合理的过期时间比如天气类20分钟过期日程类5分钟过期。计划缓存用户复述相同任务但参数不同时规划结果可以复用。比如“提醒我下午3点开会”和“提醒我下午5点开会”意图相同Plan可以复用只需替换时间参数再执行。这两层缓存做好在我自己的产品里能命中约25%-35%的日常请求。别小看这个数字——在Agent场景下每省一次完整推理就意味着在用户的手机上又少了一分功耗和发热同时响应速度直接变成“毫秒级返回”体验完全是另一档位。4. 工具调用的端侧工程实现从Function Calling到沙箱执行Agent区别于普通聊天机器人的核心是它能“动手”。端侧Agent的工具调用比云端多了三道紧箍咒上下文更小、模型能力更弱、触达权限更危险。这三条叠加让端侧工具调用的落地充满了细节和暗坑。4.1 端侧Function Calling的流程改造云端Function Calling的标准流程是把工具定义塞进system prompt模型输出一段JSON解析后调用。这个流程搬到端侧第一刀就要砍向“工具定义太长”。一个典型的云端工具描述可能要几百个Token端侧上下文本来就小塞十几个工具定义用户的话还没开始上下文先爆一半。这里必须做工具裁剪和描述精简。我的做法分三步按意图粗分类裁剪工具集。先让模型做一次很轻的意图分类比如判断是“日程类”“设备控制类”“信息查询类”只把命中类别的工具定义真正加载进上下文。手上一开始定义40个工具实际每次只暴露6~10个。用“一句话风格”重写工具描述。云端那套长段落描述在端侧全废改用“查询天气参数city城市名”这种电报体。实测发现描述简洁反而让模型的工具选择准确率小幅提升因为注意力更好聚焦了。工具定义按固定模板压缩。名字用短小驼峰get_weather_1h描述严格限制在30个汉字内参数尽量用基本类型避免嵌套Object。看一个实际示例对比一下云端版和端侧版// 云端版典型写法约120 Token { name: get_weather_forecast, description: 查询指定城市未来若干小时/若干天的天气预报信息包括温度、天气现象、降水概率、风力风向等以及出行建议和穿衣建议。适合用户查询天气情况、准备出行方案、决定是否带伞等场景。, parameters: { type: object, properties: { city: { type: string, description: 城市名称比如北京、上海 }, days: { type: integer, description: 查询天数1到7之间 } }, required: [city, days] } }// 端侧版压缩后约40 Token { name: get_weather, description: 查询天气。参数city城市名days天数, parameters: { type: object, properties: { city: { type: string }, days: { type: integer } }, required: [city, days] } }这才是端侧该有的工具定义姿态。4.2 工具注册表与执行沙箱权限是端侧Agent的第一生命线端侧Agent能触达的东西比云端Agent敏感得多。云端Agent调用API影响的顶多是一个云端账号端侧Agent一旦能读通讯录、发短信、操作支付、控制智能家居那它就是一个“装在用户手机里的数字管家”——权力越大惹祸能力也越大。工具注册表的设计是安全性的第一道闸。我建议每个工具在上线前必须登记五件事工具名称、权限等级、所需敏感权限如通讯录读取、参数校验规则、超时预算。注册表里同时维护一个“高危操作白名单”任何需要写操作的工具发消息、删日历、转账默认禁用必须单独开启。这五件事里最容易偷懒的是参数校验规则但恰恰是这里事故最多。模型输出的JSON虽然格式合法但参数内容可能离谱查询天气给了“invalid_city”发消息给了“收件人NaN”。所以每个工具真正执行前一定要加一层参数Sanity Check用正则和类型校验兜底。这一步不比你辛苦调的量化不重要我见过太多因为少了一道校验把一条垃圾短信发到全家的线上事故。执行环境本身也要沙箱化。端侧工具执行要强制加三样东西超时控制每个工具调用最多跑2秒超时直接终止并返回错误码避免某个系统调用卡死拖垮整个Agent循环。资源限额工具执行时的内存增量、CPU时间都要有配额。尤其像“读取本地文件”这种工具很容易被超大文件撑爆内存。结果大小限制工具返回的原始结果要限制体积比如单次最多64KB超过先截断再交给模型防止上下文被垃圾数据淹没。这一层的本质是把“模型不可信”和“工具不可控”这两个风险用工程隔离开。模型输出永远是概率性的工具执行则必须是确定性的。工程师要做的就是在中间架起一道防火墙。4.3 模型输出不稳定时的容错机制端侧模型再小也有一个问题绕不开——它就是会偶尔输出不可解析的JSON。这件事在云端可以靠“重试一次大模型”来解决在端侧重试成本也不低因为模型本来就慢。所以容错要讲究梯次。我在端上用的容错顺序是JSON解析失败 → 先用正则检查是否有“潜藏的JSON块”用搜索方式提取。很多时候模型只是在JSON外面包了一层废话提取出来就能用。提取失败 → 原样发回模型附一句“你的上一轮输出不合法请只输出JSON不要附带任何解释”让模型重写一次。这里要注意把上一次的完整对话历史带上否则模型会忘记上下文。仍失败 → 触发“最小可用路径”把问题降级成普通对话回复比如“我没能理解您的指令请问您是想要设置一个提醒吗”——绝不让用户看到原始报错或半截JSON。重试次数我设定为最多2次超过就直接放弃Action改走对话。因为Agent场景对实时性要求高3次重试的时间已经足够用户产生很差的体验。顺带一提在我的实测里加了“只输出JSON”这轮重试后端侧模型的工具调用成功率能从82%左右拉高到93%上下。这个数值差距对产品可用性来说是质变。工具执行完的结果校验也很关键。工具返回后不能默认结果就是对的。我会让模型在回复用户前做一个30字以内的结果摘要同时透传给一个“执行确认状态”成功、失败、部分成功。有视频门禁这种场景如果模型没发现“门已开锁”这个返回值重复执行会造成安全隐患所以这个确认状态一定要从工具侧强校验后返回不能由模型自由发挥。写到这里我刚好总结一下端侧工具调用的整个循环意图分类裁剪工具 → 精简schema进提示词 → 模型输出JSON → 解析参数Sanity Check → 沙箱内执行工具 → 结果截断瘦身 → 带回上下文 → 模型生成用户可见回复。这八步每一步都要做“失败保护”整个链路才立得住。关于端侧Agent工程化这篇“上”篇就先说这些。底座选型、内存博弈、端云分流、工具沙箱这四项是后续一切上层设计记忆管理、持久化状态、复杂规划器的地基。我个人体会最深的一点是端侧Agent的工程化每一项都不算特别难难的是把所有细节串起来同时接受“端侧永远有边界”这个前提并在边界内做出极致体验。要是你正在做这块欢迎在评论区聊聊你在端侧部署时遇到最头痛的问题我们下篇聊记忆和评测的时候可以一起展开。