vllm

vLLM 推論サービング

このスキルは、vLLM を本番環境の推論サーバーとして運用する際に使用します。Docker または Kubernetes でデプロイし、モデルとエンジン（量子化、テンソル並列処理、KV キャッシュ、コンテキスト長）を設定し、OpenAI 互換の API サーフェスを提供し、比較可能な根拠に基づいてスループットとレイテンシをベンチマークし、連続バッチ処理を調整し、基盤となる GPU を運用して、安全にアップグレードまたはロールバックします。これは、名前を指定した単一のエンジンを対象とするツールスキルです。エンジンの選定、量子化のトレードオフ、デプロイ計画、リグレッションのトリアージといったサービングの方法論は ml-engineering に、llama.cpp スタックを使った単一ノードでのローカル GGUF サービングは llama-cpp に属します。このスキルが対象とするのは、vLLM 自体の日常的な運用です。

運用上の契約

1. 調整する前に、デプロイ構成を記録してください。 vLLM のバージョンまたはイメージダイジェスト、モデルとリビジョン、量子化、並列処理、max-model-len、KV キャッシュ設定、バッチ処理の上限、GPU の構成、ワークロードを記録します。サービング設定テンプレート は、まさにこの目的のために用意されています。
2. 操作する前に、対象、範囲、ロールバック手順を確認してください。 ヘルスプローブ、/metrics、nvidia-smi による読み取り専用の調査は、確認なしで実施できます。サーバーの再起動、サービング引数の変更、レプリカのスケーリング、イメージのアップグレードといった変更には、対象のデプロイを明示した人間の指示が必要です。
3. 応答するサーバーが、正常にサービングできるサーバーとは限りません。 /health が 200 を返すことが証明するのは稼働状態であり、モデルがロードされたことや推論が機能することではありません。提供境界で確認してください。/v1/models にサービング中のモデルが表示され、代表的なリクエストから生成トークンが返ることを確認します。
4. 変更の前後でベンチマークを実施してください。 vLLM のフラグ、デフォルト、動作はリリースごとに変わるため、計測していない調整は推測にすぎません。一致した条件（バージョン、モデル、GPU、コンテキスト、バッチ、ワークロード）だけを比較し、その根拠をベンチマーク実行記録に記録します。
5. 根拠の共有は必要な範囲にとどめてください。 ログ、設定、メトリクスは要約し、サーバーログ全体、.env ファイル、HF トークンをチャットに貼り付けないでください。デバッグログで --enable-log-requests を有効にするとプロンプトの内容が漏れる可能性があります。共有セッションでは、リクエストログを無効にするか、内容を伏せてください。

vllm-health スクリプト

scripts/vllm-health は、稼働中の vLLM サーバーを調査する、エージェント優先の読み取り専用プローブです。GET リクエストのみを送信し、変更は一切行わず、サイズを制限した JSON を出力します。

scripts/vllm-health --help                    # no server needed
scripts/vllm-health --url http://127.0.0.1:8000 --json
scripts/vllm-health --check health --check models --json
scripts/vllm-health --check metrics --timeout 10 --json

終了コード：0 はすべてのチェックが成功、1 は問題の検出または致命的エラー、2 は使用方法のエラー、124 はタイムアウトです。チェック項目は、health（/health）、version（/version）、models（/v1/models）、load（/load）、metrics（/metrics の先頭からサイズを制限した範囲）です。スクリプトがデータを外部に送信することはなく、ファイルへの書き込みも行いません。

運用ループ

1. デプロイを特定します：vLLM のバージョンまたはイメージダイジェスト、モデルとリビジョン、サービングモデル名、並列処理、デプロイ方法（ベアメタルでの vllm serve、Docker、Kubernetes）を確認します。
2. 根拠を収集します：vllm-health --json を実行して、ヘルス、バージョン、モデル、負荷を確認します。/metrics のカウンター（vllm:num_requests_running、vllm:num_requests_waiting、vllm:gpu_cache_usage_perc）を確認し、nvidia-smi で GPU の状態を調べます。
3. 症状に照らしてトリアージします：問題を根拠に対応付けます（OOM → KV キャッシュまたは gpu_memory_utilization、高レイテンシ → バッチ処理、TTFT と TPOT の比較、モデルが見つからない → サービング名またはチャットテンプレート、起動が遅い → モデルのダウンロードまたはコンパイルキャッシュ）。
4. 確認を得て操作します：人間の指示を受け、先にロールバック手順を明示してから、範囲を限定した変更を行います。
5. 検証します：プローブと代表的なリクエストを再実行し、提供境界で確認します。変更がパフォーマンスに影響する場合は、ベンチマークも再実施します。

デプロイ：Docker と Kubernetes

• Docker：公式イメージは vllm/vllm-openai（Docker Hub）です。GPU アクセスを有効にし、Hugging Face キャッシュをマウントして、ゲート付きモデル用の HF トークンを設定し、ポート 8000 を公開して実行します。また、テンソル並列処理で必要となる共有メモリを確保するため、--ipc=host（または --shm-size）を指定してください。references/01-deployment.mdを参照してください。
• Kubernetes：nvidia.com/gpu（または amd.com/gpu）リソースを指定した Deployment、モデルキャッシュ用の PVC、/dev/shm にマウントする Memory backed の emptyDir、ポート 8000 の /health に対する liveness/readiness プローブ、および Service を設定します。読み込みに数分かかる大規模モデルでは、プローブの failureThreshold を引き上げてください。読み込み前にプロセスが終了すると、コンテナーのログに KeyboardInterrupt: terminated と表示されます。
• イメージタグは latest ではなく、リリースに固定してください（例：vllm/vllm-openai:v0.26.0）。また、コンパイルキャッシュ（デフォルトは ~/.cache/vllm）を再起動後も保持し、torch.compile の成果物を再利用できるようにしてください。

モデル設定

• モデルの識別：--model には HF リポジトリまたはローカルパスを指定し、--revision で重みを特定のリビジョンに固定します。--served-model-name は、クライアントが /v1 リクエストで使用する名前と、レスポンスの model フィールドに設定される名前を指定します。一部のモデルリポジトリでは --trust-remote-code が必要です。使用する前に内容を確認してください。
• コンテキスト長：--max-model-len は、リクエストごとのプロンプトと出力を合わせた長さの上限です。未指定の場合はモデル設定から決定されます。-1／auto を指定すると、GPU メモリに収まる最大の長さが選ばれます。これは KV キャッシュサイズを決める最大の要因です。
• 量子化を考慮したサービング：モデルの重みに量子化が必要な場合に限り、--quantization（または -q）を指定してください（GPTQ／AWQ／GGUF チェックポイントでは、設定から量子化方式が読み込まれます）。重みの型とアクティベーションの dtype は、カーネルがサポートするものと一致している必要があります。量子化モデルを誤った dtype でサービングすると、読み込みに失敗するか、気付かないまま性能が低下します。ハードウェアの対応状況は方式によって異なります（references/02-model-configuration.mdを参照）。
• テンソル並列処理：--tensor-parallel-size N は、同一ノード内の N 個の GPU に 1 つのモデルを分割します。--pipeline-parallel-size はノード間でレイヤーを分割します。TP には NVLink／高速インターコネクトと、各 GPU で同じメモリ容量が必要です。起動ログにはメモリプロファイリングの結果が記録され、モデルがメモリに収まることを確認できます。
• KV キャッシュ：--gpu-memory-utilization（デフォルトは 0.92）は、モデルと KV キャッシュが使用できる GPU メモリの割合を制限します。対応 GPU では --kv-cache-dtype fp8 を指定すると、長いコンテキストでキャッシュを小さくできます。エンジンログに GPU KV cache size: N tokens と、そこから算出される最大同時実行数が表示されます。両方の値を記録してください。これらの値から、その環境で指定した長さのリクエストをいくつ同時に処理できるかが分かります。

OpenAI 互換 API の構成

• 基本エンドポイント：/health（稼働確認）、/version、/v1/models（サービング中のモデル）、/load（負荷メトリクス）、/metrics（Prometheus）。推論エンドポイント：/v1/completions と /v1/chat/completions（チャットにはモデルにチャットテンプレートが含まれているか、--chat-template を指定する必要があります）、プーリングモデル用の /v1/embeddings、Responses API 用の /v1/responses。
• ストリーミング、ツール呼び出し（--enable-auto-tool-choice --tool-call-parser openai）、構造化出力、並列サンプリングは、リクエスト／レスポンスの動作を変えるサーバー側のオプションです。すべてのリリースで同じ動作をすると仮定せず、インストール済みのリリースで個別に確認してください。
• サーバーをループバック以外に公開するには、バインドアドレス、API キー、TLS または信頼できるリバースプロキシ、ファイアウォールルールについて明示的に判断する必要があります。開発専用のエンドポイント（/reset_prefix_cache、重みの転送、プロファイリング）を本番環境に公開してはいけません。

ベンチマーク：スループットとレイテンシ

• オンラインサービングのベンチマーク：代表的なデータセット（ShareGPT、ローカルの custom JSONL、または独自のプロンプト）を使い、稼働中のサーバーに対して vllm bench serve を実行します。--num-prompts、--request-rate、--max-concurrency は固定します。リクエストスループット（req/s）、出力トークンスループット（tok/s）、合計トークンスループット、および TTFT／TPOT／ITL のパーセンタイルが報告されます。
• オフラインスループット：vllm bench throughput は HTTP 経路を介さずにエンジンの生のスループットを測定します。エンジンのみを比較する際に使用し、エンドツーエンドのユーザーレイテンシの測定には使用しないでください。
• 比較可能なエビデンス：ベンチマーク実行記録のテンプレートでは、バージョン、モデル、量子化、並列化、コンテキスト、バッチ処理、GPU、データセット、負荷パターンを固定します。条件が異なる数値を、1つの変数だけが変化したかのように比較しないでください。TTFT はレイテンシの指標、トークンスループットはスループットの指標です。一方を改善する最適化が、もう一方を悪化させることもあります。
• 本番環境の容量テストには、vLLM のドキュメントでは別個の GuideLLM フレームワークが推奨されています。このスキルの対象範囲は、同梱の vllm bench ツールです。

継続的バッチ処理のチューニング

• vLLM はデフォルトで継続的にバッチ処理を行います。スケジューラーは容量が空くたびにシーケンスを受け入れ、プリフィルとデコードを混在させます。--max-num-seqs はイテレーションごとのシーケンス数を制限し、--max-num-batched-tokens はイテレーションごとのトークン数を制限します。また、--enable-chunked-prefill を指定すると、プリフィルをデコードと同じイテレーションで処理できます。
• デフォルト設定から始め、条件を固定したベンチマークでノブを1つずつ変更してください。--max-num-seqs を上げると、リクエストごとのレイテンシと KV キャッシュの負荷が増す代わりに、スループットが向上します。下げると、使用率が低下する代わりに、レイテンシが安定します。
• --enable-prefix-caching は、共通のプレフィックス（チャットのシステムプロンプト、RAG コンテキストなど）を持つリクエスト間で KV ブロックを再利用します。ヒット率は /metrics と、ベンチマークの入力トークン集計で確認できます。--performance-mode はカーネルレベルで interactivity（レイテンシ）と throughput の間の優先度を調整します。

GPU の運用

• nvidia-smi（AMD の場合は rocm-smi）を使って、変更の前後に GPU を確認します。デバイス一覧、メモリ、使用率、温度、ECC エラーを確認してください。CUDA_VISIBLE_DEVICES で vllm serve プロセスから見える GPU を選択します。テンソル並列のランクは、可視デバイスに順番に割り当てられます。
• /metrics で vllm:gpu_cache_usage_perc（KV キャッシュの負荷）、vllm:num_requests_running／waiting、vllm:generation_tokens_total を監視してください。キャッシュ使用率が 1.0 近くにあり、待機中のリクエストがある場合、デプロイは容量の上限に達しています。過剰に割り当てるのではなく、スケールアウトするか、max-model-len／同時実行数を減らしてください。
• 起動中の OOM は通常、モデルと KV キャッシュがメモリに収まらなかったことを意味します。重みだけでメモリを超える場合は、--gpu-memory-utilization を下げても解決しません。--max-model-len を減らす、量子化方式を切り替える、または GPU を追加してください。実行中の OOM は KV キャッシュの負荷を意味します。コンテキスト、同時実行数、またはバッチ制限を縮小してください。

アップグレードとロールバック

• すべてを固定する：イメージタグまたは pip install vllm==<version>、モデルのリビジョン、サービングコマンド全体を固定します。latest イメージや固定されていないリビジョンでは、ロールバックが不可能になり、アップグレードを再現できません。
• アップグレード手順：対象となるバージョン範囲全体のリリースノートを読み、変更・削除されたフラグを確認します（--engine-args は頻繁に変更されます）。実際のモデルとワークロードを使ってスクラッチインスタンスで新バージョンを検証し、条件を固定したベンチマークを再実行してから、切り替えます。その際は、再適用できるように以前のイメージタグとサービング設定を用意したロールバック計画を立ててください。
• ロールバック：設定はバージョン管理されているため、以前の固定済みイメージと設定を使って再デプロイします。リリース間で KV キャッシュのレイアウト、デフォルト設定、フラグ名が変わるため、再検証と再ベンチマークを行わずに、v0.25.x で動作した設定が v0.26.x でも同じように動作すると仮定しないでください。

参照先の振り分け

読み込むタイミング	参照先
ソース、バージョンの確認事項、更新手順	references/00-source-index.md
Docker および Kubernetes のデプロイ、イメージの固定、プローブ、ストレージ	references/01-deployment.md
モデル設定：量子化、テンソル並列処理、KV キャッシュ、メモリ予算	references/02-model-configuration.md
OpenAI 互換 API の仕様、チャットテンプレート、ツール、認証	references/03-openai-api.md
ベンチマークの方法論と vllm bench コマンド	references/04-benchmarking.md
連続バッチ処理、チャンク化プリフィル、プレフィックスキャッシュ、パフォーマンスモード	references/05-batching-and-tuning.md
GPU 運用、可観測性、アップグレード／ロールバック、トラブルシューティング	references/06-gpu-ops-and-lifecycle.md

同梱されている成果物

• scripts/vllm-health：読み取り専用のヘルス／バージョン／モデル／負荷／メトリクスプローブ（標準ライブラリのみ、--json、--check サブセット、サーバーなしでの --help）。
• tests/test_vllm_health.py：読み取り専用の契約を含む、ローカルのスタブ HTTP サーバーを使った決定論的なテスト。
• templates/serving-config.md および templates/benchmark-run-record.md：デプロイの再現性を確保し、ベンチマークの証拠を比較可能にする記入式の記録テンプレート。
• references/：上記の運用トピックを網羅する、日付とソースインデックス付きの7つの参照資料。
• evals/evals.json：エージェントの実行を対象とする、出力品質の評価ケース6件。

検証の基準

主張	最低限必要な証拠
サーバーが稼働している	vllm-health --check health が /health の 200 を報告する
正しいモデルが提供されている	/v1/models に、想定した提供モデル名が表示される
推論が動作する	代表的な /v1/chat/completions または /v1/completions リクエストが、生成トークンと finish_reason を返す
モデルが収まる	起動ログにメモリプロファイリングの完了と、設定済みの並列度に対する GPU KV cache size: N tokens が表示される
チューニング変更に効果があった	条件を一致させ、ばらつきを報告したうえで、固定したベンチマークの宣言済み指標が改善している
デプロイをアップグレードできる	以前の固定イメージとサービング設定が記録され、スクラッチインスタンスでアップグレードのリハーサルが行われている
診断が妥当である	主張の前に証拠が収集され、プローブとベンチマークを再実行して修正が検証されている

厳守事項

• 対象と明示的なロールバック手順を指定する人間からの指示なしに、vLLM デプロイを再起動、再デプロイ、スケール、またはアップグレードしてはいけません。読み取り専用の調査は自由に行えます。
• 認証されていないサーバーを誤ってループバックの外部に公開してはいけません。開発専用のエンドポイントとプロファイリング用ルートは、本番のイングレスに接続しないでください。
• HF トークン、.env の内容、サーバーログ全体を出力またはコミットしてはいけません。代わりに証拠を要約してください。
• バージョン、モデル、量子化方式、並列度、コンテキスト、バッチ、ワークロードが異なるベンチマークの数値を、あたかも1つの変数だけが変更されたかのように比較してはいけません。
• vllm-health は読み取り専用ツールとしてのみ実行してください。変更を加える機能はありません。

使用しない場合

• モデルのトレーニング、ファインチューニング、評価セットの設計、量子化の決定、サービング手法 — これらは ml-engineering の対象です。
• llama.cpp スタック（llama-cli、llama-server、GGUF の変換と量子化、ローカルの Metal/CUDA ビルド）— これらは llama-cpp の対象です。
• その他の推論エンジン（TGI、Ollama、Triton。vLLM の埋め込み／リランキングのみのワークロードは対象ですが、エンジンの選定は対象外です）— エンジン選定のトレードオフは ml-engineering の対象です。
• Kubernetes と Docker の基礎（マニフェスト、RBAC、イメージレジストリ、GPU デバイスプラグイン）— これらは kubernetes と docker-compose の対象です。
• GPU インフラのプロビジョニング（ドライバー、クラスターのスケジューリング、キャパシティプランニング）— これらは platform-engineering の対象です。このスキルが運用するのは、vLLM サーバーがすでに対象としている GPU です。