vllm-bench-serve

vLLM Bench Serve

vllm bench serve CLI を使用して、vLLM または OpenAI 互換のサービングエンドポイントをベンチマークします。設定可能なリクエスト負荷に対するスループット、レイテンシ（TTFT、TPOT）、グッドプットを測定します。

参考：vLLM Bench Serve Documentation

前提条件

• vLLM がインストールされていること（または OpenAI 互換サーバーが稼働していること）
• モデルをすでにサービングしている vLLM サーバーまたは API エンドポイント
• ベンチマーククライアント用の vLLM が含まれる Python 環境

クイックスタート

ローカルの vLLM サーバーに対する基本的なベンチマーク（デフォルトのランダムデータセット、プロンプト 1000 件）：

vllm bench serve \
  --backend openai-chat \
  --host 127.0.0.1 \
  --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions

結果を JSON に保存する：

vllm bench serve \
  --backend openai-chat \
  --host 127.0.0.1 \
  --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions \
  --save-result \
  --result-dir ./bench-results \
  --metadata "version=0.6.0" "tp=1"

注： --backend openai-chat を使用する場合は、--endpoint /v1/chat/completions を指定する必要があります（デフォルトは /v1/completions です）。

主な引数

引数	デフォルト	説明
--backend	openai	バックエンドの種類：openai、openai-chat、openai-embeddings、vllm、vllm-pooling、vllm-rerank など
--host	127.0.0.1	サーバーのホスト
--port	8000	サーバーのポート
--base-url	-	代替手段：host:port の代わりにベース URL 全体を指定
--endpoint	/v1/completions	API エンドポイント。openai-chat では /v1/chat/completions を使用
--model	(/v1/models から取得)	モデル名
--num-prompts	1000	処理するプロンプト数
--request-rate	inf	1 秒あたりのリクエスト数。inf はすべてを一度にバースト送信
--max-concurrency	-	同時リクエストの最大数（並列処理数を制限）
--num-warmups	0	測定前のウォームアップリクエスト数

データセット

--dataset-name	用途
random	合成ランダムプロンプト（デフォルト）
sharegpt	ShareGPT 会話形式。--dataset-path が必要
sonnet	ソネット形式のプロンプト
hf	HuggingFace データセット。--dataset-path（データセット ID）が必要
custom / custom_mm	カスタムデータセット。--dataset-path が必要
prefix_repetition	プレフィックス反復ベンチマーク
random-mm	ランダムなマルチモーダルデータ（画像／動画）
spec_bench	Spec bench データセット

データセット固有のオプション（例）：

# Random: control input/output length
--dataset-name random --random-input-len 1024 --random-output-len 128

# Sonnet defaults: input 550, output 150, prefix 200
--dataset-name sonnet --sonnet-input-len 550 --sonnet-output-len 150

# HuggingFace dataset
--dataset-name hf --dataset-path "lmarena-ai/VisionArena-Chat" --hf-split test

# General overrides (map to dataset-specific args)
--input-len 512 --output-len 256

負荷制御

# Fixed request rate (Poisson process)
--request-rate 10

# More bursty arrivals (gamma distribution, burstiness < 1)
--request-rate 10 --burstiness 0.5

# Ramp-up from low to high RPS
--ramp-up-strategy linear --ramp-up-start-rps 1 --ramp-up-end-rps 50

# Limit concurrency (useful for rate-limited APIs)
--max-concurrency 32

結果とメトリクス

引数	説明
--save-result	ベンチマーク結果を JSON に保存
--save-detailed	リクエストごとの TTFT、TPOT、エラーを JSON に含める
--append-result	既存の結果ファイルに追記
--result-dir	結果ファイルのディレクトリ
--result-filename	カスタムファイル名（デフォルト：{label}-{request_rate}qps-{model}-{timestamp}.json）
--percentile-metrics	パーセンタイルのメトリクス：ttft、tpot、itl、e2el（デフォルト：ttft,tpot,itl）
--metric-percentiles	パーセンタイル値。例：25,50,99（デフォルト：99）
--goodput	グッドプットの SLO：ttft:500 tpot:50（ms）

サンプリングパラメーター（OpenAI 互換バックエンド）

--temperature 0.7 --top-p 0.95 --top-k 50
--frequency-penalty 0 --presence-penalty 0 --repetition-penalty 1.0

よくあるワークフロー

1. ランダムデータセットを使ったスループットテスト（バースト）：

vllm bench serve --backend openai-chat --host 127.0.0.1 --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions \
  --dataset-name random \
  --num-prompts 500 --random-input-len 512 --random-output-len 128

2. 固定 QPS でのレイテンシテスト：

vllm bench serve --backend openai-chat --host 127.0.0.1 --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions \
  --request-rate 5 --num-prompts 200 \
  --save-result --percentile-metrics ttft,tpot --metric-percentiles 50,99

3. リモート API に対するベンチマーク（base-url）：

vllm bench serve --backend openai-chat \
  --base-url "https://api.example.com/v1" \
  --model my-model \
  --header "Authorization=Bearer $API_KEY"

4. Docker 内で実行（vLLM クライアントがホスト上にない場合）：

docker exec <container-name> vllm bench serve \
  --backend openai-chat --host 127.0.0.1 --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions \
  --dataset-name random --num-prompts 100

トラブルシューティング

• 接続が拒否される：サーバーが稼働していること、および --host／--port または --base-url が正しいことを確認してください。
• モデルが見つからない：--model を明示的に指定するか、/v1/models がモデルを返すことを確認してください。
• URL の末尾が chat/completions である必要がある：--backend openai-chat を使用する場合は、--endpoint /v1/chat/completions を指定してください。
• レート制限／429：--request-rate または --max-concurrency を下げてください。
• 準備完了チェック：ベンチマーク前にエンドポイントを待機するには、--ready-check-timeout-sec 60 を使用してください。
• SSL：自己署名証明書には --insecure を使用してください。

メモ

• 埋め込み／リランキングのベンチマークでは、--backend openai-embeddings、vllm-pooling、または vllm-rerank を使用してください。
• --profile を使用するには、vLLM のプロファイリング用にサーバーで --profiler-config が必要です。
• Goodput の SLO は SLA 形式の分析に役立ちます。詳細については、DistServe の論文を参照してください。