企业官网建设流程全解析

很多做端侧 Agent 的朋友，一开始都会把它理解成“把云端的 Agent 搬到手机上跑”。我前两篇聊了端侧 Agent 的定位和基础架构，这篇《Agent 工程化（上）》想直接踩进更疼的地方：当 Agent 真的变成一个常驻在用户设备里的运行时，你要面对的不再是“模型能不能答对”，而是内存、电量、工具调度、上下文管理、崩溃恢复这一堆工程问题。模型能力只决定 Agent 的上限，工程化才决定它能不能活着到达那个上限。

这期内容主要针对两类读者：一类是正在把端侧 Agent 从 Demo 推向真机验证的研发，另一类是准备在团队里立项做端侧 AI 应用的技术负责人。我会把我自己踩过的坑、实测过的数据、反复修正过的方案直接摊开来讲，不绕弯。

1. 端侧 Agent 的真实场景集：不是中台，是“单机事务执行器”

先说一个我反复跟团队强调的观点：端侧 Agent 不是缩小版云 Agent，它的运行范式更接近一个“单机事务执行器”。云端 Agent 可以靠弹性扩容、模型多次调用、长链路编排来解决问题，端侧不行。设备就是你的全部资源池，用户在锁屏状态下点了一下，你得在几百毫秒到几秒内给反馈，而且这个反馈还要尽量少耗电、少发热、少占内存。

1.1 端侧 Agent 到底在处理什么类型的任务

从场景上看，端侧 Agent 适合处理四类任务：一是设备内信息的提取和融合，比如从短信里识别验证码、从邮件里解读行程、从相册里找到某张票据；二是跨应用的轻量操作，比如帮你创建一个提醒、查一下日历空档、把某段文本转发到备忘录；三是本地知识的问答和摘要，比如总结聊天记录、解释文档段落；四是隐私敏感内容的本地处理，比如健康数据、支付凭证、通话录音的文字化分析。

这四类任务有个共同特征：逻辑闭环可以在设备内完成，不需要依赖云端知识库或云端大模型能力。这正是端侧 Agent 能站住脚的根基——不是因为它比云端模型聪明，而是因为它让数据不出设备，响应更可控，离线也能跑。

1.2 端侧环境的三道硬约束：算力、内存、功耗

工程化的第一步永远是画边界。我这里给一个粗粒度的参考，你拿来做预算或者跟团队对齐非常有用：

这里多说一句，内存约束在 Android 上尤其阴险。系统在低内存时可能直接杀死后台进程，如果你把 Agent 的上下文全部放在进程内不做持久化，用户切到别的应用再回来，Agent 的“记忆”就没了。所以端侧工程化的一个隐藏必修课是：把 Agent 设计成可被杀、可恢复、可续传的状态机，而不是一个长连接式的常驻对象。

1.3 一个完整的单机事务：从“帮我定个明天上午的闹钟”说起

为了让你对“单机事务”有体感，我拆一个最简单的任务：用户说“明天上午九点提醒我带身份证”。

端侧 Agent 的处理路径是这样的：语音或文本入口触发 Agent 识别意图 → 判断需要调用系统闹钟/提醒工具 → 解析出“明天上午九点”“带身份证”两个槽位 → 调用本地提醒接口 → 返回创建结果并播报确认。

就这么一个看似简单的事，工程化以后要处理的问题包括：系统时间时区的换算、提醒工具权限是否已授予、重复表达（“上午九点”和“9:00”和“明早九点”）的归一化、创建成功后的状态回读。任何一个环节出错，用户感知就是“这 Agent 不太聪明”。而实际上大部分错误不是模型笨，是工程链路缺了校验和回退。

2. 模型选型从来不只是“跑得动”：函数调用能力决定 Agent 架构

很多团队选端侧模型时只看跑分和内存占用，这是个大坑。对于端侧 Agent，模型最重要的单项能力不是通用问答，而是函数调用（function calling）。模型能不能从用户指令中准确抽出工具名和参数，直接决定了你的 Agent 能做多复杂的任务。

2.1 函数调用不是赠品，是 Agent 与工具的通信协议

我把函数调用理解为一种特殊的输出协议：模型在回答用户问题之前，先输出一个结构化的“工具调用请求”，Agent 框架拦截这个请求，执行真正的工具，把结果回填给模型，模型再生成最终回复。

这个协议如果模型不支持或者支持得很弱，Agent 就退化成“聊天机器人加规则触发”——只能靠关键词硬匹配，做不到真正的意图理解。所以选型时你要看的不只是这个模型的数学题得分，而是它在你定义的工具集合上的“选择准确率”和“参数抽取准确率”。

2.2 1B 级别模型与 7B 级别模型的真实差异

我实测过几类端侧模型，区别非常明显。1B 级别的模型在单工具、单参数场景下能用，但在多工具、多参数场景下经常犯两类错误：一是工具名混淆，把create_reminder写成create_remineder；二是参数凭空捏造，用户没说手机号，它给你补一个 138 开头的号码进去。7B 级别的模型明显好一些，能理解一些省略和指代，但代价是内存占用和功耗成倍上升。

所以工程上有个朴素原则：能用小模型解决的问题，不要轻易上大模型；但必须上大模型才能解决的工具调度，也不要硬撑。比如只做闹钟、提醒、查询日历这三板斧，1B 足够；但如果要 Agent 在复杂文档、多个应用之间做协调决策，7B 是底线。

2.3 针对函数调用能力的选型测试方法

很多公开 Benchmark 和你真实场景差得很远。我建议你构建一套自己的“工具调用集测试”，步骤非常简单：

1. 从你的真实用户场景里抽 30~50 条指令，覆盖单工具和双工具调用；
2. 整理成输入输出对，输入是用户话术，输出是期望的工具调用 JSON；
3. 用同样的 prompt 模板跑目标模型，统计工具名准确率、参数完整率、多余参数率；
4. 额外测一下“拒绝调用”能力——用户说了一句跟前置工具无关的话，模型应不应该返回 no tool call，这个很重要，避免误触发。

这套测试不需要复杂指标，几百行脚本就能做，但它能帮你过滤掉一批“看起来聪明、用起来乱调用工具”的模型。

3. 工具编排不是写函数，是给 Agent 写“执行保险”

端侧 Agent 的工具编排，和传统的函数调用链完全不是一回事。传统编程里，函数签名是编译器帮你检查的；在 Agent 里，函数签名是模型帮你“猜”的。所以工具层必须自己承担校验、纠错、兜底的责任。

3.1 工具定义的三个层次：声明、校验、调度

工具定义不能只写“函数名+参数列表”，至少要分三层来设计。

第一层是声明层，给模型的 schema。这里有个关键细节，description 写得越具体，模型抽参越准。比如一个创建提醒的工具，参数说明里要写清楚“date 只接受 YYYY-MM-DD 格式，time 用 24 小时制 HH:mm”，模型就不容易输出“明天上午九点”这种原始文本。

第二层是校验层，给运行时。模型输出的 JSON 必须经过实际校验，包括类型检查、枚举检查、范围检查。比如：

def validate_reminder_params(params: dict) -> bool: if params.get("date") is None: return False if not re.match(r"^\d{4}-\d{2}-\d{2}$", params["date"]): return False if not (0 <= int(params.get("hour", 0)) < 24): return False return True

这一层的主要作用是拦截模型幻觉，避免一个不存在的歌曲名、一个越界的时间戳被直接传给系统接口。

第三层是调度层，给执行引擎。这里要处理优先级、互斥、并发的规则。比如用户在通话中，Agent 就不应该自动调用扬声器播放语音播报；屏幕处于锁屏状态，涉及敏感信息展示的工具应当被拦截。这类规则不属于模型能力，属于业务防护，必须在调度层写死。

3.2 超时、重试、幂等：端侧最容易翻车的三个环节

我见过最多的线上问题，不是模型答错，而是工具调用链路里的“不确定性”。

先说超时。端侧工具调用有两种超时：模型生成超时和工具执行超时。模型生成超时好理解，工具执行超时则常常被忽略。比如 Agent 调一个查询本地相册的工具，图库索引没建好，可能几秒也不返回。工程上我习惯给每个工具设独立的超时阈值，比如日历查询 500ms，本地文件检索 2s，长文本摘要 5s。超时后不能死等，要立即返回一个可读的失败信息给模型，让它换路。

再说重试。模型第一次调用工具失败，有时候是参数格式问题，修一下就可以重试；有时候是模型本身选错了工具，重试永远失败。所以重试必须带诊断信息回嚼，把“这次失败的原因是参数 date 格式非法”塞回上下文，让模型重新决策。

最后说幂等。高频翻车点是用户连点两次“创建提醒”，如果工具没有幂等保护，就会建出两个一模一样的提醒。我的做法是给每次 Agent 会话生成一个全局 request_id，工具层根据这个 ID 做去重，确保同一个用户意图只执行一次写操作。

3.3 工具参数的反向注入与上下文污染

这一个是比较隐蔽的坑。模型执行完工具后，会把工具结果加到上下文里。如果工具结果很长，比如一个本地文档全文摘要输出了几千字，下一轮推理的上下文就被污染了——不仅变慢，KV Cache 占用还暴涨。更麻烦的是，工具结果里如果包含一些程序性字符（比如 JSON 转义符），模型下一轮可能被带偏。

我现在的做法是：工具结果回填前要做“瘦身”，只保留模型决策真正需要的信息。比如查询日历，不需要把整天的事件摘要全塞进去，只要返回“有空闲、空闲时段、冲突项数”这三类紧凑信息。这样既省上下文空间，也降低模型被无关信息干扰的概率。

3.4 回退策略：模型不可靠时，规则兜底

端侧工程化的最后一层保险是规则引擎。我会给关键路径写一组“如果模型调用异常，就走规则”的后备链路。比如用户说“提醒我明天带伞”，模型应该调用 create_reminder。但如果模型输出乱码、或者直接返回了一段自然语言而没有工具调用，规则层可以做一个轻量的正则匹配，把“提醒我 + 时间 + 事项”这个槽位模板接住，直接改走结构化解析，然后创建提醒。

不要觉得这是脱裤子放屁。端侧模型受限于容量，输出稳定性不可能达到云端大模型的水准。规则兜底不是替代模型，而是给模型的最坏情况买了一份保险。这套“模型优先，规则兜底”的架构，能让整体任务成功率从 70% 拉到 90% 以上。

4. 上下文窗口的工程化：压缩、遗忘与隐私边界

上下文窗口在端侧比在云端尖锐得多。云端可以靠加大窗口、多轮重读来弥补；端侧窗口小，KV Cache 占内存，推理时间跟上下文长度直接挂钩。同一个 3B 模型，上下文从 2K 拉到 8K，单次推理延迟可能从 300ms 涨到 1s 以上，耗电也跟着涨。

4.1 为什么说上下文是端侧最贵的内存

很多人只盯着模型加载占多少内存，忽略了运行时的 KV Cache。我实测过，大部分主流端侧推理引擎，上下文长度每增加一倍，KV Cache 内存占用基本线性上升。以 7B 模型、4bit 量化、8K 上下文来算，光是 KV Cache 就可能吃掉近 1GB 内存。这个数在旗舰机上尚可接受，但在 8GB 内存的机器上，跟其他应用抢内存时必然被系统回收。

所以我跟团队定的原则是：上下文按预算分配，不按需求分配。给 Agent 会话预设一个上下文硬顶，比如 4K token，一旦达到阈值，立刻触发压缩策略，而不是无限撑大。

4.2 分块重写、摘要压缩、向量召回三种策略的取舍

我实际尝试过三种上下文压缩策略，各有适用场景。

分块重写适合 Multi-turn 对话。把早期的完整对话按回合切块，只保留每轮的“用户核心诉求 + 最终工具执行结果”，把中间的思考过程全部丢掉。这样做信息损失小，实现也简单，代码量大概两三百行。

摘要压缩适合长文档和长对话。定期把前面的历史摘要成一段话，放到上下文最前面当“全局记忆”。这个策略的问题是摘要本身有信息丢失，而且摘要过程还要跑一次模型，有额外耗时。我的经验是，不要每轮都摘要，可以每 5~8 轮做一次，摘要触发尽量挪到后台空闲时段。

向量召回适合知识型场景。把工具结果、文档片段切段向量化，存到本地向量库。每次新指令进来，先用嵌入模型召回 top3 相关片段，再拼接当前上下文。这个方案最灵活，但会引入额外的嵌入推理开销和检索延迟，在低端机上要慎用。

4.3 隐私边界：本地存储也有“被泄漏”路径

端侧 Agent 的卖点之一是隐私，但工程上要做的远比“数据不出设备”多得多。即使数据在本地，依然有几个容易被忽略的泄漏路径：日志系统可能把上下文明文写出；用户在进程被杀后重启 Agent，如果持久化缓存没有加密，数据会躺在磁盘上；第三方输入法如果接管了文本输入，Agent 的内容也可能经输入法通道外泄。

我现在的做法是所有会话持久化默认加密，日志脱敏，工具返回的敏感字段打码后才进上下文或者可观测系统。记住，隐私不是一个开关，而是端侧 Agent 整个工程链路里的默认约束。

5. 推理运行时与生命周期：常驻进程的电源管理

端侧 Agent 做的是“常驻智能”，推理运行时就必须像系统服务一样被管理，而不是用完即走。这个部分我踩过不少坑，挑最值得说的讲。

5.1 引擎选型的潜在暗坑

选推理引擎不能光看峰值性能，关键要看三个指标：冷启动速度、静置内存、以及 CPU/GPU/NPU 之间的动态切换能力。

冷启动速度影响的是用户感知。用户点开一个智能摘要入口，如果模型加载花了两秒钟，前面所有优化都白做了。我常用的方案是“模型预热 + 懒加载”：应用启动时先加载小参数占位，等到第一个 Agent 任务真正进来后再加载核心模型；或者在系统负载低的时候后台预加载，用额外的空闲内存换取用户零等待。实测下来，旗舰机上把 1B 模型的首次加载从 1.5s 压到 300ms 内是能做到的。

静置内存容易被各家 SDK 的宣传掩盖。有些引擎宣称“极低内存占用”，实测却发现它为了常驻会额外申请大块显存缓存。我建议直接在你的目标设备上实测冷启、静置 10 分钟、推理解锁内存三个阶段的内存水位，用这个数据选型，别信 PPT。

5.2 一个节流实例：当 Agent 遇到连续工具失败

这是我最想分享的一个真实案例。早期版本里，Agent 在锁屏环境下被用户触发了一次多步任务，其中第一个工具调用失败。模型的反应是重新选择工具，又失败，再换一个，还是失败。结果在 20 秒内连续跑了 8 次推理，电量曲线直接垂直。我当时意识到：模型的“顽强”在端侧不是优点，是灾难。

解决思路是给 Agent 加了一个“失败预算”机制。以会话为单位，允许连续工具失败 N 次，第 N+1 次必须中止任务，并给用户播报“当前环境无法完成这个操作，请稍后再试”。这个机制上线后，异常功耗问题基本绝迹。工程上不要把 Agent 当成一个越挫越勇的谈判专家，它就是一台耗电设备，需要有保险丝。

5.3 生命周期管理：前台、后台、被杀、恢复

端侧 Agent 的生命周期比传统 App 复杂。我总结为四个状态：前台激活，后台待命，被系统回收，恢复续传。

前台激活时要响应快、占用高一点没关系；后台待命时要尽可能释放资源，模型可以被卸载，只留一个轻量状态代理；被系统回收是最常见的情况，所以 Agent 的会话状态必须持久化，恢复时把上下文重新灌回去。这里有一个容易踩的坑：模型卸载后重新加载，如果上下文里还挂着旧的会话引用，会有一堆指向临时对象的内存泄漏。所以我在恢复逻辑里强制要求：先做一次上下文压缩和重写，再重新构造请求，绝不复用旧对象。

6. 端侧 Agent 的可观测性：让“设备上发生了什么”可复现

端侧 Agent 有一个天然痛点——它跑在用户口袋里，出了问题你根本看不到现场。云端可以拉日志、看 tracing、回放网络包，端侧数据又涉及隐私，你没法随便回传。所以可观测性的核心思路是：在不出设备的前提下，把现场“拍照”留下来。

6.1 字段级埋点与本地回放

我建议端侧 Agent 的会话记录不要只记“有没有成功”，而是记一串结构化的轨迹事件：用户原始输入 → 模型完整输出（包括思考过程、工具调用 JSON）→ 校验结果 → 每个工具的入参、出参、耗时 → 上下文压缩动作 → 最终回复。这些事件全部落成一条 JSONL 文件，本地滚动保留最后 N 条会话。

一旦用户上报“Agent 刚才做错了”，你可以让用户把这份 JSONL 导出给你。因为里面全是本地数据，不涉及云端，合规风险小，而且基本能还原当时的每一步。这个能力在灰度期救过我太多次，很多模型抽参问题、工具调度问题、上下文污染问题，都是靠这种回放定位的。

6.2 三类必须跟踪的核心指标

端侧 Agent 的指标体系和云端很不一样，我不看响应延迟这一个数字，而是分三层看。

第一层是意图识别准确率，也就是用户的指令有没有被正确分解为工具调用组合；第二层是工具执行成功率，包括参数校验失败率、超时率、幂等去重率；第三层是资源健康度，包括推理内存峰值、电量消耗速率、CPU 温升曲线。这三层指标合在一起，才能判断一个端侧 Agent 是“能用的 demo”还是“可发布的系统”。

6.3 灰度发布与 A/B 的端侧做法

端侧模型的更新不像云端那么顺滑，你不能指望用户主动升级大包。我惯用的做法是把模型文件做成独立模块，支持后台静默替换。灰度时先放 5% 用户，对比新旧模型在意图识别准确率、工具调用失败率、平均推理耗时和功耗这几个维度上的差异。

另一个细节是模型版本要和 Agent 引擎版本解耦。模型可以单独回滚，引擎逻辑可以单独回滚，两者相互不影响。这样一次线上事故的爆炸半径能控制在一个可替换的单元内，而不是整个客户端都跟着动弹不得。

把这个链路做完，端侧 Agent 的“工程化”才勉强算走完了上半程。还有关于模型量化精调、系统接入调优、多端协同这些内容，我放到《Agent 工程化（下）》里继续聊。如果你正在做端侧 Agent，希望这篇能让你少踩几个我踩过的坑。