vLLM クイックスタート：高パフォーマンスなLLMサービング - 2026年版

2026年のvLLMのインストール、サービング、およびチューニング

目次

vLLMは、UC BerkeleyのSky Computing Labが開発した、大規模言語モデル（LLM）向けの高スループットでメモリ効率の良い推論・サービングエンジンです。

そのPagedAttentionアルゴリズムはKVキャッシュをOSの仮想メモリページのように扱い、継続的バッチング（continuous batching）と組み合わせることで、vLLMを本番環境でのLLMサービングのデフォルトエンジンとするに至りました。 Ollama、Docker Model Runner、LocalAIやクラウドプロバイダーとの比較——コストとインフラのトレードオフを含む——を通じて、vLLMがどのように位置づけられるかを確認するには、LLMホスティング：ローカル、セルフホスト、クラウドインフラの比較を参照してください。

vllm ロゴ

本ガイドは、vLLM v0.31.0（2026年10月）時点のものです。旧チュートリアルから来られた方にとって、最近2つの点が変更されています。1つは、python -m vllm.entrypoints.openai.api_server が非推奨となり警告が表示されるようになった点です（現在の標準CLIは vllm serve です）。もう1つは、ビルド済みホイールがデフォルトでCUDA 12.9をターゲットにしている点です（11.8ではありません）。

vLLMとは？

vLLM（virtual LLM）は、高速なLLM推論とサービングのためのオープンソースライブラリであり、急速に本番環境デプロイメントの業界標準となっています。2023年にリリースされ、サービング効率を劇的に向上させる画期的なメモリ管理技術であるPagedAttentionを導入しました。

主な機能

高スループットパフォーマンス: vLLMのリリース時点のベンチマークでは、同じハードウェア上でHuggingFace Transformersの14〜24倍のスループットが報告されました。このエンジンは、継続的バッチング、最適化されたCUDAカーネル、そしてメモリ断片化を排除するPagedAttentionアルゴリズムを通じて、そのリードを維持しています。

OpenAI API互換性: vLLMには、OpenAIのフォーマットと完全互換の組み込みAPIサーバーが含まれています。これにより、アプリケーションコードを変更せずに、OpenAIからセルフホスト環境へのシームレスな移行が可能です。単にAPIクライアントをvLLMのエンドポイントに向けるだけで、透明に動作します。

PagedAttentionアルゴリズム: vLLMのパフォーマンスの核となる革新はPagedAttentionであり、仮想メモリページングの概念をアテンションメカニズムに適用しています。KVキャッシュに連続的なメモリブロックを割り当てる（これにより断片化が発生する）代わりに、PagedAttentionはメモリを固定サイズのブロックに分割し、オンデマンドで割り当てを行います。これにより、メモリ無駄が最大4倍削減され、はるかに大きなバッチサイズを可能にします。

継続的バッチング: すべてのシーケンスが完了するまで待機する静的バッチングとは異なり、vLLMは継続的（ローリング）バッチングを使用しています。あるシーケンスが完了した時点で、新しいシーケンスがバッチに追加できます。これにより、GPUの利用効率を最大化し、受信リクエストのレイテンシを最小限に抑えます。

マルチGPUサポート: vLLMは、テンソル並列性とパイプライン並列性をサポートし、大規模モデルを複数GPUに分散配置できます。1つのGPUのメモリに収まらないモデルでも効率的にサービングでき、2枚から8枚以上のGPU構成をサポートしています。

幅広いモデル対応: LLaMA、Mistral、Mixtral、Qwen、Phi、Gemmaなど、人気のあるモデルアーキテクチャと互換性があります。HuggingFace Hubからの指示チューニング済みモデルおよびベースモデルの両方に対応しています。

vLLMを使う場面

vLLMは、その強みが活きる特定のシナリオで優れています。

本番環境APIサービス: APIを通じて多数の並行ユーザーにLLMをサービングする必要がある場合、vLLMの高スループットと効率的なバッチングにより最善の選択肢となります。チャットボット、コードアシスタント、コンテンツ生成サービスを実行している企業は、1秒あたりの数百のリクエストを処理できる利点を得られます。

高並行ワークロード: アプリケーションに同時にリクエストを行う多くのユーザーがいる場合、vLLMの継続的バッチングとPagedAttentionにより、代替手段と比較して同じハードウェアでより多くのユーザーをサービングできます。

コスト最適化: GPUコストが懸念される場合、vLLMの卓越したスループットにより、より少ないGPUで同じトラフィックをサービングでき、インフラコストを直接的に削減できます。PagedAttentionによる4倍のメモリ効率により、より小さく安価なGPUインスタンスの使用も可能になります。

Kubernetesデプロイメント: vLLMのステートレスな設計とコンテナフレンドリーなアーキテクチャにより、Kubernetesクラスターに理想的です。負荷下での一貫したパフォーマンスと直截的なリソース管理により、クラウドネイティブインフラとの統合が容易です。

vLLMを使わないべき場合: ローカル開発、実験、または単一ユーザーのシナリオでは、Ollamaやllama.cppの方が、セットアップがよりシンプルでユーザー体験が良いです。vLLMの複雑さは、本番ワークロードのパフォーマンス利点を必要とする場合に正当化されます。

vLLMのインストール方法

前提条件

vLLMをインストールする前に、システムがこれらの要件を満たしていることを確認してください。

  • OS: glibc 2.35以降のLinux（Ubuntu 22.04以上、Debian 12以上、RHEL 9以上）
  • GPU: コンピュート能力7.5以上のNVIDIA GPU（T4、A10、A100、L4、H100、B200、RTX 20/30/40/50シリーズ）。V100などの古い7.0世代のカードはサポートリストから削除されました。AMD GPUは、別のROCmホイールを通じてサポートされています——AMD固有のイメージ、デバイスフラグ、カーネルカバレッジの注意点については、ROCm vs Vulkan for AMD Local LLM Hostingを参照してください。
  • CUDA: デフォルトのpipホイールはCUDA 12.9に対してコンパイルされています。12.8および13.0のバリアントも並行して公開されています。Blackwell GPU（B200、GB200）にはCUDA 12.8以上が必要です。NVIDIAドライバーは、インストールするCUDAバージョンに対応する十分に新しいものである必要があります。
  • Python: 3.10から3.13 — 推奨バージョンは3.12です（ROCmホイールは3.12専用）
  • VRAM: 7Bモデルには最低16GB、13Bには24GB以上、より大きなモデルには40GB以上

pipによるインストール

推奨されるインストール方法は、uvを使用し、Python 3.12の環境を作成して、対応するPyTorch CUDAバックエンドを自動的に選択することです（--torch-backend=auto はインストールされたドライバーを調べます）。uv自体について詳しく知るために、uv: The New Python Package Project and Environment Managerを参照してください。

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

# インストールの検証
python -c "import vllm; print(vllm.__version__)"

プレーンなpipでも動作します。

python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

デフォルトのホイールはCUDA 12.9に対してコンパイルされています。別のCUDAバージョンが必要な場合は、対応するPyTorchホイールインデックスを取得します。例えば、CUDA 12.8の場合：

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

vllm==0.4.2+cu121 のような古いピン留めされたホイールは、この形式ではもはや存在しません。異なるPyTorchビルドを持つ既存の環境にvLLMを混在させることは、インストール失敗の一般的な原因です。プロジェクトでは新しい環境、そしてカスタムなCUDAターゲットが必要な場合はソースビルドを推奨しています。

Dockerによるインストール

Dockerは、特に本番環境において最も信頼できるデプロイ方法を提供します。イメージをlatestではなくリリースバージョンにピン留めして、アップグレードが意図的なものにし、またCUDA 12.9（-cu129 タグサフィックス）、AMD ROCm（vllm-openai-rocm）、CPU（vllm-openai-cpu）、Intel XPU（vllm-openai-xpu）用のバリアントイメージが存在することに注意してください。

# 公式vLLMイメージを取得
docker pull vllm/vllm-openai:v0.31.0

# GPUサポート付きでvLLMを実行
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.31.0 \
    --model Qwen/Qwen3-8B

マルチGPUセットアップでは、--ipc=host フラグが適切なプロセス間通信を有効にするため重要になります。

ソースからのビルド

最新機能やカスタマイズが必要な場合、ソースからビルドします。

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

vLLM クイックスタートガイド

最初のモデルの実行

コマンドラインインターフェースを使用して、モデルでvLLMを開始します。

# OpenAI互換APIでモデルをダウンロードしてサービング
vllm serve Qwen/Qwen3-8B \
    --port 8000

vllm serve は、OpenAI互換サーバーの現在のCLIです。旧来の python -m vllm.entrypoints.openai.api_server 呼び出しはまだ動作しますが、非推奨警告を表示し、将来のリリースで削除される可能性があります。そのため、まだそれを使用しているスクリプトやKubernetesマニフェストを更新してください。

vLLMは、モデルをHuggingFace Hubから自動的にダウンロードし（キャッシュされていない場合）、サーバーを開始します。サーバーが準備できたことを示す出力が表示されます。

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

APIリクエストの実行

サーバーが起動したら、OpenAI Pythonクライアントまたはcurlを使用してリクエストを行うことができます。

curlの使用例:

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-8B",
        "prompt": "Explain what vLLM is in one sentence:",
        "max_tokens": 100,
        "temperature": 0.7
    }'

OpenAI Python Clientの使用例:

from openai import OpenAI

# vLLMサーバーを指す
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # サーバーを --api-key で開始しない限りvLLMは無視します
)

response = client.completions.create(
    model="Qwen/Qwen3-8B",
    prompt="Explain what vLLM is in one sentence:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

Chat Completions API:

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is PagedAttention?"}
    ],
    max_tokens=200
)

print(response.choices[0].message.content)

高度な設定

vLLMは、パフォーマンスを最適化するための多くのパラメータを提供します。

vllm serve Qwen/Qwen3-8B \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # GPUメモリの95%を使用
    --max-model-len 32k \            # 最大シーケンス長（8192と32kの両方が動作）
    --tensor-parallel-size 2 \       # テンソル並列で2枚のGPUを使用
    --dtype float16 \                # FP16精度を使用
    --max-num-seqs 256               # 最大バッチサイズ

主要パラメータの解説:

  • --gpu-memory-utilization: モデル実行器に割り当てるGPUメモリの割合（デフォルト 0.92）。高い値はより大きなバッチを許可しますが、メモリスパイクに対する余裕を減らします。
  • --max-model-len: 最大コンテキスト長。トークン数や 32k のような人間が読める値を受け入れます。これを減らすことで、より大きなバッチのためにメモリを解放できます。
  • --tensor-parallel-size: モデルを分散させるGPUの数を指定します。
  • --dtype: 重みのデータ型（auto、float16、bfloat16、float32）。auto はチェックポイントのdtypeに従い、通常これが必要です。
  • --max-num-seqs: バッチ内の最大シーケンス数。
  • --max-num-active-seqs: max_num_seqs に独立して、RUNNING状態への受け入れを上限設定します（v0.31.0で新設）— スケジューラーのバッチウィンドウを縮小せずにレイテンシを制限するために有用です。

vLLM vs Ollama

vLLMは、継続的バッチング、PagedAttention、マルチGPUサポートを備えた、高スループットな多ユーザー本番サービングのために設計されています。Ollamaは、高速なローカルセットアップ、単一ユーザーの利便性、シンプルなモデル管理に最適化されています。

移行シグナル、計画手順、Docker Compose設定、実用的なチェックリストを含む詳細な決定ガイドについては、Ollama to vLLM: When to Migrate Your Local LLM Serverを参照してください。

vLLM vs Docker Model Runner

DockerのModel Runnerは、ローカルAIモデルデプロイメントのための公式ソリューションです。vLLMと比較してどうか？

アーキテクチャの哲学

Docker Model Runner は「Docker for AI」を目指すもの——コンテナを実行するのと同じ簡易さで、ローカルでAIモデルを実行するためのシンプルで標準化された方法です。複雑さを隠蔽し、異なるモデルやフレームワーク間で一貫したインターフェースを提供します。

vLLM は、最大のパフォーマンスでのLLMサービングにのみ焦点を当てた特殊な推論エンジンです。完全なプラットフォームではなく、Dockerでコンテナ化して使用する低レベルツールです。

セットアップと開始

Docker Model Runner のインストールは、Dockerユーザーにとって直截的です。

docker model pull llama3:8b
docker model run llama3:8b

このDockerのイメージワークフローとの類似性は、すでにコンテナを使用している開発者にとって即座に馴染みのあるものです。完全なコマンドセットはDocker Model Runner cheatsheetにあります。

vLLM は、より多くの初期セットアップ（Python、CUDA、依存関係）またはプレビルドされたDockerイメージの使用が必要です。

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vllm-openai:latest --model <model-name>

パフォーマンス特性

vLLM は、PagedAttentionと継続的バッチングのおかげで、多ユーザーシナリオにおいて卓越したスループットを実現します。1秒あたりの数百のリクエストを処理する本番APIサービスにおいて、vLLMの最適化は、一般的なサービングアプローチよりも2〜5倍の良いスループットを提供します。

Docker Model Runner は、最大のパフォーマンスではなく使いやすさに焦点を当てています。ローカル開発、テスト、中程度のワークロードには適していますが、vLLMがスケールにおいて優れる理由となる高度な最適化を実装していません。

モデルサポート

Docker Model Runner は、人気のあるモデルへの1コマンドアクセスを提供するキュレーションされたモデルライブラリを提供します。LLMだけでなく、Stable Diffusion、WhisperなどのStable Diffusion、Whisperなど他のAIモデルを含む、複数のフレームワーク（Stable Diffusion、Whisperなど他のAIモデル）をサポートしており、異なるAIワークロードにより多能です。

vLLM は、トランスフォーマーベースの言語モデルの深いサポートを持つLLM推論に特化しています。HuggingFace互換のLLMであれば何でもサポートしますが、画像生成や音声認識など他のAIモデルタイプには拡張されません。

本番デプロイメント

vLLM は、Anthropic、Replicateなどの企業で、毎日数十億のトークンをサービングする本番環境で実戦テストされています。そのパフォーマンス特性と重い負荷下での安定性により、本番LLMサービングの事実上の標準となっています。

Docker Model Runner は新しく、開発やローカルテストシナリオをより強く位置づけています。本番トラフィックをサービングすることは可能ですが、本番デプロイメントに必要な実証された実績とパフォーマンス最適化が不足しています。

統合エコシステム

vLLM は、本番インフラストラクチャツールと統合します：Kubernetesオペレーター、Prometheusメトリクス、分散サービング用のRay、そして既存アプリケーションのための広範なOpenAI API互換性。

Docker Model Runner は、DockerのエコシステムとDocker Desktopと自然に統合します。すでにDockerに標準化しているチームにとって、この統合は一貫した体験を提供しますが、特殊なLLMサービング機能は少ないです。

それぞれを使う場面

vLLMを使用するケース:

  • 本番LLM APIサービス
  • 高スループット、多ユーザーデプロイメント
  • 最大効率が必要なコスト敏感型クラウドデプロイメント
  • Kubernetesおよびクラウドネイティブ環境
  • 実証されたスケーラビリティとパフォーマンスが必要な場合

Docker Model Runnerを使用するケース:

  • ローカル開発とテスト
  • さまざまなAIモデルタイプの実行（LLMだけではない）
  • Dockerエコシステムに深く投資しているチーム
  • インフラストラクチャセットアップなしでの迅速な実験
  • 学習および教育目的

ハイブリッドアプローチ: 多くのチームは、利便性のためにローカルでDocker Model Runnerを開発し、パフォーマンスのために本番でvLLMをデプロイします。Docker Model Runnerのイメージは、vLLMコンテナの実行にも使用でき、両方のアプローチを組み合わせることができます。

本番デプロイメントのベストプラクティス

Dockerデプロイメント

本番環境向けのDocker Compose設定を作成します。

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
      - ./logs:/logs
    ports:
      - "8000:8000"
    command: >
      --model Qwen/Qwen3-8B
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.90
      --max-num-seqs 256
      --max-model-len 8192
    restart: unless-stopped
    shm_size: '16gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

Kubernetesデプロイメント

本番規模でKubernetesにvLLMをデプロイします。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
          - --model
          - Qwen/Qwen3-8B
          - --tensor-parallel-size
          - "2"
          - --gpu-memory-utilization
          - "0.90"
        resources:
          limits:
            nvidia.com/gpu: 2
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: cache
        hostPath:
          path: /mnt/huggingface-cache
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

モニタリングとオブザーバビリティ

OpenAI互換サーバーは、デフォルトで /metrics にPrometheusメトリクスを公開します — 追加のフラグは不要です。

curl -s http://localhost:8000/metrics | grep '^vllm:'

監視すべき主要メトリクス：

  • vllm:num_requests_running / vllm:num_requests_waiting / vllm:num_requests_swapped — RUNNING、WAITING、SWAPPEDスケジューラ状態にあるリクエスト
  • vllm:kv_cache_usage_perc — 使用されているKVキャッシュブロックの割合（0–1）
  • vllm:time_to_first_token_seconds — TTFTヒストグラム
  • vllm:time_per_output_token_seconds — トークンごとの生成速度
  • vllm:num_preemptions_total — 累積プリーエンプション（先取り）。カウンターが増加している場合、KVキャッシュが過剰予約されており、リクエストが再計算されていることを意味します

LLMサービングを囲むダッシュボード、PromQLの例、アラート閾値については、Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cppを参照してください。

パフォーマンスチューニング

GPUメモリ利用率の最適化: デフォルトは0.92です。観測された動作に基づいて調整します。高い値はより大きなバッチを許可しますが、トラフィックスパイク中のOOMエラーのリスクがあります。

最大シーケンス長のチューニング: ユースケースで完全なコンテキスト長を必要としない場合は、--max-model-len を減らします。これにより、より大きなバッチのためにメモリが解放されます。例えば、4Kコンテキストのみ必要とする場合は、モデルの最大値（通常8K-32K）の代わりに --max-model-len 4096 を設定します。

適切な量子化の選択: 対応するモデルについては、量子化されたバージョン（8ビット、4ビット）を使用してメモリを削減しスループットを増加させます。

--quantization awq  # AWQ量子化モデル用
--quantization gptq # GPTQ量子化モデル用

プレフィックスキャッシュ: プレフィックスキャッシュは、現在のエンジンでデフォルトで有効化されているため、プロンプトプレフィックスを共有するリクエスト（固定システムプロンプト、RAGコンテキストテンプレート）は、フラグなしでそのKVキャッシュを再利用できます。キャッシュの管理が何の利益ももたらさない多くの固有の長いプロンプトを持つワークロードでは、--no-enable-prefix-caching で無効にします。

一般的な問題のトラブルシューティング

メモリ不足エラー

症状: サーバーがCUDAメモリ不足エラーでクラッシュします。

解決策:

  • --gpu-memory-utilization を0.85または0.80に減らす
  • ユースケースが許す場合は --max-model-len を減らす
  • バッチサイズを減らすために --max-num-seqs を下げる
  • 量子化モデルバージョンを使用する
  • 張量並列性を有効にして、より多くのGPUに分散する

2種類の異なるOOMの形態があり、異なる修正が必要です。起動時のOOMは、リクエストの発生前に起こります：vLLMはメモリをプロファイリングし、最小限のKVキャッシュですら割り当てに失敗するため、--max-num-seqs を下げても役立ちません — --max-model-len を減らすか、余裕がある場合は --gpu-memory-utilization を上げます。負荷下での実行時OOMは、CUDA-graphキャプチャメモリから来ることがあります。これは --max-num-seqs と比例しますが、KVキャッシュの会計の外側に位置します；CUDAグラフが欠けているメモリかどうかを確認するために一度 --enforce-eager で実行し、キャッシュを責める前に正確に同じ設定で再テストします。同一ハードウェアでの起動が同じ割り当てで成功し続ける場合、起動時にvLLMがログ出力する --kv-cache-memory-bytes 値を渡すことで、後続の起動でのプロファイリングパスをスキップできます。

単一の16 GBカードでは、これらのOOMエラーの大部分は、重みだけでなくKVキャッシュの予算に起因します — KV Cache on 16 GB GPUsは、より小さなモデルに頼る前に、--max-model-len および --max-num-seqs の背後にある正確な数式、FP8 KV-cache dtype、プレフィックスキャッシュのトレードオフを解説します。

起動が遅い

症状: サーバーが起動から「Application startup complete」まで数分かかります。

解決策:

  • 重みの読み込み、コンパイル、CUDA-graphキャプチャが起動を支配しています — --enforce-eager はコンパイルとキャプチャの両方をスキップし、それが起動のどの程度のコストなのかを、定常状態のデコード速度の代償として教えてくれます
  • 繰り返し起動時にメモリプロファイリングとCUDAグラフ推定パスをスキップするために、ログ出力された --kv-cache-memory-bytes 値を再利用する
  • v0.30.0以降、vllm preload コマンドは永続的な重みキャッシュデーモンを実行し、量子化後の重みをGPUメモリに常駐させ続けるため、エンジン再起動はディスクからの再読み込みの代わりに、CUDA IPC経由で重みをマッピングします（--load-format ipc_cache）
  • 起動時のコンパイルでOOMするNVFP4チェックポイントに対して、ビルドスレッドを MAX_JOBS=4 と NVCC_THREADS=4 で制限することは、広く使用されている修正方法です — JITビルドは遅くなりますが、OOMを止めます

スループットが低い

症状: サーバーが予期するより少ないリクエストを処理します。

解決策:

  • より大きなバッチを許可するために --max-num-seqs を増やす
  • 余裕がある場合は --gpu-memory-utilization を上げる
  • htop でCPUがボトルネックかどうかを確認する — より高速なCPUを検討する
  • nvidia-smi でGPU利用率を確認する — 95%以上であるべきです
  • FP32を使用している場合はFP16を有効にする：--dtype float16

最初のトークン時間が遅い

症状: 生成開始前に高いレイテンシがあります。

解決策:

  • レイテンシクリティカルなアプリケーションにはより小さいモデルを使用する
  • プレフィックスキャッシュはデフォルトでオンです — フラグを再追加するのではなく、有効であることを確認する
  • スループットよりレイテンシを優先するために --max-num-seqs を減らす
  • 対応するモデルには投機的デコーディング（speculative decoding）を検討する
  • テンソル並列性設定を最適化する

モデル読み込み失敗

症状: サーバーが起動に失敗し、モデルを読み込めません。

解決策:

  • モデル名がHuggingFace形式と完全に一致することを確認する
  • HuggingFace Hubへのネットワーク接続を確認する
  • ~/.cache/huggingface に十分なディスクスペースがあることを確認する
  • ゲートされたモデルの場合、HF_TOKEN 環境変数を設定する
  • hf download <model> （または古いインストールでは huggingface-cli download <model>）で手動ダウンロードを試みる

高度な機能

投機的デコーディング（Speculative Decoding）

vLLMは、小さなドラフトモデルがトークンを提案し、大きなターゲットモデルが検証する投機的デコーディングをサポートしています。これにより、生成が1.5〜2倍高速化されることがあります。投機的デコーディング方法——ドラフトモデル、EAGLE-3、P-EAGLE、n-gram——の包括的なガイドについては、Speculative Decoding: Faster Inference Without Quality Lossを参照してください。

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --speculative-config '{"method": "draft_model", "model": "meta-llama/Llama-3.2-1B-Instruct", "num_speculative_tokens": 4}'

古い --speculative-model および --num-speculative-tokens フラグは消えました — 設定は単一の --speculative-config JSON引数に移動し、方法（draft_model、ngram、EAGLEファミリー、またはネイティブ多トークン予測ヘッドを持つモデルのMTP）も選択します。

LoRAアダプター

ベースモデルの上に複数のLoRAアダプターをサービングし、複数の完全なモデルを読み込むことなく実現します。

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-lora \
    --lora-modules sql-lora=/path/to/sql-adapter \
                   code-lora=/path/to/code-adapter

リクエストごとに使用するアダプターを指定するには、その名前を model フィールドに入れます — 同じメカニズムは、メモリにベースモデルのみを常駐させることで、顧客固有またはドメイン固有のバリアントを含む、数十のタスク固有アダプターにスケーリングされます。

response = client.completions.create(
    model="sql-lora",  # SQLアダプターを使用
    prompt="Convert this to SQL: Show me all users created this month"
)

プレフィックスキャッシュ

プレフィックスキャッシュは、共有プロンプトプレフィックスのKVキャッシュの再計算を回避し、現在のエンジンではデフォルトで有効化されています。

最も効果があるのは：

  • 固定システムプロンプトを持つチャットボット
  • 一貫したコンテキストテンプレートを持つRAGアプリケーション
  • リクエスト間で繰り返し使用されるファインショット学習プロンプト

プレフィックスを共有するリクエストについては、共有部分のプリアフィルがスキップされるため、最初のトークンまでの時間が大幅に短縮されます。

統合例

LangChain 統合

from langchain_community.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="Qwen/Qwen3-8B",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Explain PagedAttention in simple terms")
print(response)

FastAPI アプリケーション

from fastapi import FastAPI
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

@app.post("/generate")
async def generate(prompt: str):
    response = await client.completions.create(
        model="Qwen/Qwen3-8B",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

パフォーマンスベンチマーク

リアルワールドのパフォーマンスデータは、vLLMの利点を示すのに役立ちます。以下の数値は、プロジェクトのリリース時代のドキュメントおよび初期のコミュニティ測定値からのものであり、アーキテクチャの影響のオーダーを示すものとして扱い、今日のモデル世代の現在の結果としては扱わないでください。

スループット比較（A100 GPU上のMistral-7B）:

  • vLLM: 64並行ユーザーで約3,500トークン/秒
  • HuggingFace Transformers: 同じ並行性で約250トークン/秒
  • Ollama: 同じ並行性で約1,200トークン/秒
  • 結果: vLLMは基本的な実装よりも14倍の改善を提供

メモリ効率（LLaMA-2-13B）:

  • 標準実装: 24GB VRAM、32並行シーケンス
  • PagedAttention付きvLLM: 24GB VRAM、128並行シーケンス
  • 結果: 同じメモリで4倍の並行リクエスト

負荷下のレイテンシ（2xA100上のMixtral-8x7B）:

  • vLLM: 100 req/sでP50レイテンシ 180ms、P99レイテンシ 420ms
  • 標準サービング: 100 req/sでP50レイテンシ 650ms、P99レイテンシ 3,200ms
  • 結果: vLLMは高い負荷下で一貫したレイテンシを維持

コスト分析

vLLMを選択することのコスト影響を理解する：

シナリオ：1日100万リクエストのサービング

標準サービングの場合:

  • 必要: 8x A100 GPU (80GB)
  • AWSコスト: 約$32/時間 × 24 × 30 = $23,040/月
  • 100万トークンあたりのコスト: 約$0.75

vLLMの場合:

  • 必要: 2x A100 GPU (80GB)
  • AWSコスト: 約$8/時間 × 24 × 30 = $5,760/月
  • 100万トークンあたりのコスト: 約$0.19
  • 節約: $17,280/月（75%の削減）

このコスト上の優位性は、スケールとともに増加します。月間数十億のトークンをサービングする組織は、素朴な実装の代わりにvLLMの最適化されたサービングを使用することで、数十万ドルを節約します。

セキュリティの考慮事項

認証

vLLMには組み込みの --api-key フラグが付属していますが、公式ドキュメントによると、/v1、/v2 および /inference パスプレフィックスの下のエンドポイントのみを認証し、同じサーバー上の他のエンドポイントは認証されていません。これを一層として扱われ、完全な回答として扱わないでください；完全なカバーのために、リバースプロキシレベルで認証を実装します。

# Nginx 設定
location /v1/ {
    auth_request /auth;
    proxy_pass http://vllm-backend:8000;
}

location /auth {
    proxy_pass http://auth-service:8080/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

または、エンタープライズレベルの認証とレート制限のために、Kong、Traefik、またはAWS API GatewayなどのAPIゲートウェイを使用します。

ネットワーク分離

vLLMは、インターネットに直接公開するのではなく、プライベートネットワークで実行します。

# Kubernetes NetworkPolicy の例
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vllm-access
spec:
  podSelector:
    matchLabels:
      app: vllm
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: api-gateway
    ports:
    - protocol: TCP
      port: 8000

レート制限

悪用を防ぐためにレート制限を実装します。

# レート制限のためのRedis使用例
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import redis
from datetime import datetime, timedelta

app = FastAPI()
redis_client = redis.Redis(host='localhost', port=6379)

@app.middleware("http")
async def rate_limit_middleware(request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    requests = redis_client.incr(key)
    if requests == 1:
        redis_client.expire(key, 60)  # 60秒ウィンドウ
    
    if requests > 60:  # 1分あたり60リクエスト
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    
    return await call_next(request)

モデルアクセス制御

マルチテナントデプロイメントでは、どのユーザーがどのモデルにアクセスできるかを制御します。

ALLOWED_MODELS = {
    "user_tier_1": ["Qwen/Qwen3-8B"],
    "user_tier_2": ["Qwen/Qwen3-8B", "meta-llama/Llama-2-13b-chat-hf"],
    "admin": ["*"]  # 全モデル
}

def verify_model_access(user_tier: str, model: str) -> bool:
    allowed = ALLOWED_MODELS.get(user_tier, [])
    return "*" in allowed or model in allowed

移行ガイド

OpenAIからvLLMへ

APIの互換性のおかげで、OpenAIからセルフホストvLLMへの移行は直截的です。

以前（OpenAI）:

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)

その後（vLLM）:

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vllm-server.com/v1",
    api_key="your-internal-key"  # 認証を追加した場合
)
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}]
)

必要な変更は2つだけです：base_url と model 名の更新。その他のコードはすべて同一のままです。

OllamaからvLLMへ

Ollamaは異なるAPIフォーマットを使用します。基本的なクライアント側の変更は、OllamaのRESTエンドポイントからvLLMのOpenAI互換APIへの切り替えです。

Ollama API:

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={'model': 'llama2', 'prompt': 'Why is the sky blue?'})

vLLM 同等:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.completions.create(
    model="meta-llama/Llama-2-7b-chat-hf",
    prompt="Why is the sky blue?"
)

Ollama APIは独自のリクエスト形状を持つプレーンRESTですが、vLLMはOpenAIプロトコルを話します — そのAPIフォーマットの差が主なクライアント側の変更であり、段階的アプローチ（両方のサーバーを実行し、エンドポイントごとにトラフィックを移行する）は、この記事の前述でリンクされた移行ガイドでカバーされています。

HuggingFace TransformersからvLLMへ

直接的なPython使用の移行：

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

vLLM:

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B")
sampling_params = SamplingParams(max_tokens=100)

outputs = llm.generate("Hello", sampling_params)
result = outputs[0].outputs[0].text

vLLMのPython APIはよりシンプルで、バッチ推論のためにずっと高速です。

最近のリリース：2026年に何が変化したか

2026年9月〜10月の3つのリリース（v0.29.0、v0.30.0、v0.31.0）が、開発の方向性を示しています。

高速な再起動: vllm preload は、量子化後、TPシャーディングされた重みをGPUメモリに常駐させ続ける、GPUごとの永続的な重みキャッシュデーモンを開始します。これにより、再起動したエンジンはディスクからの再読み込みの代わりに、それらをCUDA IPC（--load-format ipc_cache）経由でマッピングします。実験的な vllm snapshot create/restore は、CRIUで完全に初期化されたエンジンをスナップショットします。

Model Runner V2上の投機的デコーディング: ドラフトモデルによる投機的デコーディング、カスタムロジツプロセッサ、適応的検証が新しいモデルランナーに移動し、LiLiCorrドラフターが追加され、DFlashドラフター向けの非同期スケジューリングが導入されました。

大規模MoEサービング: 新しいバランスドエキスパート並列all2allバックエンド（--all2all-backend moonep）、シーケンス並列性付きDeepEPv2、共有エキスパートオーバーラップ付きEPLB、そしてデータ並列性と組み合わせたプリアフィルコンテキスト並列性。

スケジューリング制御: --max-num-active-seqs は max_num_seqs に独立してRUNNING状態への受け入れを上限設定し、待機キューはすでにKVブロックを持つリクエストを優先的にスケジューリングするようになりました。

古いvLLMガイドからのロードマップ項目は、すでに長くリリースされています — GGUFサポート、マルチモーダルサービング、分離されたプリアフィル/デコード、マルチノード推論はすべて現在のリリースの一部です。そのため、それらを「まもなく」と列挙しているチュートリアルは時代遅れとして扱いましょう。すべてのバージョンのリリースノートは、vLLM releases pageにあります。

有用なリンク

このサイトの関連記事

  • Ollama チートシート - 完全なOllamaコマンドリファレンスおよびチートシート。インストール、モデル管理、API使用、ローカルLLMデプロイメントのベストプラクティスを含む。vLLMと併用または代用してOllamaを使用する開発者に不可欠。

  • Docker Model Runner vs Ollama: Which to Choose? - ローカルLLMデプロイメントにおけるDocker Model RunnerとOllamaの深い比較。パフォーマンス、GPUサポート、API互換性、ユースケースを分析。vLLMが運営される競争環境を理解するのに役立つ。

外部リソースとドキュメント

  • vLLM GitHub リポジトリ - ソースコード、包括的なドキュメント、インストールガイド、活発なコミュニティディスカッションを備えた公式vLLMリポジトリ。最新機能や問題のトラブルシューティングを最新に保つための不可欠なリソース。

  • vLLM ドキュメント - 基本的なセットアップから高度な設定まで、vLLMのすべての側面をカバーする公式ドキュメント。APIリファレンス、パフォーマンスチューニングガイド、デプロイメントのベストプラクティスを含む。

  • PagedAttention 論文 - vLLMの効率を支えるPagedAttentionアルゴリズムを導入する学術論文。vLLMのパフォーマンス利点の背後にある技術的革新を理解するための必読文献。

  • vLLM ブログ - リリースアナウンス、パフォーマンスベンチマーク、技術的ディープダイブ、本番デプロイメントからのコミュニティケーススタディを特徴とする公式vLLMブログ。

  • HuggingFace モデルハブ - vLLMで動作するオープンソースLLMの包括的なリポジトリ。サイズ、タスク、ライセンス、パフォーマンス特性でモデルを検索し、ユースケースに最適なモデルを見つけます。

  • Ray Serve ドキュメント - スケーラブルで分散型のvLLMデプロイメントを構築するためのRay Serveフレームワークドキュメント。Rayは、オートスケーリング、マルチモデルサービング、本番システムのリソース管理などの高度な機能を提供します。

  • NVIDIA TensorRT-LLM - NVIDIA GPUでの高度に最適化された推論のためのNVIDIA TensorRT-LLM。異なる最適化戦略を持つvLLMの代替手段であり、比較や推論最適化のランドスケープの理解に有用。

  • OpenAI API リファレンス - vLLMのAPIが互換性を持つ公式OpenAI APIドキュメント。OpenAIとセルフホストvLLMエンドポイントの両方で動作する必要があるアプリケーションを構築する場合、これを参照してください。

購読する

システム、インフラ、AIエンジニアリングの新記事をお届けします。