llama-bench 是 llama.cpp 生态中用于测量模型推理性能的核心工具。它的主要功能是在不同硬件后端、模型量化等级和运行参数下，给出可复现、可对比的吞吐量与延迟数据，帮助你在本地部署时进行性能调优和配置选型。
🎯 核心功能：三种测试类型
llama-bench 围绕推理的两个阶段设计了三种测试模式：
- Prompt Processing (
pp) ：测量提示词处理 速度。它反映模型"阅读"并理解输入文本的快慢，主要影响首字延迟（TTFT） 。通过-p指定提示词 token 数，并将-n设为 0 来单独测试。 - Text Generation (
tg) ：测量文本生成 速度。它反映模型逐字"输出"的快慢，决定了长回答的生成效率。通过-n指定生成 token 数，并将-p设为 0 来单独测试。 - Combined (
pg) ：测量提示处理 + 文本生成 的连续表现。格式为-pg <pp>,<tg>，例如-pg 512,128表示先处理 512 token 的提示，再生成 128 token。
此外，通过 -d / --n-depth 参数，可以先将 KV Cache 预填充到指定深度，再执行测试，用以评估长上下文场景下的性能衰减情况。
⚙️ 关键参数速览
llama-bench 的参数可按功能分为以下几类。除 -r、-o、-v 外，几乎所有参数都可以指定多次或使用逗号分隔的列表 （如 -n 128,256,512），以自动运行多组对比测试。
📝 测试控制
| 参数 | 含义 | 默认值 |
|---|---|---|
-r, --repetitions |
每个测试的重复次数，用于取平均值和标准差 | 5 |
--delay |
每个测试之间的延迟（秒），避免热累积影响 | 0 |
--no-warmup |
跳过测试前的预热运行 | 否（默认预热） |
🧠 模型与后端
| 参数 | 含义 |
|---|---|
-m, --model |
指定 GGUF 模型文件路径，可多次指定以对比不同模型 |
-hf, --hf-repo |
直接从 Hugging Face 拉取模型，格式为 user/model[:quant] |
-ngl, --n-gpu-layers |
卸载到 GPU 的层数 。-1 或 99 通常表示全部卸载；设为 0 则强制使用 CPU |
-dev, --device |
指定使用的设备（如 CUDA0、Vulkan0），用于多 GPU 选择 |
-sm, --split-mode |
多 GPU 分割模式：none、layer（按层分割）或 row |
-t, --threads |
CPU 线程数 |
-fa, --flash-attn |
是否启用 Flash Attention（0 或 1），对长上下文性能影响显著 |
🔧 性能与缓存调优
| 参数 | 含义 | 默认值 |
|---|---|---|
-b, --batch-size |
逻辑批大小（影响吞吐） | 2048 |
-ub, --ubatch-size |
物理微批大小（受显存限制） | 512 |
-ctk / -ctv |
K/V Cache 的数据类型（如 f16、q8_0） |
f16 |
-mmp, --mmap |
是否使用内存映射加载模型（0 或 1） |
1（启用） |
📤 输出与格式
| 参数 | 含义 |
|---|---|
-o, --output |
输出格式：md（Markdown，默认）、csv、json、jsonl、sql |
-oe, --output-err |
将结果同时输出到 stderr，便于脚本捕获 |
--list-devices |
列出当前可用的计算设备后退出 |
📊 输出指标解读
默认的 Markdown 输出会呈现一个清晰的表格，核心列的含义如下：
| 列名 | 含义 |
|---|---|
model |
模型名称与量化类型（如 llama 7B Q4_0） |
size |
模型文件大小 |
params |
模型参数量（如 6.74 B） |
backend |
实际使用的计算后端（如 CUDA、Metal、CPU） |
ngl |
卸载到 GPU 的层数 |
test |
测试类型与规模，如 pp512、tg128，带 @d512 表示上下文深度 |
t/s |
核心吞吐量指标：每秒处理的 token 数，越高越好 |
t/s 通常以 平均值 ± 标准差 的形式呈现，例如 132.19 ± 0.55 表示平均约 132 token/s，波动很小，结果稳定可靠。需要注意，在 pg 测试中，如果只关注纯生成速度，不能直接使用端到端的平均 t/s，因为它混入了提示处理的时间。此时更应参考工具可能分别报告的 Prompt Throughput 和 Generation Throughput。
💡 典型使用示例
1. 基础测试：全部层卸载到 GPU，使用默认参数
bash
llama-bench -m model.gguf -ngl 99这会依次运行 pp512 和 tg128，给出该模型在当前 GPU 上的基准表现。
2. 对比不同模型或量化的生成速度
bash
llama-bench \
-m model-q4_0.gguf \
-m model-q4_k_m.gguf \
-m model-q5_k_m.gguf \
-p 0 -n 128,256,512-p 0 关闭提示处理，专注于比较不同量化等级在多个生成长度下的 tg 速度。
3. 测试不同 GPU 卸载层数的影响
bash
llama-bench -m model.gguf -ngl 0,10,20,30,99 -p 512 -n 0通过列表 -ngl 0,10,20,30,99，一次运行即可观察从纯 CPU 到全 GPU 卸载过程中，提示处理速度的变化趋势。
4. 评估长上下文下的性能
bash
llama-bench -m model.gguf -p 512 -n 128 -d 4096使用 -d 4096 将 KV Cache 预填充到 4096 token 深度，再执行测试，以模拟真实的长对话场景。
⚠️ 注意事项
- 确保后端一致性 ：
llama-bench会使用编译llama.cpp时启用的后端。在对比测试前，建议先用--list-devices确认可用设备，并尽量在相同后端下比较。 -ngl的默认值因版本而异 ：部分旧版文档显示默认值为99，而较新的代码中可能为-1（自动）。为获得确定结果，显式指定-ngl是更稳妥的做法。- 合理设置重复次数 ：对于追求精确对比的场景，可以考虑将
-r提高到10或更高，以降低测量噪声的影响。