vLLM をデプロイ production

#vLLMでできることと必要な条件

vLLMは、カリフォルニア大学バークレー校のSky Computing Labで生まれたオープンソースの推論エンジンです。中心となる仕組みのPagedAttentionは、OSの仮想メモリのように、アテンションのキー・バリューキャッシュをページ単位で管理します。2023年のプロジェクトの初期発表によると、既存のシステムはメモリの大きな割合を無駄にしており、vLLMは当時のテストでHugging Face Transformersの最大24倍、TGIの最大3.5倍のスループットを達成しました。これらは古い数値で、そのベンチマーク環境に限られた結果です。方向性を示すものであり、お使いのモデルやGPUで得られる性能を示すものではありません。

動作要件として、現在のドキュメントではLinuxとPython 3.10〜3.13が必要とされています。Macでは、MLXを利用するvLLM-Metalという別の方法があります。サーバーはOpenAI互換のAPIを公開し、デフォルトではポート8000で待ち受けます。一度に提供できるモデルは1つだけなので、複数のモデルを提供するには複数のインスタンスが必要です。

#OllamaではなくvLLMを選ぶべき場面

違いは、リクエストを並列に処理できるかどうかではなく、メモリの共有方法にあります。並列処理はOllamaでも可能です。OllamaのFAQによると、モデルの並列処理では、コンテキストサイズがリクエスト数倍になります。たとえば、2,000トークンのコンテキストで4件のリクエストを並列処理する場合、メモリ上では8,000トークン分のコンテキストが事前に確保されます。vLLMは必要に応じてキャッシュをブロック単位で割り当て、処理中のリクエストをまとめて同じ計算で処理します。

実用上の目安として、モデルを同時に使う人数が3人未満の場合や、頻繁にモデルを切り替えたい場合は、Ollama で十分です。それ以上の人数で使う場合や、単一のモデルを継続的に提供する場合は、vLLM の複雑さに見合うメリットが得られます。比較ガイドで選び方を詳しく解説しています。

#vLLMが適切な選択でない場合

8〜12 GBのGPUを一人で使う場合、vLLMには利点がありません。共有キャッシュに必要なメモリが足りず、Ollamaやllama.cppのほうが簡単に起動できます。一日のうちに5つのモデルを切り替えて使う場合にも不向きです。モデルごとにインスタンスを起動し直す必要があるためです。Macでは別の方法を取り、MLXを使います。最後に、高負荷のAPIよりもチーム向けのチャット画面が必要な場合は、OllamaとOpen WebUIを組み合わせた構成のほうが適しており、運用の手間も少なくなります。

• 本番環境で使うならOllamaかvLLMか：比較
• vLLMとは：どんな人に向いているか、いつ使うべきか

#必要なメモリ容量を見積もる：何よりも先に行う計算

vLLM サーバーの容量設計を左右するのは、モデルの重みではなく KV キャッシュです。モデルを読み込んだ後、vLLM は GPU メモリの一定割合を確保します。現在の設定コードによると、デフォルトは 92％です。その確保した領域のうち、モデルの読み込み後に残る容量をすべてキャッシュに充てます。この残りの容量によって、同時に保持できる会話トークン数、つまり同時に対応できるユーザー数が決まります。

Qwen2.5-7B-Instruct を例にとると、その仕様には 76.1億のパラメータ、28 層、4 つのキーバリューヘッド（Grouped-Query Attention）と記載されています。16 ビットでの重みは約 15.2 GB です。1 トークンのキャッシュは 2（キーとバリュー）× 28 層 × 4 ヘッド × 128 次元 × 2 バイトで、57 344 バイト、約 56 KiB になります。

これらの上限値は高めです。計算用バッファとCUDAグラフが残りのメモリの一部を消費し、モデルによってメモリ使用の特性が異なる場合もあります。この方法はどのモデルにも使えます。モデルの仕様に記載されたレイヤー数とキーバリューヘッド数を確認し、トークンあたりのメモリ使用量を計算して、残りのメモリ容量をその値で割ってください。ログにプリエンプションが記録されている場合、ドキュメントではgpu_memory_utilizationを増やすか、max_num_seqsを減らすことを推奨しています。

グラフィックカードを交換せずにキャッシュを拡大する方法は2つあります。量子化したモデルを読み込んで重みが占めるメモリの一部を空けるか、--max-model-len を制限して、誰も使わない長さのコンテキスト用にメモリが確保されるのを防ぐ方法です。前者は品質が少し低下する可能性があります。後者は、リクエストが短い限り、デメリットはありません。

#1. インストール

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

ドキュメントではuvが推奨されています。uvはCUDAドライバーに応じて適切なPyTorchのバージョンを自動的に選択します。AMD GPUの場合は専用のインデックスからインストールします。Intel、TPU、Ascend向けにはプラグインがあります。本番環境では、Dockerイメージを使うことでCUDAのバージョン競合を避けられ、タグを変更するだけで更新できます。

#2. サーバーを起動

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --api-key "$VLLM_API_KEY"

vllm serve コマンドは、以前の python -m vllm.entrypoints.openai.api_server による起動方法に代わるものです。現在のドキュメントでは、以前の起動方法は使われていません。初回起動時には、モデルの重みが Hugging Face からダウンロードされます。ディスク容量を確保してください（16ビットの7Bモデルで約15GB）。サーバーはデフォルトでモデルリポジトリの generation_config.json を適用するため、モデルの提供元が推奨するサンプリングパラメータが使われます。--generation-config vllm を指定すると、vLLM のデフォルト値に戻ります。

curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

#3. Docker および systemd

公式イメージvllm/vllm-openaiを使うのが最も安全な方法です。重みを再ダウンロードしないようにHugging Faceのキャッシュをマウントし、コンパイルキャッシュ用のボリュームもマウントしてください。そうしないと、新しいコンテナは毎回空のキャッシュで起動し、そのモデルの生成物を再コンパイルします。なお、このイメージはデフォルトでrootとして実行されます。ドキュメントには、非特権ユーザーで実行する方法（--user 2000:0）が記載されています。

docker run --rm --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v vllm-cache:/root/.cache/vllm \
  -p 8000:8000 \
  --ipc=host \
  -e VLLM_API_KEY=$VLLM_API_KEY \
  vllm/vllm-openai:latest \
  Qwen/Qwen2.5-7B-Instruct

[Unit]
Description=vLLM OpenAI API
After=network.target

[Service]
Type=simple
User=vllm
EnvironmentFile=/etc/vllm/env
ExecStart=/opt/vllm/bin/vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

#4. 重要な設定

ドキュメンテーションの原則として、モデルが 1 つの GPU に収まる場合、分散処理はおそらく不要です。収まらないが 1 つのノードに収まる場合は、--tensor-parallel-size を使用してテンソル並列処理を行います。すでに量子化されたモデルは、特別なオプションなしで Hub から直接読み込むことができます。--quantization オプションは、動的量子化のみに使用されます。

• KVキャッシュの量子化：VRAMを節約
• Flash Attention : llama.cpp および Ollama、vLLM で有効にする

#5. スループットを正しく測定する

vllm bench serve コマンドはサーバーにリクエストを送り、スループット、最初のトークンが出るまでの時間（TTFT）、トークン間のレイテンシを報告します。ドキュメントでは、これらのベンチマークは主に機能の評価とリグレッションの検出に使うものと説明されており、本番環境のサーバーのテストにはGuideLLMを推奨しています。

vllm bench serve \
  --backend vllm \
  --model Qwen/Qwen2.5-7B-Instruct \
  --endpoint /v1/completions \
  --dataset-name sharegpt \
  --dataset-path CHEMIN/ShareGPT_V3_unfiltered_cleaned_split.json \
  --num-prompts 200

#稼働開始と運用

サイズ設定が完了すると、導入は常に同じ手順に従います。これは、20人程度のチームが24 GBまたは48 GBのカード上で70億から80億パラメータの同じモデルを照会する場合に適用されます。

1. 01
   モデルとフォーマットを選択

   1インスタンスにつきモデルは一つです。利用可能なメモリに応じて、量子化済みのモデル、または16ビットのモデルを提供するリポジトリを優先してください。
2. 02
   キャッシュを計算する

   サイジングのセクションにあるトークンあたりの計算を使って、--max-model-lenと--max-num-seqsを設定してください。
3. 03
   Dockerで起動する

   アップデートで動作が変わるのを避けるため、Hugging Faceのキャッシュをマウントし、latestではなく固定したバージョンタグを指定して、公式イメージを使ってください。
4. 04
   プロキシを追加

   ルートの許可リスト、TLS、レート制限を備えたリバースプロキシを配置し、さらに補助的な対策としてAPIキーを追加します。
5. 05
   測定する

   vllm bench serveでシードを変えながら負荷テストを実行し、TTFTと総スループットを記録してください。
6. 06
   監視する

   監視ツールで /metrics エンドポイントからメトリクスを収集するよう設定してください。

監視すべきなのは、キャッシュ不足の兆候です。ログに記録されるプリエンプション、TTFTの上昇、長くなる待ち行列が該当します。ドキュメントによると、プリエンプションはデフォルトでは再計算モードで動作し、サービスを保護する一方で、エンドツーエンドのレイテンシを悪化させます。頻繁に発生する場合は、gpu_memory_utilizationを上げるか、コンテキストを短くするか、同時リクエスト数を制限してください。最後の手段として、GPUを追加し、テンソル並列化でモデルを分散してください。

#6. セキュリティと公開：--api-key だけでは不十分です

よく見かける説明とは異なり、vLLMは--api-keyまたは環境変数VLLM_API_KEYを使ってAPIキーを検証できます。ただし、セキュリティドキュメントは、キーで保護されるのは/v1、/v2、/inference、/cohere配下のルートだけだと強調しています。それ以外のルートは認証なしのままで、/v1配下ではない推論ルート、/pauseや/abort_requestsなどの制御ルート、/healthも含まれます。したがって、--api-keyだけに頼ることは決して避けてください。

リバースプロキシ

vLLMの前段にnginx、Envoy、またはKubernetesゲートウェイを配置し、公開するルートだけを許可リストに登録して、それ以外のルートはすべてブロックしてください。

ネットワーク

VPNまたは隔離ネットワーク：分散デプロイメント内のノード間の通信はデフォルトで安全に保護されていません

開発モード

本番環境では VLLM_SERVER_DEV_MODE=1 を絶対に有効にしないでください。危険なルートが公開されます。

制限

ドキュメントの推奨どおり、プロキシ側でレート制限とリクエストの検証を適用してください。

ログ

デバッグや監査のために、誰が何を送信したかを記録してください。

• ローカルAIサーバーのセキュリティ：認証、リバースプロキシ、公開

• 出典：vLLMのクイックスタートガイド
• 出典：vLLMのセキュリティ
• ソース：Docker での vLLM
• 出典：vLLMとPagedAttentionの発表