在已有 max serve 端点时，用 max…

当需要基准测试、压测或量化运行中的 MAX 模型服务的吞吐与延迟，并做并发/请求速率扫描或部署容量评估时使用。

适用场景

解决思路

1. 每次运行都会同时报告吞吐和延迟，没有模式可选；先决定要学什么，再选择能测量它的 workload；单流延迟和峰值吞吐来自不同 workload，所以所选 workload 就是测量本身，选对后自然得到干净数字。
2. 先确认服务可用：执行 `curl -s http://localhost:8000/v1/health`，返回 200 表示 ready；执行 `curl -s http://localhost:8000/v1/models` 查看已服务模型名。
3. 确保 `max benchmark` 的 `--model` 与服务器的 `--served-model-name` 完全一致；从 `/v1/models` 取值，不要猜测，否则每个请求都会失败。
4. 如果 `/v1/models` 返回的 served name 是不含 `/` 的别名而不是 Hugging Face ID，`--tokenizer` 会默认使用它并解析失败，运行会报 “not a valid model identifier.”；此时把模型真实 Hugging Face ID 传给 `--tokenizer`。
5. 如果没有任何服务在跑，先用 `max serve` 启动服务；自定义架构使用 `serve-model` 技能。注意服务器的 `--max-batch-size` 会限制真实并发：如果扫描到 `--max-concurrency 32` 而服务器以 `--max-batch-size 1` 启动，请求会排队而不是批处理，应把服务器 batch size 提高到与扫描匹配，否则高并发点无意义。
6. 等待出现 `Server ready` 后再跑基准测试；在编译或 warmup 期间跑会产生垃圾 first-token 时间。
7. 按要回答的问题选择 workload：要测最佳单请求延迟（TTFT、TPOT）时，用 `--max-concurrency 1`、固定 `random` shape、较小 `--num-prompts`。
8. 要测峰值吞吐和延迟开始劣化的位置时，用 `--max-concurrency 1,2,4,8,16,32` 扫描并增加 `--num-prompts`。
9. 要测真实混合负载下的性能时，用 `--dataset-name sharegpt` 和中等并发。
10. 要测目标负载下的行为时，用 `--request-rate 1,2,4,8` 扫描（requests/sec）。
11. 如果要同时得到单请求延迟和吞吐，直接用并发扫描：`--max-concurrency 1` 点给出最佳延迟，扫描中的峰值给出吞吐；如果只想要延迟数值，才单独跑 concurrency-1。
12. 设置 `--dataset-name`：`random` 用于合成、可通过 `--random-input-len` 和 `--random-output-len` 塑形、适合干净可复现的微测量；`sharegpt` 用于真实聊天；`arxiv-summarization` 用于长上下文。
13. 设置 `--max-concurrency` 和 `--request-rate`：可传单个值或逗号分隔的 sweep（如 `1,2,4,8`）；用 sweep 找吞吐拐点。
14. 设置 `--endpoint`：base LM 用 `/v1/completions`，不需要 chat template；instruct/chat 模型用 `/v1/chat/completions`，且必须有 chat template，否则请求返回 400。
15. 设置 `--max-output-len` 控制 decode 长度，它主导运行耗时。
16. 单轮运行必须设置 `--num-prompts`。
17. 跑最佳单请求延迟示例：`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`
18. 跑峰值吞吐和延迟拐点示例：`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`
19. 需要跟踪或比较运行就设置 `--result-filename`：它把指标写入 JSON 并自动创建所需目录；不设置则 MAX 什么都不保存；可用 `--metadata key=value` 给 JSON 打标，例如 `--metadata tp=1 gpu=b200`；扫描还会在 `--log-dir` 下为每个 step 生成 `results-<N>-median.json`。
20. 需要 GPU utilization 和峰值显存就加 `--collect-gpu-stats`；该选项只在 benchmark 与 server 运行在同一台 NVIDIA 机器上时有效。
21. 需要版本控制配置时，把选项放在 YAML 文件的 `benchmark_config:` 键下，并用 `--config-file file.yaml` 传入；键使用 `snake_case`，CLI flags 覆盖文件。
22. 读取运行输出：每次运行都打印吞吐和延迟，扫描每个点打印一行；重点指标包括 output token throughput（tok/s，主吞吐）、TTFT（prefill 响应性，关注 p50 和 p99）、TPOT 和 ITL（decode 速度）、以及配合 `--collect-gpu-stats` 的 GPU utilization 和峰值显存。
23. 要把吞吐/延迟数字转成结论并理解扫描揭示的 latency-vs-throughput 权衡，读取 `references/metrics.md`。
24. 遇到运行不连接、请求失败或数字异常时，按症状查 `references/troubleshooting.md`；其中覆盖连接失败、模型名不匹配、tokenizer 别名错误、chat-template 400、因 batch-size 上限导致的吞吐平台、以及被 warmup 扭曲的 first-token 时间。
25. 在检查其他问题前，先确认 `curl /v1/health` 返回 200。
26. 选择超出上述范围的 flag 或 dataset 时，读取 `references/flags.md`；只为当前在做的事读对应 reference，不要一开始全读。
27. MAX 可用 pip 或 pixi 安装；在 pixi 项目中，命令前加 `pixi run`。

适用边界 · 注意事项

• 没有正在运行的 `max serve` 端点时不要用它；它是客户端，应先用 `serve-model` 技能启动服务。
• 要定位 kernel 级推理耗时来源时不要用它，改用 `profile-model`。
• 要检查输出是否正确时不要当基准测试做，应按 parity 任务处理（先 `import-model`，再 `debug-model`）。