benchmark-model

在 MAX 上对模型进行基准测试

max benchmark 用于测量正在运行的模型服务。它是一个负载生成器：向运行中的 max serve 端点发送推理请求、计时，并报告吞吐量（tokens/sec）和延迟（TTFT、TPOT、令牌间延迟）。一次基准测试包含两部分：待测服务，以及与要解答的问题相匹配的工作负载。

每次运行都会同时报告吞吐量和延迟，因此无需选择模式。先确定想要了解什么，再选择能测量它的工作负载。单流延迟和峰值吞吐量来自不同的工作负载，因此你选择的就是测量方式。选对工作负载，就能得到准确的数值。

当你想了解 MAX 上模型的性能数据时，请使用此技能：tokens/sec、TTFT / TPOT、并发或请求速率扫描、延迟与吞吐量的权衡，或部署容量规划。

如果尚未运行服务，请勿使用此技能。max benchmark 是一个客户端，因此请先使用 serve-model 技能启动服务。若要了解推理时间在内核级别的分布，请使用 profile-model。若要检查输出是否正确，请将其视为一致性任务（先用 import-model，再用 debug-model），而不是基准测试。

只要安装了 MAX（通过 pip 或 pixi），就可以使用此技能。在 pixi 项目中添加 pixi run。

参考资料

下表列出了参考文件及其适用场景：

文件	阅读时机
references/flags.md	选择下文未提及的任何标志或数据集时
references/metrics.md	根据吞吐量和延迟数据得出结论时
references/troubleshooting.md	运行无法连接、请求失败或数据看起来不对时

按需阅读对应的参考资料，无需事先全部阅读。

1. 检查服务并读取其模型名称

curl -s http://localhost:8000/v1/health     # 200 = ready
curl -s http://localhost:8000/v1/models      # note the served model name

开始运行基准测试前，务必完成这两项检查：

• 基准测试的 --model 必须与服务的 --served-model-name 完全一致，否则所有请求都会失败。请从 /v1/models 获取该值，不要猜测。
• 如果该服务名称是别名而不是 Hugging Face ID（其中不含 /），--tokenizer 默认会使用该名称，但无法解析，运行会因“不是有效的模型标识符”而失败。请将模型实际的 Hugging Face ID 传给 --tokenizer。

如果没有服务正在运行，请使用 max serve 启动服务（对于自定义架构，请使用 serve-model 技能）。还有一项重要的服务设置：--max-batch-size 会限制实际并发数。若对使用 --max-batch-size 1 启动的服务进行 --max-concurrency 32 扫描，请求只会排队，而不会批处理。因此，应提高服务的批量大小以匹配扫描设置，否则高并发数据点毫无意义。

请等到出现 Server ready 之后再开始基准测试。在编译或预热期间进行基准测试，会导致首个令牌时间数据失真。

2. 为问题选择工作负载

工作负载就是测量内容。根据你想了解的信息选择：

你想了解的信息	工作负载
单请求的最佳延迟（TTFT、TPOT）	--max-concurrency 1，固定的 random 形状，较小的 --num-prompts
峰值吞吐量及延迟开始恶化的位置	扫描 --max-concurrency 1,2,4,8,16,32，增加提示词数量
真实混合负载下的性能	--dataset-name sharegpt，适中的并发量
目标负载下的表现	扫描 --request-rate 1,2,4,8（请求/秒）

一次扫描即可同时回答前两行的问题：并发数为 1 时的数据点就是最佳延迟值，扫描中的峰值则是吞吐量值。如果你只想获取延迟数据，不想承担测量整条曲线的开销，可以单独运行并发数为 1 的测试。

关键参数如下（完整参数列表请参阅 references/flags.md）：

• --dataset-name：选择 random（合成数据，通过 --random-input-len 和 --random-output-len 设置形状）、sharegpt（真实对话）或 arxiv-summarization（长上下文）。random 最适合进行干净、可复现的微基准测量。
• --max-concurrency 和 --request-rate：接受单个值或以逗号分隔的扫描值（1,2,4,8）。扫描可以帮助你找到吞吐量拐点。
• --endpoint：对于不需要聊天模板的基础大模型，使用 /v1/completions；对于指令微调模型和聊天模型，使用 /v1/chat/completions。这些模型必须有聊天模板，否则请求会返回 400。
• --max-output-len：设置解码长度，它是影响运行时长的主要因素。
• --num-prompts：单轮运行时必需。

3. 运行测试、保存结果并添加 GPU 统计信息

要测量单请求的最佳延迟，请将并发数固定为 1，并保持形状不变：

pixi run max benchmark --backend modular --base-url http://localhost:8000 \
  --model <served-model-name> --endpoint /v1/completions \
  --dataset-name random --random-input-len 128 --random-output-len 128 \
  --max-output-len 128 --num-prompts 32 --max-concurrency 1 \
  --result-filename results/latency.json --collect-gpu-stats

要测量峰值吞吐量和延迟拐点，请扫描并发数并发送更多提示词：

pixi run max benchmark --backend modular --base-url http://localhost:8000 \
  --model <served-model-name> --endpoint /v1/completions \
  --dataset-name random --random-input-len 512 --random-output-len 128 \
  --max-output-len 128 --num-prompts 200 \
  --max-concurrency 1,2,4,8,16,32 \
  --result-filename results/throughput.json --collect-gpu-stats

保存和监控运行结果时，请注意以下三点：

• --result-filename：将指标写入 JSON，并创建所需目录。需要跟踪或比较运行结果时，请设置此参数；如果不设置，MAX 不会保存任何内容。--metadata key=value 会为 JSON 添加标记，例如 --metadata tp=1 gpu=b200。扫描还会在 --log-dir 下为每个步骤生成一个 results-<N>-median.json。
• --collect-gpu-stats：添加 GPU 利用率和峰值显存数据。此功能仅在基准测试运行于与服务相同的机器上时有效（NVIDIA）。
• 对于版本控制的配置，请将选项放在 YAML 文件的 benchmark_config: 键下，并传入 --config-file file.yaml。键名使用 snake_case，命令行参数会覆盖文件中的设置。

4. 查看指标

运行结果会显示吞吐量和延迟，扫描则会为每个数据点输出一行。主要指标如下：

• 输出 Token 吞吐量（tok/s）：主要的吞吐量指标。
• TTFT（首 Token 时间）：预填充响应速度。关注 p50 和 p99。
• TPOT 和 ITL（每个输出 Token 的时间和 Token 间延迟）：解码速度。
• GPU 利用率和峰值显存：通过 --collect-gpu-stats 报告。

有关如何根据这些数据得出结论，以及扫描所揭示的延迟与吞吐量权衡，请参阅 references/metrics.md。

故障排除

请在 references/troubleshooting.md 中查找与症状相符的条目，其中涵盖连接失败、模型名称不匹配、分词器别名错误、聊天模板导致的 400 错误、批次大小上限导致的吞吐量停滞，以及预热导致的首 Token 时间偏差。开始排查其他问题之前，请确认 curl /v1/health 返回 200。