vllm-deploy-docker

vLLM の Docker デプロイ

公式のビルド済みイメージを使うか、CUDA 対応の NVIDIA GPU 向けにソースからイメージをビルドして、Docker で vLLM をデプロイする方法を説明する Claude スキルです。NVIDIA CUDA のサポート、docker run の例、最小限の docker-compose スニペット、推奨フラグ、トラブルシューティングの注意事項が含まれています。AMD、Intel、その他のアクセラレーターについては、別のデプロイ方法が記載されている vLLM のドキュメントを参照してください。

このスキルでできること

• ビルド済みイメージ（ほとんどのユーザーに推奨）を使って vLLM を Docker でデプロイするか、カスタム設定向けにソースからビルドします
• GPU アクセスと Hugging Face キャッシュのマウントに対応した、OpenAI 互換サーバーの実行コマンド例を示します
• カスタムイメージやオプションの依存関係が必要な場合に、ソースからのビルド手順を案内します
• --ipc=host、共有キャッシュのマウント、HF_TOKEN の取り扱いなど、よく使われるフラグについて説明します

前提条件

• Docker Engine がインストールされていること（Docker 20.10 以降を推奨）
• 適切なドライバーと CUDA Toolkit がインストールされた NVIDIA GPU
• オプション：API テスト用の curl
• 非公開モデルを取得する場合、またはレート制限を避ける場合は Hugging Face トークン：HF_TOKEN

ビルド済みイメージを使ったクイックスタート（推奨）

GPU アクセスを有効にして vLLM OpenAI 互換サーバーを実行し、HF キャッシュをマウントしてポート 8000 を転送します。

docker run --rm --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=$HF_TOKEN" \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-1.5B-Instruct

• --gpus all はすべての GPU をコンテナに公開します。特定の GPU が必要な場合は調整してください。
• PyTorch と vLLM がホストの共有メモリーを共有できるように、--ipc=host または十分な大きさの --shm-size を指定することを推奨します。
• ~/.cache/huggingface をマウントすると、コンテナ内でモデルを再ダウンロードせずに済みます。

注： vLLM とこのスキルでは、最新の Docker イメージ（vllm/vllm-openai:latest）の使用を推奨しています。旧バージョンのイメージについては、Docker Hub のイメージタグを参照してください。

Docker イメージをソースからビルドする

提供されている docker/Dockerfile を使用して、vLLM をソースからビルドして実行できます。
まず、ホストマシンのハードウェアを確認し、必要な依存関係（NVIDIA ドライバー、CUDA Toolkit、BuildKit に対応した Docker など）がインストールされていることを確認してください。ARM64/aarch64 向けのビルドについては、「ARM64/aarch64 向けのビルド」セクションを参照してください。

基本的なビルドコマンド

DOCKER_BUILDKIT=1 docker build . \
  --target vllm-openai \
  --tag vllm/vllm-openai \
  --file docker/Dockerfile

--target vllm-openai は、OpenAI 互換サーバーのイメージをビルドすることを指定します。DOCKER_BUILDKIT=1 環境変数は BuildKit を有効にし、より優れたキャッシュ機能と高速なビルドを実現します。

ビルド引数とオプション

• --build-arg max_jobs=<N> — CUDA カーネルのビルドで並列コンパイルジョブ数を設定します。マルチコアシステムでビルドを高速化するのに役立ちます。
• --build-arg nvcc_threads=<N> — CUDA コンパイラーのスレッド数を制御します。過剰なメモリー使用を避けるため、max_jobs より小さい値を使うことを推奨します。
• --build-arg torch_cuda_arch_list="" — 空文字列に設定すると、vLLM は現在の GPU のコンピュート能力を検出し、その GPU 向けにのみビルドします。デフォルトでは、より広く配布できるよう、vLLM はすべての GPU タイプ向けにビルドします。

ビルドを高速化するためにプリコンパイル済みホイールを使用する

C++ または CUDA カーネルのコードを変更していない場合は、プリコンパイル済みホイールを使用して Docker のビルド時間を大幅に短縮できます。

• プリコンパイル済みホイールを有効にする： ビルドコマンドに --build-arg VLLM_USE_PRECOMPILED="1" を追加します。
• 仕組み： デフォルトでは、vLLM はアップストリームの main ブランチとのマージベースコミットを使用して、Nightly Builds から適切なプリコンパイル済みホイールを自動的に見つけます。
• コミットを指定する： 特定のコミットのホイールを使用するには、--build-arg VLLM_PRECOMPILED_WHEEL_COMMIT=<commit_hash> を追加します。

プリコンパイル済みホイールと高速コンパイル向けオプションを使った例：

DOCKER_BUILDKIT=1 docker build . \
  --target vllm-openai \
  --tag vllm/vllm-openai \
  --file docker/Dockerfile \
  --build-arg max_jobs=8 \
  --build-arg nvcc_threads=2 \
  --build-arg VLLM_USE_PRECOMPILED="1"

オプションの依存関係を含めたビルド（任意）

vLLM では、ライセンス上の問題を避けるため、ビルド済みイメージにオプションの依存関係（音声処理など）は含まれていません。オプションの依存関係が必要な場合は、ベースイメージを拡張するカスタム Dockerfile を作成してください。

例：音声処理のオプションの依存関係を追加する

# NOTE: MAKE SURE the version of vLLM matches the base image!
FROM vllm/vllm-openai:0.11.0

# Install audio optional dependencies
RUN uv pip install --system vllm[audio]==0.11.0

例：transformers の開発版を使用する：

FROM vllm/vllm-openai:latest

# Install development version of Transformers from source
RUN uv pip install --system git+https://github.com/huggingface/transformers.git

次のコマンドで、このカスタム Dockerfile をビルドします。

docker build -t my-vllm-custom:latest -f Dockerfile .

その後、ほかの vLLM イメージと同様に使用します。

docker run --rm --gpus all \
  -p 8000:8000 \
  --ipc=host \
  my-vllm-custom:latest \
  --model Qwen/Qwen2.5-1.5B-Instruct

ARM64/aarch64 向けのビルド

ARM64 システム（NVIDIA Grace-Hopper や Grace-Blackwell など）向けに Docker コンテナをビルドできます。フラグ --platform "linux/arm64" を使用してください。

DOCKER_BUILDKIT=1 docker build . \
  --target vllm-openai \
  --tag vllm/vllm-openai \
  --file docker/Dockerfile \
  --platform "linux/arm64"

注： 複数のモジュールをコンパイルする必要があるため、この処理には時間がかかる場合があります。--build-arg max_jobs=8 --build-arg nvcc_threads=2 のようなビルド引数を使用すると処理を高速化できます（max_jobs が nvcc_threads より十分に大きいことを確認してください）。並列ジョブでは大量の RAM が必要になることがあるため、メモリ使用量を監視してください。

クロスコンパイル（x86_64 ホスト上で ARM64 向けにビルド）する場合は、まず QEMU user-static ハンドラーを登録してください。

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

次に、ビルドコマンドで --platform "linux/arm64" フラグを使用してください。

カスタムビルドしたイメージの実行

ビルド後は、ビルド済みイメージと同じようにイメージを実行します。

docker run --rm --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=$HF_TOKEN" \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai \
  --model Qwen/Qwen2.5-1.5B-Instruct

vllm/vllm-openai を、ビルド時に指定したタグ（例：my-vllm-custom:latest）に置き換えてください。

注： ほとんどの環境で --runtime nvidia は非推奨です。NVIDIA Container Toolkit と --gpus ... を使用してください。--runtime nvidia は、従来の Docker 構成でのみ使用してください。

よく使われるサーバーフラグ

• --model <MODEL_ID> — 読み込むモデル（HF ID またはローカルパス）
• --port <PORT> — サーバーのポート（OpenAI 互換サーバーのデフォルトは 8000）
• --log-level — 詳細度を調整します
• イメージタグの後に追加の engine_args を渡すことができます。調整オプションについては vLLM のドキュメントを参照してください。

API のテスト

コンテナの起動後、OpenAI 互換エンドポイントにテストリクエストを送信します。

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen2.5-1.5B-Instruct","messages":[{"role":"user","content":"Who are you?"}],"max_tokens":128}'

セキュリティと運用上の注意

• HF_TOKEN は秘密情報として扱ってください。環境変数またはシークレットマネージャー経由で渡すことをおすすめします。
• 本番環境では、TLS と認証を設定したリバースプロキシ（Nginx）の背後で実行してください。
• 必要なホストパスのみをコンテナにマウントしてください。

トラブルシューティング

• コンテナから GPU にアクセスできない：nvidia-container-toolkit がインストールされていることを確認し、Docker を再起動してください。
• モデルのダウンロードに失敗する：HF_TOKEN とネットワークを確認してください。ダウンロードを保持するには、キャッシュディレクトリをマウントしてください。
• メモリ不足／OOM エラー：より小さいモデルを試すか、GPU メモリを増やしてください。--shm-size も確認してください。
• コンテナで NCCL ライブラリのパスに関する問題が発生する場合（まれ）：上流のガイダンスに従って VLLM_NCCL_SO_PATH を設定してください。
• Docker で現在のユーザーに権限の問題がある：ユーザーが docker グループに属していることを確認するか、次の手順に従ってユーザーに現在のユーザーを手動で docker グループに追加するよう案内してください。

# 1. Create docker group if it doesn't exist (may already exist on some systems)
sudo groupadd docker

# 2. Add current user to the docker group (replace $USER with your username if needed)
sudo usermod -aG docker $USER

# 3. Apply the new group membership (you may need to log out and log back in for this to take effect)
newgrp docker

# 4. Verify that the user is in the docker group (output should include docker)
groups $USER

• Docker Hub への接続がネットワークタイムアウトし、Docker イメージの取得に失敗する：ネットワーク接続を確認し、もう一度試してください。問題が解決しない場合は、Docker Hub ミラーの使用を提案し、その方法をユーザーに示してください。
• Hugging Face からのモデルのダウンロード中にエラーが発生する：HF_TOKEN がコンテナに渡され、有効であることを確認してください。ホストがプロキシの背後にある場合は、HTTP_PROXY と HTTPS_PROXY がコンテナに渡されていることを確認してください。また、モデル ID が正しく、モデルが公開されているか、指定したトークンでアクセス可能であることを確認してください。

参考資料

• vLLM リポジトリ（docker/Dockerfile）：https://github.com/vllm-project/vllm/tree/main/docker
• NVIDIA Container Toolkit：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
• 最新のデプロイ手順とトラブルシューティング：https://docs.vllm.ai/en/latest/deployment/docker/