vLLM KV キャッシュのメモリが不十分な場合の対処方法: ビデオメモリ、コンテキスト、同時実行性のトラブルシューティング

Sat, 11 Jul 2026 09:36:02 +0800

vLLM の開始時に次のエラーが発生する場合、通常はモデルの重みのダウンロードが壊れているためではありません。

`1`	`The model's max seq len ... KV cache is needed, which is larger than the available KV cache memory`

これは、モデルの重みと実行時のオーバーヘッドがビデオメモリを占有すると、設定した最大コンテキスト長に合わせて KV キャッシュを準備するには残りのスペースが十分ではないことを意味します。最も直接的な処理シーケンスは次のとおりです。 **最初に --max-model-len を削減し、次に同時実行性を確認し、最後にメモリ使用率の改善、KV キャッシュの定量化、または容量の拡張を検討します。 **

--gpu-memory-utilization を最初から 1 にしないでください。これにより、vLLM は初期化を通過できる可能性がありますが、実際のリクエスト、CUDA グラフ、またはその他のプロセスがビデオメモリをめぐって競合すると、OOM が発生しやすくなります。

まず理解してください: なぜ KV キャッシュがビデオメモリをいっぱいにするのか

モデルの重みは「モデルをロードできるかどうか」を決定し、KV キャッシュは「モデルが同時に記憶できるトークンの数と処理するリクエストの数」を決定します。トークンが生成または読み取られるたびに、アテンション層は対応するキー/値の状態を保存する必要があります。

したがって、KV キャッシュの使用量は次の項目で増加します。

max_model_len: 許可される最大コンテキストが長くなるほど、キャッシュ要件も大きくなります。
同時リクエストの数: 各同時リクエストは独自のコンテキスト空間を占有します。
モデル構造: レイヤーの数、KV ヘッドの数、非表示サイズ、データ型はすべてキャッシュサイズに影響します。
キャッシュ精度: 通常、デフォルトはモデルのデータ型に従います。 FP8 などの低精度キャッシュはスペースを節約できますが、互換性と品質の限界があります。

最も見落とされているのは同時実行性です。各リクエストに 8K コンテキストしか与えられていない場合でも、複数のリクエストが同時に実行されている場合、KV キャッシュの総需要は依然として急速に増加します。

まずはログからどのような問題なのかを判断します

起動ログには通常、次の 3 つの重要な情報が含まれています。

モデルによって指定された、またはユーザーが構成した最大シーケンス長。
KV キャッシュに必要な GiB 数。
KV キャッシュに現在利用可能な実際のスペースと、vLLM によって推定される実現可能な最大長。

ログに「最大長 32768 には 10GiB KV キャッシュが必要ですが、現在は 4GiB のみです」と表示されている場合は、最初にモデルが 32K をサポートしているかどうかを心配する必要はありません。モデル サポート は、カードが現在の構成で 32,000 のリクエストを処理できることを意味するものではありません。

まず、ログによって提供される推定最大長に注目し、最初のテストをその長さの約 60% ～ 80% に設定し、その後長さを増やしていきます。

最優先: 低い `--max-model-len`

これは、成功率が最も高く、影響が最も予測しやすい調整です。たとえば、モデルはネイティブで 32K をサポートしており、実際のビジネスでは通常の会話、ショートコード、小さなドキュメントのみを処理する場合、8K から始めることができます。

1
2

vllm serve Qwen/Qwen3-8B \
  --max-model-len 8192

それでも十分でない場合は、もう一度試してください。

1
2

vllm serve Qwen/Qwen3-8B \
  --max-model-len 4096

モデルカードの公称 128K、256K、またはそれ以上のコンテキストをサービスパラメータに直接書き込まないでください。シングルカード導入の場合、実際に利用可能な長さは、重量、ビデオメモリ、同時実行性、およびキャッシュの精度によって異なります。

実際的な出発点:

ビデオメモリと使用量	最初に試行するコンテキストの長さ
12GB～16GB シングルカード、クラス 8B モデル	4096 または 8192
24GB シングルカード、7B ～ 14B モデル	8192 または 16384
24GBシングルカード、30Bレベル量子化モデル	4096 から始める
長文/RAG/マルチユーザーサービス	表に従うだけではなく、ログの推定とストレステストに基づいて意思決定を行います。

これらの値は、メモリの使用量ではなく、トラブルシューティングの開始点です。 KV キャッシュのサイズはモデル間で大幅に異なる場合があります。

2 番目の優先事項: 同時実行性とバッチ処理を制限する

サービスを開始できるからといって、同時実行性が高い条件下でサービスが安定するとは限りません。まず、同時実行性を小さい値に制御します。

1
2
3

vllm serve Qwen/Qwen3-8B \
  --max-model-len 8192 \
  --max-num-seqs 4

--max-num-seqs は、1 回の反復で処理できるシーケンスの数を制限します。数値を大きくするとスループットが高くなる可能性がありますが、KV キャッシュとスケジューリングのプレッシャーも大きくなります。

リクエストに長いプロンプトが含まれることが多い場合は、--max-num-batched-tokens にも注意する必要があります。一度に処理できるトークンの最大数を決定します。この値が高すぎると、プレフィルフェーズでより多くのリソースが即座に占有される可能性があります。トラブルシューティングの際は慎重に行い、安定性を確認してから徐々に拡張してください。

ストレステストは次の順序で実行することをお勧めします。

単一リクエスト、4K コンテキスト、サービスの安定性を確認しました。
単一リクエスト、8K コンテキスト、最初のトークンのレイテンシとビデオメモリを観察します。
2 つの同時リクエストにより、OOM がないことが確認されます。
次に、max_num_seqs またはバッチトークンの数を徐々に増やします。

コンテキスト、同時実行性、バッチおよびモデルの量子化を同時に調整しないでください。調整しないと、ビデオメモリを使い果たす原因となっているパラメータを特定することが困難になります。

3 番目の優先事項: `--gpu-memory-utilization` を適切に設定する

--gpu-memory-utilization は、現在の vLLM インスタンスで使用できる GPU メモリの割合を 0 ～ 1 の値で指定します。vLLM は、スペースのこの部分に基づいて重み、ランタイム、および KV キャッシュを計画します。

例えば：

vllm serve Qwen/Qwen3-8B \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --max-num-seqs 4

エラーメッセージが明らかに「利用可能な KV キャッシュが少なすぎます」と表示され、GPU 上に他のプロセスがない場合は、0.90 から 0.92 または 0.94 まで試すなど、小さなステップで改善できます。一度に少しずつ追加して、実際のリクエストでテストしてください。

以下の状況ではデッドリフトを高く上げることはお勧めできません。

同じカード上で、デスクトッププログラム、別の推論サービス、またはトレーニングタスクも実行されます。
使用可能なビデオメモリは起動後に変動します。
CUDA グラフ、ビジョンモデル、または同時実行性の高いプレフィルを使用する場合、スパイクが発生する傾向があります。
初期化チェックの失敗だけでなく、実行中の CUDA OOM が発生しました。

複数のインスタンスが同じ GPU を共有する場合は、すべてを 0.9 に設定するのではなく、インスタンスごとに明示的なバジェットを設定する必要があります。

FP8 KV キャッシュ: グラフィックスメモリを保存する前にモデルとバージョンを確認してください

vLLM は、--kv-cache-dtype によるキャッシュデータタイプの変更をサポートしています。 CUDA 11.8 以降の環境では、次のような FP8 関連のオプションを使用できます。

1
2
3

vllm serve Qwen/Qwen3-8B \
  --kv-cache-dtype fp8 \
  --max-model-len 16384

FP8 KV キャッシュはキャッシュ使用量を大幅に削減できますが、完全に無料のスイッチとは考えないでください。

まず、現在の vLLM、CUDA、およびハードウェアがこのデータ型をサポートしていることを確認します。
モデルチェックポイントが適切な KV スケールを提供するかどうかは、結果に影響します。存在しない場合は注意して評価する必要があります。
長いコンテキスト、複雑な推論、ツール呼び出し、構造化された出力はすべて、デフォルトのキャッシュ精度に対してテストする必要があります。
不適切な大きなモデルをグラフィックスカードに適合させたいだけの場合は、通常、最初にコンテキストを下げるか、より適切なモデルに変更する方が安定します。

したがって、より推奨される順序は、最初にデフォルトの精度を使用して 4K/8K を安定して実行し、次に FP8 がビジネスで必要なコンテキストまたは同時実行性を実際に取得できるかどうかをテストすることです。

KV キャッシュサイズを手動で指定する場合の優先順位を把握する

新しい vLLM は、GPU あたりの KV キャッシュサイズをバイト単位で正確に指定するための kv_cache_memory_bytes を提供します。これは、複数のサービスがカードを共有し、固定のグラフィックスメモリバジェットを必要とするシナリオに適しています。

注: キャッシュバイト数を明示的に設定すると、gpu_memory_utilization によるキャッシュサイズの自動推論がオーバーライドされます。両方を相加的な利益とは考えないでください。まず、「比例予算」を使用するか「固定キャッシュ予算」を使用するかを決定します。

固定予算は、運用とメンテナンスの明確な制約があるサーバーに適しています。単一マシンのトラブルシューティングには --gpu-memory-utilization と --max-model-len を使用する方が直感的です。

CPU オフロードで何が解決でき、何が解決できないのか?

新しいバージョンの vLLM は、KV キャッシュの一部を CPU にオフロードするか、LMCache などのバックエンド処理キャッシュレイヤーと組み合わせることをサポートします。これにより、GPU キャッシュが不十分な場合に容量を拡張できますが、PCIe/メモリ転送と遅延が犠牲になります。

以下の場合に適しています。

非常に長いコンテキストリクエストが発生する場合があります。
ビジネスは、初期トークンの遅延が長くても許容できます。
十分なシステムメモリがあり、実際のストレステストが実施されています。
最高のスループットを追求するのではなく、長いプロンプトに対して機能低下パスを作成したい。

「モデルの重みを下げることができない」という問題を隠すのには適していませんし、同時実行性やコンテキストの上限の管理を置き換えることもできません。すべてのリクエストが頻繁にスワップアウトおよびスワップインされると、スループットが大幅に低下することがよくあります。

複製可能なトラブルシューティングテンプレート

保守的な構成から始めます。

vllm serve Qwen/Qwen3-8B \
  --gpu-memory-utilization 0.90 \
  --max-model-len 4096 \
  --max-num-seqs 2

オーダーリクエストが安定して処理できることを確認したら、以下の順序で調整してください。

4096 上下文稳定
-> 8192 上下文稳定
-> max_num_seqs 从 2 调到 4
-> 调整 max_num_batched_tokens
-> 再测试 FP8 KV Cache 或 CPU offload

各ラウンドでは、利用可能な KV キャッシュトークンの数、最初のトークン遅延、生成されたトークン/秒、およびピークビデオメモリの 4 つのデータが記録されます。こうすることで、最適化によってスループットが向上しているのか、それとも単に OOM を延期して同時実行性を高めているのかを知ることができます。

よくある誤解

誤解 1: モデルは長いコンテキストをサポートしているため、サービスを完全に有効にする必要があります

モデルの機能の上限とグラフィックスカードの保守性の上限は別のものです。サーバーの max_model_len は、ハードウェアおよびビジネスの上限に従って設定する必要があります。

誤解 2: 問題を解決するには `gpu_memory_utilization` を 1 に設定します

これにより安全マージンが減少しますが、KV キャッシュ自体の必要性は減少しません。実行時のスパイクにより CUDA OOM がトリガーされる可能性が高くなります。

誤解 3: 同時実行性に関係なく、重みの量子化のみを削減する

重みの量子化によりビデオメモリを解放できますが、同時実行性とコンテキストにより KV キャッシュが急速に拡大します。サービス構成では、リクエストの長さと数の両方を制限する必要があります。

誤解 4: CPU オフロードは、長いリクエストを拒否するよりも明らかに優れています

レイテンシが重要な場合、頻繁なオフロードは、より大きなメモリを備えたノードに長いリクエストを明示的にルーティングするよりも悪い可能性があります。まず、ビジネスの遅延とコストの境界を定義します。

要約する

vLLM KV キャッシュにメモリが不足しています。最も信頼性の高い処理優先度は次のとおりです。

降低 max_model_len
-> 限制 max_num_seqs 与 batch
-> 小步调整 gpu_memory_utilization
-> 验证 FP8 KV Cache
-> 最后考虑固定缓存预算或 CPU offload

最初は短いコンテキストと低い同時実行構成で安定して動作させ、その後ビジネスデータに応じて徐々に拡張していきます。モデルの重み、KV キャッシュ、同時実行性、および実際のコンテキストの長さを個別に検討する限り、ほとんどの「メモリ不足」問題をより迅速に特定できます。

参照:

LLM推理 on KnightLiブログ

vLLM KV キャッシュのメモリが不十分な場合の対処方法: ビデオ メモリ、コンテキスト、同時実行性のトラブルシューティング

まず理解してください: なぜ KV キャッシュがビデオ メモリをいっぱいにするのか