Last verified: 2026-10-14 — vLLM v0.31.0.
V1がデフォルト。 V1アーキテクチャはvLLM v0.31.0でデフォルトとなった。新しいスケジューラー、デフォルトで有効化されたチャンクドプリフィル、改善されたGPUメモリ管理をもたらす。古いガイドとの動作差異がある場合、V1がその原因である可能性が高い。
KVキャッシュのチューニング
KVキャッシュはすべてのアクティブなシーケンスの各トークンのキーバリューテンソルを格納する。モデルウェイト自体に次ぐGPUメモリの最大の消費源であり、これをチューニングすることで同時リクエスト数を最大限に変更できる。サイジング計算式
vLLMはKVキャッシュサイズを自動計算するが、計算式を理解しておくと上限設定に役立つ。float16)の場合:
fp8 KVキャッシュの使用
--kv-cache-dtype fp8はデフォルトのfloat16と比較してKVキャッシュメモリを約50%削減する。キャッシュ可能なトークン数が直接倍増し、より多くの同時シーケンスまたはより長いコンテキストに対応できる。
--max-num-seqsと--max-model-len
これら2つのフラグは同じKVキャッシュプールを競合する。
--max-model-lenは単一シーケンスのコンテキスト長に上限を設定する。これを下げるとKVキャッシュが解放され、より多くの同時シーケンスに対応できる。--max-num-seqsは単一のバッチで処理されるシーケンス数に上限を設定する。これを上げるとスループットが向上するが、シーケンスごとのメモリコストが増加する。
--max-model-lenを下げ、--max-num-seqsを上げて並行性を最大化する。ロングコンテキストリクエストを扱う場合はその逆を行う。
プレフィックスキャッシング
多くの実ワークロードでは、共通のプレフィックスを共有するリクエストが送信される。システムプロンプト、RAGの検索ブロック、マルチターン会話の過去のターンなどだ。プレフィックスキャッシングがない場合、vLLMは共有プレフィックスのKVキャッシュをリクエストごとに再計算する。--enable-prefix-cachingは計算済みのKVブロックをハッシュインデックス付きテーブルに格納する。キャッシュ済みブロックと一致するプレフィックスを持つ新しいリクエストが到着すると、vLLMはKVテンソルを再計算せずにキャッシュを再利用する。
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を通じて実行時にアダプターを追加または削除できる。多数のアダプターを持ち、そのうち少数のみが常にアクティブな場合に有用だ。量子化オプション
量子化はモデルウェイトの精度を16ビット未満に下げ、わずかな精度と引き換えに大きなメモリとスピードの向上を得る。vLLMは複数の量子化フォーマットをサポートする。量子化モデルの使用
事前量子化モデルの場合、vLLMはモデルのconfig.jsonからフォーマットを自動検出する。
オンライン量子化
ロード中にモデルをオンザフライで量子化することも可能だが、本番環境では事前量子化モデルが推奨される。スループットとレイテンシ
最適化戦略はスループット(全リクエスト合計の毎秒トークン数)とレイテンシ(個別リクエストの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を使用する。
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エンドポイントを公開する。
設定例
高スループットバッチ処理
個別リクエストのレイテンシよりも毎秒合計トークン数が重要なオフラインバッチワークロードの場合。低レイテンシインタラクティブサービング
ユーザーがレスポンスを待つチャットアプリケーションで、TTFTを500ms未満に抑える場合。マルチアダプターLoRAサービング
単一のベースモデルから複数のファインチューニング済みバリアントをサービングする場合。modelフィールドでアダプターを名前で選択する。全3アダプターが同じベースモデルウェイトを共有するため、GPUメモリ使用量はベースモデル単体のサービングとほぼ同等で、各LoRAアダプターは数メガバイトしか追加しない。
vLLMの設定を変更した後、Tokiosデプロイメントを再登録して、コネクターが新しいアップストリームエンドポイントを取得できるようにする。Register Modelを参照。