vLLM完全ガイド【2026年5月最新版】インストールから本番運用・高速化まで徹底解説

vLLM完全ガイド【2026年5月最新版】 チュートリアル

vLLMは、1台のGPUで数十人規模の同時リクエストを高速にさばける、ローカルLLM推論サーバーの決定版です。本記事を読む2026年5月時点での最新安定版はv0.21.0（2026年5月15日リリース）で、開発版としてv0.22.0系がリリース候補（RC）段階にあります。「llama.cppやOllamaは触ったが、本番APIとして複数ユーザーに配信したい」「PagedAttentionや連続バッチングで何が速くなるのか正しく理解したい」という方に向けて、インストールから本番運用、トラブルシューティングまでをこの1記事で完結できるように徹底解説します。

vLLMはGPU前提・Linux前提の硬派なツールですが、その分スループット（単位時間あたりの処理トークン数）は群を抜いています。本記事では2026年5月時点の公式ドキュメントとGitHubリリースノートを実際に確認し、コピペで動くコマンドと具体的なパラメータ値だけを掲載しています。バージョン番号や対応ハードウェアはすべて執筆時点の最新情報に基づいています。

vLLM 公式ロゴ（Easy, fast, and cheap LLM serving）
vLLM公式ロゴ。「Easy, fast, and cheap LLM serving」を掲げる高速推論エンジン（出典: 公式GitHubリポジトリ / Apache-2.0ライセンス）
  1. vLLMとは何か
    1. vLLMが解決する問題
    2. 主な特徴
  2. 最新リリース情報（2026年5月最新）
    1. 注目すべき破壊的変更
  3. 他ツールとの比較
  4. メリット・デメリット
    1. メリット
    2. デメリット
  5. 動作要件
    1. 対応ハードウェアの全体像
  6. インストール手順
    1. Linux（NVIDIA GPU・推奨）
    2. Linux（CPUのみ）
    3. Docker（最も手軽な本番デプロイ）
    4. Windows（WSL2経由が前提）
    5. ソースからのビルド
  7. 初期設定
  8. 基本的な使い方
    1. OpenAI互換サーバーの起動
    2. OpenAI Python SDKから利用する
  9. 実践的な使い方
    1. ユースケース1: 複数GPUで大型モデルを配信する
    2. ユースケース2: 量子化モデルで省VRAM配信する
  10. 応用・カスタマイズ
    1. 構造化出力（JSON Schema）
    2. 投機的デコード（Speculative Decoding）
    3. プレフィックスキャッシュ（Automatic Prefix Caching）
  11. パフォーマンス最適化
    1. 量子化方式の選び方
  12. よくあるエラーとトラブルシューティング
    1. 1. 起動時のCUDA Out of Memory（OOM）
    2. 2. 「No available memory for the cache blocks」
    3. 3. インストール時のtorch/CUDAバージョン不整合・ModuleNotFoundError
    4. 4. 複数GPUでNCCLハング・タイムアウト
    5. 5. 量子化（AWQ/GPTQ/FP8）の読み込みエラー
    6. 6. max_model_lenがモデルのコンテキスト長を超過
    7. 7. Windowsでネイティブ動作しない
    8. 8. FlashAttentionバックエンドのエラー
  13. おすすめの組み合わせ・連携
  14. 推奨PCスペック
  15. まとめ
  16. 📦 この記事で紹介した商品

vLLMとは何か

vLLMは、vllm-project/vllmとして公開されているオープンソースの大規模言語モデル（LLM）推論・配信エンジンです。もともとはカリフォルニア大学バークレー校のSky Computing Labで生まれた研究プロジェクトで、2023年に公開されると同時に「PagedAttention」という独自のメモリ管理機構によって、当時の他エンジンを大きく上回るスループットを叩き出して一躍注目を集めました。現在はコミュニティ主導のオープンガバナンスで運営され、世界中の数百人規模のコントリビューターによって週単位で活発に開発が続いています。

ライセンスはApache License 2.0で、商用利用・改変・再配布が自由に行えます。提供形態はPythonライブラリ（オフラインのバッチ推論用）と、OpenAI互換のHTTP APIサーバー（オンライン配信用）の2つが中心です。後者により、OpenAIのSDKやChatGPT向けに書かれた既存のコードを、エンドポイントのURLを差し替えるだけでローカルLLMに切り替えられます。

vLLMが解決する問題

HuggingFace Transformersの素朴なmodel.generate()や、単一ユーザー向けのllama.cppでLLMをWebサービスに組み込もうとすると、同時アクセスが増えた瞬間にレスポンスが破綻します。これは、リクエストごとに最大コンテキスト長ぶんのKVキャッシュ（Key-Valueキャッシュ）をあらかじめVRAMに予約してしまい、メモリの断片化と過剰確保でGPUが遊んでしまうためです。vLLMはこの構造的な無駄をPagedAttentionと連続バッチングで解消し、同じGPUで何倍ものリクエストを同時にさばけるようにします。

主な特徴

  • PagedAttention: KVキャッシュをOSの仮想メモリのように固定サイズのブロックで動的管理し、メモリ断片化をほぼゼロにする
  • 連続バッチング（Continuous Batching）: デコードの1ステップごとにバッチへリクエストを出し入れし、GPUを遊ばせない
  • OpenAI互換APIサーバー: /v1/chat/completionsや/v1/completionsをそのまま提供
  • 200以上のモデルアーキテクチャに対応: Llama、Qwen3、DeepSeek-V3/V4、Gemma 3、Mistral、Mixtral、マルチモーダル（Vision/Audio）まで網羅
  • 豊富な量子化対応: FP8、AWQ、GPTQ、bitsandbytes、GGUF、INT8/INT4
  • テンソル並列・パイプライン並列: 1枚に載らない巨大モデルを複数GPU・複数ノードに分割
  • 投機的デコード・プレフィックスキャッシュ・構造化出力（JSON Schema）などの本番運用機能を標準搭載

最新リリース情報（2026年5月最新）

vLLMは月に複数回のペースでリリースされており、2026年5月29日時点での最新安定版はv0.21.0（2026年5月15日）です。同日付けでv0.22.0が公開されていますが、これはリリース候補（rc）扱いのプレリリースであり、本番環境では原則v0.21.0を使うことを推奨します。直近6ヶ月の主要なアップデートを時系列で整理します。

バージョンリリース日主な変更点
v0.16.02026-02-25非同期スケジューリング＋パイプライン並列の完全対応でE2Eスループット+30.8%／TPOT+31.8%。ストリーミング音声向けのリアルタイムAPI（WebSocket）追加
v0.17.02026-03-07PyTorch 2.10必須化（破壊的変更）。FlashAttention 4統合。Qwen3.5ファミリー対応。--performance-mode追加。KVロード失敗時の既定動作が「recompute」から「fail」に変更
v0.18.02026-03-20gRPC配信（--grpc）追加。Rayが既定依存から外れる（破壊的変更）。RISC-V CPUバックエンド対応
v0.19.02026-04-03Google Gemma 4フル対応（transformers>=5.5が必要）。NVIDIA B300/GB300対応。/v1/chat/completions/batchエンドポイント追加
v0.20.02026-04-27DeepSeek V4初期対応。PyTorch 2.11／CUDA 13.0が既定ホイールに。transformers>=5がベースライン。Python 3.14対応（破壊的変更多数）。FlashAttention 4が既定MLAプリフィルに。TurboQuant 2-bit KVキャッシュ
v0.21.02026-05-15最新安定版。C++20コンパイラ必須化。transformers v4が非推奨に。BlackwellでTOKENSPEED_MLAバックエンド追加。投機的デコードがthinking/reasoningのトークン予算を尊重するように
v0.22.0（RC）2026-05-29DeepSeek V4の成熟。Qwen3密モデルでModel Runner V2が既定に。実験的なRustフロントエンド。※リリース候補のため本番非推奨

注目すべき破壊的変更

過去半年で依存関係が大きく動いています。古いバージョンからアップグレードする場合は、以下に特に注意してください。

  • PyTorch 2.11／CUDA 13.0が既定（v0.20.0〜）: CUDA 12.9環境のままにしたい場合は、インストール時に--torch-backend=cu129を明示する必要がある
  • transformers v5がベースライン（v0.20.0〜）、v4は非推奨（v0.21.0〜）: 古いtransformersに依存したスクリプトは更新が必要
  • Rayが既定依存から外れた（v0.18.0〜）: 複数ノードでRayを使う構成では明示的にpip install rayが必要
  • C++20コンパイラ必須（v0.21.0〜）: ソースからビルドする場合はGCC 10以降など、C++20対応コンパイラが必須

最新の変更点は必ず公式リリースページで確認してください。

他ツールとの比較

ローカルLLM推論エンジンは選択肢が増えました。vLLMの立ち位置を正しく理解するために、主要な競合と比較します。バージョンはすべて2026年5月時点の最新を記載しています。

項目vLLMllama.cppOllamaHugging Face TGISGLang
最新版（2026年5月時点）v0.21.0b9404（ローリング）v0.24.0v3.3.7（開発凍結）v0.5.12.post1
主目的高スループット配信軽量・どこでも動く手軽なローカル実行本番配信（HF製）高スループット＋構造化
実装言語Python＋CUDAC/C++Go＋llama.cppRust＋PythonPython＋CUDA
CPUのみ動作限定的（実験的）得意可能非推奨非推奨
同時多人数の性能非常に高い中程度中程度高い非常に高い
OpenAI互換API標準搭載llama-serverで対応対応対応対応
セットアップ難易度中低〜中非常に低い中中
導入の手軽さpip/Dockerビルド/バイナリワンコマンドDocker中心pip/Docker

重要な注意点として、Hugging Face Text Generation Inference（TGI）はv3.3.7（2025年12月19日）を最後にリポジトリがアーカイブ（メンテナンスモード）化されており、新規採用は推奨しません。一方SGLangはvLLMの最有力ライバルとして急速に成熟しており、構造化出力や大規模MoEモデルの配信に強みがあります。手軽さ重視なら当ブログのOllama完全ガイド、CPU・エッジ・GGUF重視ならllama.cpp完全ガイドも併せて参照してください。

メリット・デメリット

導入を判断するために、vLLMの長所と短所を正直に整理します。

メリット

  • 同時多人数での圧倒的なスループット。1枚のGPUで数十人規模のリクエストを高い総トークン/秒でさばける
  • PagedAttentionにより同じVRAMでより多くの同時シーケンスを処理できる（メモリ効率が高い）
  • OpenAI互換APIで既存資産をそのまま流用できる
  • 200超のモデルと幅広い量子化方式に対応し、最新モデルへの追従が非常に速い
  • テンソル並列・パイプライン並列で巨大モデルを複数GPU・複数ノードにスケールできる
  • 投機的デコード、プレフィックスキャッシュ、構造化出力など本番機能が標準搭載

デメリット

  • 実質的にGPU必須。CPUのみの動作は実験的で、llama.cppのような快適さはない
  • 公式対応OSはLinuxのみ。Windowsは後述のWSL2経由が前提
  • 設定パラメータが多く、最適化には学習コストがかかる
  • VRAMをあらかじめ大きく確保するため、単一ユーザーの軽い用途ではOllama等の方が手軽
  • 依存関係（PyTorch・CUDA・transformers）の更新が速く、バージョン整合に注意が必要

結論として、「単一ユーザーのローカル利用ならOllama／llama.cpp、複数ユーザーへの本番配信ならvLLM」という使い分けが最も実態に即しています。バッチサイズ1（1人が短いプロンプトを投げる）状況では、3者とも同じ行列演算カーネルに到達するため性能差は10〜15%程度に収まります。差が爆発的に開くのは同時接続が増えたときです。

動作要件

vLLMはGPUとLinuxを前提とします。NVIDIA GPUの場合、コンピュート能力（Compute Capability）7.5以上が必要です（Turing世代のRTX 20シリーズ以降が該当）。OS別・用途別の要件を整理します。

項目最小推奨
OSUbuntu 22.04（またはWSL2上のUbuntu）Ubuntu 24.04
Python3.103.12（対応は3.10〜3.13）
GPUNVIDIA RTX 2080（CC 7.5, 8GB）NVIDIA RTX 5090（32GB）／H100
VRAM8GB（小型モデル＋低コンテキスト）24GB以上
システムRAM16GB64GB以上
ストレージNVMe SSD 50GB空きNVMe SSD 1TB以上
CUDA12.813.0（ホイールは12.8/12.9/13.0に対応）

対応ハードウェアの全体像

プラットフォーム対応状況・備考
NVIDIA CUDAコンピュート能力7.5以上。CUDA 12.8/12.9/13.0向けホイールあり。Blackwell（B200/GB200）はCUDA 12.8以上が必要
AMD ROCm対応。ROCm 7.x系の専用ホイールあり（glibc 2.35以上）
Intel XPU（GPU）対応（v0.16.0でIPEXからvllm-xpu-kernelsへ刷新）
CPU（x86）AVX-512推奨／AVX2は限定対応。FP32/FP16/BF16
CPU（ARM AArch64）NEON必須。FP32/FP16/BF16
Apple Silicon実験的（要ソースビルド、FP32/FP16のみ）
その他プラグインGoogle TPU、Intel Gaudi、IBM Spyre、Huawei Ascend、RISC-Vなど

インストール手順

インストールは仮想環境（venvやconda）を新規に作成し、その中で行うことを強く推奨します。既存のPyTorchと混在させると、後述するCUDAバージョン不整合の温床になります。公式は高速なパッケージマネージャuvの利用を推奨しています。

Linux（NVIDIA GPU・推奨）

最も簡単で確実な方法です。--torch-backend=autoを付けると、uvがドライバを見て適切なPyTorch/CUDAビルドを自動選択します。

# uvのインストール（未導入の場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 仮想環境を作成して有効化
uv venv vllm-env --python 3.12
source vllm-env/bin/activate

# vLLM本体をインストール（PyTorch/CUDAは自動選択）
uv pip install vllm --torch-backend=auto

uvを使わず、標準のpipでインストールする場合は次の通りです。

python -m venv vllm-env
source vllm-env/bin/activate

# 既定（CUDAビルド）をインストール
pip install vllm

# CUDA 12.9環境を明示したい場合
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu129

Linux（CPUのみ）

GPUがない環境向けのCPUホイールも提供されています。性能は限定的ですが、動作確認やテストには使えます。

export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
uv pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cpu-cp38-abi3-manylinux_2_35_x86_64.whl --torch-backend cpu

Docker（最も手軽な本番デプロイ）

公式のOpenAI互換サーバーイメージvllm/vllm-openaiを使えば、Python環境を一切汚さずにサーバーを起動できます。--ipc=hostは共有メモリ確保のために重要です。

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model Qwen/Qwen3-0.6B

バージョンを固定したい場合はvllm/vllm-openai:v0.21.0のようにタグを指定します。

Windows（WSL2経由が前提）

vLLMの公式サポートはLinuxのみで、ネイティブWindowsでは動作しません。WindowsユーザーはWSL2（Windows Subsystem for Linux 2）上のUbuntuで動かすのが正攻法です。

# PowerShell（管理者）でWSL2とUbuntuを導入
wsl --install -d Ubuntu-24.04

# 再起動後、WSL内のUbuntuを起動
wsl

その後はWSL内のUbuntuで、上記「Linux（NVIDIA GPU）」の手順をそのまま実行します。Windows側に最新のNVIDIAドライバ（CUDA on WSL対応）が入っていれば、WSL内からGPUが見えます。なお非公式のネイティブWindowsビルド（コミュニティ製のプリビルドホイール等）も登場していますが、安定運用にはWSL2を推奨します。

ソースからのビルド

最新の開発版や独自パッチが必要な場合のみ使います。事前コンパイル済みカーネルを流用するPythonのみビルドが高速です。

git clone https://github.com/vllm-project/vllm.git
cd vllm
# 事前コンパイル済みカーネルを使う高速ビルド（C++/CUDAコンパイル不要）
VLLM_USE_PRECOMPILED=1 uv pip install --editable . --torch-backend=auto

初期設定

インストール後、まずは正しく動くかをオフライン推論で確認します。次のPythonスクリプトをtest.pyとして保存し実行してください。初回はモデルがHugging Faceから自動ダウンロードされます。

from vllm import LLM, SamplingParams

prompts = [
    "日本の首都は",
    "ローカルLLMの利点を一言で言うと",
]
sampling_params = SamplingParams(temperature=0.7, top_p=0.9, max_tokens=128)

# 小型モデルで動作確認
llm = LLM(model="Qwen/Qwen3-0.6B")
outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    print(f"プロンプト: {output.prompt}")
    print(f"生成結果: {output.outputs[0].text}\n")
python test.py

Hugging Faceの認証が必要なモデル（Llama系など）を使う場合は、事前にトークンを環境変数に設定します。

export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
# モデルキャッシュの保存先を変えたい場合
export HF_HOME=/data/hf_cache

基本的な使い方

vLLMの真価はOpenAI互換APIサーバーにあります。ここからが本番です。

OpenAI互換サーバーの起動

vllm serveコマンド一発で、http://localhost:8000にOpenAI互換のエンドポイントが立ち上がります。

vllm serve Qwen/Qwen2.5-1.5B-Instruct

起動後、別のターミナルからcurlで叩いて確認します。

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen2.5-1.5B-Instruct",
        "messages": [
            {"role": "user", "content": "vLLMの特徴を3つ挙げて"}
        ],
        "max_tokens": 256,
        "temperature": 0.7
    }'

OpenAI Python SDKから利用する

APIキーにはダミー文字列（EMPTY）を渡し、base_urlをローカルサーバーに向けるだけです。ChatGPT向けに書いた既存コードがそのまま動きます。

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1",
)

response = client.chat.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[
        {"role": "system", "content": "あなたは親切な日本語アシスタントです。"},
        {"role": "user", "content": "PagedAttentionを初心者向けに説明して"},
    ],
    max_tokens=512,
)
print(response.choices[0].message.content)

実践的な使い方

ここでは、現場で頻出する2つのユースケースを手順付きで解説します。

ユースケース1: 複数GPUで大型モデルを配信する

70B級のモデルは1枚のGPUに載りません。--tensor-parallel-size（略記-tp）でモデルを複数GPUに分割します。下記は4枚のGPUに分割する例です。

vllm serve Qwen/Qwen2.5-72B-Instruct \
    --tensor-parallel-size 4 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.92

GPUが同一ノードにある場合はテンソル並列、複数ノードにまたがる場合はパイプライン並列（--pipeline-parallel-size、略記-pp）を組み合わせます。例えば4GPU×2ノードの計8枚なら-tp 4 -pp 2とします。

ユースケース2: 量子化モデルで省VRAM配信する

VRAMが限られる環境では量子化が必須です。AWQ量子化済みのモデルを読み込む例です。vLLMはチェックポイントの形式を自動検出しますが、明示することもできます。

vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ \
    --quantization awq \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.85

事前量子化済みチェックポイントがない場合でも、Hopper/Ada世代以降のGPUならFP8オンライン量子化で起動時に重みを8bit化できます。

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --quantization fp8 \
    --kv-cache-dtype fp8

応用・カスタマイズ

vLLMには本番運用で効く高度な機能が揃っています。最新版で標準搭載された機能を中心に紹介します。

構造化出力（JSON Schema）

出力を必ず特定のJSON構造に従わせる機能です。RAGやエージェントで構造化データを安定取得したい場面で必須です。OpenAI互換APIのresponse_formatで指定します。

from openai import OpenAI

client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")

response = client.chat.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[{"role": "user", "content": "東京の天気を構造化して"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "weather",
            "schema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "temperature": {"type": "number"},
                    "condition": {"type": "string"},
                },
                "required": ["city", "temperature", "condition"],
            },
        },
    },
)
print(response.choices[0].message.content)

バックエンドには高速なxgrammarが既定で選ばれます。構造化出力を使う場合でも、プロンプト側でスキーマの説明を添えると各フィールドの埋まり精度が上がります。

投機的デコード（Speculative Decoding）

小さなドラフトモデルが先に数トークンを「予測」し、本体モデルが1回の順伝播でまとめて検証する技術です。出力は通常デコードと等価のまま、低〜中負荷時に1.3〜2倍の高速化が見込めます。追加モデルが不要なN-gram方式は手軽です。

# N-gram投機的デコード（追加モデル不要、入力に繰り返しが多いタスクに有効）
vllm serve Qwen/Qwen2.5-7B-Instruct \
    --speculative-config '{"method":"ngram","num_speculative_tokens":4,"prompt_lookup_min":2,"prompt_lookup_max":5}'

投機的デコードは高負荷・高同時接続時にはGPUが既に飽和しているため効果が薄くなります。チャットやエージェントなど低同時接続でレイテンシを詰めたい場面で使うのが定石です。

プレフィックスキャッシュ（Automatic Prefix Caching）

共通の長いシステムプロンプトや、マルチターン会話の履歴など、繰り返し現れるプレフィックスのKVブロックを再利用してプリフィルを省略する機能です。最新版（V1エンジン）では既定で有効です。明示する場合は次の通りです。

vllm serve Qwen/Qwen2.5-7B-Instruct --enable-prefix-caching

パフォーマンス最適化

vLLMの性能は起動時のフラグで大きく変わります。主要なチューニングパラメータと推奨値を解説します。

フラグ既定値役割と推奨
--gpu-memory-utilization0.9GPUメモリの使用上限割合。専有GPUなら0.90〜0.95。他プロセス（ComfyUI等）と共有するなら0.80〜0.85に下げる
--max-model-lenモデル設定から自動1リクエストの最大トークン数。KVキャッシュ使用量に直結するため、必要最小限に明示設定するとVRAMを大きく節約できる
--max-num-seqs256（V1）同時処理する最大シーケンス数。多いほど高スループットだが、KVキャッシュ枯渇でプリエンプションが起きると遅延が悪化する
--max-num-batched-tokens自動1イテレーションで処理する最大トークン数。8192以上でスループット重視、2048程度でトークン間遅延重視
--kv-cache-dtypeautofp8でKVキャッシュ容量を約半減。Hopper/Ada/MI300世代で有効。長コンテキスト・多同時接続時に効く
--tensor-parallel-size1層内をN GPUに分割。モデルが1枚に載らない場合に使用。NVLink等の高速接続が前提
--enforce-eagerfalseCUDAグラフ捕捉を無効化。VRAM節約・断片化回避に有効だが、わずかに遅くなる

量子化方式の選び方

方式-qの値対応ハード推奨用途
FP8（W8A8）fp8Ada／Hopper／MI300モダンGPUでの最適バランス。H100でFP16比約2倍のスループット。オンライン量子化可
AWQawqTuring以降のNVIDIA／Intel GPU4bit重みのなかで最高の精度。小さなGPUに大型モデルを載せたいとき
GPTQgptqVolta以降（最も広い対応）4bitで互換性最優先。古いGPUでも動きやすい
bitsandbytesbitsandbytesVolta〜Hopperキャリブレーション不要で手軽。4bitのみ対応（8bit非対応）
GGUFggufNVIDIA／AMDllama.cpp由来のGGUFを読み込む互換用途

モダンなデータセンターGPUならFP8、メモリ制約の厳しいコンシューマGPUならAWQ（精度重視）かGPTQ（互換性重視）が定石です。重みの量子化と--kv-cache-dtype fp8を併用すれば、メモリ削減効果は最大化します。

よくあるエラーとトラブルシューティング

GitHubのバグ報告で実際に頻出する問題と、その具体的な対処法をまとめます。

1. 起動時のCUDA Out of Memory（OOM）

原因: 重み＋活性化＋KVキャッシュがVRAMを超過。既定で約90%のVRAMを確保し、長すぎる既定コンテキスト分のKVキャッシュを先取りするため無駄が出る。
対処: 使用率上限とコンテキスト長を下げる。それでもダメなら--enforce-eagerでCUDAグラフ捕捉を切る。重みがわずかに載らないだけなら--cpu-offload-gbでCPU RAMへ退避（スループットは落ちる）。

vllm serve  --gpu-memory-utilization 0.85 --max-model-len 2048 --enforce-eager

2. 「No available memory for the cache blocks」

原因: 重みを載せた後、KVキャッシュ用のVRAMが残っていない。gpu_memory_utilizationが低すぎるか、クラッシュした前プロセスがVRAMを掴んだままのことが多い。
対処: 上限を上げて余白を増やす（--gpu-memory-utilization 0.95）か、KVキャッシュを減らす（--max-model-len 4096）。CPUスワップを追加するのも有効（--swap-space 4）。nvidia-smiで残留プロセスを確認し、必要なら終了させる。

3. インストール時のtorch/CUDAバージョン不整合・ModuleNotFoundError

原因: プリビルドホイールが特定のCUDA/PyTorch向けにコンパイルされており、システムのtorchと食い違う（libcudart.so.13 not foundなど）。既存のtorchとvLLMの固定torchが混在すると起きやすい。
対処: 新規の仮想環境にインストールし、バックエンドを自動選択させる。事前に競合するtorchを入れないこと。

uv pip install vllm --torch-backend=auto

4. 複数GPUでNCCLハング・タイムアウト

原因: --tensor-parallel-size > 1時にNCCLが誤ったネットワークインターフェース（ループバック等）を選ぶ、Dockerの共有メモリ（既定64MB）不足、P2P初期化失敗など。
対処: 環境変数で正しいインターフェースを指定し、Dockerでは共有メモリを増やす。

export NCCL_SOCKET_IFNAME=eth0   # 実際の高速インターフェース名に変更
export NCCL_P2P_DISABLE=1        # P2P初期化でハングする場合
export NCCL_DEBUG=INFO           # 原因切り分け用
# Dockerなら共有メモリを拡大
# docker run --shm-size=16g --gpus all ...

5. 量子化（AWQ/GPTQ/FP8）の読み込みエラー

原因: ハードウェアが方式に非対応（FP8 W8A8はHopper/Ada必須、Turing/AmpereはW8A16のみ）、--quantizationとチェックポイント形式の不一致など。
対処: チェックポイントに合うフラグを渡す（--quantization awq等）。古いGPUでFP8 W8A8は使わず、AWQ/GPTQ INT4へ切り替える。量子化ローダーは回帰が入ることがあるため最新安定版を使う。

6. max_model_lenがモデルのコンテキスト長を超過

原因: モデルの学習済みコンテキストより長い--max-model-lenを要求した、またはプロンプト＋出力が設定値を超えた。
対処: --max-model-lenをモデルのネイティブコンテキスト以下に設定する。本当に延長したい場合はRoPEスケーリングを使う（旧--rope-scalingは廃止され、--hf-overridesを使用）。

vllm serve Qwen/Qwen3-0.6B \
  --hf-overrides '{"rope_parameters":{"rope_type":"yarn","factor":4.0,"original_max_position_embeddings":32768}}' \
  --max-model-len 131072

7. Windowsでネイティブ動作しない

原因: 公式vLLMはLinux専用で、Linux向けCUDAカーネルがWindowsにビルドされていない。
対処: WSL2（Ubuntu）＋CUDA on WSLドライバで動かす。あるいはDocker Desktopで--gpus allを使う。コミュニティ製の非公式ネイティブWindowsビルドもあるが、安定運用にはWSL2を推奨。

8. FlashAttentionバックエンドのエラー

原因: FlashAttentionが未インストール、またはGPUが古くFA2非対応（V100/Turing等）。
対処: 互換バックエンドを明示する。古いGPUではXFORMERSやTORCH_SDPAへフォールバックする。

export VLLM_ATTENTION_BACKEND=XFORMERS   # 古いGPUではTORCH_SDPAも可
vllm serve  --enforce-eager

おすすめの組み合わせ・連携

vLLMはあくまで推論エンジンです。実用システムは周辺ツールとの連携で完成します。

  • Open WebUI: vLLMのOpenAI互換エンドポイントをそのまま接続でき、ChatGPT風のWeb UIを自前ホストできる。社内向けチャットの定番構成
  • LangChain / LlamaIndex: base_urlをvLLMに向けるだけで、RAGやエージェントのバックエンドとして利用できる
  • Nginx / Caddy: 前段にリバースプロキシを置き、認証・TLS終端・レート制限を担わせる
  • Prometheus / Grafana: vLLMは/metricsエンドポイントを公開しており、スループットや遅延を監視できる
  • Hugging Face Hub: モデルの取得元。認証必須モデルはHF_TOKENを設定

開発・検証は手軽なOllamaで行い、本番配信をvLLMに切り替える、という二段構えも実践的です。同じOpenAI互換APIなので、クライアント側コードの変更はほぼ不要です。

推奨PCスペック

vLLMは複数ユーザー配信を前提とするため、GPUのVRAMが最重要です。用途別に3段階でまとめます。GPUにはRTX 5090（VRAM 32GB）など大容量VRAMモデルが有利で、CPUオフロードやスワップを活かすために64GB DDR5メモリ以上のシステムRAM、モデル保管用に2TB NVMe SSDが快適な目安です。

項目入門（7B級・少人数）標準（14〜32B級・社内配信）ハイエンド（70B級・本番）
GPURTX 4070 Ti SUPER（16GB）RTX 5090（32GB）H100（80GB）×複数 または RTX 5090×2〜4
VRAM合計16GB32GB80GB以上
システムRAM32GB DDR564GB DDR5128GB以上
ストレージ1TB NVMe SSD2TB NVMe SSD4TB NVMe SSD（RAID推奨）
電源850W1000W1600W以上（複数GPU）
想定モデルQwen3-8B（FP8/AWQ）Qwen2.5-32B（AWQ）Llama-3.1-70B、DeepSeek-V3

まとめ

vLLMは、ローカル環境でLLMを「複数ユーザーに、速く、安く」配信するための決定版エンジンです。2026年5月時点の最新安定版v0.21.0では、PagedAttentionと連続バッチングという土台の上に、FlashAttention 4、DeepSeek V4対応、TurboQuant 2-bit KVキャッシュ、Model Runner V2といった最新技術が積み上がり、対応モデルとハードウェアの幅も着実に広がっています。

単一ユーザーで手軽に試すならOllamaやllama.cppが向きますが、本番のAPIエンドポイント、RAGやエージェントのバックエンド、社内向けチャット基盤を構築するなら、vLLMが最有力の選択肢です。本記事のインストール手順とチューニングフラグをそのまま使えば、あなたのGPUでも今日から高スループットな推論サーバーを立ち上げられます。

今後はModel Runner V2の正式既定化、Rustフロントエンドによるさらなる高速化、最新モデルへの即時対応が見込まれます。最新の動向は必ず公式リリースページと公式ドキュメントで確認してください。

📦 この記事で紹介した商品

※ 上記リンクはAmazonアソシエイトリンクです。購入いただくと当サイトに紹介料が入ります。

タイトルとURLをコピーしました