端侧Agent模型部署实战：从硬件选型到推理调优

1. 为什么端侧 Agent 的第一道坎是模型部署1.1 端侧 Agent 与云端方案的本质差别这一篇是深入理解端侧 Agent系列的第二讲主角是端侧 LLM 部署。上一篇我们聊过端侧 Agent 的整体架构感知、记忆、规划、工具、执行最后所有模块都要围绕一个核心决策引擎转这个引擎就是 LLM。当时很多朋友留言问模型到底怎么跑到 RK3588、Jetson Orin 这类硬件上跑起来之后为什么速度忽快忽慢为什么同一个模型在别人的板子上能跑出 15 token/s自己只能跑出 3 token/s这些问题恰好就是端侧 LLM 部署的核心内容。云端方案里模型部署是运维工程师的事买 GPU、起容器、上推理服务开发者只需要调 API。可到了端侧模型部署变成每一个做智能体的人都要亲自动手的活。你既没有机房里的 A100也没有等着被调用的现成接口硬件资源抠抠搜搜散热、功耗、内存带宽全都得自己操心。端侧 Agent 和云端 Agent 的定位差别决定了部署思路完全不同。云端智能体追求能力上限模型越大越好上下文越长越好工具越多越好。端侧智能体追求响应闭环摄像头拍到画面传感器读到数据用户说出指令模型要在几百毫秒到几秒内给出决策而且很多场景要求断网可用、数据不出本地。换句话说云端部署考虑的是吞吐端侧部署考虑的是时延和功耗。很多人在这一步犯了认知错误以为把一个大模型塞进开发板就是端侧部署。实际上端侧 Agent 要的从来不是模型能跑而是模型跑得够快、够可靠、能支撑完整任务链路。一个 32B 模型在 RK3588 上跑出 1 token/s对智能体来说基本没法用因为一次工具调用加上上下文回传用户要等几分钟。部署这件事本质是在硬件约束下把模型的能力和响应速度压到任务可接受的区间里。1.2 部署要解决的核心矛盾端侧 LLM 部署有四个绕不开的矛盾我习惯称之为端侧四象限模型容量、推理速度、工具能力、功耗。这四个维度相互制约任何一个被拉满另外三个就要让路。模型容量看的是硬件内存能装下多大的模型。端侧设备的内存通常只有 4GB 到 64GB而且不像服务器那样可以弹性扩展。推理速度看的是内存带宽和算力LLM 解码是典型的内存密集型任务权重传输速度决定 token 生成速度而不是单纯看 NPU 有多少 TOPS。工具能力看的是模型对 Function Calling 的支持程度这直接决定智能体能不能可靠地调用摄像头、传感器、外部程序这个能力在端侧小模型上往往比答题能力更重要。功耗看的是设备的散热设计开发板没有数据中心那种恒温机房长时间满载推理温度一上来就会降频速度断崖式下跌。这四个矛盾里最容易踩坑的是只看 TOPS 不看带宽。很多人看到 RK3588 标称 6 TOPS NPU觉得跑个 7B 模型绰绰有余实际部署后傻眼了NPU 算力再高权重从内存搬到计算单元的路上就卡死了。我见过不少项目模型确实在跑但 CPU 算出来比 NPU 还快就是因为整机内存带宽成了瓶颈。理解了这四个矛盾后面选硬件、选模型、选引擎、调参数本质上都是在同一个坐标系里找平衡点。这一篇会按照硬件评估→模型选型→推理引擎→智能体对接→问题排查的顺序把整个链路过一遍所有操作都以能实际落地为准。2. 动手之前先算账硬件带宽与内存容量2.1 常见端侧平台的底细选硬件之前先看一张参数表。这里列的都是目前端侧智能体项目里最常见的平台指标有差异适合的场景也明显不同。平台内存内存带宽理论典型算力能跑的模型档位典型功耗Raspberry Pi 54/8GB约 34GB/sCPU 为主1.5B~3B 量化5~10WRK35888/16GB34~51GB/s6 TOPS NPU3B~7B 量化5~15WJetson Orin Nano8GB8GB约 68GB/s40 TOPS7B~8B 量化7~15WJetson Orin NX16GB16GB约 102GB/s100 TOPS8B~14B 量化10~25WApple M 系列16/24/32GB100~200GB/s统一内存8B~32B 量化10~30W这张表里最该记住的不是 TOPS而是内存带宽。端侧平台的内存带宽差距非常大树莓派 5 的 34GB/s 和 Orin NX 的 102GB/s虽然都叫开发板实际能流畅运行的最大模型差了一整个档位。这里补充一个容易被忽略的点内存带宽是理论值实际可用要打折扣。DDR/LPDDR 实测带宽通常是理论值的 60%80%而且并发读写、缓存命中率、NPO 与 CPU 共享内存总线都会进一步影响实际吞吐。所以我更建议大家按理论带宽乘以 0.60.7来估算下限乘以 0.8来估算上限这样规划出来的方案才不容易翻车。2.2 内存带宽决定 Token 速度LLM 在推理时的生成阶段每一步都要把模型全部权重从内存读一遍然后做一次前向计算。这个过程是内存带宽主导的可以用一个很粗糙但很实用的公式估算预估 Token 速度 ≈ 可用内存带宽 ÷ 模型文件体积举例来说一个 7B 模型做 Q4_K_M 量化后GGUF 文件大约 4.5GB。放在 Jetson Orin Nano 8GB 上按 68GB/s 的 70% 折算可用带宽约 47GB/s那么预期速度大约是 47÷4.5 ≈ 10 token/s。换到 RK3588按 51GB/s 的 70% 折算可用带宽约 35GB/s预期速度大约是 35÷4.5 ≈ 7.7 token/s。这个估算和社区里大家实测的 llama.cpp 跑 Qwen2.5-7B 的成绩基本对得上。这个公式有两点使用前提。第一它只适用于自回归解码阶段也就是生成每个 token 的过程模型预热加载、处理长 Prompt 的预填充阶段更依赖算力速度规律不一样。第二它假设内存带宽是唯一瓶颈现实中还要看引擎是否支持权重缓存、是否用到了硬件加速单元、是否存在 CPU 算力不足的情况。但它已经足够在买板子之前帮我们判断这个硬件跑这个模型大概什么速度。2.3 除了权重还要给 KV Cache 留位置模型文件大小是内存开销的大头但绝对不是全部。生成过程中Transformer 会把已经见过的历史 token 的 Key 和 Value 缓存下来避免重复计算这部分内存叫 KV Cache。上下文越长KV Cache 越大而且增长得很快。KV Cache 的占用有个估算公式KV Cache 体积 ≈ 2 × 层数 × KV头数 × 头维度 × 上下文长度 × 每项字节数以 Qwen2.5-7B 为例它一共 28 层KV头数 4头维度 128如果用 FP16 存储每项占 2 字节那么每 token 的 KV 占用是 2 × 28 × 4 × 128 × 2 ≈ 57344 字节约 56KB。把上下文设为 8192 tokenKV Cache 就要吃掉约 458MB上下文拉到 32K就要超过 1.8GB。在 8GB 内存的开发板上这个数字已经相当可观了。所以部署时要算的账应该是模型文件体积 目标上下文长度的 KV Cache 运行时系统占用 ≤ 硬件可用内存 × 安全系数。安全系数我建议至少留 20%。别小看这 20%内存占满之后触发的 swap 和进程被杀是端侧部署最常见的翻车方式。这个账本一定要在选模型之前算而不是部署之后再看。我见过一个项目板子只有 8GB 内存硬要跑 8B 模型加 32K 上下文部署过程很顺利一旦上下文涨上去系统直接 OOM 把进程杀了智能体动不动就中断整个链路完全不可用。3. 模型选型与量化性能与可用性的第一道分水岭3.1 参数规模怎么匹配任务端侧模型选型有一个很实在的规律任务难度决定参数规模下限硬件内存决定参数规模上限两者取交集。如果你的智能体只需要做意图识别、简单问答、固定流程的工具调用1.5B3B 的模型完全够用。这类模型量化后只有 12GB在大多数开发板上都能跑出不错的响应速度。社区里现在很流行用蒸馏模型比如 DeepSeek-R1 蒸馏出来的 Qwen2.5-1.5B/7B 系列推理能力比同尺寸的基座模型强不少特别适合端侧做需要一点思考链的场景。蒸馏模型的代价是输出会变长每个任务消耗的 token 数更多实际响应时间未必比非推理模型快。如果你的智能体要处理复杂指令、多轮对话、阅读理解、结构化信息抽取7B8B 是一个比较舒服的档位。Qwen2.5-7B-Instruct、Llama-3.1-8B-Instruct 都是这个档位的主力工具调用能力经过针对性训练配合正确模板可以做到不错的可靠性。8B 模型在 Jetson 平台上属于可以日常用的级别在 RK3588 上属于能跑但别太贪上下文的级别。再往上14B 甚至 32B 的模型在端侧不是不能跑但一般只建议出现在 64GB 统一内存的 Apple Silicon 或者 Orin AGX 这类高端平台上。以我的经验端侧智能体项目里7B 是性能和成本平衡点最好的一档能力够用、量化后体积可控、推理速度勉强能支撑实时交互。3B 是低功耗和低内存平台的保险牌除非任务确实复杂否则不太建议在 8GB 以下内存的设备硬上 8B。3.2 GGUF、AWQ 还是 INT8量化方案怎么选模型选好后还要定量化方案。量化就是降低权重精度把原本 FP16 的 2 字节权重压缩到 4 位甚至更少用轻微的能力损失换体积和速度。端侧主流的量化方案有三类GGUF 的 K-quant、AWQ/GPTQ 的 INT4、以及各类 INT8。GGUF 是 llama.cpp 生态的标准格式也是端侧 CPU/GPU 混合推理场景最通用的方案。它提供了 Q2_K、Q3_K、Q4_K_M、Q5_K_M、Q6_K、Q8_0 等档位其中 Q4_K_M 是默认首选能力损失通常在 5% 以内文件体积接近原模型的 1/3.5。Q5_K_M 比 Q4_K_M 大 15% 左右质量略好适合内存有余量的平台。Q8_0 几乎无损但体积只比 FP16 小一半适合内存宽裕且对输出质量要求高的场景。AWQ 和 GPTQ 主要面向 GPU 推理框架Jetson 平台用 TensorRT-LLM 时会用到。它们的好处是优化了某些权重的重要性感知在 INT4 下的能力保留通常优于普通均匀量化但配置门槛也高需要跑校准流程而且格式绑定特定引擎不如 GGUF 灵活。INT8 是另一个常见选择尤其适合 RK3588 的 NPU 路线。Rockchip 的 RKLLM 工具链普遍支持 W8A8权重 8 位、激活 8 位量化转换出来的模型体积比 INT4 大但 NPU 加速效果明显。这里有个取舍INT4 体积小、带宽压力小但很多端侧 NPU 对 INT4 的支持不完善INT8 对 NPU 更友好但模型体积大一倍内存带宽压力也翻倍。实际操作中我建议普通场景直接用 Q4_K_M别纠结。先把链路跑通再对比 Q5_K_M / Q8_0 的实际输出质量差异用你自己的任务测而不是凭感觉。很多模型从 Q4_K_M 升到 Q8_0能力提升远没有文件体积带来的内存压力那么明显。3.3 参考榜单但别迷信榜单模型选型时大家都会去翻 Open LLM Leaderboard 之类的公开榜单。榜单有价值但一定要明白它衡量的东西和端侧 Agent 要的东西不完全是一回事。公开榜单主要测常识问答、数学推理、代码生成这类静态能力而端侧智能体最需要的是工具调用可靠性、指令遵循、多轮一致性以及低量化下的能力保留程度。这些恰恰是榜单很少覆盖的维度。我测试模型时会自己准备三组评估集第一组是典型工具调用场景比如从传感器读取温度超过阈值就调用报警脚本第二组是多轮对话一致性比如反复追问同一件事看模型会不会自相矛盾第三组是格式约束场景比如要求输出严格的 JSON看成功率。这三组测试跑完基本就知道这个模型在本地任务里靠不靠谱。另外还有一个很实用的做法用 LLM as Judge 做自动化评估。把模型的输出和标准答案一起丢给一个更强的模型打分比如拿云端 API 当裁判本地模型当选手。虽然不能完全替代人工评测但能快速筛掉明显不行的模型节省大量手动测试时间。注意裁判模型本身可能有偏好尤其是对格式长一点的回答打分偏高所以评估时最好混合使用规则判断和模型判断。4. 选引擎、跑服务、调性能实操部署全流程4.1 推理引擎的对比模型和量化定了接下来要选推理引擎。端侧常用的引擎有这么几个各有各的适用场景。引擎硬件支持特点适合场景llama.cppCPU、CUDA、Metal、Vulkan、OpenCL格式统一、部署简单、社区活跃绝大多数端侧开发板首选Ollama基于 llama.cpp封装命令行一条命令拉模型起服务接口 OpenAI 兼容快速原型和中小型项目MLC-LLM支持 iOS/Android/WebGPU移动端和浏览器端优化好手机、边端 Web 应用RKLLM-ToolkitRockchip NPU模型转成 RKLLM 格式走 6 TOPS NPU瑞芯微平台省 CPU 资源TensorRT-LLMJetson/英伟达 GPU官方优化延迟低Jetson 平台追求极致性能vLLM服务器 GPUPagedAttention高吞吐多并发设备服务端侧一般用不到这里面 vLLM 需要单独说一句它是为高并发、高吞吐设计的服务端框架端侧设备内存小、并发低硬上 vLLM 只会徒增开销。端侧智能体通常是单用户或低并发场景llama.cpp 或 RKLLM 就够了。很多项目把能上 vLLM当成技术先进性的象征其实在端侧这叫杀鸡用牛刀。4.2 llama.cpp 从源码到服务llama.cpp 是目前端侧部署最通用的选择我直接演示一遍完整流程以 RK3588 的 Ubuntu 系统和 Jetson 的 JetPack 系统为例。第一步拉源码编译git clone https://github.com/ggml-org/llama.cpp cd llama.cpp cmake -B build cmake --build build --config Release -j$(nproc)如果是在 Jetson 平台并为其他平台做评估可以加上 CUDA 支持编译cmake -B build -DGGML_CUDAON -DCMAKE_CUDA_ARCHITECTURES87 cmake --build build --config Release -j$(nproc)在纯 CPU 平台上也可以加上 OpenBLAS 或者 OpenCL 后端让矩阵计算快一些。编译完先跑一下内置的测试确认二进制没问题再下载模型。模型用 Hugging Face 下载比较方便huggingface-cli download Qwen/Qwen2.5-7B-Instruct-GGUF \ qwen2.5-7b-instruct-q4_k_m.gguf --local-dir ./models然后启动 OpenAI 兼容的服务./build/bin/llama-server \ -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 \ -c 4096 \ --chat-template chatml启动之后用 curl 请求一次就能验证curl http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-7b,messages:[{role:user,content:你好}],stream:false}这一步成功说明模型部署通了。接着用一个关键参数把服务的上下文限制好-c 4096表示最多缓存 4096 个 token 的上下文这个值要根据之前算过的 KV Cache 账来定不是越大越好。很多新手把上下文拉到 32K然后发现速度慢得像蜗牛就是因为 KV Cache 把内存带宽吃掉了。这里提示一个部署时特别容易忽略的参数--chat-template。不同模型使用不同的对话模板Qwen 系用 ChatMLLlama 系用 Llama Chat模板错了模型会输出乱码或者答非所问。llama.cpp 模型文件里通常自带模板信息但有些 GGUF 文件模板不全手动指定--chat-template是保险做法。4.3 RK3588 走 NPU 的路线如果用 RK3588 做端侧智能体还有一个不同于纯 CPU 路线的选项走 Rockchip 的 NPU。RK3588 的 6 TOPS NPU 对端侧来说不算小关键是它能把 CPU 解放出来让模型推理和图像采集、视频编解码并行处理这对带摄像头的智能体项目特别重要。NPU 路线的工具链叫 RKLLM-Toolkit。流程大致是先在 PC 上把模型转换成 RKLLM 格式再用板子上的 runtime 加载推理。转换过程类似# 在 PC 端用 rkllm-toolkit 转换 rkllm_toolkit --model_path qwen2.5-3b-sft \ --target_platform rk3588 \ --quantize w8a8 \ --output qwen2.5-3b.rkllm转换完成后把.rkllm文件传到板子上用官方提供的 RKLLM runtime 库集成调用。runtime 提供 C 和 Python API可以直接把输出接进智能体逻辑。走 NPU 路线要注意的点不少。第一RKLLM 对模型支持有名单不是所有模型都能直接转换Qwen2.5 系列、Phi 系列这类主流小模型基本没问题但太新的模型可能要等工具链适配。第二W8A8 量化下体积偏大3B 模型大约 3GB 多7B 模型要 7GB 以上8GB 版本跑 7B 会很紧张。第三NPU 推理时的 concurrency 支持有限串行调用为主智能体如果频繁并行发请求要考虑排队策略。从我自己的实测看RK3588 上 Qwen2.5-3B 走 NPU 可以获得比纯 CPU 快不少的速度而且 CPU 几乎不占用。但如果只是做原型验证纯 CPU 的 llama.cpp 会省心很多等逻辑全部跑通再换 NPU 也不迟。4.4 Jetson Orin 用 CUDA 加速的路线Jetson 平台和 RK3588 路线不同。Jetson 自带 CUDA 核心和 Tensor Corellama.cpp 编译 CUDA 版本就能直接用不需要额外转换模型。Orin Nano 建议从 7B 起步Orin NX 16GB 能扛到 14B。Jetson 上首先确认 JetPack 版本。JetPack 5 和 6 的 CUDA 环境有差异llama.cpp 编译时用-DGGML_CUDAON会自动检测。编译前注意设置前面提到的CMAKE_CUDA_ARCHITECTURES87因为 Orin 系列是 Ampere 架构不指定架构会导致生成的 cubin 无法在目标 GPU 上运行。启动服务时Jetson 平台可以加几个参数./build/bin/llama-server \ -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 \ -c 8192 \ -ngl 99 \ --chat-template chatml-ngl 99表示把所有层都加载到 GPU 上数字改成某个具体数值就是只放一部分层到 GPU。这里有一个经验如果 GPU 内存不够把模型切成一半在 GPU 一半在 CPU性能会大打折扣因为 CPU 和 GPU 之间反复搬运权重的开销比想象中大得多。与其这样不如换更小的量化档位或者更小的模型保证所有层都能放进 GPU。Jetson 的另一个特色是电源模式。用nvpmodel和jetson_clocks可以切换运行模式sudo nvpmodel -m 0 # 最大性能模式 sudo jetson_clocks # 锁住高频默认的低功耗模式下GPU 频率被限制得很低模型推理速度会明显偏慢。很多玩家说自己 Orin 上 7B 模型只有 5 token/s一问就是忘了调电源模式。但也要提醒一句锁高频之后功耗和发热都会上去如果设备是闷在壳子里的长时间跑可能降频甚至重启。工业场景建议根据散热条件选一个折中的电源模式而不是无脑拉满。5. 从模型服务到智能体Function Calling 与框架对接5.1 让模型学会调用工具的三种做法模型跑起来了服务也起来了但这只是第一步。端侧智能体和普通聊天机器人的区别在于能不能可靠地调用工具。常见的实现方式有三种按推荐程度排。第一种是模型原生支持工具调用。Qwen2.5-Instruct、Llama-3.1 这类模型在训练阶段就加入了工具调用数据只要你按正确格式把工具描述、系统提示和用户请求喂给它它就能输出结构化 JSON告诉你该调哪个函数、参数是什么。这是目前最推荐的方案可靠性最高但要确认你选的模型确实支持这个能力并且用对了模板。第二种是纯提示词约束。把工具列表写进系统提示约束模型只能输出某种格式然后用代码解析输出。这种方式对模型要求高小模型很容易在复杂任务里无视格式输出一段废话。一般只作为后备方案。第三种是用推理引擎的 JSON 输出约束。llama.cpp 支持 GBNF 语法和 JSON schema 约束可以在解码阶段强制模型输出合法 JSON。配合工具调用模板能明显提升输出格式的可靠性。代价是约束过强时可能影响模型语义理解需要在约束和自由发挥之间调平衡。无论用哪种方式工具定义本身很重要。工具描述要具体参数类型要明确枚举值要写清楚。端侧模型能力有限一个含糊的工具描述就会让它乱传参数。我在项目里会把工具描述当成给实习生写需求文档来对待每一步都讲清楚禁止使用模糊词汇。5.2 用 OpenAI 兼容接口接入智能体框架模型服务搭好后接入智能体框架的方式通常非常统一不管用 LangGraph、CrewAI、AutoGen 还是自研调度逻辑只要模型服务提供 OpenAI 兼容的/v1/chat/completions接口就直接替换base_url。以 LangChain 生态为例代码长这样from langchain_openai import ChatOpenAI llm ChatOpenAI( modelqwen2.5-7b-instruct, base_urlhttp://127.0.0.1:8080/v1, api_keynot-needed, temperature0.3, timeout60, ) # 然后直接把 llm 传给 Agent 节点Ollama 更省事一条命令启动ollama pull qwen2.5:7b ollama run qwen2.5:7b它的默认端口是 11434接口同样是 OpenAI 兼容路径/v1/chat/completions智能体框架里把base_url指过去就能用。这步操作门槛很低但有个隐藏重点超时配置。端侧模型推理速度比云端慢一个数量级云端习惯设置的 510 秒超时在端侧根本不够用。我一般建议至少 60 秒起步涉及长上下文或复杂工具调用时直接 120 秒。否则智能体框架很容易因为超时而把正常的慢响应当成故障触发重试或者直接中断任务。重试问题也很烦云端模型重试一次问题不大端侧模型重试一次就意味着用户要多等一整轮推理而且同一请求重试还会空耗算力。5.3 并发调度与功耗控制端侧模型服务默认一次只能处理一个请求或者支持极有限的小批量。不是引擎做不到而是硬件资源摆在那里。智能体框架如果设计成多个任务并行每个任务调一次模型请求就会在服务端排队整体体验反而变慢。解决方法是智能体侧做请求串行化。框架里用一个信号量或队列把所有 LLM 请求串起来保证同时只有一个请求到达模型服务。实测下来串行请求 较短上下文比并行请求 内存溢出或者频繁换页的体验好得多。这点和服务器端高并发是反着来的也别指望用扛并发的思路去优化端侧模型服务那是硬件的天花板决定的。功耗控制同样重要。开发板不是服务器长时间满负荷推理会让电源和散热都吃紧。我的建议是三层控制第一层模型量化档位决定基础功耗Q4 比 Q8 省接近一半的带宽和功耗第二层在智能体逻辑里减少无效调用比如能走规则判断的简单分支就不要让模型介入给模型减负才是最大的省电第三层在系统层面做频率管理Orin 用 nvpmodelRK3588 可以用 DTS 调频策略让设备在低负载时自动降频。特别提醒端侧智能体如果涉及摄像头持续采集CPU 和 NPU 会争抢内存带宽。模型推理和图像处理同时发生时两者都会变慢。解决思路是错峰处理或者把图像预处理放到独立的视频处理单元上尽量别让两个重负载任务同时抢总线。6. 常见问题与排查实录6.1 推理速度慢得离谱速度慢是端侧部署最常遇到的问题而且原因五花八门。排查时我会按以下顺序走一遍。先看模型体积和内存带宽的比例。如果用的模型是 Q8 量化、文件体积快 9GB而板子带宽只有 34GB/s那 34 token/s 就是物理极限不是调优能解决的。这种就换 Q4 量化或者换更小的模型。再看引擎配置。llama.cpp 启动参数里-t线程数设置太小时 CPU 核心用不满-ngl层数设置太小时 GPU 加速等于摆设。还有一个常见坑CPU 设备的--mlock参数如果不锁内存模型权重可能在内存和 swap 之间来回搬运速度慢到让人怀疑人生。内存够用的板子建议把模型权重锁进内存。接着看系统状态。用top、htop看 CPU 占用率用nvidia-smi看 Jetson 的 GPU 占用和温度。查到温度 90 度以上就去调整电源模式和散热。开发板散热不是能开机就行满载推理十分钟和满载推理两小时的温度完全不同。最后还要看是不是上下文拉太长。KV Cache 占用过大会挤占内存带宽同样一个模型4096 上下文和 32K 上下文的实测速度可能差出一倍。这个因素最隐蔽但影响最直接。6.2 内存不够与进程被杀OOM 的表现通常是进程直接被系统杀掉日志里出现 Killed 字样。排查思路是看 dmesg 或者journalctl确认是不是 OOM。然后回到第 2.3 节的那本账模型体积 KV Cache 系统占用是不是超过了内存上限。解决方案按优先级排列减少上下文长度换更低档位的量化换更小的模型关闭模型服务里不必要的内存缓存。实在不行把系统里不需要的服务关掉给模型腾地方。要特别说一句swap 不是端侧 LLM 的救星。虽然开 swap 可以让进程不立刻被杀但模型权重一旦换出内存推理速度会跌到不可用的程度而且反复换页会大量磨损 SD 卡或者固态盘。开发板上的 NVMe 一般是 TLC 颗粒频繁 swap 会明显缩短寿命。所以我通常不建议靠 swap 硬撑。6.3 输出乱、格式错、工具调用失效输出乱码或者答非所问排第一的原因一定是对话模板错误。用 llama.cpp 时--chat-template指定的模板必须和模型训练时一致用 Ollama 时默认模板一般是对的但如果你是自己下载 GGUF 手动起服务就很容易错。典型症状是模型重复系统提示、把用户消息原样吐回来、或者在回答前加一堆神秘字符。格式错是另一类高频问题。模型该输出 JSON 的时候输出了一段解释文字这在工具调用场景里意味着解析失败。排查顺序是确认模型本身支持工具调用确认工具描述和 JSON schema 没有冲突确认系统提示有没有要求模型输出 JSON最后再考虑用引擎的 JSON 约束功能强制格式。工具调用失效还有一种情况模型把函数名或者参数名改了。这通常是模型太小的原因3B 以下模型在这种场景最容易出问题解决办法是换大模型或者在工具描述里写得更死板。我见过一个项目工具名叫turn_on_light模型每次都输出turn_on_the_light这就是典型的语义过度泛化。6.4 智能体链路超时与崩溃模型服务本身正常但智能体框架一直报超时或连接错误这种情况大多出在接口对接层。先检查base_url是否拼对OpenAI 兼容接口基本都要求/v1结尾再检查超时参数端侧按第 5.2 节说的调大最后检查模型服务是否还在运行端侧设备上服务被 OOM 杀掉是常有的事建议用 systemd 或者 supervisor 把服务守护起来崩溃后自动拉起。还有一个很多人会忽略的问题流式输出。智能体框架默认经常开启streamtrue如果模型服务的流式输出实现不标准框架解析会有问题。通信时如果发现首帧迟迟不来可以在模型侧检查是否预填充耗时过长。长 Prompt 场景下几千个 token 的预填充可能要好几秒这在端侧很正常不要因为首字太慢就觉得服务卡死了。链路稳定性建议做一个最简单的健康检查脚本定期请求一次/v1/models连续失败就重启服务。这个脚本放 cron 里每两分钟跑一次开销可以忽略但对生产环境的保障价值极高。机器重启后模型服务也要能自动起来这些细节看着不酷却是端侧智能体真正能落地和只停留在 demo的分水岭。排查问题的时候最好养成一个习惯每次改动只改一个变量。先固定模型调引擎参数引擎参数固定了再动模型。很多朋友喜欢一次性改动三个配置出了问题根本分不清是谁导致的。端侧环境不像云端那样可以随便上监控平台排查问题靠的其实就是这种朴素的控制变量法。最后再分享一个我做端侧 Agent 项目的习惯所有部署文档里一定把硬件型号、内存规格、JetPack 或系统版本、引擎版本、模型文件 ID、量化档位、启动参数这七项完整记录下来。同样一个模型别人能跑你不能跑、昨天能跑今天不能跑排查时往往就是这七项里某一项对不上。本地部署这行所谓经验很大一部分就是把每次踩坑的环境快照保存下来下次对照着少走弯路。