1. 端侧 Agent 工程化和云端差在哪三个绕不开的约束做端侧 Agent 的人大多都有类似经历在云端用大模型 API 把 Agent 跑通逻辑链路、工具调用、多轮对话都很顺畅结果一旦要把这套东西搬到真机上第一天就崩。不是模型不行而是工程化没跟上。先说清楚这里讨论的“端侧 Agent”是什么它指完全运行在终端设备上的智能体程序模型推理在本地完成不依赖云端 API 返回结果。手机、平板、树莓派、智能家居中枢、车载硬件都算端侧。它和云端 Agent 最大的区别在于三堵墙——内存墙、功耗墙、稳定性墙。内存墙云端跑一个 7B 模型可能只占 GPU 显存的一小部分但端侧设备的内存是固定的。手机可用内存可能只有 4GB 到 8GB还要同时跑系统、其他 App、Agent 的执行引擎和工具进程留给模型的内存往往只有 1GB 到 2GB。这意味着模型参数量、量化精度、KV Cache 每一项都得精打细算。功耗墙端侧设备靠电池供电。模型推理是计算密集型任务连续跑推理会让设备发热、掉电。工程化时必须考虑推理频率控制、任务调度策略、低功耗模式切换。这不是优化问题是能不能让产品存活的问题。稳定性墙云端挂了可以重启、扩容、快速回滚端侧设备一旦系统崩溃用户直接无法使用而且你没法跑到用户设备上去修。所以端侧 Agent 的每一项能力都要做降级预案模型加载失败怎么办、工具调用超时怎么办、上下文溢出怎么办。云端你可以说“加机器”端侧你只能把代码写得更稳。这三堵墙决定了端侧 Agent 工程化不是简单的“把模型缩小塞进去”而是一整套从模型选型、推理引擎、执行框架、工具链路、内存管理到异常恢复的系统工程。这篇文章先聊地基部分也就是从模型部署到 Agent 执行骨架这一段。2. 端上模型部署参数量取舍、量化与推理引擎适配2.1 模型选型1B 到 7B 不是越大越好端侧 Agent 的语言模型选型基本是在推理效果和资源占用之间做权衡。这里给出我实测过的参考经验0.5B 到 1B只能处理非常简单的意图识别、JSON 结构化输出做 Agent 的“决策大脑”明显吃力工具选择经常选错。3B 左右端侧 Agent 的甜点区。在量化到 Q4 之后大约占用 2GB 内存能比较稳定地完成工具选择、参数填充、多轮对话摘要。目前很多端侧 Agent 设备选的大多是这个规模。7B 及以上效果最好但量化后仍要占用 4GB 以上内存对手机和边缘盒子来说已经是极限状态通常只在旗舰机上勉强可用。选型建议如果你的 Agent 只有三五个工具、任务链路固定3B 足够。如果需要复杂推理、多步骤规划先考虑 7B 量化后能否塞进目标设备不行宁可选择云端和端侧混合方案。硬把 7B 塞进 4GB 内存的设备跑几个轮次就被系统杀掉没有任何工程意义。2.2 量化不能只看体积还得看工具调用的稳定输出端侧部署几乎必做量化。常见的方案有 INT8、INT4、GPTQ、AWQ。这里有一个容易被忽视的问题量化到 INT4 后模型的困惑度可能只上升一点点但工具调用时的 JSON 输出稳定性会明显下降——模型更容易在函数名、参数名上产生幻觉或者输出格式不规范。我在项目里遇到过这样的情况同一个 3B 模型Q8 量化时工具调用成功率在 92% 左右Q4_K_M 量化后掉到 85% 左右。表面看 7 个百分点的差距但在生产环境里意味着每 20 次工具调用就有 3 次需要重试Agent 的响应时间和用户体验都受到明显影响。建议量化后一定要用你的真实工具定义做回归测试不要只测通用对话效果。如果发现工具调用成功率下降有两个调整方向——一是把工具描述的写法改得更短更明确二是对关键工具切换到 Q6_K 或 Q8 精度只对非关键部分保留低比特量化。2.3 推理引擎选型与系统级适配端侧推理引擎的选择影响的不只是推理速度还直接影响内存占用和系统集成方式。我接触比较多的几类引擎优势劣势适合场景llama.cpp跨平台支持好、量化方案丰富、内存占用低部分高级算子优化一般树莓派、Linux 边缘盒子、自研硬件MLC LLMGPU 加速好、针对移动端优化配置复杂、框架绑定较深手机端、有 GPU 的设备ONNX Runtime生态全、算子兼容好模型转换过程繁琐量化工具链要求高已有 ONNX 生态的团队MediaPipe LLM安卓/iOS 集成方便、Google 生态可定制性弱快速验证 Android 端 Agent我自己的习惯是先用 llama.cpp 做原型验证因为它最快的路径能让我确认模型在目标硬件上的真实表现包括内存峰值、推理延迟和 CPU 占用。确认可行之后再根据产品形态决定是否需要切换到更底层的方案。还需要注意端侧推理引擎一定要打开内存映射和内存池复用。llama.cpp 里开启--mmap可以让模型文件直接映射到内存避免重复加载。推理过程中 KV Cache 是动态分配的不做好内存复用会让设备在每轮对话后内存碎片化越来越严重跑几个小时之后 OOM 几乎是必然的。我用 mmapmadvise 的方式在树莓派 4B 上把 3B Q4 模型的内存峰值压到了 1.6GB 左右勉强能在 2GB RAM 的设备上跑通。2.4 内存规划预把 KV Cache 算清楚KV Cache 是端侧 Agent 最容易被忽略的内存黑洞。一个长度为 2048 token 的上下文窗口3B 模型在 INT4 量化下KV Cache 大约需要 200MB 到 400MB 内存。这个数字会随模型层数和注意力头数变化必须在部署前根据具体模型算清楚。计算方法其实不复杂KV Cache 大小 层数 × 注意力头数 × 头维度 × 序列长度 × 2K 和 V × 字节数。以 3B 模型、24 层、32 个头、头维度 32、序列长度 2048、INT8 缓存为例24 × 32 × 32 × 2048 × 2 × 1 100MB左右。如果放大到 4096 上下文就是 200MB。部署前把这条公式套进你的目标模型能给内存规划省下很多调整时间。3. 执行骨架循环、工具注册与上下文窗口管理3.1 Agent 执行循环的三大纪律端侧 Agent 的核心执行逻辑是一个循环模型根据当前上下文决定调用哪个工具工具执行完把结果写回上下文模型再继续判断下一步。工程化上这个循环要定下几条纪律最大步数限制云端 Agent 可以跑 20 步 30 步端侧必须限制在 5 到 8 步以内。每一步都是一次完整的前向推理步数越多响应越快越不可能。单步超时机制每一步推理和工具执行都要设置超时。我用的是“推理 400ms 工具执行 1500ms”的默认值实际按设备算力调整宁可超时返回错误结果也不能让用户一直等。失败重试策略工具调用失败必须区分是“模型选错了工具”还是“工具执行时报错”。前者让模型重新选择后者直接返回用户可理解的错误信息不能无限循环重试。这里要给 Agent 的执行加一个“隔离层”或者说 harness。Agent 本体负责决策而执行框架负责调度、超时、重试和资源管理。就像驾驶员的职责是判断路线方向盘、刹车和油门的执行机构是独立的不能让驾驶员的每一步思考都直接控制机械部件。工程化上必须把决策和执行解耦。3.2 工具注册的本质是定义动作空间工具定义给到模型的方式决定了 Agent 的能力边界和决策质量。端侧 Agent 的工具注册有一个关键原则工具数量要克制。云端 Agent 可以注册五十个工具让模型自行挑选端侧模型参数量小面对太多工具选择时经常出现幻觉——选择一个不存在的工具或者工具名相近但功能不对。我在 3B 模型上实测的结果是工具数量超过十个之后选择准确率会明显下降。所以端侧工具注册不是做加法而是做减法把相似工具合并把低频工具做成动态加载。核心频率高的三到五个工具常驻其他工具按需注册用完就释放。每个工具的描述也要精简。大模型是靠工具名称和描述来做选择不是靠读源码。描述写得太长不仅浪费 token还会引入干扰信息。我的建议是每个工具描述控制在两到三句话覆盖“功能是什么 何时使用 关键参数”。3.3 上下文窗口是稀缺资源要精细化经营上下文窗口是 Agent 的短期记忆端侧设备因为 KV Cache 内存限制窗口通常只有 2048 到 4096 token非常不够用。上下文里塞的每一段内容都要问一句值得占这么多 token 吗最大的浪费来源有三个系统提示词写太长。很多人的 system prompt 洋洋洒洒几百字讲角色设定、讲历史背景对端侧小模型来说大多数是噪声。端侧 Agent 的系统提示词要精简到能直接指导行为而不是塑造人格。核心只要交代清楚你是谁、你能调用哪些工具、输出必须用什么格式。工具定义重复加载。有些框架会在每一轮对话重新拼接所有工具定义等于每轮都白费一段 token 开销。工程化上应该把工具定义放在系统提示词里一次性加载后续轮次不重复追加。历史消息无限累积。多轮对话后历史消息会迅速撑爆上下文。端侧不能像云端那样靠大上下文硬扛必须在累积到一定长度后做摘要压缩或者直接滚动丢弃最早的消息。3.4 让历史记忆“瘦身”的两种实用策略端侧 Agent 的记忆管理我只推荐两种经过验证的策略。滚动窗口机制保留最近 800 token 的完整对话更早的内容丢弃。适合那些不需要长期记忆、只关注当前任务的 Agent。实现简单、稳定、不依赖额外的模型调用是最不容易出错的选择。摘要压缩机制当历史消息超过阈值时用一次额外的推理调用把之前的对话压缩成 100 到 200 token 的摘要然后丢弃原文。摘要会损失细节但保留了任务主线。适合需要多轮交互才能完成复杂任务的场景。两种策略可以组合先滚动窗口保留最近内容滚动窗口本身满了再对更早内容做摘要。摘要过程也受端侧资源限制建议放在低负载时段触发避免和正常推理抢算力。我踩过的坑是在用户说话的同时触发摘要压缩结果两件事互相争抢内存直接 OOM。后来改成了“对话空闲 2 秒后才执行压缩”的触发方式问题才消失。4. 端侧工具调用链路权限、校验与异步回调4.1 工具调用的本质让模型输出结构化指令安全执行端侧 Agent 的工具调用和云端有本质区别云端工具调用通常跑在隔离的容器里错误影响有限端侧工具直接操作真实设备能发短信、能关蓝牙、能删除本地文件。一个错误的参数就可能导致用户数据的丢失。所以工具调用的执行链路必须有两层防护。第一层模型输出不能直接作为系统指令执行要先经过解析和校验。第二层解析后的调用必须经过权限判断再进入真实的执行模块。这两层之间不能有任何“捷径”哪怕模型输出再怎么貌似可信。我见过一个低级但致命的错误开发时图方便直接在代码里把模型的自然语言输出拼接成 shell 命令执行。Demo 阶段一切正常但模型在干扰条件下输出了一段包含恶意指令的文本差点删掉整个用户目录。从那之后我定了一个规矩模型永远不直接接触系统调用层它只能产出结构化工具调用参数由执行引擎校验后转译成系统操作。这个原则在端侧 Agent 工程化里优先级最高。4.2 JSON 输出不稳定端侧模型比云端更容易犯的错大模型工具调用的标准做法是让模型输出 JSON 格式的参数。在云端GPT 级别的大模型输出 JSON 的可靠性极高闭源模型还自带严格的 function calling 约束。端侧小模型却没有这个待遇输出经常是不完整 JSON、额外夹带说明文字、或者用单引号代替双引号解析失败率远高于云端。处理方案有三层按优先级排列第一层是输出格式约束在系统提示词里把 JSON 格式写清楚并给出一个完整的示例。小模型对“照葫芦画瓢”的能力比对抽象描述强得多。第二层是解析容错解析失败时不要直接放弃先尝试修复常见错误——比如截取第一对花括号之间的内容、把单引号替换成双引号、去掉末尾多余的逗号。第三层是强制约束生成如果上面两层都解决不了就用带约束解码的推理把输出限制在合法 JSON 范围内。但这会增加实现复杂度通常只在关键工具上使用。我得提醒一下不要用正则表达式去“猜”模型输出里的工具名尤其是模型输出自然语言时。正确做法是让模型先输出一个唯一的动作标识再输出对应的参数 JSON。动作标识匹配后用 JSON Schema 做参数校验校验不通过就直接报错不要尝试“智能纠正”参数值——纠正错了问题更大。4.3 端侧权限工具必须按能力分级端侧设备的工具权限要按风险分级处理。我把常见的工具分成三级风险等级示例处理方式低风险查询天气、计算器、打开网页直接执行中风险发送消息、切换设置执行前弹窗确认高风险删除文件、发送支付、修改系统配置必须用户手动授权且每次执行都要二次确认注意中风险和高风险的区别中风险可以“免确认以后记住”高风险必须每次执行都要现场确认不能记住授权状态。端侧 Agent 和云端 Agent 不同云端的服务条款和隔离环境能兜底一部分责任端侧如果绕过用户确认执行了高风险操作产品口碑和合规上都会出大问题。4.4 长耗时工具必须异步化不能阻塞推理端侧设备上有些工具的执行时间很长拉取远程数据可能花几秒、处理本地文件可能花十几秒。如果 Agent 的执行循环是同步等待推理线程会被工具执行阻塞期间用户如果发来新消息整个 Agent 都没法响应。这是我在开发语音助手时踩过的深坑之一第一次让 Agent 调用一个耗时的网络请求工具结果整个对话界面卡死体验堪称灾难。工程化方案是引入异步执行机制Agent 循环发起工具调用后立刻挂起不占用推理线程工具执行完成后通过回调把结果写回消息队列推理线程检测到队列里有新消息再继续循环。这样即使工具执行耗时很长用户依然可以继续输入只是 Agent 的后续判断会被延迟到工具真正返回之后。实现上关键是定好回调的数据结构不能只用布尔值表示“成功/失败”至少要有状态码、返回数据、耗时、错误信息。模型读这些信息才能判断是重试还是换个工具。只用成功/失败会让模型在失败场景下变成瞎子只能靠猜来决策。5. 多 Agent 协作的工程代价内存、并发与消息协议5.1 端侧多 Agent 为什么不是默认答案很多从云端转过来的团队一上来就设计多 Agent 架构一个 Planner 规划任务一个 Executor 执行一个 Reflector 反思检查结果。这套架构在云端确实有效但在端侧三个 Agent 意味着同时加载三个模型实例——内存翻三倍推理延迟翻三倍。在 4GB 内存的设备上几乎不可能跑通。端侧的推荐做法是默认单体 Agent只有一个模型实例通过多轮上下文和工具调用来完成任务分解。只有当任务类型差异极大、单体 Agent 上下文频繁溢出时才考虑多 Agent。而且多 Agent 不一定非要并行加载三个模型——可以让一个模型实例切换不同角色提示词串行执行三个阶段。内存不变只是时间变长换来的是多 Agent 的规划能力。我实测过树莓派上跑单体 Agent 和双 Agent 的对比单体 3B 模型完成一个三步骤任务需要 8 秒左右双 Agent两个 3B 模型串行需要 14 秒且内存从 1.6GB 跳到 2.8GB。多出来的 6 秒对用户来说是明显的卡顿如果任务本身不复杂单体 Agent 的体验反而更好。5.2 串行调度和消息优先级如果你的场景确实需要多 Agent调度策略上优先选择串行而不是并行。并行调度意味着多个模型实例同时驻留内存端侧设备几乎扛不住。串行调度则可以做到同一时刻只有一个模型在内存中其他 Agent 只保存轻量的状态数据。消息队列的优先级也要设计好。我把端侧 Agent 的交互消息分成三级用户打断消息优先级最高、工具执行结果次之、内部规划消息最低。用户一旦打断当前推理马上做 checkpoint 并暂停优先响应用户的新语音或文本。如果没有优先级设计就可能出现用户连说三遍“停”Agent 还在继续执行旧任务的情况。5.3 消息协议务必轻量化不要过度设计端侧多 Agent 的消息传递协议我的原则是尽量精简。见过有人设计复杂的消息事件总线、订阅发布模式、消息路由规则在端侧这纯属过度设计。内存资源和算力都有限复杂的消息框架本身就在争夺资源。端侧多 Agent 之间的消息传递只需要四个字段发送者、接收者、消息类型、内容对象。消息类型用整数枚举而不是长字符串解析快、占内存少。队列长度也要限制比如最多缓存 20 条消息超出后按优先级丢弃低优先级消息。消息缓存持久化不是首要需求Agent 之间短连接通信丢了消息就让上层重试没必要引入消息持久化组件增加额外负担。节点间的通信如果走 IPC 或者网络协议一定要用简单的文本格式而不是序列化大对象。在一个 Agent 场景里每个 Agent 的状态都包含模型上下文如果消息传递时把上下文拷贝一份每个消息都会是几 MB 的巨无霸内存瞬间就被打满。正确做法是消息里只传 message_id 和任务片段Agent 自己的上下文留在各自进程里。6. 写在最后先把地基压实再谈上层建筑这篇文章讲到的模型部署、执行骨架、工具调用链路到多 Agent 协作是我在端侧 Agent 工程化项目中反复验证过的核心环节。给你几个我个人的实操体会。第一个体会量化和精度评估一定要用“Agent 真实任务”来测不要只测语言模型的标准 benchmark。工具调用成功率、JSON 输出稳定性、多轮任务完成率这三个指标比困惑度更能反映端侧 Agent 的可用性。第二个体会上下文管理要用“指标驱动”的方式去优化。每轮对话后记录上下文 token 数、工具调用步数、推理耗时。连续观察几天数据你就能精准发现哪里该压缩、哪里该缓存、哪里该改工具描述而不是凭感觉调参。第三个体会宁可少做功能也别让 Agent 做事做到一半崩溃。端侧 Agent 最伤用户体验的瞬间不是“做不到”而是做了几步之后突然卡死、白屏、或者把用户数据搞乱。降级、超时、权限校验、异步执行这些“不性感”的工程细节才是端侧 Agent 能稳定落地的真正保障。下一篇我会继续展开 Agent 工程化的下半部分持久化记忆与知识库、更细的并发控制、以及跨设备迁移等场景。如果你正在做端侧 Agent 的工程化建议先把这一篇的几个关键点落地验证一遍尤其是“模型不直接触达系统调用层”和“上下文 token 分布可视化”这两项它们能帮你避开端侧 Agent 项目里绝大部分的返工坑。