1. 为什么 Agent 必须拥有端侧 LLM——从云上跑不动说起去年聊端侧 Agent 的整体设计时我把整个系统拆成了三条线感知流水线、决策推理、工具执行。今天这篇单独把中间那条线拎出来讲——端侧 LLM 部署。你可以在本地设备上放一个 7B 甚至 14B 的量化模型让 Agent 的规划、工具选择、结果判断都发生在设备内这套东西现在基本可以落地了但不是所有板子都能跑得舒服。1.1 Agent 的推理模式比普通应用苛刻得多理解端侧 LLM 部署之前先得想清楚 Agent 和传统 AI 应用的区别。传统接口调用式 AI 应用是一次请求、一次返回用户问一句模型答一句中间没有任何状态流转。Agent 则是感知-决策-行动-再感知的循环一个任务往往要经过多轮模型推理理解用户意图、选择工具、构造参数、执行、观察结果、决定下一步、再推理。我实测过一个带网页搜索和数据库查询功能的 Agent一个看起来挺简单的帮我对比这两款产品任务最后跑了 23 轮模型调用。每一轮调用如果都走云端 API延迟是叠加的。每轮 1 到 2 秒的网络往返乘以 20 多轮就是半分钟以上的等待。用户早就不耐烦了。更麻烦的是如果执行过程中网络抖动一次整个链路就挂了。对于智能家居中控、车载助手、工业边缘设备这些场景网络环境本来就不可控云端方案从头到尾都是脆的。成本也是必须算的一笔账。云端 LLM 按 token 计费而 Agent 的 token 消耗量往往对应着上下文不断累积。每一次工具执行结果都要塞进消息历史下一条推理请求的输入越来越长成本呈指数上涨。把高频、简单、敏感的推理留在端侧本质上就是省钱。1.2 隐私不再是口号而是端侧 Agent 的刚需都说 Agent 是替你做事可做事的前提是要拿到你的数据。日历、通讯录、短信、位置、相册、健康数据一个真正的个人 Agent 全都得碰。这些数据如果每轮决策都传去云端做推理那 Agent 越聪明隐私泄露风险越大。端侧部署 LLM 之后数据到模型推理之间只隔着本机内存不出设备隐私问题从架构层面消解了一大半。我见过不少团队评估端侧 Agent 方案时第一版需求文档写得都是响应快、成本低后来做安全评审时才把隐私摆上台面。其实这个顺序应该反过来如果你要做的是一个主动型、常驻型 Agent隐私就该是第一优先级。端侧 LLM 不是锦上添花而是满足隐私约束的唯一现实选择。当然端侧 LLM 也不是万能的。本地模型的智力上限、知识广度、工具调用稳定性目前跟云端大模型还有肉眼可见的差距。所以真正合理的方案是端侧兜底、云端兜聪明——这句话我在文章后半部分会展开。先把端侧这一条腿练扎实。2. 端侧 LLM 部署的硬件选型先说算力账再说选型很多人的第一反应是买一块贵的开发板结果到手之后发现推理速度跑不起来或者内存不够量化模型直接 OOM。选硬件必须从算力账开始算而不是从价格表开始看。2.1 从 RK3588 到 Jetson Orin端侧算力怎么算端侧 LLM 推理有一个经常被忽略的事实多数场景下瓶颈是内存带宽而不是算力。大模型推理时每生成一个 token 都要把全部权重从内存读一遍。7B 模型即使量化到 Q4权重文件也有 4 到 5GB每生成一个 token内存要搬运 4 到 5GB 的数据。这时候芯片的 TOPS 再高也没用内存带宽不够算力就只能闲着等数据。拿 RK3588 举例。它的 NPU 标称 6 TOPS听着跑 LLM 毫无压力但实际上它的 NPU 对 LLM 这类大算子的支持很有限跑 Transformer 模型往往只能走 CPU 或部分加速。RK3588 的内存是 LPDDR4X/5典型带宽 30GB/s 到 50GB/s 左右跑一个 4GB 权重的 Q4 7B 模型理论极限也就每秒 10 个 token 上下。实测用 llama.cpp 跑 Qwen2.5-7B-Instruct 的 Q4_K_M速度大概在 8 到 12 token/s。这个速度做问答勉强能忍做多轮工具调用的 Agent 就有点难受了因为每轮都要重新上下文推理。Jetson Orin 是另一个典型。Orin NX 16GB 的内存带宽大约 102GB/s比 RK3588 翻了一倍还多CUDA 生态下 llama.cpp 可以用 GPU 加载全部层7B Q4 模型跑起来能到 30 到 50 token/s加上 TensorRT-LLM 的优化速度可以更高。Orin AGX 64GB 带宽更高跑到 14B 模型也有实用价值。所以我的建议是如果预算允许、对工具调用稳定性有要求Jetson 系列仍然是目前综合体验最好的端侧 Agent 平台。我顺手整理了一个当前主流的硬件档位参考表方便大家按自己的场景对号入座档位代表设备内存适合模型规模实测速度参考典型场景入门树莓派 5 / 低端 RK 板4-8GB1B-3B Q43-10 token/s极简意图分类、固定命令识别中端RK358816/32GB16-32GB3B-7B Q48-15 token/s家居中控、轻量 Agent 原型高端Jetson Orin NX/AGX16-64GB7B-14B Q430-80 token/s复杂工具调用 Agent、多模态感知工作站Mini PC 消费级显卡32GB14B-32B Q450-150 token/s办公室私有 Agent、开发调试环境2.2 一版用在选型阶段的内存占用公式选型阶段可以按一个粗公式快速估算端侧 LLM 稳定运行要求设备在权重文件大小 上下文 KV Cache 系统余量上留足空间。权重大小好算GGUF 量化文件在模型卡片上都会标注。KV Cache 占用的经验值大约是7B 模型、4096 上下文、Q4 量化约需要 1 到 2GB如果上下文扩到 8K 或 16K缓存几乎线性增长。所以我的经验法则是可用内存至少是模型文件的 2 倍最好 2.5 到 3 倍。选 4GB 内存的板子跑 2GB 的 Q4 3B 模型剩余只有 2GBKV Cache 和系统占用很容易把内存顶爆进程直接被 OOM Killer 带走。反过来32GB 内存跑 4.4GB 的 Q4 7B内存余量充裕KV Cache 给到 8K 都不慌系统还能同时跑向量检索、语音识别这些周边服务。另外要注意内存带宽这个指标在厂商宣传页上经常不写但对你最终的 token/s 体验影响最大。两类设备对比时单看 CPU 核心数没用优先看内存类型和通道数。DDR5 双通道和 LPDDR5X 的带宽差距直接决定了推理速度的差距。3. 软件栈部署从 Ollama 到 llama.cpp 的一路实测选好硬件之后就是软件栈。现在端侧 LLM 部署工具已经相当成熟最省心的方案是 Ollama最可控的方案是 llama.cpp 系。我把两种都跑过一遍各有各的脾气。3.1 Ollama 是最省心方案但别急着上生产Ollama 在端侧部署这件事上做得确实到位。安装之后一条命令拉模型一条命令起服务而且提供了 OpenAI 兼容的/v1/chat/completions接口意味着 Agent 框架可以直接把它当 GPT 的本地替代品来连。基础部署流程非常简单# 安装Linux 环境 curl -fsSL https://ollama.com/install.sh | sh # 拉取一个端侧常用的量化模型 ollama pull qwen2.5:7b-instruct-q4_K_M # 启动服务 ollama serve服务起来之后Agent 侧只需把 base_url 指向http://127.0.0.1:11434模型名填qwen2.5:7b-instruct-q4_K_M就能拿到一个标准的聊天补全接口。实测在 Jetson Orin 上Ollama 默认使用的是 CUDA 后端不需要额外配置模型一到手就能跑起来。但我说别急着上生产是因为 Ollama 在端侧有几个隐藏行为要提前压住。第一Ollama 默认会同时加载多个模型并且并行处理多个请求在内存只有 16GB 的设备上连续跑 Agent 任务非常容易 OOM。建议设置OLLAMA_MAX_LOADED_MODELS1和OLLAMA_NUM_PARALLEL1强制单模型、单并发先把稳定性压住。第二模型默认保活时间是 5 分钟端侧 Agent 如果频繁在多个模型间切换每次切换都要重新加载权重耗时十几秒。可以设置OLLAMA_KEEP_ALIVE-1让模型常驻但前提是内存足够。3.2 llama.cpp 手动部署参数和细节才是灵魂Ollama 封装程度高适合快速验证。但做端侧 Agent 的长期迭代我更推荐直接上llama.cpp。它的开源生态活跃对国产板卡、ARM 平台的适配比很多商业框架都积极。手动部署并不难核心就三步git clone 官方 llama.cpp 仓库 cd llama.cpp cmake -B build -DCMAKE_BUILD_TYPERelease cmake --build build --config Release -j $(nproc)编译完成后不要直接用命令行交互模式要用它的llama-server子命令。这个程序会把模型包成一个 HTTP 服务同样兼容 OpenAI 接口而且支持并发请求、Jinja 模板、结构化输出这些 Agent 刚需能力。一个典型启动命令./build/bin/llama-server \ -m /models/qwen2.5-7b-instruct-q4_K_M.gguf \ -c 4096 \ -ngl 999 \ --host 0.0.0.0 \ --port 8080几个参数逐个说。-c是上下文长度直接决定 KV Cache 的大小端侧默认 4096 够用别盲目开 32K 否则内存直接爆掉。-ngl是 GPU 卸载层数Jetson 上设 999 表示全部层都上 GPU理论上越快越好在 RK3588 这类 CPU-only 平台上设 0 就行。--jinja参数需要确认是否在启动命令中传入不同的 llama.cpp 版本默认行为不同但建议开启它能让模型的对话模板和工具调用格式保持一致。这里有一条实操经验llama.cpp 的编译版本要和硬件驱动严格匹配。Jetson 上如果你用 JetPack 5.x对应 CUDA 版本是 11.4 / 11.4.4这时如果拉了最新版 llama.cpp它的预编译产物往往用的是 CUDA 12跑不起来。所以我在 Jetson 上习惯从源码编译让 CMake 自己探测设备上的 CUDA 版本这也是为什么上一步强调不要直接下载预编译包。4. 量化档位与模型选择端侧 Agent 的内存守恒法则模型和量化档位的选择基本决定了端侧 Agent 的上限。不是越大的模型就越好而是能稳定落地的模型才是好模型。4.1 GGUF 量化到底在干什么GGUF 是当前端侧 LLM 最通用的模型格式llama.cpp 系和 Ollama 都原生支持。它的核心就是量化把原本 FP16 的权重用更小的数值精度表示代价是精度损失收益是内存占用和带宽需求的成倍下降。量化的几个常见档位我用 7B 模型举例量化格式近似大小相对原始 FP16质量损失FP16约 14GB基准无Q8_0约 7GB50%几乎不可感知Q5_K_M约 5GB36%小Q4_K_M约 4.4GB31%可接受Q3_K_M约 3.5GB25%明显下降Q2_K约 2.7GB19%严重下降实测下来Agent 工具调用场景对模型质量比纯聊天更敏感。Q4_K_M 是我的底线再往下压缩到 Q3模型开始出现函数名幻觉、参数类型错乱Agent 的执行链路会频繁断掉。Q8_0 质量最好但内存和带宽压力都上去了RKN 3578 之类的中端板子可能吃不消。所以当前端侧 Agent 的主流性价比区就是 Q4_K_M 到 Q5_K_M 这一层。4.2 给小 Agent 选多小参数的模型确定了量化档位下一个问题是选多大参数量的底座。我的建议是按设备内存倒推8GB 设备能稳定跑 Q4_K_M 的 3B-4B 模型16GB 设备可以上 7B32GB 以上设备才有资格考虑 14B。注意这里说的是设备内存不是模型内存。一台 16GB 内存的设备系统占掉 3-4GB向量库和 Agent 运行时占掉 2GB真正留给模型的往往只有 9-10GB。这时候跑 7B Q4_K_M4.4GB 权重 1-2GB KV Cache刚好处于安全区间但如果同时还想跑 Whisper 语音识别就得重新分配了。模型家族的选择上端侧 Agent 我更偏爱中文能力均衡、工具调用指令遵循稳定的模型。实测下来Qwen2.5 系列的 7B 版在函数调用上的表现有惊喜即使量化到 Q4_K_M简单的工具选择准确率仍然可接受。Llama 3.1 8B 在英文场景不错但中文 Agent 场景偶尔会有模板格式漂移。Phi-3.5-mini 参数小、速度快适合做云端大模型之前的快速意图分类。也有团队用 Mixtral 8x7B 的量化版在 64GB 的 Orin 上跑速度能保持但内存和带宽压力相当大适合不差钱的场景。5. 打通 Agent 工具调用本地 LLM 怎么做 Function Calling很多团队在端侧把模型跑起来之后第一反应是能聊天了但距离 Agent 还差最关键一步工具调用。没有 Function Calling 的本地模型只是一个人工智障聊天机器人不是 Agent。5.1 OpenAI 兼容接口是第一步工具调用的标准路径是通过 OpenAI 兼容接口的tools参数。Ollama 和 llama.cpp 的 server 都实现了这套协议所以 Agent 框架侧的接入工作量很小。你在messages里塞入用户请求在tools里声明可调用的函数模型返回一个包含tool_calls字段的结构化响应指示 Agent 应该调用哪个函数以及传什么参数。一份工具定义示例{ type: function, function: { name: query_database, description: 查询结构化数据库按条件返回记录, parameters: { type: object, properties: { table: {type: string, description: 表名}, keyword: {type: string, description: 搜索关键词} }, required: [table] } } }看起来很简单但端侧小模型面对多份工具定义时很容易在该选哪个函数上翻车。我的实测体会是本地模型能稳定处理的工具数量远少于 GPT 级别的大模型。把一次请求里的工具数量控制在 5 个以内每个工具的 description 不超过两句话命中率会显著上升。工具多了小模型就开始在函数名之间打转甚至自创一个不存在的函数名。5.2 小模型在工具调用上的补救与兜底如果模型仍然频繁出错误格式有几个补救手段。第一个是开结构化输出让模型返回严格符合 JSON Schema 的结果而不是自由文本。llama.cpp 的 server 支持在请求里带 JSON schemaOllama 也有format: json选项配合起来可以极大减少括号缺失、引号错位这类低级错误。第二个兜底是在 Agent 框架里加一个工具调用校验层。我习惯在模型输出落地之前做一层规则校验函数名必须存在于白名单必填参数必须完整参数类型必须正确。校验失败时不要急着把错误返回给用户而是把错误信息拼接成一条新消息重新提交给模型修正一次。这个做法让工具调用成功率从 70% 提到了 90% 以上成本只是一次额外的本地推理。第三个建议是降低对端侧模型工具调用能力的期望值。端侧 LLM 负责执行层复杂规划交给云端大模型。比如云端负责分解任务、选择工具、编排顺序端侧负责执行某一个具体工具的参数补齐和结果解析。这种分层在工程上更稳也是我最后要说的话题。6. 端侧部署的真实翻车现场哪些坑值得提前蹲任何谈部署的文章不讲翻车现场都是耍流氓。端侧 LLM 部署的坑比云端多十倍。6.1 温度墙推理没跑多少就先降频了最容易被忽略的是散热。开发板跑 LLM 和跑普通负载完全不是一回事模型推理是持续高负载任务RK3588 的五分钟压力测试之后温度能冲到 80 度以上。板子的温控策略一触发CPU 频率从 2.2GHz 降到 1.2GHztoken/s 直接腰斩而且这个降频是瞬时的你还没反应过来Agent 就变得又慢又卡。解决思路就三个字加强散热。RK3588 的板子最好上主动散热风扇不要指望被动散热片能压住持续推理。Jetson Orin 我自己用的时候散热模组是出厂配好的但如果你把 Orin 塞进一个封闭的工业机箱里一样会撞温度墙。部署之前先跑一个持续推理的压测脚本观察 30 分钟内的温度和速度曲线比任何基准测试都真实。6.2 并发、Docker 与内存限额别让 OOM 教做人端侧 Agent 往往是一套系统里跑全家桶LLM 服务、向量检索、语音识别、摄像头推理、消息总线全挤在一台设备上。内存分配稍有不慎OOM Killer 就会随机带走一个进程。被带走的最惨情况是 LLM 服务因为模型推理中断后整个 Agent 状态机全部失效。如果你用 Docker 部署一定要显式设置内存和 PID 限制docker run -d \ --name local-llm \ --memory 8g \ --memory-swap 8g \ --pids-limit 512 \ --gpus all \ -p 8080:8080 \ local-llm-image--memory和--memory-swap设置成一样是为了禁止容器使用 swap否则容器宁可频繁换页也不肯释放内存性能会烂到无法理解。Jetson 上还要注意--gpus all的前提是容器里安装了和宿主机驱动匹配的 CUDA runtime。我踩过的最典型的坑是JetPack 5 的宿主机装了一个 CUDA 12 的容器镜像启动之后nvidia-smi在容器内直接报错模型全部落回 CPU 推理速度惨不忍睹。容器镜像的 CUDA 版本必须和 L4T 驱动匹配这是 Jetson 部署的铁律。6.3 模型指纹与一致性本地跑一个版本云端跑一个版本端侧 Agent 的另一个隐蔽风险是模型不一致。同一个任务本地 7B 模型和云端 70B 模型的输出风格、工具选择逻辑、甚至回复内容都可能不一致。用户可能上午在车内用本地端侧 Agent 干活下午回家切到云端 Agent发现两边行为完全不同这体验非常割裂。我见过的项目会在 Agent 层做混合路由的同时特意固定本地版本和云端版本的角色分工本地负责能被严格规则约束的高频动作云端负责需要开放创造力的低频复杂任务。两边都有明确的指令前缀避免让用户感知到换了个模型。具体怎么路由下面细说。7. 与云端 LLM 共存混合路由是端侧 Agent 的成熟形态端侧 LLM 不是要取代云端大模型而是要在合适的时候顶上去。一个真正能用的端侧 Agent十有八九是混合架构。7.1 哪类任务放本地哪类任务回云端我的划分经验是四句话高敏感、低复杂度、高频的任务放本地。比如读取本地日历、查询备忘录、操作智能家居这些任务语义简单但涉及隐私必须留在端侧。离线环境下的所有任务放本地。断网时本地模型是最后的执行保障。高复杂度、强推理、低频的任务回云端。比如总结一份长文档、写一段复杂代码、进行多步数学推理本地模型能力不够硬跑只会让用户失望。知识更新快的任务回云端或用 RAG 补。本地模型的知识截止日期是固定的如果 Agent 需要实时信息要么云端代答要么在本地挂一个小的检索增强模块。7.2 用路由层把两套模型缝合起来工程实现上我会在 Agent 和模型之间加一个轻量级路由层这层不需要是复杂的框架用 Python 就能实现。先让本地小模型做一次意图分类和敏感性检测然后根据分类结果决定请求走本地还是走云端def route_request(query, local_llm, cloud_llm): # 先用本地小模型做意图分类 intent local_llm.classify(query) if intent.sensitivity high: return local_llm.answer(query) if intent.complexity simple: return local_llm.answer(query) if not is_online(): return local_llm.answer(query) return cloud_llm.answer(query)这里的核心是把路由判断这件事和执行推理分开。路由判断用本地 1.5B 小模型就够毫秒级返回不占大模型资源执行推理才轮到 7B 或云端大模型。这个分层思路和 LLM 网关类似对外暴露一个统一的 OpenAI 兼容端点对内根据策略动态分发。想清楚路由规则之后Agent 的部署体验会顺滑很多用户不会察觉到两套模型的存在只会觉得这个 Agent 又快又聪明。我自己的项目目前就是这样跑的Jetson Orin NX 上部署 Qwen2.5-7B-Instruct Q4_K_M 作为端侧主力云端挂一个大模型做高难任务兜底。实测日常任务有 80% 以上落在端侧响应速度稳定在两三秒以内隐私敏感数据完全不出设备。剩下 20% 的高难任务自动切云端体验无损。这就是我想表达的端侧 Agent 成熟形态不是非此即彼而是在正确的地方用正确的模型。最后分享一个小的调试经验端侧模型刚接进 Agent 框架时不要一上来就跑完整流程。先把工具调用单独拎出来用一批带标准答案的测试用例跑一遍统计函数名命中率和参数正确率。这个数字达标了再接入完整链路否则你连问题是出在模型还是出在编排都分不清。部署端侧 LLM 从来不是把模型文件放进内存这么简单它是一整套围绕设备算力、内存、散热、路由策略的系统工程。每一步都踩熟了Agent 才算真正在你的设备上扎下根来。