llama.cpp 参数调优指南Jetson 8GB 实战手记平台Jetson Orin Nano Super 8GBJetPack 6.2 / CUDA 12.6模型Qwen2.5-3B Q4_K_M、Qwen2.5-VL-3B Q4_K_M mmproj-f16数据基准全部真机实测tegrastats 自写 bench 脚本未实测处明确标注很多人用 llama.cpp 就是 ./llama-server -m model.gguf 一把梭能用但在 8GB 这种资源受限板子上默认参数随时教你做人上下文溢出、swap 抖动、功耗撞墙。这篇文章把我在 Jetson 8GB 上部署 Qwen2.5 系列时实际调过的参数整理成一份指南——每个参数说清楚干什么、怎么选、我踩过什么坑。一、先建立心智参数分五组llama.cpp 的参数看着几十个其实就五类问题分组回答的问题核心参数① 模型加载装什么、怎么装-m、–mmproj、–mlock、–no-mmap② GPU 卸载多少层放 GPU-ngl③ 显存/上下文8GB 怎么分–ctx-size、–cache-type-k/v、-np、-cram④ 性能并发跑多快、扛几路-t、-b/-ub、–flash-attn、–parallel⑤ 生成采样输出质量–temp、–top-p、–top-k、–repeat-penalty资源受限设备的调优顺序先保证不崩③→ 再榨速度②④→ 最后调质量⑤。顺序反了就是白忙。二、模型加载组-m 主模型路径没争议但量化档位的选择是第一个分水岭档位3B 模型体积我的选择Q4_K_M~2GB✅ 主力体积/精度平衡点Q5_K_M~2.4GB精度略好8GB 上余量变薄Q8_0~3.4GB❌ 8GB 上 KV cache 没空间了经验8GB 板子 3B 模型Q4_K_M 是甜点再往上每一 GB 都在抢 KV cache 的地盘。–mmproj 视觉投影VLM 专用部署 Qwen2.5-VL 这类多模态模型时必须单独挂–mmproj Qwen2.5-VL-3B-Instruct-mmproj-f16.gguf坑 1实测踩过漏挂 mmproj文本问答正常一发图片请求直接 500。排查半天以为是服务崩了其实是视觉塔没加载。坑 2mmproj 保持 f16 别量化。视觉编码器对精度敏感量化后 grounding坐标输出容易漂移——f16 版本约 1.2–1.4GB这钱省不得。–mlock / --no-mmap–mlock把权重锁在物理内存防 swap。8GB 板子上我强烈建议加——我实测常驻 7078MB 时被挤了 580MB 进 swap推理延迟立刻抖。–no-mmap不用内存映射、启动时全量读入。启动慢一点但首次推理不会因为按需调页而卡一下。SD 卡启动的板子别用读盘慢eMMC/SSD 随意。三、GPU 卸载组-ngl offload 层数-ngl 99 # 全部层卸载到 GPU直接给结论Jetson 上无脑 99。 3B 模型 36 层全扔 GPU 后 CPU 只剩预处理活实测 CPU 六核基本 0–1%。唯一例外是模型KV cache 真塞不下时才减少层数让部分层回 CPU——但那是降级方案速度掉一个量级不如降量化档位。四、显存/上下文组8GB 生死线–ctx-size 上下文长度最大的坑重点讲这个参数决定了 KV cache 预分配多少内存是 8GB 板子上最先要算的账KV cache 占用 ≈ 层数 × ctx × KV头维度 × 2(KV) × 每元素字节数不用背公式记住我实测的两个锚点就行ctx2048 时 Qwen2.5-VL-3B 直接溢出一张 768px 图片产生约 2716 个视觉 token报错 2716 2048——图还没说话上下文就满了。VLM 场景的 ctx 必须给视觉 token 留足预算我后来调到 3072 才正常。ctx 开大是有代价的3072 比 2048 多占几百 MB我实测常驻 RAM 到 7078MB、触了 580MB swap。权衡办法ctx 该给够但图片输入侧降分辨率视觉 token 数随分辨率平方涨两头挤一挤就平衡了。经验值3B 模型 8GB纯文本 2048 够用VLM 至少 3072且喂图前把长边压到 768px 以内。–cache-type-k / --cache-type-v KV cache 量化KV cache 默认 f16可以量化成 q8_0 甚至 q4–cache-type-k q8_0 --cache-type-v q8_0ctx 开大后 KV cache 成为大头时这是不降 ctx 还能省内存的关键手段。q8_0 精度损失很小q4 损失明显尤其长上下文注意力。我在 8GB 上的策略宁肯 KV cache 上 q8_0也不砍 ctx——上下文不够是直接报错精度略降是软性损失。但注意KV cache 量化是补救手段不是默认配置。 纯文本 3B ctx 2048 时 KV cache 才几百 MB内存离红线还远实测未触 swap加了白吃精度损失——尤其 Function Calling 这类要确定性的场景没病不吃药。真正的触发条件就一条常驻内存逼近红线或已触 swap。 所以下面两份启动命令里纯文本版不加、VLM 版ctx 3072实测触过 swap才加。-np 并行序列数–parallel N 允许 N 路并发但每路都独立吃一份 KV cache——8GB 板子上 -np 1 就是正确答案开并发前先确认内存余量。这也是我 ROS2 机器人项目里坚持单请求串行 请求缓存的原因板子就这点内存并发是奢侈品。-cram / --cache-ram prompt 缓存上限新版 server 参数容易和前两个cache混淆在内存有限的边缘设备部署时如果你的显存不够很容易-cram 2048 # prompt cache 上限 2048 MiB默认 8192-1 不限0 禁用llama-server 会把已算过的 prompt 前缀 KV 存进 RAM下次请求前缀命中就跳过 prefill 直接续算——会话级缓存思路和我在应用层做的 LRU 指令缓存一样只是它藏在引擎内部。三个cache别搞混参数缓存什么影响–ctx-size当前会话正在推理的 KV装不下直接报错–cache-type-k/v上面这个 KV 的存储精度省内存、略掉精度–cache-ram历史请求的 prompt 前缀 KV供下次命中命中省 prefill 时间8GB 上的坑默认上限 8192 MiB 是照着桌面机给的你的板子总共才 7607MB。它按实际使用增长、上限只是封顶但长期跑多轮会话prompt cache 悄悄吃掉 1–2GB 是真实风险。我的处理机器人 FC 场景指令短、重复前缀少且应用层已有指令缓存直接 -cram 0 禁用多轮长对话场景给 -cram 2048 折中。五、性能并发组-t CPU 线程数GPU 全卸载后 CPU 只干预处理-t 4 足够Orin Nano 6 核留 2 核给系统。-t 开满反而可能因为调度竞争更慢。-b / -ub batch 大小prefill 阶段一次处理多少 token。默认 512/2048 在 Jetson 上工作正常我没动过——这是调了也没明显收益的一类参数除非你 prefill 特别慢否则别折腾。–flash-attn FlashAttention–flash-attn建议开。省 KV cache 访存带宽长上下文下收益更明显。注意个别老模型架构不支持会告警Qwen2.5 系列实测正常。功耗档位不算 llama.cpp 参数但比参数更猛这是我实测里收益最大的单一调优而且不在 llama.cpp 里sudo nvpmodel -m 2 # 25W 模式Orin Nano Supersudo jetson_clocks # 锁最高频指标15W默认25W超频提升纯文本 Decode15.3 tok/s23.9 tok/s56%图片理解 Decode15.2 tok/s23.5 tok/s55%图片 TTFT2525ms1694ms−33%一句话软件参数抠半天不如功耗档位切一刀。 当然 25W 要主动散热连续跑注意温度Orin Nano 降频墙 ~87°C。六、生成采样组按场景抄作业llama-server 支持 OpenAI 兼容参数我的三组预设场景temptop_prepeat_penalty理由Function Calling / 结构化输出0.1–0.20.91.0要确定性乱发挥就是 bug问答 / VQA0.3–0.50.91.05少量灵活性防复读闲聊0.7–0.80.951.1多样性优先机器人项目里我 FC 用 temp0.13B 小模型本身就会漂采样上绝不能再给它自由度。输出 JSON 格式错了靠双模式解析兜底但源头能压就压。七、我的启动命令实测版直接抄纯文本机器人 Agent 后端./build/bin/llama-server-m ~/models/Qwen2.5-3B-Instruct-Q4_K_M.gguf-ngl 99–ctx-size 2048-np 1–flash-attn–mlock-t 4–host 0.0.0.0 --port 8080视觉理解Qwen2.5-VL./build/bin/llama-server-m ~/models/qwen2.5-vl-3b/Qwen2.5-VL-3B-Instruct-Q4_K_M.gguf–mmproj ~/models/qwen2.5-vl-3b/Qwen2.5-VL-3B-Instruct-mmproj-f16.gguf-ngl 99–ctx-size 3072-np 1–cache-type-k q8_0 --cache-type-v q8_0–flash-attn–mlock-t 4–host 0.0.0.0 --port 8080差异就三处VLM 多挂 mmproj、ctx 从 2048 提到 3072、KV cache 上 q8_0ctx 开大后内存逼近红线用 KV 量化换余量——纯文本版内存宽裕则不加。注意两份命令都显式写了 -np 1-np 默认是 -1auto服务器按需开槽位内存行为不可预测。机器人场景必须锁单槽位——内存可预测全系统就一份 KV、行为确定性车同一时刻只执行一条指令并发调度交给应用层引擎层不开多头。八、调优 SOP四步走空载基线tegrastats 记一条我的RAM 2570MB / 整板 4.5W / ~50°C常驻采样模型加载完、未发请求记 RAM我的7078MB注意 swap 是否为 0——不为 0 就先降 ctx 或加 --mlock负载采样发真实请求看 GR3D_FREQ应 90%、VDD_IN 峰值、tj 温度基准对比固定 prompt 测 TTFT/Decode改一个参数测一轮——一次只动一个变量否则不知道是谁起的作用九、排错速查表症状最可能原因第一动作发图 500文本正常漏挂 --mmproj查启动日志有没有 mmproj 加载行XXXX 2048 报错ctx 装不下视觉 token升 ctx 或压图片分辨率推理中途变慢、抖动SWAP 0tegrastats 确认加 --mlock、降 ctx速度只有个位数 tok/s层没卸载到 GPU查 -ngl看日志 CUDA 字样输出重复、漂移采样太自由temp 降到 0.3 以下温度撞墙降频25W 档散热不够tegrastats 看 tj加强散热写在最后8GB 板子调 llama.cpp本质是做预算权重、KV cache、系统三家分 8GB谁多谁少全凭参数权衡。我的原则就三条——先不崩ctx 算够、再求快ngl 99 功耗档、防抖动mlock 看住 swap。参数全都可以测别信任何推荐值包括我这篇——在你的板子上跑一遍 tegrastats比什么都准。