メインコンテンツへスキップ
vLLMはGPUで大規模言語モデルをサービングするための最も機能豊富なオープンソースランタイムだ。スループット、レイテンシ、メモリ使用量に直接影響する幅広い設定オプションを備えている。このガイドでは最も重要な設定項目と、ワークロードに応じた設定方法を解説する。
Last verified: 2026-10-14 — vLLM v0.31.0.
V1がデフォルト。 V1アーキテクチャはvLLM v0.31.0でデフォルトとなった。新しいスケジューラー、デフォルトで有効化されたチャンクドプリフィル、改善されたGPUメモリ管理をもたらす。古いガイドとの動作差異がある場合、V1がその原因である可能性が高い。

KVキャッシュのチューニング

KVキャッシュはすべてのアクティブなシーケンスの各トークンのキーバリューテンソルを格納する。モデルウェイト自体に次ぐGPUメモリの最大の消費源であり、これをチューニングすることで同時リクエスト数を最大限に変更できる。

サイジング計算式

vLLMはKVキャッシュサイズを自動計算するが、計算式を理解しておくと上限設定に役立つ。
係数の2はキーとバリューの両方を考慮したものだ。7Bモデル(32レイヤー、32 KVヘッド、128ヘッドディメンション、float16)の場合:
24 GBのKVキャッシュスペースがある場合、全シーケンス合わせて約48,000トークンを格納できる。

fp8 KVキャッシュの使用

--kv-cache-dtype fp8はデフォルトのfloat16と比較してKVキャッシュメモリを約50%削減する。キャッシュ可能なトークン数が直接倍増し、より多くの同時シーケンスまたはより長いコンテキストに対応できる。
FP8 KVキャッシュはわずかな精度の低下を伴う。ほとんどのチャットやコード生成ワークロードでは影響は無視できるが、特定のタスクで評価を実行する場合は、本番環境で有効化する前に出力品質が閾値を満たすことを確認してほしい。

--max-num-seqsと--max-model-len

これら2つのフラグは同じKVキャッシュプールを競合する。
  • --max-model-lenは単一シーケンスのコンテキスト長に上限を設定する。これを下げるとKVキャッシュが解放され、より多くの同時シーケンスに対応できる。
  • --max-num-seqsは単一のバッチで処理されるシーケンス数に上限を設定する。これを上げるとスループットが向上するが、シーケンスごとのメモリコストが増加する。
ワークロードが短いプロンプト(2Kトークン未満)を送信する場合、--max-model-lenを下げ、--max-num-seqsを上げて並行性を最大化する。ロングコンテキストリクエストを扱う場合はその逆を行う。

プレフィックスキャッシング

多くの実ワークロードでは、共通のプレフィックスを共有するリクエストが送信される。システムプロンプト、RAGの検索ブロック、マルチターン会話の過去のターンなどだ。プレフィックスキャッシングがない場合、vLLMは共有プレフィックスのKVキャッシュをリクエストごとに再計算する。 --enable-prefix-cachingは計算済みのKVブロックをハッシュインデックス付きテーブルに格納する。キャッシュ済みブロックと一致するプレフィックスを持つ新しいリクエストが到着すると、vLLMはKVテンソルを再計算せずにキャッシュを再利用する。
プレフィックスキャッシングが特に効果を発揮するのは以下の場合だ:
  • すべてのリクエストに同じシステムプロンプトが含まれる場合(チャットアプリやコーディングエージェントで一般的)。
  • 固定の検索ブロックを各クエリの先頭に付加するRAGを使用している場合。
  • マルチターン会話で過去のターンをコンテキストとして再利用する場合。
すべてのリクエストが固有のプレフィックスを持つ場合は、効果はない。
V1ではプレフィックスキャッシングはデフォルトで有効だ。V0スケジューラーモードで実行している場合にのみ明示的にフラグが必要になる。

チャンクドプリフィル

プリフィル(入力プロンプトの処理)は計算負荷が高い。長いプロンプト(8K+トークン)はGPUを数百ミリ秒にわたって占有し、他のシーケンスのデコードステップをブロックしてレイテンシスパイクを引き起こす可能性がある。 チャンクドプリフィルはプリフィルをデコードステップと交互に挿入される小さなチャンクに分割する。GPUはプロンプトのチャンクを処理し、次に他のアクティブなシーケンスのデコードステップを実行し、その後次のプリフィルチャンクを処理する。これによりデコードレイテンシが予測可能に保たれる。 V1ではチャンクドプリフィルはデフォルトで有効だ。チャンクサイズは制御できる。
--max-num-batched-tokensは単一のスケジューラステップで処理されるトークンの最大数を設定する。低い値はデコードレイテンシへのプリフィル影響を軽減するが、TTFT(Time-to-First-Token)の総時間が増加する。高い値は時折のデコードジッターと引き換えにプリフィックススループットを向上させる。
古いvLLMバージョンでチャンクドプリフィルを無効にしていてV1にアップグレードする場合、--enable-chunked-prefillフラグを削除してほしい。V1では常にオンであり、フラグは無視される。

LoRAサービング

vLLMは複数のLoRAアダプターをベースモデルにマージすることなく単一のプロセスからサービングできる。単一のベースモデルを実行し、異なるファインチューニング済みバリアントにリクエストをルーティングできる。例えば、コーディングアダプター、要約アダプター、汎用チャットアダプターを、すべて同じベースウェイトをGPUメモリで共有しながら実行できる。

LoRAサービングの有効化

設定の--lora-modulesの各エントリは、リクエスト-facingの名前をローカルパスにマッピングする。クライアントはmodelフィールドでアダプターを選択する。

動的ローディング

vLLMは動的なLoRAローディングをサポートする。サーバーを再起動せずにAPIを通じて実行時にアダプターを追加または削除できる。多数のアダプターを持ち、そのうち少数のみが常にアクティブな場合に有用だ。
設定 --max-lora-rank でランクを制限する。低ランクのアダプターはより少ないメモリを使用する。すべてのアダプターが同じランクを共有する場合は、未使用の容量にメモリを過剰割り当てしないよう、そのランクに設定する。

量子化オプション

量子化はモデルウェイトの精度を16ビット未満に下げ、わずかな精度と引き換えに大きなメモリとスピードの向上を得る。vLLMは複数の量子化フォーマットをサポートする。

量子化モデルの使用

事前量子化モデルの場合、vLLMはモデルのconfig.jsonからフォーマットを自動検出する。
FP8ショートハンドはv0.31で変更された。 FP8量子化識別子は現在fp8_per_tensorだ。スクリプトやCIパイプラインで--quantization fp8を明示的に渡している場合は、新しい識別子に更新してほしい。config.jsonにFP8を持つモデルは影響を受けない。自動検出は引き続き機能する。

オンライン量子化

ロード中にモデルをオンザフライで量子化することも可能だが、本番環境では事前量子化モデルが推奨される。

スループットとレイテンシ

最適化戦略はスループット(全リクエスト合計の毎秒トークン数)とレイテンシ(個別リクエストのTTFTとトークン間レイテンシ)のどちらを優先するかによって異なる。

スループットの最大化

バッチサイズを増やしてGPUステップあたりの作業量を高める。
  • --max-num-seqs 256はバッチ内の同時シーケンスを最大256まで許可する。
  • --max-num-batched-tokens 16384はスケジューラステップあたりのトークン数を増やす。
  • --kv-cache-dtype fp8はより多くのシーケンス用にメモリを解放する。

レイテンシの最小化

バッチサイズを減らし、レイテンシをスループットに置き換える最適化を無効にする。
  • --max-num-seqs 16はバッチを小さく保ち、各リクエストがより早くGPU時間を得られるようにする。
  • --enforce-eagerはCUDAグラフを無効にする。CUDAグラフは固定計算グラフをキャプチャしてリプレイし、スループットを向上させるが、新しいバッチシェイプの初回実行時にレイテンシを追加する。デバッグ時またはTTFTの毎ミリ秒が重要な場合に--enforce-eagerを使用する。
ユーザーがレスポンスを待つインタラクティブアプリケーションでは、TTFTを500ms未満に抑えることを目標とすべきだ。--max-num-seqs 32と--max-num-batched-tokens 4096から始め、負荷下で測定したTTFTに基づいて調整する。

V1アーキテクチャの変更

V1はvLLM v0.31.0のデフォルトスケジューラーだ。以前vLLMを使用していた場合、以下が変更点だ。 新しいスケジューラー。 V1スケジューラーはV0ブロックマネージャーを統一メモリマネージャーに置き換え、KVキャッシュ、プレフィックスキャッシング、チャンクドプリフィルを単一のパスで処理する。これによりスケジューリングオーバーヘッドが削減され、V0がGPUメモリを断片化する可能性があったいくつかのエッジケースが解消される。 チャンクドプリフィルがデフォルト。 プリフィルとデコードは自動的にインターリーブされる。--enable-chunked-prefillは不要で、常にオンになっている。 より良いメモリ管理。 V1はGPUメモリをより細かい粒度で追跡し、パディングとアライメントからの無駄なスペースを削減する。5-15%のより多くの利用可能なKVキャッシュを、同じハードウェアでV0と比較して期待できる。 CUDAグラフの改善。 V1はより幅広いバッチシェイプで積極的にCUDAグラフをキャプチャし、手動チューニングなしにスループットを向上させる。
V1でリグレッションが発生した場合は、サーバー起動前に環境変数VLLM_USE_V1=0を設定してV0にフォールバックできる。問題をvLLMチームに報告してほしい。V0は新機能を受け取らない。

v0.31の新機能:永続ウェイトキャッシュとスナップショット

vLLM v0.31は2つの新しいCLIコマンドを導入する。
  • vllm preload は永続ウェイトキャッシュデーモンを起動し、サーバー再起動間でもモデルウェイトをGPUメモリに保持する。再起動ごとに数ギガバイトのモデルをディスクから再ロードする代わりに、サーバーがデーモンに接続してキャッシュされたウェイトを再利用する。これによりコールドスタート時間が数分から数秒に短縮される。
  • vllm snapshot create は現在のサーバー状態(ロード済みモデル、アダプター、設定)をキャプチャし、vllm snapshot restore が即座に復元する。悪い設定変更後のロールバックや、既知の良好な設定をマシン間で複製するのに有用だ。

v0.31の破壊的変更

  • --trust-request-mm-kwargs はクライアントがリクエストボディを通じてマルチモーダル入力(画像、オーディオ)を送信する際に現在必須だ。このフラグがない場合、vLLMはセキュリティ上の理由からマルチモーダルkwargsを拒否する。アプリケーションがAPIリクエストで画像やその他のメディアを送信する場合は追加する。
  • --grpc はHTTPサーバーと並行してgRPCサービングを有効にする。gRPCクライアントを使用する場合は、このフラグを付けてvLLMを起動し、gRPCエンドポイントを公開する。

設定例

高スループットバッチ処理

個別リクエストのレイテンシよりも毎秒合計トークン数が重要なオフラインバッチワークロードの場合。
この設定は4-GPUセットアップで並行性を最大化する。4ビット相当のKVキャッシュと高いバッチ制限は、リクエストごとのレイテンシが長くなるのと引き換えにスループットを押し上げる。

低レイテンシインタラクティブサービング

ユーザーがレスポンスを待つチャットアプリケーションで、TTFTを500ms未満に抑える場合。
小さなバッチサイズと中程度のトークン制限によりGPUの応答性が保たれる。プレフィックスキャッシングはレイテンシを追加せずに繰り返しのシステムプロンプトを高速化する。

マルチアダプターLoRAサービング

単一のベースモデルから複数のファインチューニング済みバリアントをサービングする場合。
クライアントはmodelフィールドでアダプターを名前で選択する。全3アダプターが同じベースモデルウェイトを共有するため、GPUメモリ使用量はベースモデル単体のサービングとほぼ同等で、各LoRAアダプターは数メガバイトしか追加しない。
vLLMの設定を変更した後、Tokiosデプロイメントを再登録して、コネクターが新しいアップストリームエンドポイントを取得できるようにする。Register Modelを参照。