benchmark-model

MAX でモデルをベンチマークする

max benchmark は実行中のモデルサーバーを測定します。これは負荷生成ツールです。稼働中の max serve エンドポイントに推論リクエストを送信して所要時間を測り、スループット（tokens/sec）とレイテンシ（TTFT、TPOT、トークン間レイテンシ）を報告します。ベンチマークは、テスト対象のサーバーと、調べたい内容に合ったワークロードの 2 つで構成されます。

各実行ではスループットとレイテンシの両方が報告されるため、測定モードを選ぶ必要はありません。まず何を知りたいかを決め、それを測定できるワークロードを選んでください。単一ストリームのレイテンシとピークスループットは異なるワークロードで測定されるため、選んだワークロードそのものが測定内容になります。適切に選べば、信頼できる数値が得られます。

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 はデフォルトでその名前に設定されますが、解決できず、"not a valid model identifier." というエラーで実行が終了します。--tokenizer にはモデルの本来の Hugging Face ID を指定してください。

サーバーが起動していない場合は、max serve で起動してください（カスタムアーキテクチャの場合は、serve-model スキルを使用してください）。サーバーの設定でもう 1 つ重要なのが --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のスイープ（リクエスト数／秒）

スイープを行うと、最初の2行の両方を一度に確認できます。同時実行数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：チャットテンプレートが不要なベースLMには/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

実行の保存と計測について、次の3点に注意してください。

• --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を使い、CLIのフラグがファイル内の設定より優先されます。

4. メトリクスを読む

実行結果にはスループットとレイテンシが出力され、スイープでは各測定ポイントの行が表示されます。主な指標は次のとおりです。

• 出力トークンスループット（tok/s）：主なスループット指標です。
• TTFT（最初のトークンまでの時間）：プリフィルの応答性を示します。p50とp99を確認してください。
• TPOTとITL（出力トークンあたりの時間、トークン間レイテンシ）：デコード速度を示します。
• GPU使用率とピークメモリ：--collect-gpu-statsを指定すると報告されます。

これらの数値から結論を導く方法や、スイープで明らかになるレイテンシとスループットのトレードオフについては、references/metrics.mdをご覧ください。

トラブルシューティング

症状に応じてreferences/troubleshooting.mdをご確認ください。接続失敗、モデル名の不一致、トークナイザーエイリアスのエラー、チャットテンプレートによる400エラー、バッチサイズ上限によるスループットの頭打ち、ウォームアップによる初回トークン時間の偏りについて説明しています。ほかのことを確認する前に、curl /v1/healthが200を返すことを確認してください。