# 本地模型测速一键执行指南（SOP 完整版）
## ——基于当前 GitHub 官方工具 + 本地推理实践经验

**核对日期：2026-10-13**  
**定位：** 给论坛读者、本地 Agent、个人工作站用户使用的可复现测速 SOP。  
**范围：** 只讨论**速度 / 延迟 / 吞吐 / 资源占用**，不涉及模型质量评测。  

---

# 1. 这份 SOP 的原则

本指南不试图发明一套新的“大一统 Benchmark”。

而是：

1. **裸性能**：引用 `llama.cpp / llama-bench`
2. **API / 实际服务体验**：引用 `GuideLLM`
3. **并发 / Serving / 饱和点**：引用 `Kubernetes SIG inference-perf`
4. **客户端整机标准化体验**：引用 `MLPerf Client`

在此基础上，再加入一套适合论坛横向比较的**统一测试条件、准备工作、Cache 规则、长 Context 规则、失败判定、报告模板和 Agent 一键 Prompt**。

> 官方工具负责“怎么测”；本 SOP 负责“怎样让不同人的结果尽量可比较”。

---

# 2. 常用性能指标与术语

| 缩写 | 英文全称 | 中文解释 | 主要看什么 |
|---|---|---|---|
| PP | Prompt Processing | 提示词处理 / Prefill | 模型处理输入上下文的速度，通常 tok/s |
| TG | Text Generation | 文本生成 / Decode | 模型持续生成输出 Token 的速度，通常 tok/s |
| TTFT | Time To First Token | 首 Token 延迟 | 请求发出到收到第一个输出 Token 的时间 |
| TPOT | Time Per Output Token | 平均每个输出 Token 的耗时 | Decode 阶段平均延迟，常用 ms/token |
| ITL | Inter-Token Latency | Token 间延迟 | 相邻流式输出之间的时间间隔 |
| TPS | Tokens Per Second | 每秒 Token 数 | 每秒生成多少 Token |
| E2E | End-to-End Latency | 端到端总耗时 | 请求发出到完整响应结束 |
| QPS / RPS | Queries / Requests Per Second | 每秒请求数 | Serving 吞吐 |
| Goodput | Goodput | 有效吞吐 | 在满足 SLO 的前提下真正有效完成的请求速率 |
| C1/C2/C4/C8 | Concurrency | 并发 1/2/4/8 | 同时存在多少请求 |
| VRAM | Video RAM | 显存 | 模型、KV Cache、临时 Workspace 等 GPU 占用 |

简单理解：

- **PP**：吃得快不快
- **TTFT**：多久开口
- **TG/TPS**：说得快不快
- **ITL**：会不会一卡一卡
- **E2E**：整件事多久做完

---

# 3. 测试前准备：必须记录的环境

任何 benchmark 之前，先记录环境。

## 3.1 硬件

至少记录：

| 项目 | 内容 |
|---|---|
| GPU | 型号、数量、显存 |
| CPU | 型号 |
| RAM | 容量、频率（能确认则写） |
| 主板 | 型号 |
| PCIe | GPU 实际链路宽度/代际（能确认则写） |
| 存储 | 模型所在 SSD/HDD 类型（如影响加载） |
| 电源模式 | Performance / Balanced / 其他 |
| GPU 功耗限制 | 默认 / 手动限制 |
| GPU 频率策略 | 默认 / 锁频 / 超频 / 降压 |

## 3.2 软件

至少记录：

| 项目 | 内容 |
|---|---|
| OS | Windows / Linux / macOS + 版本 |
| GPU Driver | 版本 |
| ROCm / CUDA | 版本 |
| Python | 如工具依赖 Python |
| Engine | llama.cpp / vLLM / SGLang / TGI / 其他 |
| Engine Version | Release / commit / build 日期 |
| Benchmark Tool Version | GuideLLM / inference-perf / MLPerf Client 等版本 |
| API | completion / chat / OpenAI-compatible |
| Container | Docker / Podman / bare metal，如有 |

### 为什么版本必须写？

同一模型、同一 GPU，不同：

- Engine commit
- ROCm/CUDA
- Flash Attention 路径
- Kernel
- Scheduler
- Prefix Cache
- KV dtype

都可能明显影响结果。

**只写“7900 XTX 100 t/s”是不够的。**

---

# 4. 测试前准备：必须固定的推理参数

为了做到“苹果和苹果比”，以下参数必须固定或明确记录。

## 4.1 模型参数

- 模型完整名称
- 模型 revision / commit（能确认则写）
- Quant 格式
- Weight dtype
- Activation dtype（如适用）
- MoE / Dense
- 是否有多模态 projector
- 原生最大 Context

## 4.2 服务端参数

至少记录：

- max model length / ctx size
- batch size
- micro-batch / ubatch（如适用）
- tensor parallel / pipeline parallel
- tensor split
- GPU offload 层数
- KV Cache dtype
- Flash Attention 是否开启
- Prefix Cache 是否开启
- CPU offload 是否开启
- Expert offload / Expert Cache（MoE）
- MTP / Speculative Decode 是否开启
- speculative draft length / num speculative tokens（能确认则写）
- scheduler / chunked prefill 等特殊路径
- GPU memory utilization 参数
- mmap / mlock（llama.cpp 如适用）

> 如果你只是测“当前真实生产配置”，不要为了 benchmark 改参数。  
> 如果你是做 A/B 优化实验，每次只改一个变量。

---

# 5. 测试机状态：避免系统噪声

测试前建议：

1. 关闭其他明显占用 GPU 的程序
2. 关闭其他高 CPU / 高磁盘 I/O 任务
3. 确认没有另一个推理请求正在跑
4. 记录 GPU idle VRAM
5. 记录 GPU 温度和功耗状态
6. 如果刚启动模型，先完成 warm-up
7. 长时间压力测试注意 thermal throttling
8. 笔记本必须注明：
   - 是否插电
   - 电源模式
   - dGPU / iGPU
9. 多 GPU 必须确认所有卡的实际 PCIe 链路
10. 若有 NUMA / 多路 CPU，记录 NUMA 策略

### 建议

同一次 A/B benchmark，尽量：

- 同一台机器
- 同一室温/功耗限制
- 同一服务启动参数
- 同一时间段连续测试

不要 A 在冷机测、B 在 GPU 已经高温降频后测。

---

# 6. Warm-up 规则

Warm-up 的目的是排除：

- lazy kernel initialization
- JIT / graph capture
- memory allocation
- page fault
- model mmap 首次访问
- GPU clocks 从 idle 拉升
- allocator 初次扩容

## 6.1 llama-bench

当前 llama-bench 本身有 warmup 流程，并提供 `--no-warmup` 用于关闭。

**论坛建议：不要关闭默认 warmup。**

## 6.2 API Benchmark

GuideLLM 当前 profile 支持 `warmup` / `cooldown`。

论坛建议：

- 简单 C1：先跑 1 次不计入成绩
- 并发压力：用工具自带 warmup/cooldown
- 不把第一轮直接当正式成绩

## 6.3 报告要求

必须写：

```text
Warm-up：有 / 无
Warm-up 次数或比例：
```

---

# 7. 重复次数与统计规则

## 裸性能

`llama-bench` 当前默认：

```text
-r 5
```

即每项 5 次，输出平均 tok/s 和标准差。

论坛建议：**直接沿用官方默认 5 次。**

## API 单用户

建议每个 Context：

```text
10 requests
```

至少记录：

- Median / P50
- P95 或 P99
- Error count

## 为什么不要只报最好一次？

最好一次只能说明：

> “这台机器某一瞬间跑到过多少。”

真正可复现的结果应该至少给：

- Median
- Mean
- P95/P99（延迟指标）
- Std（裸性能）

---

# 8. Context 测试矩阵

论坛建议统一：

```text
4K / 8K / 16K / 32K / 64K / 128K
```

对应：

```text
4096
8192
16384
32768
65536
131072
```

如果模型不支持某一档：

- 测到实际支持上限
- 后续写 `N/A`
- 不要通过偷偷改 RoPE / 换模型来补齐表格

## 为什么是这六档？

- 4K：短问答
- 8K：轻量工作会话
- 16K：中等上下文
- 32K：常见长期工作区间
- 64K：长上下文
- 128K：压力区 / 长 Agent

这不是 GitHub 四套工具共同规定的官方矩阵，而是**论坛建议矩阵**。

---

# 9. Output Length 规则

论坛建议：

```text
Output = 512 tokens
```

理由：

- 太短容易被 TTFT 污染
- Speculative/MTP acceptance 波动影响更大
- Decode 还没进入稳定区间就结束
- 很难看 ITL 长尾

快速筛选可以：

```text
256 tokens
```

正式横向比较优先：

```text
512 tokens
```

## EOS 问题

模型可能提前 EOS。

优先使用工具/服务支持的：

- ignore_eos
- min_tokens
- 固定 synthetic output

如果无法强制：

**必须记录实际输出 token 数。**

不要把：

```text
实际生成 83 tokens
```

和：

```text
实际生成 512 tokens
```

当成完全等价测试。

---

# 10. Prompt / Context 构造规则

这是最容易被忽略的部分。

## 10.1 Token 数必须以目标模型 tokenizer 为准

不要按：

- 字数
- 英文单词数
- 文件 KB 大小

估算 Context。

应该按：

```text
目标模型实际 tokenizer
```

计算。

## 10.2 Chat Template

API Chat 模式下，实际模型输入通常包含：

- system prompt
- role tokens
- chat template
- special tokens

所以：

> “用户文本 8192 tokens” 不一定等于“模型实际 prompt_tokens = 8192”。

正式报告优先使用服务返回的：

```text
prompt_tokens
```

或 benchmark 工具计算的实际 token 数。

## 10.3 固定长度 vs 自然数据

两种都可以，但不能混着比较。

### 合成固定长度

适合：

- GPU / Engine 横向比较
- Context scaling
- 并发测试

### ShareGPT / 真实数据集

适合：

- 更真实 workload
- 生产 Serving

报告里必须注明 Dataset。

---

# 11. Cache：最重要的可比性规则之一

必须至少标记：

```text
Cold / Fresh
Prefix Cache Hit
Unknown
```

## 11.1 Cold / Fresh

定义：

> 本次被计时 Prompt 的目标前缀没有从已有 Prefix Cache 中直接复用。

注意：

**Cold 不一定等于重启整个 Server。**

核心是要明确：

> 有没有 Prefix Cache reuse。

## 11.2 Prefix Cache Hit

如果你就是在测长期 Chat / Agent：

Cache Hit 反而是非常重要的真实指标。

但要单独标：

```text
Warm / Cached
```

不要和 Fresh 混成一个结果。

## 11.3 当前 vLLM 官方警告

vLLM 当前 benchmark 文档明确提醒：

重复对同一个 server 跑相同 prompt，可能复用 Prefix Cache，从而**人为抬高 throughput**。

如果不希望 reuse：

- 改 seed
- reset / restart server
- 或使用会清理 cache 的 sweep 方式

因此：

> Cache 状态不是备注，而是正式 benchmark 条件。

## 11.4 实践建议

Fresh 测试：

- 每轮生成不同内容但相同 token 长度
- 或改变 seed
- 或安全清 cache

不要为了“Cold”测试随意重启生产服务。

如果无法确认：

```text
Cache = Unknown
```

比假装 Cold 更诚实。

---

# 12. TTFT、Prefill 与 Queue Time 不能混为一谈

这是论坛里最容易误用的地方。

## TTFT

客户端看到的：

```text
Request sent → first streamed output
```

TTFT 里可能包含：

- network / IPC
- queue time
- scheduling
- tokenization
- prefill
- first decode step
- streaming flush

因此：

> TTFT ≠ 纯 Prefill 时间

尤其并发时，Queue Time 可能占掉大头。

## Prefill tok/s

如果 Engine 提供原生：

```text
prefill_time
prompt_tokens
```

可以更准确计算。

如果只能：

```text
prompt_tokens / TTFT
```

必须标记：

```text
“客户端近似 Prefill”
```

不要把它写成纯 Engine Prefill。

---

# 13. Decode TPS、TPOT、ITL 的关系

## TPOT

当前 vLLM 官方定义：

```text
TPOT = (E2E - TTFT) / (output_tokens - 1)
```

它是：

> 整个 Decode 阶段平均到每一个输出 token 的时间。

对应近似：

```text
Decode TPS ≈ 1000 / TPOT(ms)
```

在普通 AR Decode 下，这个近似通常很好。

## ITL

ITL 是：

```text
连续两次 streamed output 之间的时间
```

### 关键坑：一个 streaming chunk 不一定等于一个 token

尤其：

- Speculative Decoding
- MTP
- 一次 engine step 接受多个 draft token

一个 SSE / streaming chunk 可能包含多个 token。

因此：

> 不能简单用 “1 / chunk interval” 当成 token/s。

这是非常容易制造“虚高 Decode TPS”的方法。

---

# 14. Speculative / MTP：ITL 和 TPOT 必须分开看

vLLM 当前官方文档明确说明：

在普通 decoding 下：

```text
ITL ≈ TPOT
```

但在 speculative decoding 下：

一个 streamed output 可能一次包含多个 accepted tokens。

于是：

- ITL：只看到 streaming event 之间的间隔
- TPOT：按所有真正输出 token 平摊 Decode 时间

因此：

> Speculative/MTP 测试不能只拿 ITL 换算 TPS。

建议同时报告：

| 指标 | 说明 |
|---|---|
| TPOT | 真正 token 级平均 Decode 延迟 |
| ITL P50/P99 | streaming 流畅度 |
| Output TPS | 实际输出吞吐 |
| Acceptance Rate | speculative 接受率 |
| Accepted Tokens | 被接受 draft token 数 |
| Draft Tokens | 尝试 draft token 数 |

---

# 15. Max Stall / 卡顿规则

官方工具通常提供 ITL 分布。

论坛实践建议额外观察：

```text
Max Stall
```

即：

> 单个请求里最长的一次无输出停顿。

因为：

```text
平均 Decode = 100 t/s
```

并不代表体验一定流畅。

可能出现：

```text
大部分时间 150 t/s
中间突然停 2 秒
```

如果工具能输出 per-request / per-token latency：

建议记录：

- ITL P50
- ITL P95
- ITL P99
- Max ITL / Max Stall

---

# 16. VRAM / RAM / GPU 指标

至少记录：

- Idle VRAM
- Peak VRAM
- System RAM peak

建议有条件再记录：

- GPU utilization
- GPU power
- GPU clock
- GPU temperature
- PCIe RX/TX
- CPU utilization

## MoE / CPU Offload 额外建议

记录：

- Host RAM
- PCIe traffic
- Expert Cache
- CPU utilization
- offload 层/专家数量

因为 MoE 的 Decode 性能经常受：

```text
PCIe + host memory + expert movement
```

影响，而不仅仅是 GPU FLOPS。

---

# 17. Thermal Throttling / 功耗墙

长时间测试必须注意：

- GPU 频率是否下降
- 温度是否接近 throttle
- 功耗是否 hit power limit
- CPU 是否因散热降频

如果前 3 分钟 120 t/s，20 分钟后只剩 105 t/s：

这不是同一工作状态。

建议长压力测试报告：

```text
测试开始 GPU 温度 / Clock / Power
测试结束 GPU 温度 / Clock / Power
```

---

# 18. 失败判定规则

不要为了让表格好看，把失败档位删掉。

建议统一：

| 状态 | 写法 |
|---|---|
| Out of Memory | OOM |
| 请求超时 | Timeout |
| API error | Error |
| 服务崩溃 | Crash |
| Watchdog reset | Watchdog |
| Context 超限 | Context Limit |
| 输出未达到目标 | Early EOS |
| 指标异常无法确认 | Invalid |
| 不适用 | N/A |

---

# 19. 什么时候必须重测？

建议出现以下情况重测：

1. 某档结果和相邻档明显反常
2. 5 次裸性能标准差异常大
3. API 测试出现错误请求
4. GPU 温度/频率发生明显变化
5. 测试期间有其他 GPU 任务介入
6. Prefix Cache 状态不确定
7. 服务发生 OOM / 重启
8. 输出 token 数与目标差距过大
9. TTFT 突然比其他轮高数倍
10. Speculative Acceptance 状态发生明显切换

不要擅自删除“慢的那次”。

如果要排除 outlier：

> 必须保留原始数据，并说明排除规则。

---

# 20. A/B 测试规则

测试优化是否有效时：

**一次只改一个主要变量。**

例如：

```text
A：ROCm 7.0
B：ROCm 7.1
```

其他保持一致。

不要同时：

- 换 ROCm
- 换量化
- 换 batch
- 开 Flash Attention
- 改 KV dtype

然后说：

> “Kernel 优化提升 30%”

那无法判断提升来自哪里。

---

# 21. llama.cpp / llama-bench

## 当前 GitHub

https://github.com/ggml-org/llama.cpp

https://github.com/ggml-org/llama.cpp/tree/master/tools/llama-bench

https://github.com/ggml-org/llama.cpp/blob/master/tools/llama-bench/README.md

**核对日期：2026-10-13**

## 当前官方能力节选

当前 llama-bench README 明确支持：

- Prompt processing (`-p`)
- Text generation (`-n`)
- Prompt processing + generation (`-pg`)
- `-r` repetitions，默认 5
- 平均 tok/s + standard deviation
- `-d` 指定 context depth
- CSV / JSON / JSONL / Markdown / SQL
- 默认 warmup，可用 `--no-warmup` 关闭
- 测量不包含 tokenization 和 sampling

## 推荐用途

- Quant A/B
- GPU A/B
- Backend A/B
- Kernel A/B
- Context Depth 对 Decode 影响
- Multi-GPU 参数 A/B

---

## 一键 Agent Prompt：llama-bench

```text
请使用当前机器已有的 llama.cpp / llama-bench，对指定 GGUF 做裸性能 Benchmark。

第一阶段：只读审计
1. 输出 llama-bench 版本/build/commit（能确认则写）。
2. 执行 `llama-bench --help`，确认当前版本参数。
3. 记录：
   - Model
   - Quant
   - GPU / CPU / RAM
   - Backend
   - GPU offload
   - tensor split / TP 类设置
   - KV dtype
   - Flash Attention
   - batch / ubatch
   - Context 上限
4. 不修改生产服务，不升级 llama.cpp，不重新量化模型。

第二阶段：PP / Prompt Processing
论坛建议 Context：
4096,8192,16384,32768,65536,131072

使用当前版本官方 `-p` 做 PP 测试。
重复次数使用官方默认 5 次，或显式 `-r 5`。
不要关闭默认 warmup。

参考：
llama-bench -m <MODEL> -p 4096,8192,16384,32768,65536,131072 -n 0 -r 5

若当前版本命令语法与上面不同，以 `--help` 为准。

第三阶段：TG / Decode at Context Depth
固定 generation = 512 tokens。
使用 `-d` 测：
4096,8192,16384,32768,65536,131072

参考：
llama-bench -m <MODEL> -p 0 -n 512 -d 4096,8192,16384,32768,65536,131072 -r 5

重要：
- `-d` 的预填只是建立 Context Depth，不要把该预填过程误计入 TG。
- llama-bench 官方计时不包含 tokenization 和 sampling。
- 如果某档 OOM/Context Limit，原样记录失败，不改变量化或配置。
- 保存 JSON 输出（如果当前版本支持）以及终端 Markdown。

最终报告：

环境表：
Model | Quant | llama.cpp版本 | Backend | GPU | CPU | RAM | FA | KV dtype | batch | ubatch | GPU offload

结果表：
Context | PP t/s Mean | PP Std | TG t/s Mean | TG Std | Peak VRAM | 状态

三句总结：
1. PP scaling
2. TG scaling
3. Context 从哪一档开始明显影响 Decode
```

---

# 22. GuideLLM

## 当前 GitHub

https://github.com/vllm-project/guidellm

https://github.com/vllm-project/guidellm/blob/main/README.md

**核对日期：2026-10-13**

当前 README 将 GuideLLM 定位为：

- OpenAI-compatible / vLLM-native server benchmark
- 真实和 synthetic workload
- TTFT / ITL / end-to-end distributions
- synchronous / concurrent / rate-based profiles
- sweep
- warmup / cooldown
- JSON / CSV 输出

官方 quick start：

```bash
guidellm run \
  --backend kind=openai_http,target=http://localhost:8000 \
  --profile kind=sweep \
  --constraint kind=max_duration,seconds=30 \
  --data kind=synthetic_text,prompt_tokens=256,output_tokens=128
```

---

## 一键 Agent Prompt：GuideLLM

```text
请使用 GuideLLM 对当前 OpenAI-compatible 本地模型 API 做单用户 C1 Benchmark。

安全规则：
1. 先只读确认 endpoint、model、engine、API 健康状态。
2. 查询当前 GuideLLM version 和 `guidellm --help`。
3. 不重启、不升级、不修改服务参数。
4. 若 GuideLLM 未安装：
   - 优先使用独立临时 venv / 容器，不污染生产环境；
   - 如果安装属于系统修改，先停止并报告，不擅自执行。
5. 4K~128K 是论坛建议矩阵，不是 GuideLLM 官方固定标准。

固定条件：
- Context：4096 / 8192 / 16384 / 32768 / 65536 / 131072
- Output：512 tokens
- Concurrency：1
- Requests：10 / Context
- Dataset：synthetic_text
- Cache：尽量 Fresh
- Warm-up：使用 GuideLLM 当前 profile 支持的 warmup，或先做独立 warm-up 不计成绩
- 保留 benchmarks.json / benchmarks.csv

每档参考结构：
guidellm run \
  --backend kind=openai_http,target=<ENDPOINT> \
  --profile kind=synchronous \
  --constraint kind=max_requests,count=10 \
  --data kind=synthetic_text,prompt_tokens=<N>,output_tokens=512

Cache：
- 避免重复固定 Prompt 导致 Prefix Cache hit。
- 使用足够 synthetic samples / 不同 seed（若当前版本支持）。
- 不为了清 cache 擅自重启生产服务。
- 无法确认写 Cache=Unknown。

统计：
优先读取 GuideLLM 原生输出：
- TTFT distribution
- ITL distribution
- E2E
- token throughput
- request throughput
- errors

不要把 TTFT 当纯 Prefill。
不要把 stream chunk rate 当 token rate。
如果自己推导 Decode TPS，标“Derived”并写公式。

最终表：
Context | Actual Input Tokens | Actual Output Tokens | TTFT P50 | TTFT P99 | ITL P50 | ITL P99 | E2E P50 | Output TPS | Errors | Cache
```

---

# 23. inference-perf

## 当前 GitHub

https://github.com/kubernetes-sigs/inference-perf

https://github.com/kubernetes-sigs/inference-perf/blob/main/README.md

https://github.com/kubernetes-sigs/inference-perf/blob/main/docs/config.md

**核对日期：2026-10-13**

该项目明确源于：

> inference benchmarking and metrics standardization effort

当前明确支持：

- TTFT
- TPOT
- ITL
- Normalized TPOT
- Input / Output / Total TPS
- Goodput
- constant / poisson / concurrent
- multi-stage
- saturation detection
- vLLM / SGLang / TGI
- extensible OpenAI-compatible endpoints

`streaming: true` 是获取 TTFT / ITL / TPOT 的关键条件之一。

---

## 一键 Agent Prompt：inference-perf

```text
请使用 Kubernetes SIG inference-perf 对当前本地模型服务做并发/饱和测试。

这是压力测试，执行前必须：
1. 确认当前服务没有其他重要用户/任务。
2. 记录服务配置和系统 idle 状态。
3. 查询 `inference-perf --help` 和版本。
4. 确认实际 server.type / endpoint / tokenizer 配置。
5. 不改变生产模型、量化和服务参数。

论坛建议测试：
Context：固定 8192（也可另跑 16384）
Output：512
Streaming：true
Concurrency：
C1 / C2 / C4 / C8

每档请求数：
40
如果机器太慢可统一降低，但所有档位保持一致。

生成 config.yml，按当前 config.md 语法。

建议结构：

api:
  type: completion
  streaming: true

server:
  type: <ACTUAL_SERVER_TYPE>
  model_name: <MODEL>
  base_url: <ENDPOINT>

data:
  type: random
  input_distribution:
    min: 8192
    max: 8192
    mean: 8192
    std_dev: 0
    total_count: 200
  output_distribution:
    min: 512
    max: 512
    mean: 512
    std_dev: 0
    total_count: 200

load:
  type: concurrent
  base_seed: 12345
  stages:
    - concurrency_level: 1
      num_requests: 40
    - concurrency_level: 2
      num_requests: 40
    - concurrency_level: 4
      num_requests: 40
    - concurrency_level: 8
      num_requests: 40

report:
  request_lifecycle:
    summary: true
    per_stage: true
    per_request: true
    per_request_fields:
      request: false
      response: false
      info: false
      response_chunks: false
      computed_metrics: true
    percentiles: [50, 90, 95, 99]

注意：
- `api.type` 必须与当前 endpoint 匹配；chat 就用 chat。
- server.type 必须以当前版本实际支持为准。
- 如果 tokenizer 配置是必须项，按当前文档添加。
- 如果固定 output 512 需要 ignore_eos，而当前服务支持，则记录并使用；否则记录实际 output tokens。
- C8 出现 OOM / 大量错误 / 服务失稳时停止继续提高并发。

最终输出：
C | Requests | TTFT P50/P99 | TPOT P50/P99 | ITL P50/P99 | Output TPS | Request TPS | Goodput | Errors

另写：
- 最大稳定 C
- 饱和点
- TTFT 开始恶化点
- throughput 边际收益开始明显下降点
```

---

# 24. MLPerf Client

## 当前 GitHub

https://github.com/mlcommons/mlperf_client

https://github.com/mlcommons/mlperf_client/blob/main/README.md

**核对日期：2026-10-13**

MLPerf Client 当前定位：

- personal computer inference benchmark
- JSON configuration
- models / execution providers
- Windows / Mac binary
- vendor execution paths
- WarmUp / Iterations
- CSV export

它不是任意 OpenAI-compatible API 的通用 benchmark。

---

## 一键 Agent Prompt：MLPerf Client

```text
请检查当前机器是否适合运行当前 MLPerf Client 官方/供应商配置。

原则：
1. MLPerf Client 不是任意本地 OpenAI API benchmark。
2. 只使用当前仓库支持的 Scenario / Model / Execution Provider。
3. 不自创配置后声称是“官方 MLPerf 成绩”。

步骤：
1. 记录 OS / CPU / GPU/NPU / RAM。
2. 查询 MLPerf Client version / --help。
3. 检查当前可用 config。
4. 选择与本机匹配的官方或 vendor config。
5. 保留配置中原始 WarmUp / Iterations。
6. 导出 CSV。

Windows：
.\mlperf-windows.exe -c <CONFIG.json> -x <RESULT.csv>

macOS：
./mlperf-mac -c <CONFIG.json> -x <RESULT.csv>

如果修改：
- WarmUp
- Iterations
- Model
- Execution Provider
- Scenario

必须标：
“Custom / Non-standard run”。

最终报告：
Device | OS | CPU | GPU/NPU | RAM | MLPerf version | Config | Scenario | Model | Execution Provider | WarmUp | Iterations | Official Metrics | CSV
```

---

# 25. 统一论坛摘要表

无论使用哪套工具，建议帖子最前面都给：

| Model | Quant | Engine | GPU | Context | Output | C | Cache | Prefill | TTFT | Decode/TPS | VRAM |
|---|---|---|---|---:|---:|---:|---|---:|---:|---:|---:|
|  |  |  |  | 4K | 512 | C1 | Cold |  |  |  |  |
|  |  |  |  | 8K | 512 | C1 | Cold |  |  |  |  |
|  |  |  |  | 16K | 512 | C1 | Cold |  |  |  |  |
|  |  |  |  | 32K | 512 | C1 | Cold |  |  |  |  |
|  |  |  |  | 64K | 512 | C1 | Cold |  |  |  |  |
|  |  |  |  | 128K | 512 | C1 | Cold |  |  |  |  |

没有的指标：

```text
留空 / N/A
```

不要为了填表自己造指标。

---

# 26. 原始数据必须保留

建议保留：

- benchmark JSON
- CSV
- config.yml / command line
- server startup command
- engine log
- GPU monitoring log（有条件）
- timestamp
- benchmark tool version

这样几个月以后你才能回答：

> “为什么我去年测的是 120 t/s，现在只有 95？”

---

# 27. 文件命名建议

建议：

```text
YYYYMMDD_GPU_MODEL_QUANT_ENGINE_TESTTYPE_CONTEXT
```

例如：

```text
20261013_7900XTXx2_Qwen27B_W8A8_SGLang_GuideLLM_C1
```

配置：

```text
config.yml
```

结果：

```text
results.csv
results.json
server.log
gpu.log
README.md
```

---

# 28. 最终检查清单

测试发布前逐项确认：

```text
[ ] GPU / CPU / RAM / OS 已记录
[ ] Engine + Version/Commit 已记录
[ ] Model + Quant 已记录
[ ] Context 已记录
[ ] Output Length 已记录
[ ] Concurrency 已记录
[ ] Cache 状态已记录
[ ] Warm-up 已记录
[ ] 重复次数 / Requests 已记录
[ ] Actual input/output tokens 已记录
[ ] TTFT 未被误称为纯 Prefill
[ ] Chunk rate 未被误称为 Token rate
[ ] Speculative 测试同时看 TPOT / ITL / Acceptance
[ ] OOM / Timeout / Early EOS 没被偷偷删掉
[ ] 原始 JSON / CSV 已保存
[ ] 测试命令 / config 已保存
```

---

# 29. 官方出处

## llama.cpp / llama-bench
https://github.com/ggml-org/llama.cpp  
https://github.com/ggml-org/llama.cpp/tree/master/tools/llama-bench  
https://github.com/ggml-org/llama.cpp/blob/master/tools/llama-bench/README.md

## GuideLLM
https://github.com/vllm-project/guidellm  
https://github.com/vllm-project/guidellm/blob/main/README.md

## Kubernetes SIG inference-perf
https://github.com/kubernetes-sigs/inference-perf  
https://github.com/kubernetes-sigs/inference-perf/blob/main/README.md  
https://github.com/kubernetes-sigs/inference-perf/blob/main/docs/config.md

## MLPerf Client
https://github.com/mlcommons/mlperf_client  
https://github.com/mlcommons/mlperf_client/blob/main/README.md

## vLLM benchmark metric definitions（用于 TTFT / TPOT / ITL / Prefix Cache 注意事项）
https://github.com/vllm-project/vllm/blob/main/docs/benchmarking/cli.md

---

# 30. 版本声明

**核对时间：2026-10-13。**

GitHub 项目会快速变化。

每次真正执行时：

```text
本机当前版本 --help
+
当前 release/commit README
```

优先级高于本附件里的旧 CLI 示例。

本附件真正应该长期保留的是：

- 测试变量控制
- Cache 规则
- Context / Output / Concurrency 记录
- TTFT / TPOT / ITL 定义
- 原始数据保留
- A/B 单变量原则
- 失败结果不隐藏
- 测试可复现性

而不是某一条永远不变的命令。