之前在做端侧智能助理落地时，最头疼的问题不是模型效果不够好，而是“模型选型”和“Agent 编排”两条线经常打架。模型太大跑不起来，模型太小又撑不住多轮任务；Agent 框架放到手机端又面临算子兼容、内存抖动、功耗超标等问题。最近 LFM2.5-2.6B 这类中小规模参数模型进入视野，成为端侧 Agents 落地的重要候选方案。本文就从端侧 Agent 的概念出发，结合模型部署与推理优化、最小可运行原型、常见问题与工程建议，把 On-Device Agents 这条技术路径完整拆解一遍。
1. 背景与核心概念
1.1 什么是 On-Device Agent
On-Device Agent，中文常翻译为“端侧智能代理”或“设备端 Agent”，指的是完全在用户终端设备（手机、平板、车载系统、嵌入式开发板、智能家居设备等）上运行的 AI 代理程序。
传统的 Agent 应用大多跑在云端：请求发送到服务器，模型在云端推理，结果返回终端。这种方式能力强大，但依赖网络连接、存在隐私传输链路，同时每次交互都会产生服务端成本。On-Device Agent 则不同，模型推理和逻辑决策都在本地完成，云端的参与降到最低，甚至完全离线运行。
一个完整的 Agent 至少需要具备感知、记忆、规划、工具调用四类能力。在云端方案里，这四类能力可以依靠大规模模型和大内存服务器轻松实现；在端侧，却要面对算力、内存、功耗、模型尺寸的多重约束。因此 On-Device Agent 的核心研究问题变成了：如何在有限的设备资源上，用尽量小的模型完成尽量完整的 Agent 行为链。
1.2 LFM2.5-2.6B 在其中的角色
LFM2.5-2.6B 可以理解为一种规模约 26 亿参数的端侧语言模型。这里要说明一点，关于该模型的公开技术细节、许可协议、评测数据，目前不同渠道的信息并不完整，本文将其作为“中小规模端侧模型”的代表案例来讨论，具体 API、配置项和部署方式请以官方发布说明为准。
2.6B 规模在端侧模型里是一个比较关键的档位。小于 1B 的模型部署非常轻量，但复杂指令跟随、多步推理、工具调用能力明显不足；大于 7B 的模型效果更好，但经过量化后仍然可能接近甚至超过许多设备的可用内存上限。2.6B 处于中间位置：量化到 4bit 之后体积可以压缩到 1.5GB 至 2GB 左右，配合适当的推理优化，能够在高端手机和部分开发板上换取“准可用”的 Agent 体验。
在实际项目中，LFM2.5-2.6B 更适合承担端侧主控模型的角色，负责意图理解、任务拆解和回复生成，而具体的知识检索、计算、系统调用则交给本地工具模块完成。
1.3 为什么端侧 Agent 会成为趋势
端侧 Agent 的兴起，根本原因是用户对隐私、时延和可用性有了更高要求。
首先是隐私。大量个人数据——聊天记录、通讯录、位置、健康数据——如果都要上传云端才能完成智能处理，用户顾虑会越来越大。端侧推理让敏感数据留在设备本地，这是一个重要的产品卖点。
其次是时延。云端 Agent 每次交互要经历“数据上送-服务端排队-模型推理-返回结果”的完整链路，在弱网环境下往往需要数秒甚至更久。端侧推理可以做到几十毫秒到几百毫秒的响应，在多轮对话和实时助手场景中体验优势明显。
最后是可用性。网络断线、偏远地区、地下车库、飞行模式下，云端 Agent 基本不可用，而端侧 Agent 可以保持基础服务能力。这个特性对于智能车载、工业巡检、户外作业等场景至关重要。
1.4 与云端 Agent 的定位差异
不是说端侧 Agent 会取代云端 Agent，二者更多是互补关系。
端侧 Agent 适合：对隐私敏感、对时延敏感、需要离线可用、交互相对标准化、任务链路较短的应用。
云端 Agent 适合：需要大量世界知识、需要多模态复杂推理、需要联网获取最新信息、需要对超长上下文进行深度理解的任务。
业界常见的做法是“端云协同”：端侧模型先做意图判断，难度高或权限受限时再请求云端大模型。这个思路在工程上非常实用，既控制了成本，也保留了能力上限。
2. 端侧 Agent 的技术约束与整体架构
2.1 端侧部署的硬性约束
在搭建 On-Device Agent 之前，必须先了解设备端的物理边界。下面这些限制会直接影响模型选型、量化方案和推理引擎的选择。
内存限制是最大的制约因素。以手机为例，当前主流内存从 8GB 到 16GB 不等，但操作系统、其他应用会占用大量内存，留给大模型的通常只有 2GB 到 4GB。开发板如树莓派、Jetson Nano 之类的设备，可用内存更少。模型加载后不能始终常驻超大显存，必须考虑按需加载或使用低比特量化。
算力限制同样关键。端侧 CPU 擅长并行计算但浮点性能有限，NPU（神经网络处理单元）速度快但算子覆盖不完整，GPU 在部分平台性能好但功耗和发热明显。很多端侧模型推理的失败案例，不是模型本身效果差，而是某个关键算子（比如某些自定义 Attention）在目标 NPU 上不支持，导致被迫回退到 CPU 推理，速度骤降。
功耗与发热也是不可忽视的因素。长时间运行大模型推理会显著增加设备发热，尤其在移动设备上，过热会触发系统降频，表现为“一开始正常，跑几分钟后快速变慢”。因此工程上不仅要优化单次推理耗时，还要控制连续推理频率，避免 Agent 长期占用计算资源。
2.2 典型端侧 Agent 运行流程
一个 On-Device Agent 的完整运行流程可以拆成六步。
第一步是输入接收。用户通过语音、文本或图像等方式发起请求。语音输入需要先在端侧完成语音识别，文本输入则直接送入模型，图像需要先经过多模态编码器。
第二步是意图理解。小型语言模型在端侧先对用户指令进行分类，判断这个任务属于问答、任务执行、控制设备、还是需要请求云端。这个过程要尽量轻量，因为它是 Agent 后续所有决策的基础。
第三步是任务拆解与规划。对于复杂指令，Agent 需要生成一个行动序列。例如用户说“明天早上八点提醒我带伞”，Agent 需要识别出“明天早上八点”是一个时间实体，“提醒我”是一个动作指令，“带伞”是提醒内容。
第四步是工具调用。Agent 根据规划调用本地工具，比如日历接口、提醒服务、天气查询、文件搜索、系统设置等。这一步可能完全不需要语言模型参与，而是通过结构化参数传递完成。
第五步是结果融合。工具返回的结果需要重新拼装成自然语言回复，或者直接触发系统操作。如果是多模态任务，还需要把图片、表格等信息整合进上下文。
第六步是记忆更新。Agent 将本轮交互的关键信息写入本地存储，以便后续对话引用。
整个流程中，语言模型并不是一直参与推理的。优秀的端侧 Agent 会尽量让模型只负责“思考”和“表达”，把重复性、确定性操作交给传统代码模块完成。
2.3 关键模块拆解
接下来逐个拆解端侧 Agent 的核心模块。
推理模块：负责加载模型、执行推理、生成回复。这是整个 Agent 的计算核心。推理模块需要封装成独立适配层，方便替换不同模型与推理引擎。上层 Agent 不应该关心底层是 ONNX Runtime 还是 MNN，只需要拿到输入、输出即可。
记忆模块：端侧 Agent 的记忆分为短期工作记忆和长期持久记忆。短期记忆是当前多轮对话的上下文，长期记忆则是历史对话和用户偏好的持久化存储。由于端侧模型上下文窗口有限，不能把所有历史都灌给模型，必须设计摘要和检索机制。
工具模块：工具是 Agent 与设备交互的桥梁。一个工具通常包含名称、描述、参数 schema 和执行函数。例如“打开手电筒”这个工具，参数为空；而“设置闹钟”工具，参数是时间和标签。
执行与安全模块：执行器负责调用工具并处理返回值。安全模块则进行权限校验，比如执行系统级操作前检查是否获得用户授权，避免 Agent 在无人监督时执行危险命令。
3. 模型部署与推理优化思路
3.1 量化与压缩
端侧部署的第一步通常是模型量化。常见的量化方案有 INT8、INT4 和混合精度。
INT8 量化是相对稳妥的起点，精度损失较小，大多数推理引擎都提供了较完整的支持。INT4 量化可以把模型体积压缩到原来的四分之一左右，是 2.6B 规模模型部署到手机端的常见选择，但要注意部分层（如 Embedding、LayerNorm）可能对量化更敏感，更适合保留为更高精度。
关于量化效果，这里建议用你实际业务数据做验证，不要只看 benchmark 报告。通用评测分数下降一点可能不影响主流程，但某个特定实体识别、特定指令格式可能发生严重退化。在生产项目中，量化后的模型必须放入完整的回归测试集，覆盖主要 Agent 路径。
3.2 推理引擎与算子兼容
端侧推理引擎的选择会直接影响部署成功率。常见的开源推理引擎包括 ONNX Runtime、MNN、TFLite、NCNN 等。不同引擎的算子支持范围、NPU 加速能力、设备兼容性差异很大。
选择引擎时，建议先做一张算子支持清单。把你的模型导出为 ONNX 格式，用引擎的算子检查工具跑一遍，看哪些算子不被当前后端支持。常见的问题算子包括：
- 动态 Shape 相关的算子
- 某些较新的 Attention 变体
- 自定义激活函数
- 部分整数除法、取整类算子
遇到不支持的算子时，解决思路通常有三个方向。一是把模型结构替换为更基础的等价算子组合；二是关闭某些模型选项，例如不使用 attention mask 的动态变化；三是放弃 NPU 加速，回退到 CPU 推理。
3.3 上下文管理与缓存策略
端侧模型的上下文窗口有限，通常在 2048 到 8192 个 token 左右。Agent 多轮交互很快就可能触顶，所以必须设计上下文管理策略。
一个实用的做法是分层上下文：系统提示词始终保持，用户当前指令完整保留，历史对话只保留摘要和关键实体。工具调用返回的结果不要全部放入上下文，只把重要的、需要模型理解的结果片段送进去，完整结果存入结构化存储备查。
缓存策略同样重要。对于固定系统提示词和工具定义，建议使用 KV Cache 预填充，避免每轮对话都重复计算。模型第一次加载的速度也很关键，推荐在应用启动时预热，或者使用“加载一半，推理时再补全”的分阶段加载策略。
3.4 多端适配与监控
真实的 On-Device Agent 不会只跑在一台设备上。不同手机的 CPU 性能、NPU 版本、内存大小差异很大，需要在构建期做多目标适配。
工程上的做法是建立“设备能力分级”。例如高配设备启用 INT4 + NPU 加速，中配设备启用 INT8 + CPU 多线程，低配设备只保留意图识别和简单工具调用，复杂功能自动降级到云端。每台设备在启动时执行一个轻量的性能探测，根据探测结果决定加载哪个规格的模型。
监控方面，端侧模型不像云端服务器那样容易采集日志，建议统一记录推理耗时、内存峰值、功耗估算（可用电池管理接口）和失败样本。日志在设计时就要做本地留存与按需上送，而不是把全部日志直接传到云端，以免引发隐私争议。
4. 实战案例：在开发板上跑一个最小端侧 Agent
下面我们用一个最小原型来演示 On-Device Agent 的搭建思路。示例环境以常见的 Linux 开发板为例，重点展示 Agent 编排逻辑，而不是绑定具体模型。代码中使用的是抽象接口，如果你手头已经有可运行的端侧模型，可以通过适配器直接替换。
4.1 环境与项目结构
建议使用 Python 3.10 及以上版本，安装项目所需依赖。为便于展示，这里把模型推理层抽象成接口，实际部署时再接入你的推理引擎。
项目目录结构如下：
ondevice-agent/ ├── agent.py # Agent 编排主逻辑 ├── model_adapter.py # 模型推理适配层 ├── tools.py # 本地工具注册表 ├── memory.py # 简单记忆存储 ├── config.yaml # 模型与运行参数 └── requirements.txt4.2 模型适配层
先定义一个模型适配接口。实际使用 LFM2.5-2.6B 时，你只需要把generate方法替换为具体推理引擎的调用代码。
# 文件路径：ondevice-agent/model_adapter.py from abc import ABC, abstractmethod class ModelAdapter(ABC): @abstractmethod def generate(self, prompt: str, max_new_tokens: int = 128) -> str: """根据 prompt 生成回复文本""" pass @abstractmethod def get_context_size(self) -> int: """返回模型最大上下文长度""" pass这里不绑定具体实现是因为不同推理引擎的调用方式差异很大。实际项目里，如果你使用 ONNX Runtime，可以在子类中加载量化后的 ONNX 模型并调用会话推理；如果使用 MNN，则加载 MNN 模型并调用解释器。模型适配层隔离了底层差异，使上层 Agent 代码不用频繁改动。
4.3 工具注册表
接下来定义工具注册表。工具是 Agent 与设备交互的桥梁，每个工具包含名称、描述、参数说明和执行函数。
# 文件路径：ondevice-agent/tools.py import json class ToolRegistry: def __init__(self): self._tools = {} def register(self, name: str, description: str, params_schema: dict, handler): self._tools[name] = { "name": name, "description": description, "params_schema": params_schema, "handler": handler, } def list_tools(self) -> list: return [ {"name": t["name"], "description": t["description"]} for t in self._tools.values() ] def call(self, name: str, arguments: str) -> str: tool = self._tools.get(name) if not tool: return f"错误：未知工具 {name}" try: params = json.loads(arguments) if arguments else {} except json.JSONDecodeError: return "错误：参数不是合法 JSON" return str(tool["handler"](**params)) def set_alarm(time: str, label: str = "") -> str: # 这里仅作为示例，实际应调用系统闹钟接口 return f"已设置闹钟：{time}，提醒事项：{label or '无'}" def open_flashlight() -> str: # 实际项目中调用硬件控制接口 return "手电筒已打开"这个工具注册表的优势是结构清晰。新增加一个工具只需要注册一次，Agent 不需要为每种工具写分支判断。
4.4 Agent 编排核心代码
下面是最核心的部分：Agent 主循环。这里的策略是先用规则解析用户意图，如果涉及工具调用，则从模型输出中提取工具名和参数；否则直接返回模型生成的回复。
# 文件路径：ondevice-agent/agent.py import re from model_adapter import ModelAdapter from tools import ToolRegistry from memory import Memory SYSTEM_PROMPT = """你是一个端侧智能助理。请根据用户指令完成任务。 如果需要调用工具，请严格使用以下格式输出： 工具调用：工具名 参数：{"参数名": "参数值"} 不要输出其他无关内容。""" class OnDeviceAgent: def __init__(self, model: ModelAdapter, tools: ToolRegistry, memory: Memory): self.model = model self.tools = tools self.memory = memory def run(self, user_input: str) -> str: # 1. 保存用户输入到短期记忆 self.memory.add_user_message(user_input) # 2. 拼接系统提示词与上下文 context = SYSTEM_PROMPT + "\n\n" + self.memory.build_context() # 3. 模型生成回复 response = self.model.generate(context, max_new_tokens=256) # 4. 解析是否包含工具调用指令 tool_name = self._find_tool_name(response) if tool_name: args_text = self._find_args(response) result = self.tools.call(tool_name, args_text) self.memory.add_assistant_message(f"工具调用结果：{result}") return f"已为您执行：{tool_name}，结果：{result}" # 5. 非工具调用场景直接返回回复 self.memory.add_assistant_message(response) return response def _find_tool_name(self, response: str) -> str: match = re.search(r"工具调用：(\S+)", response) return match.group(1) if match else "" def _find_args(self, response: str) -> str: match = re.search(r"参数：(\{.*?\})", response, re.S) return match.group(1) if match else "{}"4.5 记忆模块
记忆模块负责保存多轮对话。这里采用最简单的短期记忆实现：只保留最近 4 条消息，超过后丢弃早期消息。这个设计是为了控制模型上下文长度。
# 文件路径：ondevice-agent/memory.py from collections import deque class Memory: def __init__(self, max_messages: int = 4): self.messages = deque(maxlen=max_messages) def add_user_message(self, content: str): self.messages.append(f"用户：{content}") def add_assistant_message(self, content: str): self.messages.append(f"助理：{content}") def build_context(self) -> str: return "\n".join(self.messages)4.6 运行与验证
为了验证原型，我们写一个简单的示例脚本：
# 文件路径：ondevice-agent/main.py from model_adapter import ModelAdapter from tools import ToolRegistry, set_alarm, open_flashlight from agent import OnDeviceAgent from memory import Memory # TODO: 这里需要替换为你的真实模型适配实现 class DummyAdapter(ModelAdapter): def generate(self, prompt: str, max_new_tokens: int = 128) -> str: # 模拟模型输出 return "工具调用：set_alarm\n参数：{\"time\": \"07:00\", \"label\": \"起床\"}" def get_context_size(self) -> int: return 2048 if __name__ == "__main__": registry = ToolRegistry() registry.register("set_alarm", "设置闹钟", {"time": "时间", "label": "提醒标签"}, set_alarm) registry.register("open_flashlight", "打开手电筒", {}, open_flashlight) agent = OnDeviceAgent(DummyAdapter(), registry, Memory()) result = agent.run("明早七点提醒我起床") print(result)预期输出：
已为您执行：set_alarm，结果：已设置闹钟：07:00，提醒事项：起床这个示例中，DummyAdapter 模拟了模型输出。切换到 LFM2.5-2.6B 时，只需要把 DummyAdapter 替换为真实模型加载与推理代码，Agent 编排层可以保持不变。这也说明了抽象层设计的价值。
5. 常见问题与排查思路
在实际部署 On-Device Agent 时，以下几类问题最容易出现。
首先是模型加载后内存不足。现象是应用启动后系统被 kill，或者推理过程中出现 OOM。常见原因包括：未使用量化模型、推理引擎的内存池配置过大、模型被重复加载到多个副本。排查时先确认模型文件体积，再查看运行时内存占用。解决方案是切换到 INT4 量化，或调整推理引擎的线程数和内存分配策略。
其次是部分算子不支持导致推理速度骤降或直接失败。现象是模型在某些设备上无法运行，报错信息提到某个算子未实现。此时需要回退到 CPU 推理，或者重写模型结构中的关键层。在选型阶段就做算子兼容测试可以避免后期返工。
第三是量化后 Agent 的意图识别变差。具体表现为原先能识别的指令变得识别不了，或工具调用参数经常错误。建议对量化模型做针对性微调，或者在业务逻辑里增加规则兜底，不要完全依赖模型输出格式。
第四是多轮对话后响应明显变慢。原因通常是上下文越来越长，解码阶段计算量增大，而且 KV Cache 占用内存增加。解决方式是启用记忆摘要、限制上下文长度、定时清理历史。
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 启动后内存不足被杀 | 未量化或量化位宽过高 | 切换 INT4 量化，调整推理引擎内存池 |
| 部分设备推理失败 | 算子不兼容 | 回退 CPU 推理，或改写问题算子 |
| 量化后意图识别退化 | 量化损失影响关键能力 | 针对性微调，增加规则兜底 |
| 多轮后响应变慢 | 上下文过长 | 增加摘要，限制长度，清理历史 |
| 发热严重触发降频 | 连续推理频率过高 | 增加休息间隔，控制加载模型大小 |
6. 最佳实践与工程建议
6.1 模型管理
模型文件建议在构建阶段与应用打包在一起，避免运行时联网下载。模型版本要与应用版本绑定，防止旧版本应用加载不兼容的新模型。当一个 Agent 应用用到多个模型或同一模型多个量化版本时，要建立清晰的命名规范，例如lfm2_5_2b6_int4_v1.3.onnx。
6.2 安全与权限
端侧 Agent 拥有调用系统工具的能力，权限安全问题必须认真对待。为每个工具分配独立权限级别，例如日历读取属于低风险，发送短信、修改系统设置属于高风险。高风险工具执行前必须再次向用户确认，不能只凭模型输出直接执行。同时要为工具调用增加审计日志，记录调用时间、触发输入与执行结果。
6.3 性能与功耗
推理引擎的线程数建议设为可配置项，根据设备核心数动态调整。在充电状态下可以放开性能限制，在电池供电时自动降低线程数、关闭语音模型。对 Agent 的高频交互要设置频率限制，防止模型在短时间内被频繁调用，导致设备过热。
6.4 可观测性
端侧 Agent 的排错成本远高于云端，所以要在一开始就搭建完善的日志体系。每个请求请求要记录耗时、token 数量、内存变化、工具调用链。使用统一 ID 串联一次 Agent 任务的全链路日志。日志在本地达到阈值后自动清理或压缩上送，避免占用用户存储空间。
7. 总结与学习路线
本文以 LFM2.5-2.6B 为代表的端侧模型为切入点，梳理了 On-Device Agent 的核心概念、整体架构、模型部署优化思路，并提供了一个最小可运行的 Agent 原型。你可以发现，端侧 Agent 的关键不只是模型参数量，更在于如何把推理、记忆、工具调用和安全控制有效地编排起来，在资源受限环境下实现稳定的智能服务。
如果要在实际项目中落地这套方案，后续可以重点深入几个方向：一是学习具体推理引擎的底层原理，掌握算子优化和内存管理技巧；二是熟悉量化训练与训练后量化差异，学会评估量化对业务指标的影响；三是研究端云协同架构，把端侧 Agent 和云端大模型正确分工。
实际动手时，建议先在高配开发板上跑通最小案例，记录基线指标，再逐步迁移到目标设备。遇到模型效果下降、内存不足、工具调用失败等问题时，按照本文的排查思路逐层定位，通常能省下不少时间。如果本文对你有帮助，可以收藏备用，后面我会继续拆解端侧模型的量化细节和推理引擎适配方案。
