vLLM Docker：アーキテクチャ、性能、クラウド導入ガイド

vLLM Docker：アーキテクチャ、性能、クラウド導入ガイド

Dockerは、自分で管理するGPU上でvLLMをOpenAI互換エンドポイントとして公開する最も直接的な方法です。ただし、優れたvLLM Dockerデプロイは単なるdocker runコマンドではありません。互換性のあるGPUランタイム、メモリと同時実行数を制限する計画、エッジでの認証、そしてトラフィック到来前に性能をテストする再現可能な方法が必要です。

このガイドでは、アーキテクチャ、安全な初回デプロイ、実際に容量を変える設定項目、そして1台のGPUからクラウドGPUフリートへ移行する道筋を解説します。

vLLM Dockerを使用するケース：モデルの重み、デプロイ場所、ランタイム設定を制御する必要がある場合、または安定したセルフホスト型ワークロードがある場合です。運用コストがその制御の価値を上回る場合は、マネージドモデルAPIや統合ゲートウェイの方が適切な境界となることがよくあります。

vLLM Dockerで得られるもの

vLLMは、OpenAI互換サーバーを起動する公式のvllm/vllm-openai Dockerイメージを公開しています。これにより、vLLM Dockerは、モデルリポジトリと、すでにOpenAIクライアント形式を使用しているアプリケーションとの有用な橋渡しになります。モデル一覧、チャット補完、補完、埋め込み、および関連する互換エンドポイントは、デプロイするモデルとサーバーバージョンに依存します。現在のイメージとランタイムの例については、vLLMのDockerドキュメントを参照してください。

実務上の意味は単純です。自社GPUにワークロードを移しただけで、アプリケーションに専用のモデルサーバークライアントは必要ありません。ただし、明示的なモデル名、APIキー、タイムアウト、および自社の可用性目標に合ったリトライ動作は依然として必要です。

vLLM Dockerのアーキテクチャの仕組み

大まかに言うと、vLLM Dockerは5つのレイヤーで構成されています。

1. クライアントは、認証済みリクエストをOpenAI互換エンドポイントに送信します。
2. APIサーバーがリクエストを検証してトークン化し、vLLMエンジンに渡します。
3. スケジューラーが互換性のある処理をバッチ化し、1つ以上のGPUワーカーにディスパッチします。
4. GPUワーカーはトークン生成中、モデルの重みとキー・バリュー（KV）キャッシュを保持します。
5. レスポンスはAPIサーバーを経由してクライアントへストリーミングで返されます。

性能の中核となる考え方はPagedAttentionです。リクエストの最大可能長に対して1つの大きな連続KVキャッシュ領域を予約する代わりに、vLLMはKV状態をブロック単位で管理します。これにより、可変長のワークロードを利用可能なメモリに詰め込みやすくなり、完了したリクエストは後続の処理のためにブロックを解放できます。元のPagedAttention論文では、スケジューラー、GPUワーカー、論理KVブロックから物理KVブロックへの対応、およびキャッシュ利用率とバッチ処理のトレードオフが説明されています。

このアーキテクチャには重要な運用上の帰結があります。VRAMは単なる「モデルサイズ」ではありません。モデルの重み、ランタイムオーバーヘッド、アクティベーション、およびコンテキスト長と同時リクエスト数に応じて需要が増えるKVキャッシュで共有されます。コンテキスト、同時実行数、メモリ使用率は、3つの別々のチューニング作業ではなく、1つの判断として扱ってください。

クラウドGPUでvLLM Dockerを実行する前に

まず、次の4点を確認してください。

1. テスト済みのイメージタグを選ぶ。本番環境では、latestを無批判に追従するのではなく、vLLMのリリースタグを固定してください。フラグやデフォルト値に依存する前に、そのタグに対応するドキュメントを読んでください。
2. ダウンロードおよび提供する権利があるモデルを使用する。一部のリポジトリでは、Hugging Faceトークンまたはモデルライセンスへの同意が必要です。検証後にモデルリビジョンを固定してください。
3. モデルコンテナの外部でGPUアクセスを確認する。ホストのNVIDIAドライバーとNVIDIA Container Toolkitをインストールし、nvidia-smiでGPU対応コンテナを検証してください。NVIDIAのインストールガイドでは、ホスト側の前提条件とランタイム設定を説明しています。
4. 最初はポートを非公開にする。単一ホストの概念実証ではループバックにバインドするか、TLS、認証、リバースプロキシ／ロードバランサーの背後にあるプライベートサブネットにサービスを配置してください。素のモデルサーバーをインターネット向けのセキュリティ境界として扱わないでください。

vLLM自体のデバッグを始める前に、NVIDIAのサンプルコマンドを使用してください。

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

このコマンドで想定されるGPUを確認できない場合は、そこで止めてください。モデルサーバーのログで、欠落したドライバー、未設定のコンテナランタイム、またはクラウドVMに割り当てられていないGPUを修正することはできません。

単一GPUのvLLM Dockerサーバーを実行する

以下は意図的に最小限にした出発点です。公式イメージのパターンを踏襲しつつ、APIキーを追加し、公開ポートをループバックにバインドしています。プレースホルダーは、テスト済みのモデルとイメージタグに置き換えてください。

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

共有メモリ設定とHugging Faceキャッシュのマウントは、公式のvLLM Docker例に従っています。キャッシュをマウントすることで、コンテナを再作成した際に同じモデルの重みを再ダウンロードせずに済みます。APIキーはアプリケーションの制御手段であり、ネットワーク分離、TLS、レート制限、シークレットマネージャーの代替ではありません。

アプリケーションを接続する前に、サーバーが想定したモデルを提供していることを確認します。

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

次に、/v1/models が返した同じモデル識別子を使用して、小さなリクエストを1つ送信します。

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

モデルに使用可能なチャットテンプレートが含まれていない場合、コンテナが起動していてもチャット補完リクエストは失敗することがあります。vLLMでは、トークナイザー設定にテンプレートがないモデルに対して--chat-templateを指定する方法が説明されています。アプリケーションをロールアウトする前に、これをテストしてください。チャットテンプレートのガイダンスを参照してください。

フラグを変更する前に性能の範囲を設定する

すべてのケースで正しいvLLM Dockerコマンドは存在しません。適切な構成は、モデルアーキテクチャ、GPUの種類とメモリ、入出力長の分布、同時実行数、レイテンシ目標によって異なります。代表的なワークロードでベースラインを確立してから、一度に1つの変数だけを変更してください。

少なくとも以下の測定値を取得します。

• リクエストの成功率・エラー率、および再起動・OOMイベント。
• 最初のトークンまでの時間（TTFT）と出力トークンあたりの時間（TPOT）。プロンプト長ごとに分類します。
• 想定する同時実行数における、エンドツーエンドレイテンシのp50およびp95/p99。
• 入力トークン、出力トークン、キュー時間、アクティブリクエスト、GPUメモリ使用量。
• 満たしたレイテンシおよび品質目標と併せてのみ評価するスループット。

容量を大きく左右するvLLM Dockerフラグ

正確なオプションのデフォルト値と動作はバージョンに依存します。vLLMの最新のエンジン引数リファレンスでは、スケジューラー、キャッシュ、並列性、キューの制御が定義されています。また、キャッシュ構成リファレンスでは、メモリ使用率とプレフィックスキャッシュの設定を説明しています。

実践的なチューニング順序

1. アプリケーションの制限に基づいて、現実的な --max-model-len を設定します。
2. メモリ使用率は控えめに始め、ドライバー／ランタイムのオーバーヘッド分の余裕を残します。
3. 実際のプロンプト長と補完長で --max-num-seqs および --max-num-batched-tokens の負荷テストを行います。
4. 1台のGPUではモデルを収容できない、または目標を達成できない場合にのみ、テンソル並列化を追加します。
5. 可用性または総トラフィックの要件から独立した障害ドメインが必要な場合は、ロードバランサーの背後にレプリカを追加します。

この順序により、ワークロードが実際にコンテキスト制約、キュー制約、メモリ制約、またはコンピュート制約のいずれなのかを把握する前に、GPUを追加したり同時実行数を増やしたりするという、よくある間違いを防げます。

複数のGPUにわたってvLLM Dockerをスケールする

複数のGPUを必要とする1つのモデルに対して、vLLMはテンソル並列およびパイプライン並列のサービングをサポートしています。単一ホストでは、GPUをコンテナに公開し、テンソル並列サイズを、そのモデルサーバーに意図的に割り当てるGPU数に設定します。

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

vLLMの並列化とスケーリングのガイドでは、テンソル並列化、パイプライン並列化、および単一ノードと複数ノードの実行に関する選択肢を説明しています。2 GPUノードに対して、例の 4 をそのままコピーしないでください。このフラグはこのサーバーに割り当てたGPU数に合わせ、通信トポロジー、メモリバランス、障害時の挙動を検証してください。

実装の詳細、トポロジーチェック、テンソル並列化とパイプライン並列化の選択については、FlatkeyのvLLMマルチGPU推論ガイドを参照してください。Dockerデプロイメントではなくサービングランタイムの選定については、vLLM vs. SGLangを参照してください。

本番クラウドデプロイメントの構成

本番のvLLM Dockerデプロイメントでは通常、パブリックエッジとGPU実行を分離します。

通常の再起動が予期しないモデルダウンロードにつながらないよう、Hugging Faceキャッシュは永続ストレージまたは意図的にウォームアップされたストレージに配置してください。モデルのライセンスとアクセス制御をデプロイメント記録に残します。モデルリポジトリが変動するブランチを参照している場合、イメージタグだけを固定しても十分ではありません。

GPUの選定、コンテキスト主導のメモリ計画、クラウドインフラストラクチャが適切となるタイミングの背景については、このランブックをFlatkeyのLLM GPUメモリ要件ガイド、GPUクラウドガイド、およびGPUクラウドとモデルAPIフレームワークの比較にリンクしてください。

推測に頼らないvLLM Dockerのトラブルシューティング

サーバーが稼働していても、アプリケーションの挙動がホスト型 API と異なる場合は、エンドポイントとパラメータの互換性を明示的に確認してください。Flatkey のOpenAI 互換推論サーバーガイドでは、クライアント側の移行と互換性テストの対象範囲を解説しています。

vLLM Docker を自ら運用すべきでない場合

セルフホスティングはインフラストラクチャへの継続的な取り組みです。イメージの更新、モデルの来歴、GPU 容量、ノード障害、アクセス制御、レイテンシー検証、オンコール対応を自ら担うことになります。ランタイム制御が要件である場合、これは適切な選択となり得ます。

モデルの選択肢、プロバイダーの可用性、または運用の簡素さが GPU の直接制御よりも重要なワークロードでは、アーキテクチャにマネージド API の経路を残してください。Flatkey は補完的なワークフロー向けに設計されています。すなわち、一元化された請求とともに、プロバイダーをまたいでモデルにアクセスするための単一の OpenAI 互換統合を提供し、本当に必要なワークロードについてはセルフホスト型 vLLM エンドポイントも選択肢として維持します。

次に取るべき手順は、単独でベンチマークを最大化することではありません。本番トラフィックの背後にvLLM Dockerを配置する前に、イメージとモデルを固定し、GPU ランタイムを検証し、明示的なコンテキストおよびキューポリシーを設定し、本番環境に即したリクエストでテストし、障害時の対応経路を文書化してください。

よくある質問

vLLM Docker はマネージド LLM API と同じですか？

いいえ。vLLM Docker は、自分で運用する GPU 上でモデルを提供するランタイムです。マネージド API では、モデルホスティングと GPU 運用が抽象化されます。どちらも OpenAI 互換のクライアントインターフェースを公開できますが、運用上の責任は異なります。

vLLM Docker には NVIDIA Container Toolkit が必要ですか？

NVIDIA GPU コンテナでは、ホストに互換性のある NVIDIA ドライバーと、構成済みの GPU コンテナランタイムが必要です。NVIDIA Container Toolkit は、GPU を Docker コンテナで利用可能にするために NVIDIA がドキュメントで示している標準的な方法です。

最初に調整すべき vLLM Docker フラグはどれですか？

まず現実的な最大コンテキスト長を設定し、その後、代表的なリクエスト構成でメモリ使用率、同時実行性、バッチトークン制限をテストしてください。ワークロードのベースラインなしにフラグを変更しても、ほとんどの場合、再現不可能な結果になるだけです。

vLLM Docker は複数の GPU にまたがってモデルを実行できますか？

はい。vLLM はテンソル並列およびパイプライン並列のサービングをサポートしています。まず単一ホストで開始し、設計を拡張する前に、正確な GPU 数、トポロジー、通信の挙動を検証してください。

情報源と参考資料

• vLLM: Docker の使用
• vLLM: 並列処理とスケーリング
• vLLM: エンジン引数
• NVIDIA Container Toolkit インストールガイド
• PagedAttention を用いた大規模言語モデルサービングのための効率的なメモリ管理