端侧 Agent 的工程化，聊到“下篇”这个位置，基本上就是在解决一个很现实的问题：demo 能跑和能上线之间，到底差了什么。很多团队做端侧 Agent，第一版都是在 PC 或者开发板上把模型跑通、让 Agent 能调用一两个工具，感觉“成了”。但真正走到产品化，要面对的是模型怎么塞进有限内存、硬件平台怎么适配、任务并发怎么控制、记忆怎么落盘、以及最容易被忽略的——端侧这套东西怎么保证安全和可维护。这篇是系列第四篇，也是工程化的下篇，我打算把这些“从能跑到能交付”的硬骨头逐个拆开讲。
标题里的“端侧 Agent”说的不是云端那种有大模型集群撑腰的 Agent，而是把模型和 Agent 运行时都压在本地设备上的方案。适合谁来读？如果你正在做端侧 AI 硬件部署、Agent 应用开发，或者你只是好奇一个跑在手机和 IoT 设备上的智能体到底怎么设计，这篇都能给你一套可以照着落地的思路。
1. 端侧 Agent 工程化的整体架构拆解
1.1 先分清 Harness 和 Agent 的边界
工程化第一步不是写代码，而是把架构边界划清楚。很多人把 Agent 做成一个大而全的类，模型推理、工具调用、上下文管理全塞在一起，前期跑起来很爽，后期改一个功能就得动全身。我的习惯是严格区分Harness（运行时容器）和Agent（智能决策体）两个层面。
Harness 负责的是“环境”这件事：模型加载与生命周期管理、推理引擎的封装、流式输出的通道、工具注册表、内存和线程资源分配。它不关心 Agent 下一步要干什么，只保证 Agent 想干什么的时候，有稳定的基础设施可用。Agent 则是纯“决策层”：接收用户输入，维护上下文，决定调用哪个工具，解析工具返回结果，规划下一步动作。
这个分层在端侧尤其重要。云端 Agent 挂了可以快速重启，资源池随便拉，端侧则是资源本身就很紧张，如果 Harness 和 Agent 混在一起，一个工具调用卡死就可能拖垮整个进程。把 Harness 独立出来之后，我可以给工具调用做超时熔断、给推理引擎做进程级隔离、给记忆模块做独立缓存，Agent 层崩了最多重启决策循环，底层模型服务不受影响。
类比一下就是：Harness 是汽车的底盘、悬挂和变速箱，Agent 是司机。底盘不好，换再好的司机也跑不了长途；底盘稳了，司机怎么开都有底气。端侧工程化第一步，就是先把底盘和司机分清楚。
1.2 端侧不同于云端的工程化约束
脱离硬件谈端侧 Agent 架构都是空谈。云端考虑的是吞吐量和弹性扩缩容，端侧考虑的是内存上限、功耗、发热、以及碎片化的硬件平台。我自己做端侧部署时，最看重的四个约束指标：
- 内存预算：端侧设备内存是固定的，模型权重、KV cache、Agent 运行时、工具执行栈全要在这块内存里共存，规划不好就是频繁 OOM。
- 算力形态：不同设备有 CPU、GPU、NPU 之分，同样的模型在不同算力单元上的性能和精度差异极大，需要做到运行时动态调度。
- 功耗与散热：连续推理会导致设备发热降频，推理速度断崖式下跌，工程上要做任务间的冷却间隔和功耗监控。
- 离线环境：端侧 Agent 不能假设随时有网，模型、技能包、知识库全部要支持离线更新和离线推理。
这四个约束直接决定了后面所有设计选择。比如“模型体积压缩到多少才合适”这个问题，不是拍脑袋定的，而是先算清楚设备给 Agent 划分的内存预算，再反推模型量化方案。
1.3 端侧 Agent 的分层架构参考
基于上面的约束，我一般把端侧 Agent 分成四层来组织工程代码：
- 硬件抽象层：封装推理引擎、传感器、系统 API，对上提供统一接口，对下适配不同芯片平台。
- 运行时层（Harness）：模型生命周期管理、上下文管理、工具注册与调度、任务队列、资源监控。
- 智能层（Agent）：意图识别、规划决策、工具选择、记忆读写、输出生成。
- 应用层：交互界面、业务逻辑、用户数据管理。
这四层之间严格单向依赖，下层不依赖上层。这么设计的好处是测试可以分层做，硬件抽象层用 mock 测，智能层用真实模型但固定工具链，应用层可以独立做 UI 迭代。端侧 Agent 本身迭代就比云端慢，分层不清会导致每次改动都要全链路回归，非常痛苦。
2. 模型压缩、加载与推理链路的关键细节
2.1 模型量化与内存预算怎么算
端侧部署的第一步是选模型、定量化。很多新手上来就想塞一个 7B 甚至 13B 模型的量化版，结果内存一算直接劝退。这里给一个简单实用的估算公式：模型权重内存 = 参数量 × 每参数比特数 / 8。比如 3B 模型用 int4 量化，权重占用就是 3 × 10^9 × 4 / 8 = 1.5GB。再加上 KV cache、激活值、Agent 运行时开销，整机内存至少得留 3-4GB 才稳。
这里有个经验：端侧 Agent 模型参数量建议在 0.5B 到 8B 之间，且优先选择 int4/int8 量化后权重体积小于设备空闲内存三分之一的模型。如果量化后还是超标，就得考虑裁剪层数或者用蒸馏版的小模型。我踩过最大的坑是只算了权重内存，没算 KV cache。上下文窗口调到 4K 后 KV cache 能吃掉几百 MB，运行时直接卡死。现在每次定方案，我都会先列一张内存预算表，把模型权重、KV cache、Agent 运行时、临时缓存逐项填进去，不够就降上下文长度或者换更小的模型。
2.2 推理引擎选型与硬件适配
端侧可选的推理引擎不少，各家 NPU 的 SDK 也各不相同。我的建议是：推理引擎不要直接写在业务代码里，而是封装在硬件抽象层后面。这样换引擎就是换底层实现，智能层完全无感。
选型标准我一般看四点：
- 算子覆盖度：目标模型里的算子（比如某些 attention 变体）在引擎里是否都有高效实现
- 内存管理方式：是否支持显式内存池，避免推理过程中的频繁分配和释放
- 多平台支持：是否同时覆盖 CPU/GPU/NPU，同一套代码跨设备跑
- 量化工具链：是否能方便地把模型量化并导出为引擎支持的格式
实操中我遇到过几次模型量化后精度掉得没法用的情况，后来排查发现是引擎不支持某些算子，自动降级到 CPU 实现，速度和精度全崩。所以选引擎之前，先把你目标模型的算子列表导出来对一遍，比看什么性能测试报告都管用。
2.3 冷启动优化与模型预热
端侧 Agent 体验差，很多时候不在推理速度，而在冷启动。应用一点开，先加载模型、初始化引擎、构建上下文，这一套下来好几秒，用户直接卸载。解决思路是把“加载”这件事拆成两段：首帧快出 + 全量后台加载。
实际操作上，我建议启动时先加载一个极小的意图分类模型（比如 10MB 级别的），让用户输入框立刻可用。用户输入的同时，后台加载主模型，加载完成后再无缝切换。这个“先小后大，先快后全”的策略在手机和嵌入式设备上都很好用。另外一个细节是常驻内存：如果设备内存允许，模型加载后不释放，下次进入直接走 warm path，配合内存池复用，推理延迟能降低 30%-50%。
3. 完整实操：端侧 Agent 任务执行管线落地
3.1 技能体系的注册与调度
Agent 光会聊天没用，能执行任务才是价值所在。工程化里，我把每个工具能力封装成Skill（技能），并且做成可注册、可枚举、可升级的模块。
Skill 的注册表是一个关键设计。每个 Skill 需要有唯一的名称、描述、输入输出 schema、权限级别、超时时间。Agent 决策时拿到的不是内部函数，而是这份注册表的元信息，由它来决定调用哪个技能。这样做的好处有三个：
- 智能层只和 schema 打交道，不感知实现细节，新增一个技能不需要改 Agent 核心逻辑
- 技能可以独立发布和更新，端侧支持热更新技能包，不用整包升级
- 权限收敛可以在这一层做，敏感操作（发送消息、删除文件等）要求更高授权等级
3.2 流式输出与任务中断恢复
端侧 Agent 执行一个复杂任务往往需要多轮推理和工具调用，如果中间被用户打断，或者系统资源紧张导致任务挂了，不能直接丢状态。这里我建议实现一套基于事件的任务状态机。任务状态分为 pending、running、paused、completed、failed，每个关键步骤都持久化一个状态快照。
具体到实操：每完成一次工具调用，就把当前的上下文、工具调用历史、已有结论序列化到一个本地状态文件。任务重新启动时，先读状态文件，跳过已完成步骤，继续执行未完成部分。中断恢复是端侧 Agent 非常容易忽略但用户感知极强的一项能力，一个能记住做到哪儿的助手，和一个每次都要重头开始的助手，体验差距是数量级的。
3.3 端侧怎么“扛并发”：不硬扛，要限流
端侧设备不是服务器，没有扛高并发的物理条件。与其想办法并发推理，不如做请求排队和任务优先级。端侧同时只会有一个 Agent 推理任务在跑，其他请求全部进队列，这不仅是性能问题，也是保证 KV cache 不互相污染的唯一办法。
我常用的一套参数是：普通请求队列最多排 10 个，超过直接返回“稍后再试”；优先级较高的请求（比如用户实时对话）可以插队；每个请求的最大等待时间控制在 2 秒内，超过就告知用户当前繁忙。这套机制配合前面说的中断恢复，用户体验不会比云端差多少，因为用户感知到的是“它在忙但知道我在等”。
4. 记忆管理与上下文工程化
4.1 记忆分层：工作记忆、短期记忆、长期记忆
端侧 Agent 没法像云端那样无限拉长上下文，所以记忆必须分层管理。我实践的方案是三层：
- 工作记忆：当前会话内的上下文，直接放在模型上下文窗口里，存对话轮次、工具调用结果。
- 短期记忆：当前会话的完整历史，按需写入本地缓存文件，会话中断后用于恢复。
- 长期记忆：跨会话的用户偏好、历史结论、知识片段，通过向量化存储和检索按需加载。
这三层的读写频率差异很大。工作记忆每个推理 step 都要读写，短期记忆在任务状态切换时写，长期记忆只在特定时机（用户明确要求、任务完成总结）才写。长期记忆不能每轮对话都写，否则不仅性能扛不住，还会存一堆垃圾信息，检索质量急转直下。
4.2 长期记忆落盘与检索的关键点
端侧长期记忆的落盘格式，我建议用 SQLite 加向量索引的组合。每条记忆有结构化字段（时间、来源、类型、重要性）和向量字段（语义特征）。检索时先按重要性过滤，再做向量相似度召回，最后用重排模型挑最相关的几条注入上下文。
这里有个容易踩的坑：向量化模型本身也是模型，在端侧做检索同样要跑推理。我曾经把向量库塞到几千条后，每轮对话检索耗时飙升。后来改成“分层召回”：先用关键词粗筛（SQLite 的 FTS5 就行），把候选集压到几十条，再对这几十条做向量排序，耗时降了一个数量级。
4.3 Token 预算控制：把上下文当内存管理
端侧模型上下文窗口有限，所以每一轮对话都要做预算管理。我的习惯是给上下文分三个预算池：系统提示词固定占用 20%，记忆注入最多 30%，剩余 50% 留给当前对话和工具结果。每次新请求进来，先算当前占用，超了就触发压缩策略。
压缩策略从轻到重依次是：丢弃最旧的对话轮次、摘要历史对话、精简工具输出、丢弃不相关的长期记忆。这套机制写起来不复杂，但对整体体验的提升非常明显。很多端侧 Agent 越聊越笨，就是上下文被垃圾信息塞满了，预算管理可以保证模型的注意力永远集中在重要内容上。
5. 安全机制与沙箱隔离
5.1 权限收敛：Agent 不是超级用户
端侧 Agent 能调用系统 API 是卖点，但也是最危险的地方。一个被提示词注入的 Agent，可以读取通讯录、发送短信、删除文件。所以权限体系必须在 Harness 层做，而不是在 Agent 决策层做。
我把权限分成四级：无权限（只能聊天）、低权限（读取非敏感数据）、中权限（读+写应用内数据）、高权限（系统级操作）。Agent 提一次调用请求，Harness 检查该 Skill 的权限等级和当前用户的授权状态，不匹配直接拦截。个别高风险操作还要二次确认弹窗，这个交互虽然打断流畅性，但安全上值得。
5.2 输入输出护栏
端侧 Agent 的输入输出都需要护栏。输入端要检测并拦截恶意构造的查询，比如试图让模型执行违规操作、混淆身份、诱导越权的内容。输出端要检查模型生成结果，防止生成违规内容、泄露隐私信息、或者包含误导性的虚假信息。
工程化实现上有两种做法：一种是规则加分类模型组合，规则层先拦截明显的违规输入，分类模型兜底识别复杂恶意内容；另一种是纯粹用另一个小模型做审核员，对 Agent 的输出做二次判定。端侧算力有限，我用得最多的是第一套组合，而且会把大部分规则做成离线可更新的配置文件，这样不用为了更新审核规则发新版本。
5.3 沙箱隔离与数据安全
工具调用执行环境必须隔离。能跑在独立进程的就独立进程，能放在容器里的就放容器，至少也要用受限的用户态权限来执行。恶意技能包如果直接获得应用全部权限，等于给攻击者开后门。还有数据安全：模型输入输出、记忆库里的用户数据都要加密存储，传输走安全通道，本地日志里不能出现明文的敏感字段。
6. 常见问题与排查技巧实录
6.1 端侧 Agent 常见故障速查表
实际项目里问题五花八门，但高频故障其实集中在几个点，我整理了一张速查表：
| 故障现象 | 常见原因 | 排查思路 | 解决方案 |
|---|---|---|---|
| 启动后闪退 | 模型权重加载内存溢出 | 看崩溃日志中内存占用，确认是否量化+缓存叠加超预算 | 降上下文长度、换 int4 模型、延迟加载非核心模块 |
| 推理速度越来越慢 | 设备发热降频启动 | 监控 CPU 温度，对比刚启动和半小时后的推理耗时 | 任务间加冷却间隔，降低连续推理频率 |
| 工具调用后 Agent 卡死 | 工具超时未处理 | 查工具执行状态，确认是否有死锁或长时间阻塞 | 给每个 Skill 强制设置超时，超时返回错误信息给 Agent |
| Agent 回复质量突然下降 | 上下文窗口被占满 | 打印上下文 token 占用，看是否大量冗余信息 | 触发压缩策略，清理旧对话和无效工具结果 |
| 检索记忆不准 | 向量库污染 | 抽样检查入库记忆质量 | 提高入库阈值，增加重要性过滤，定期清理低价值记忆 |
| 换设备后精度异常 | 量化格式与硬件不适配 | 对比同一模型在不同引擎下的输出 | 按平台重新校准量化参数，必要时回退 int8 |
6.2 排查工具与调试方法
端侧 Agent 的调试比云端难，因为看不到实时日志、不好打断点、设备资源又有限。我强烈建议在 Harness 层从一开始就埋点：每次推理记录模型名、输入 token 数、推理耗时、内存增量；每次工具调用记录 Skill 名、参数、耗时、返回状态；每次记忆读写记录类型、条数、耗时。这些日志统一走一个环形缓冲区，平时不落盘，崩溃时自动导出。
这套“故障回放”机制帮我解决过很多诡异问题。有一次用户反馈 Agent 偶尔回复乱码，现场复现不了。后来回放日志才发现，是某个工具返回了一个超长字符串，把上下文预算撑爆后触发压缩，模型注意力全乱了。没有埋点，这种问题基本无解。
6.3 工程化过程中我最后悔没早点做的事
端侧 Agent 工程化做久了，我有几个很深的体会，现在每次开新项目都会提前安排好，也算是给大家的避坑建议：
第一，可观测性从第一天就要建，不要等出问题再补。端侧设备拿不到现场，日志和回放能力就是你唯一的眼睛。第二，版本管理要覆盖模型和技能包。Agent 代码版本一致但模型版本不同，行为可能天差地别，部署清单里必须锁死模型哈希。第三，端侧 Agent 的测试要分三层：单元测试覆盖决策逻辑、集成测试覆盖工具链路、真机测试覆盖硬件适配。我在很长一段时间只做集成测试，结果模型换了个版本后单元逻辑没跑通，排查浪费了大量时间。
还有一个很实用的习惯：保持一套完整的离线回归用例集。每次更新模型或技能包，先跑一遍用例集，对比输出差异。这个用例集不需要很大，覆盖核心对话场景、高频工具调用、敏感请求拦截这几类就够。它能帮你在发版前拦住大多数回归问题，尤其是端侧这种更新链路长、回滚成本高的环境，提前拦截的价值会成倍放大。
端侧 Agent 的工程化没有银弹，每一类设备都有自己苛刻的面孔。但把 Harness 和 Agent 分清楚、把资源预算和生命周期管理做扎实、把记忆和权限体系当一等公民来设计，这套方法论放到哪一类端侧设备上都适用。我在实践中最大的体会是：端侧 Agent 项目的技术难点很少在“模型够不够聪明”，更多在“这套系统能不能在任何环境下都稳定地让模型发挥出它应有的聪明”。想清楚这一点，工程化的重心就不会跑偏。
