之前在做端侧智能助理落地时最头疼的问题不是模型效果不够好而是“模型选型”和“Agent 编排”两条线经常打架。模型太大跑不起来模型太小又撑不住多轮任务Agent 框架放到手机端又面临算子兼容、内存抖动、功耗超标等问题。最近 LFM2.5-2.6B 这类中小规模参数模型进入视野成为端侧 Agents 落地的重要候选方案。本文就从端侧 Agent 的概念出发结合模型部署与推理优化、最小可运行原型、常见问题与工程建议把 On-Device Agents 这条技术路径完整拆解一遍。1. 背景与核心概念1.1 什么是 On-Device AgentOn-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_tokens256) # 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(maxlenmax_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 和云端大模型正确分工。实际动手时建议先在高配开发板上跑通最小案例记录基线指标再逐步迁移到目标设备。遇到模型效果下降、内存不足、工具调用失败等问题时按照本文的排查思路逐层定位通常能省下不少时间。如果本文对你有帮助可以收藏备用后面我会继续拆解端侧模型的量化细节和推理引擎适配方案。