vllm-prefix-cache-bench

vLLM プレフィックスキャッシュのベンチマーク

vLLM の自動プレフィックスキャッシュ（APC）機能の効率をベンチマークします。オフラインスクリプト benchmarks/benchmark_prefix_caching.py は、vLLM エンジンに対して直接実行します（サーバーは不要です）。オンライン／サービングのテストには、prefix_repetition データセットと vllm bench serve を使用します。

使用する場面

• 繰り返し使われるプロンプトや一部が共有されるプロンプトについて、プレフィックスキャッシュがパフォーマンスに与える影響を測定したい場合。
• --enable-prefix-caching の有効時と無効時で、スループット／レイテンシを比較したい場合。
• 固定の合成プロンプト、実データセット（例：ShareGPT）、または合成したプレフィックス／サフィックスの反復パターンを使って、プレフィックスキャッシュをテストしたい場合。

オプション 1（デフォルト）。プレフィックスキャッシュを使用した固定プロンプト

同一の固定プロンプトを複数回繰り返す合成ベンチマークを実行し、キャッシュヒットの効率を直接測定します。データセットのダウンロードは不要です。

python3 benchmarks/benchmark_prefix_caching.py \
  --model Qwen/Qwen3-8B \
  --enable-prefix-caching \
  --num-prompts 1 \
  --repeat-count 100 \
  --input-length-range 128:256

キャッシュを無効にしたベースラインと比較するには、次のようにします。

python3 benchmarks/benchmark_prefix_caching.py \
  --model Qwen/Qwen3-8B \
  --no-enable-prefix-caching \
  --num-prompts 1 \
  --repeat-count 100 \
  --input-length-range 128:256

オプション 2。プレフィックスキャッシュを使用した ShareGPT データセット

ShareGPT の実際の会話データを使い、自然に発生するプロンプト共有によるプレフィックスキャッシュの効果を評価します。

まず、データセットをダウンロードします。

wget https://huggingface.co/datasets/anon8231489123/ShareGPT_Vicuna_unfiltered/resolve/main/ShareGPT_V3_unfiltered_cleaned_split.json

次に、ベンチマークを実行します。

python3 benchmarks/benchmark_prefix_caching.py \
  --model Qwen/Qwen3-8B \
  --dataset-path ShareGPT_V3_unfiltered_cleaned_split.json \
  --enable-prefix-caching \
  --num-prompts 20 \
  --repeat-count 5 \
  --input-length-range 128:256

オプション 3。プレフィックス反復データセット（オンライン）

vllm bench serve と合成データセット prefix_repetition を使用し、サービング API 経由でキャッシュをテストします。このテストには、起動中の vLLM サーバーが必要です。

まず、サーバーを起動します。

vllm serve Qwen/Qwen3-8B

次に、ベンチマークを実行します。

vllm bench serve \
  --backend openai \
  --model Qwen/Qwen3-8B \
  --dataset-name prefix_repetition \
  --num-prompts 100 \
  --prefix-repetition-prefix-len 512 \
  --prefix-repetition-suffix-len 128 \
  --prefix-repetition-num-prefixes 5 \
  --prefix-repetition-output-len 128

prefix_repetition の主なパラメーター：

パラメーター	説明
--prefix-repetition-prefix-len	共有プレフィックス部分のトークン数
--prefix-repetition-suffix-len	固有サフィックス部分のトークン数
--prefix-repetition-num-prefixes	切り替えて使用する異なるプレフィックスの数
--prefix-repetition-output-len	リクエストごとに生成する出力トークン数

注意事項

• すべてのコマンドは vLLM リポジトリのルート（cd vllm）から実行してください。
• 別のモデルを指定する場合、またはデフォルトモデルが利用できない場合を除き、デフォルトモデル（Qwen/Qwen3-8B）を使用してください。変更するのは --model のみです。
• オプション 1 および 2 の --repeat-count は、サンプリングした各プロンプトを再生する回数を指定します。値を大きくすると、キャッシュヒット率が上がります。
• --input-length-range には、128:256 のような min:max 形式のトークン範囲を指定します。
• マルチ GPU 構成の場合は、--tensor-parallel-size <N> を追加してください。
• プレフィックスキャッシュ内部で異なるハッシュアルゴリズムをテストするには、--prefix-caching-hash-algo xxhash を使用してください（pip install xxhash が必要です）。

benchmark_prefix_caching.py の引数

引数	必須	説明
--model	はい	モデル名またはパス（HuggingFace ID またはローカルパス）
--num-prompts	はい	処理するプロンプトの数
--input-length-range	はい	入力のトークン長の範囲。例：128:256
--repeat-count	いいえ	各プロンプトを繰り返す回数（デフォルト：1）
--dataset-path	いいえ	データセットファイルへのパス（例：ShareGPT JSON）。合成の固定プロンプトモードでは省略します
--prefix-len	いいえ	各プロンプトの先頭に付加する固定プレフィックスのトークン長
--output-len	いいえ	リクエストごとに生成する出力トークン数
--sort	いいえ	ベンチマーク前にプロンプトを長さ順に並べ替える
--enable-prefix-caching / --no-enable-prefix-caching	いいえ	APC の有効／無効を切り替える（キャッシュをテストする場合は有効を推奨）
--prefix-caching-hash-algo	いいえ	ハッシュアルゴリズム：sha256、sha256_cbor、xxhash、xxhash_cbor
--tensor-parallel-size	いいえ	テンソル並列に使用する GPU 数
--disable-detokenize	いいえ	オーバーヘッドを減らすため、デトークナイズをスキップする

トラブルシューティング

• python3 benchmarks/*.py でファイルが見つからないと表示される場合は、ローカルの vLLM リポジトリを見つけて、そのリポジトリのルートからコマンドを実行してください。
• リポジトリをまだお持ちでない場合は、クローンしてから続行してください。

git clone https://github.com/vllm-project/vllm
cd vllm

• アクセス制限により HuggingFace モデルのダウンロードに失敗する場合は、トークンを設定してください：export HF_TOKEN=<your_token> または --hf-token <your_token> を渡してください。
• xxhash または cbor2 がインストールされておらず、これらのハッシュアルゴリズムを使用する場合は、先にインストールしてください：pip install xxhash cbor2。