干了几年端侧 AI最近被问得最多的一个问题是手里有块 Jetson Orin 或者 RK3588到底怎么把 LLM 跑起来让它能替 Agent 干活说实话这件事比很多人想得要绕。笔记本上pip install一把梭是另一回事端侧部署要同时跟算力、内存、量化、温控、Agent 接入纠缠在一起任何一个环节掉链子模型都只是个跑不动的玩具。这篇文章是“深入理解端侧 Agent”的第二篇专门讲端侧 LLM 部署这条链路从硬件选型、框架对比、模型量化到把本地模型封装成 Agent 真正能调用的服务一次讲清楚。文章默认你有基本的 Linux 操作能力知道ssh、docker、curl是什么。如果你是刚入门建议先对着文档把开发板刷好系统再回来看部署这块不然一步跟不上后面全是懵的。1. 为什么端侧 LLM 是 Agent 落地的必经之路1.1 时延、隐私与成本三个绕不开的驱动力做 Agent 的人迟早会碰到一个尴尬你调用的云端大模型响应很快但你的 Agent 每次决策都要经历“本地处理 → 上传 → 云端推理 → 回传 → 本地执行”这么一整轮。就算云端再快网络往返的物理时间摆在那里首 token 延迟动不动几百毫秒起步如果遇到高峰期排队一次工具调用的决策链路上多出好几秒都很正常。端侧 LLM 最直接的价值就是把推理从“远程调用”变成“本地函数”首 token 延迟能压到几百毫秒甚至更低整个 Agent 的响应节奏立刻不一样了。第二个驱动力是隐私。Agent 场景里很多数据并不适合离开设备比如本地文档、摄像头画面、个人健康数据。你把 prompt 封装得再漂亮数据只要出了设备就存在泄露风险。端侧部署从架构上切断了这条链路数据自始至终留在本机。还有一个特别现实的原因是成本。云端 API 按 token 计费一个 Agent 如果频繁调用模型做规划、反思、工具调用一天的 token 消耗量是很惊人的。端侧模型一次性投入硬件成本之后跑多少轮推理都不再产生 API 费用。对于做原型验证、私有化部署、或者想长期跑自动化任务的团队来说这个账怎么算都是划算的。1.2 离线可用与可控性Agent 的可靠性底座很多 Agent 场景是跑在无人值守环境里的比如巡检机器人、边缘网关、监控系统。这些环境的共性是网络不可靠甚至根本没有外网。如果 Agent 的大脑在云端网络抖动一次整个任务链就断了。端侧 LLM 让 Agent 在完全离线的情况下也能保持推理能力这已经不是“体验更好”的问题而是业务能不能跑起来的问题。另外端侧部署还带来一个不太起眼但很关键的好处可控性。云端模型版本更新、接口变动、服务下线这些都是你控制不了的外部因素。端侧模型一旦部署好行为是确定性的同一份权重、同一个推理框架、同样的参数今天跑出来和三个月后跑出来结果一致。这种确定性对 Agent 的调试来说极其重要你排查问题的时候不需要怀疑“是不是模型在云端又偷偷更新了”。我在实际项目里最深的一个体会是端侧 LLM 并不是要替代云端大模型而是补上了 Agent 在响应速度、隐私、离线可靠性上的短板。一个成熟的端侧 Agent 方案往往是本地模型负责高频、低延迟、敏感数据的处理云端大模型负责少数需要超强推理能力的场景。2. 端侧 LLM 部署的硬件与框架选型2.1 硬件平台盘点从 Jetson Orin 到 RK3588端侧 LLM 部署的第一个岔路口是选硬件。很多人一上来就纠结“哪个板子最好”其实没有最好的板子只有匹配你场景的板子。Jetson Orin 系列是当前端侧 LLM 部署里最主流的选择。Orin Nano 8GB 可以跑 7B 量化的模型速度虽然不快但能用Orin NX 16GB 跑 7B-14B 模型比较舒服AGX Orin 64GB 能勉强塞下 30B 级别的量化模型。Orin 的优势是软件生态成熟CUDA 生态直接兼容了大量现有推理框架而且有官方提供的 Maxine、TensorRT 等优化工具调试起来心里有底。它的主要问题是价格偏高而且功耗不低整机跑到 25W-60W 都很正常必须考虑散热。RK3588 是另一条路线。这块芯片八核 CPU 加上 6 TOPS 的 NPU价格比 Orin 便宜一个量级很多国产开发板都是用它。它跑轻量级模型1B-4B完全没问题跑 7B 就需要靠 CPU 硬扛或者 NPU 配合了。RK3588 的 NPU 生态相比 CUDA 要弱不少很多模型不能直接无缝跑起来需要针对 RKNN 格式做转换这是一个不小的工程。还有一类平台容易被忽略x86 工控机或者迷你主机。别觉得端侧就一定是 ARM 开发板。一台不带 GPU 的 x86 小主机用 llama.cpp 的 CPU 推理跑 7B 量化模型配合 AVX512 指令集速度其实相当能打。这类设备的好处是兼容性最好所有推理框架都能直接跑散热也好设计。整理一份选型参考表硬件平台推荐模型规模典型功耗推理框架兼容性适合场景Jetson Orin Nano 8GB3B-8B量化10W-25WCUDA/TensorRT 生态完善入门探索、小型 AgentJetson Orin NX 16GB7B-14B量化15W-40WCUDA 生态机器人、边缘网关Jetson AGX Orin 64GB14B-30B量化30W-60WCUDA 生态复杂 Agent、多模型并行RK3588 开发板1B-4B5W-15WNPU 需转 RKNNCPU 可跑 llama.cpp低功耗、高性价比x86 迷你主机7B-14BCPU15W-35W几乎全兼容快速原型、内网私有化选型有一个核心原则不要买“理论上够用”的板子要买“实测过能跑”的板子。参数表上的 TOPS 和你实际跑 LLM 的 token/s 不是一回事后者受内存带宽、算子实现、量化质量共同影响。我见过不少人在纸面上算了一通最后跑起来才发现内存带宽是瓶颈模型装进去但生成速度慢得没法用。2.2 推理框架对比llama.cpp、Ollama、MLC LLM 怎么选硬件定了之后下一步是选推理框架。这个选择直接决定你后面踩坑的深度。llama.cpp 是端侧 LLM 部署绕不开的框架。它用 C/C 实现有极高的移植性支持 CPU、CUDA、Metal、Vulkan甚至 RK3588 的 ARM CPU 也能直接编译跑。llama.cpp 的核心优势是量化支持极其成熟GGUF 格式配合不同量化等级可以让你精确地在内存占用和模型质量之间做取舍。缺点是它更偏“库”而不是“服务”你需要自己处理启动脚本、API 封装、进程管理。Ollama 是把 llama.cpp 包装成了一个开箱即用的服务。它提供了命令行拉取模型、自动管理模型文件、启动 OpenAI 兼容 API 这几件事零配置就能本地跑起来。对于快速验证、个人开发调试甚至一些轻量生产场景Ollama 是效率最高的选择。我前文提到的很多 LLM 部署用 Ollama 一行ollama run就解决了。它的弱点在于“封装太严实”很多底层参数被隐藏了遇到性能问题时排查路径比较有限。MLC LLM 更像是一个“编译器”它能把模型编译成适配不同后端的可执行程序在 Apple Silicon 上支持很好也能上 Android 和 iOS。如果你的端侧目标是手机或者平板MLC LLM 是比 llama.cpp 更合适的选择。它的问题是工具链上手门槛高对新手不友好。还有一个需要提的是 vLLM 等高性能服务框架它们在大规模并发场景表现很好但依赖 GPU 显存和 CUDA在 8GB 这种小显存设备上优势发挥不出来反而因为内存开销大导致模型装不下。端侧场景我通常不建议用 vLLM。我的选型策略是快速原型、验证想法 → Ollama精细控制、要跑某些奇奇怪怪的硬件 → llama.cpp手机/平板端侧 → MLC LLM真要做大规模并发服务 → 别用端侧设备上 GPU 服务器2.3 模型格式与量化等级理解 GGUF 和 q4_K_M端侧部署绕不开“量化”这个词。一个 7B 参数的模型如果用 FP16 存储体积是 14GB7B × 2 字节端侧设备内存基本被吃干。量化的本质是把每个参数从 16 位浮点数压到更低的精度比如 4 位整数体积直接降到 3.5GB 左右。llama.cpp 生态用 GGUF 格式承载量化模型。量化等级命名里的 q4_K_M、q5_K_M、q8_0 这些字符串看起来晦涩拆开看就不难懂q4/q5/q8表示每个参数用多少位存储K_M表示分组量化模式其中K是 K-means 聚类的意思它会把权重分成小块每个块自适应选择量化策略M是 mixed 混合模式平衡了质量和速度_0表示基础量化速度最快但质量相对低端侧 Agent 场景我最常用的是 q4_K_M。它相比更高精度的 q5_K_M、q8_0内存占用明显更低而推理质量差距在大多数任务上是可以接受的。q2_K 这种激进量化虽然省内存但模型在复杂推理上会明显“变笨”Agent 经常给出逻辑不通的答案我不建议用。量化不能解决所有问题。很多人以为模型量化完内存一定够用忽略了还有 KV Cache、运行时临时缓冲区、Agent 框架本身的开销。后面我专门讲这块的估算。3. 部署实操在端侧跑起一个可被 Agent 调用的 LLM3.1 模型准备从 HuggingFace 到本地 GGUF我先以 RK3588 开发板加 Ollama 为例讲一条最快的路径因为这条路最直观跑通了也最容易建立信心。之后再用 llama.cpp 讲更精细的控制。第一步是选模型。端侧 Agent 场景我推荐优先考虑 Qwen2.5 系列和 Llama 3.x 系列。Qwen2.5 的中文能力好Agent 工具调用支持也不错而且 Qwen 官方对 Ollama 的支持很积极。7B 级别的模型在 Orin NX 16GB 上能舒服运行8GB 设备建议考虑 4B 甚至 3B。在 Ollama 里拉模型很简单ollama pull qwen2.5:7b-instruct-q4_K_M这里有两点要说明。第一Ollama 会从它的模型库拉取已经量化好的 GGUF 文件不用你手动量化。第二这个命令拉下来的是 Ollama 内部的模型结构它以qwen2.5:7b-instruct-q4_K_M这样的 tag 来区分不同量化版本。如果你用的是自定义模型文件比如从 HuggingFace 下载原始权重再手动转 GGUF流程是这样的pip install huggingface_hub huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen2.5-7b然后去 llama.cpp 目录执行转换python convert_hf_to_gguf.py ./qwen2.5-7b --outfile qwen2.5-7b-f16.gguf --outtype f16 ./llama-quantize qwen2.5-7b-f16.gguf qwen2.5-7b-q4_K_M.gguf q4_K_M手动量化有个好处是你可以精确控制输出路径、文件名、量化参数而且可以顺带转出不同等级的多个版本在同一个设备上对比测试。用 Ollama 拉现成的虽然方便但想比较 q4_K_M 和 q5_K_M 的差异就有点绕。注意转换和量化这些操作建议在 PC 上完成生成 GGUF 文件后再传到端侧设备。端侧设备性能有限跑一次 7B 模型的量化可能要几个小时纯属浪费时间。3.2 启动服务让 Ollama 暴露一个 OpenAI 兼容接口模型就位后启动 Ollama 服务ollama serve默认情况下 Ollama 监听127.0.0.1:11434。如果 Agent 框架和 Ollama 在同一个设备上这个默认配置没问题。如果你要把服务暴露给局域网里的其他设备访问需要改监听地址通常通过设置环境变量OLLAMA_HOST0.0.0.0来实现OLLAMA_HOST0.0.0.0 ollama serve验证服务是否正常最直接的方式是用 curl 打一发curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b-instruct-q4_K_M, messages: [ {role: user, content: 用一句话解释什么是 Agent} ] }看到模型返回 JSON 结构的结果就说明服务已经通了。Ollama 的这个/v1/chat/completions端点兼容 OpenAI 的 API 格式这意味着几乎所有 OpenAI SDK 都可以通过改base_url直接切到本地模型Agent 框架的适配成本极低。如果你用 llama.cpp 的llama-server启动方式也类似./llama-server -m qwen2.5-7b-q4_K_M.gguf \ --host 0.0.0.0 --port 8080 \ -c 8192 --n-gpu-layers 999--n-gpu-layers 999表示尽可能把模型层加载到 GPU/NPU 上如果端侧设备内存不够可以把这个数字调小让更多层留在 CPU 跑。llama-server 同样提供 OpenAI 兼容的/v1/chat/completions路由。3.3 把端侧模型接入 Agent一个最小可用的调用示例服务启动之后Agent 接入环节有一个常见的误区直接让 Agent 框架去调用本地模型然后裸调用裸返回全程没有结构化输出Agent 在解析模型回答时经常失败。正确的做法是让端侧模型以 Agent 能解析的方式输出。现在很多模型支持 function calling但端侧小模型的 function calling 稳定性参差不齐。最稳妥的模式是让模型以 JSON 格式返回结构化内容然后在 Agent 侧做解析和校验。举个最小示例假设 Agent 需要让模型决定调用什么工具import json import requests def call_llm(user_query: str, tools_desc: list[str]) - dict: system_prompt f 你是端侧Agent的决策模型根据用户的请求选择合适的工具。 可用的工具如下{json.dumps(tools_desc, ensure_asciiFalse)} 请严格输出JSON格式包含字段 - tool_name: 选择的工具名 - params: 工具参数 - reason: 简要说明原因 不要输出任何多余内容。 resp requests.post( http://127.0.0.1:11434/v1/chat/completions, json{ model: qwen2.5:7b-instruct-q4_K_M, messages: [ {role: system, content: system_prompt}, {role: user, content: user_query}, ], temperature: 0, }, timeout60, ) content resp.json()[choices][0][message][content] # 清理可能包裹的json标记 if content.startswith(): content content.strip() if content.startswith(json): content content[4:] try: return json.loads(content) except json.JSONDecodeError as e: # 这里做容错二次请求或者直接返回固定错误 return {tool_name: error, params: {}, reason: f解析失败: {e}} if __name__ __main__: tools [ {name: lookup_price, desc: 查询商品价格}, {name: check_stock, desc: 查询库存}, ] result call_llm(帮我查一下这个商品的库存量, tools) print(result)这个模式的核心在于你用一份足够明确的 system prompt 约束了模型的输出格式再用一层 JSON 解析做防御。这样即使模型偶尔输出多了几个字或加了 markdown 代码块标记也能被兜住不会让 Agent 哭死在解析步骤上。4. Agent 视角下的端侧 LLM 运行时优化4.1 上下文窗口与 KV Cache算清楚你的内存账本端侧设备最稀缺的资源不是算力而是内存。很多人只看模型权重体积忽视了 KV Cache 这个内存黑洞。KV Cache 简单理解就是模型在生成时保留的“临时笔记”记录已经处理过的历史信息的缓存避免每次生成新 token 都重新算一遍前面的内容。上下文越长KV Cache 越大。以 Qwen2.5-7B 为例假设采用 GQA 分组查询注意力KV Cache 的粗略估算公式是KV Cache 大小 ≈ 2K 和 V 两组× 层数 × KV 头数 × 每头维度 × 每 token 字节数 × 上下文长度Qwen2.5-7B 大约 28 层、KV 头数 4、每头维度 128如果用 FP16 存储每 token 2 字节每个 token 的 KV Cache 大约 28 × 4 × 128 × 2 × 2 57344 字节约 56KB。听起来不多但上下文长度 8K 时KV Cache 就超过 400MB。如果同时跑多个并发请求每个请求都有独立的 KV Cache内存会迅速膨胀。实际部署中我会这样算内存预算项目7B q4_K_M 模型单请求 8K 上下文并发 2 请求模型权重约 4.4GB4.4GB4.4GBKV Cache估算—约 0.45GB约 0.9GB运行时开销约 0.5GB约 0.5GB约 0.5GB剩余给系统/Agent看设备看设备看设备一个 8GB 的 Orin Nano跑 7B 模型加 8K 上下文内存已经非常紧张。这也解释了为什么端侧 Agent 场景下我不建议大家盲目拉长上下文窗口。Agent 的高效做法是只保留当前任务相关的上下文把历史信息存到向量库里按需检索而不是全部塞进模型上下文里。4.2 并发、排队与超时端侧模型的承载上限“AI Agent 怎么扛并发”是很多人在端侧踩坑之后才想起来搜的问题。真相是端侧设备天生不适合高并发这不是优化能解决的问题是物理资源的上限。Ollama 默认情况下模型实例是单例的并发请求会进入阻塞队列一个跑完再跑下一个。你可以通过设置OLLAMA_NUM_PARALLEL环境变量来允许多个请求并行比如OLLAMA_NUM_PARALLEL2 ollama serve看起来像是提升了并发吞吐但代价是每个请求都会占用独立的 KV Cache内存直接翻倍。如果设备内存本来就不宽裕强行开并行只会导致 OOM内存溢出。我的经验是端侧 LLM 服务不适合做“每个独立请求都走模型”的高并发架构。更好的模式是做一个请求合并层把短时间内的多个请求合并成一个带多任务的 prompt 批处理或者在 Agent 层做单例循环一次只处理一个决策任务。如果确实需要扛几十路并发正解是上多设备横向扩展让每台端侧设备只跑单路或双路推理。超时控制也要提前做好。端侧模型推理速度不如云端一次 7B 模型的完整对话生成可能要 10 秒以上。Agent 框架的默认 HTTP 超时往往只有几秒你需要在客户端显式调大 timeout。我在 Agent 侧调用时统一设置为 60 秒首 token 的等待加上完整生成的耗时都在这个范围内。4.3 能效与散热端侧部署的物理约束这是很多人最容易忽略的一块但它往往决定了你的方案能不能长期稳定跑。Jetson Orin 系列默认工作在“自适应”模式遇到持续高负载会自动降频防止过热。端侧 Agent 如果要做 7×24 小时监听持续推理时设备温度会快速上升。我实测过 Orin Nano 满载跑 7B 模型核心温度可以逼近 85℃一旦超过温控阈值推理速度直接腰斩。在部署层面散热方案要提前规划。开发板至少需要一个主动散热的金属外壳或者风扇底座。RK3588 开发板也有同样的需求它虽然功耗低但 NPU 满载时积热集中在芯片内部被动散热片如果不加风扇温度照样飙到 90℃。软件层面有几个小手段可以控制发热给推理服务限制 CPU 核心比如taskset -c 4-6 ollama serve让高温核心空闲下来在 Jetson 上通过nvpmodel -m 1切换低功耗模式给模型加--mlock参数锁定内存避免系统因内存换页增加 CPU 开销在 Agent 侧做冷却窗口连续推理 N 次后强制 sleep 几秒给芯片缓冲时间你可能会觉得“限制核心数和功耗模式”会让推理变慢没错是有影响但换来的是设备长时间稳定运行不降频。短期的快和长期的稳在端侧 Agent 场景我选后者。5. 端侧 Agent 部署中的常见问题与排查实录5.1 我踩过的几个坑慢、胡编、被杀进程先说速度问题。我第一次在 RK3588 上跑 7B 模型用的是 CPU 推理生成速度只有不到 2 token/s一个 200 token 的回答要等 2 分钟Agent 基本没法用。后来排查发现瓶颈在内存带宽而不在 CPU 计算能力。解决方案是换更小的模型4B并开启更激进的量化q3 级别同时把进程绑定到大核 CPU 上速度勉强能到 6 token/s。如果你在类似平台跑 LLM建议先跑一个小模型测试一下 baseline 速度再决定你的 Agent 场景能不能接受这个延迟。再说胡编问题。端侧模型一旦量化过狠或者上下文里塞了太多不相关内容输出质量会明显下降。我遇到过一次 Agent 在复盘历史任务时开始“编造”从未执行过的操作记录排查发现是模型在长上下文中注意力涣散。解决方式不是换更大的模型而是在 prompt 层级做“约束限定”要求模型只基于给定的结构数据回答并且禁止补充任何未经验证的信息。还有一个特典型的问题端侧设备内存不足导致的进程被杀。Jetson 平台的机制是当内存紧张时会启动 OOM Killer 杀掉最占内存的进程。你的推理服务如果瞬间峰值内存超过设备内存大概率会被直接 kill而且dmesg日志里只会留一句Out of memory: Kill process排查起来很迷。我现在的做法是在正式部署前先用stress-ng做一次内存压力测试把推理服务的内存占用峰值压出来计算出实际剩余内存再决定要不要开并发要不要拉长上下文。5.2 一份可以直接抄的常见问题速查表现象可能原因排查手段与解法模型加载失败内存不足GGUF 文件太大改用 q3 或更小模型检查是否有其他进程占内存推理速度极慢CPU 推理 内存带宽瓶颈换更小模型开启 NPU/CUDA 加速检查降频温度过高自动降频散热不足加风扇/散热片切低功耗模式限制 CPU 核心偶尔输出乱码/答非所问量化等级过低或上下文过长改用 q4_K_M 以上缩短上下文清理 KV CacheAgent 解析 JSON 失败模型输出被 markdown 包裹加 JSON 清理逻辑system prompt 注明不要额外输出服务进程被 killOOM Killer 触发增加 swap降低并发减少模型加载层数首 token 延迟高没有使用前缀缓存保持上下文结构稳定减少 system prompt 反复拼接并发请求全部超时单实例排队时间过长提高客户端 timeout开OLLAMA_NUM_PARALLEL1优先稳定考虑多设备排查时还有一个通用原则先用最小样例复现问题比如用curl直接打一次模型接口看是模型本身的问题还是 Agent 框架层的问题。不要一上来就怀疑 Agent 代码先确定推理侧是否健康。6. 写在最后端侧 Agent 部署的一些个人体会写到这里把端侧 LLM 部署的主干链路梳理完了硬件选型、框架选择、模型量化、服务启动、Agent 接入、运行时优化、问题排查。每一步我都给的是实际可用、可以直接往下抄的方案而不是泛泛的架构图。我个人在实际操作中的体会是端侧 Agent 部署最大的挑战不是“跑起来”而是“稳定跑下去”。模型能跑通只是第一步真正花时间的是内存预算管理、温控策略、Agent 侧的超时与容错设计。如果你是在做一个长期运行的项目建议把内存和温度的监控脚本从一开始就加上别等到设备把进程杀了才发现问题。另外再说一个容易忽略的点端侧模型的能力每天都在变一个新的小模型发布之后很可能会比你当前部署的模型强一个档次。部署方案不要定死尽量在框架层预留“换模型只需改配置”的灵活性。我通常会把模型版本号写进配置中心Agent 启动时动态读取换模型就是个改配置文件的事。这个内容后续还可以往两个方向扩展一个是端侧 RAG把本地知识库和模型检索结合起来让 Agent 能回答私有知识相关的问题另一个是端侧模型与云端模型的混合编排高频决策走本地、复杂推理走云端。等我有时间实测完一轮再开一篇专门聊。
