vLLMとは？高速・スケーラブルなAPIでLLM推論を強化

大規模言語モデル（LLM）アプリケーションを構築していて、推論速度の遅さやGPUメモリの制限に悩んでいませんか？vLLMは、LLMの提供を高速化し、高い同時実行性を実現し、インフラコストを抑えるために使われるオープンソース推論エンジンです。この記事では、vLLMの仕組み、インストール方法、オフラインバッチ推論、OpenAI互換APIサーバーとしての使い方を、実装手順中心に説明します。

今すぐApidogを試す

vLLMとは？LLM APIにとってなぜ重要なのか？

vLLMは、大規模言語モデルを高速かつメモリ効率よく提供するためのオープンソース推論エンジンです。LLM APIを本番運用する際に問題になりやすい、次の2点を改善します。

• 推論速度の遅さ: 同時ユーザー数が多い場合や、大量のバッチ処理でレイテンシが悪化しやすい
• GPUメモリ使用量の大きさ: 従来のAttention実装ではKVキャッシュがGPUメモリを圧迫し、扱えるモデルサイズや同時処理数が制限される

vLLMの主要な特徴は次の2つです。

• PagedAttention: KVキャッシュをページ単位で管理し、GPUメモリの無駄を削減する
• 連続バッチ処理（Continuous batching）: リクエスト到着時に動的にバッチへ組み込み、GPU利用率を高める

LLM APIを自己ホストし、スループットとレイテンシを改善したい場合、vLLMはバックエンド推論エンジンとして有力な選択肢です。

API開発者とバックエンドエンジニアがvLLMを使う理由

vLLMは、LLM推論APIの実装で次のようなメリットがあります。

• 高スループット: 1秒あたりに処理できるリクエスト数を増やしやすい
• 効率的なGPU使用: 同じGPUでより大きなモデルや多くのリクエストを扱いやすい
• 動的なバッチ処理: 固定バッチを待たず、実トラフィックに合わせて処理できる
• OpenAI互換API: 既存のOpenAIクライアントやAPI設計を流用しやすい
• オフライン推論とオンラインAPIの両対応: バッチ処理にもリアルタイムAPIにも使える
• 幅広いモデルサポート: Llama、Mistral、Qwen、OPT、Falconなど、Hugging FaceやModelScopeのモデルを利用できる
• 活発なオープンソース開発: 機能追加や改善が継続されている

サポートモデルの詳細は、vLLMドキュメントの対応モデル一覧を確認してください。

ヒント: LLM搭載APIを構築・テストする場合は、ApidogのようなAPIツールを使うと、vLLM、OpenAI、カスタムバックエンドのエンドポイント設計、テスト、ドキュメント化をまとめて扱いやすくなります。

サポートされるLLM：vLLMで動作するモデル

vLLMは、以下を含むTransformerベースのモデルをサポートしています。

• Llamaシリーズ: Llama、Llama 2、Llama 3
• Mistral / Mixtral
• Qwen / Qwen2
• GPT-2、GPT-J、GPT-NeoX
• OPT
• Bloom
• Falcon
• MPT
• その他、マルチモーダルモデルを含むモデル

対応モデルは継続的に増えています。最新の互換性は、公式vLLMサポートモデルリストを確認してください。

モデルが一覧にない場合でも、サポート済みモデルとアーキテクチャを共有していれば動作する可能性があります。ただし、本番投入前に必ず検証してください。カスタムアーキテクチャでは、追加実装やアップストリームへのコード貢献が必要になる場合があります。

主要な概念: PagedAttentionと連続バッチ処理

vLLMを使う前に、特に重要な2つの仕組みを押さえておきます。

PagedAttention

従来のAttentionでは、KVキャッシュに連続したGPUメモリを割り当てるため、フラグメンテーションや未使用領域が発生しやすくなります。

PagedAttentionは、OSの仮想メモリに似た考え方でKVキャッシュを「ページ」に分割して管理します。これにより、メモリの無駄を減らし、共通プレフィックスを持つシーケンスでメモリ共有しやすくなります。

連続バッチ処理（Continuous Batching）

静的バッチ処理では、バッチが揃うまで処理を待つため、GPUがアイドル状態になったり、リクエスト待ち時間が増えたりします。

連続バッチ処理では、GPUリソースが空いたタイミングで新しいリクエストを随時処理に組み込みます。これにより、GPU利用率を高めつつ、オンラインAPIでのレイテンシを抑えやすくなります。

前提条件: vLLMをインストールする前に必要なもの

vLLMを使う前に、環境を確認します。

• OS: Linux推奨。WSL2やmacOSでも利用可能な場合がありますが、Linuxが最も一般的です
• Python: 3.9、3.10、3.11、または3.12
• GPU: CUDA対応NVIDIA GPU推奨
• PyTorch: vLLMインストール時に互換バージョンが入ります。CUDA構成を細かく管理したい場合は事前インストールも可能です

本番や検証環境では、仮想環境を使って依存関係を分離することをおすすめします。

vLLMのインストール方法

1. pipでインストールする

python -m venv vllm-env
source vllm-env/bin/activate
# Windowsの場合: vllm-env\Scripts\activate

pip install vllm

インストール後、vLLM本体と必要な依存関係が利用可能になります。

2. Condaでインストールする

conda create -n vllm-env python=3.11 -y
conda activate vllm-env
pip install vllm

CUDAやPyTorchのバージョンを明示的に管理したい場合は、先にCondaでPyTorchをインストールしてからvLLMを入れると調整しやすくなります。

3. uvでインストールする

uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate
uv pip install vllm

4. インストールを確認する

python -c "import vllm; print(vllm.__version__)"
vllm --help

バージョン番号とCLIヘルプが表示されれば、インストールは完了です。

vLLMによるオフラインバッチ推論

バッチ推論は、複数のプロンプトに対してまとめて生成を実行したい場合に便利です。評価、データセット生成、一括処理などに使えます。

バッチ推論スクリプト例

from vllm import LLM, SamplingParams

# 1. プロンプトを定義
prompts = [
    "The capital of France is",
    "Explain the theory of relativity in simple terms:",
    "Write a short poem about a rainy day:",
    "Translate 'Hello, world!' to German:",
]

# 2. サンプリングパラメータを設定
sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.95,
    max_tokens=150,
    stop=["\n", " Human:", " Assistant:"]
)

# 3. vLLMエンジンを初期化
# GPUメモリに収まるモデルを選択してください
llm = LLM(model="mistralai/Mistral-7B-Instruct-v0.1")

# 4. 生成を実行
outputs = llm.generate(prompts, sampling_params)

# 5. 結果を表示
for output in outputs:
    print("-" * 20)
    print(f"Prompt: {output.prompt!r}")
    print(f"Generated Text: {output.outputs[0].text!r}")
    print("-" * 20)

実装時のポイント:

• vLLMはデフォルトでHugging Face Hubのモデルを使用します
• ModelScopeを使う場合は、環境変数 VLLM_USE_MODELSCOPE=1 を設定します
• モデルの生成設定をvLLM側で上書きしたい場合は、LLM コンストラクタで generation_config="vllm" を指定します
• AWQやGPTQなどの量子化モデルを使う場合は、vLLMドキュメントとHugging Faceのモデルカードを確認してください

vLLMをOpenAI互換APIサーバーとして実行する

vLLMはOpenAI互換APIサーバーとして起動できます。これにより、既存のOpenAIクライアントコードやAPIテストツールを使って、自己ホストしたモデルへリクエストできます。

vLLMサーバーを起動する

source vllm-env/bin/activate

vllm serve mistralai/Mistral-7B-Instruct-v0.1

# 別モデルの例:
# vllm serve Qwen/Qwen2-1.5B-Instruct

デフォルトでは、サーバーは次のURLで起動します。

http://localhost:8000

主なオプション:

• --model <model_name_or_path>: 提供するモデルを指定
• --host 0.0.0.0: 外部アクセスを許可する場合に使用
• --port 8000: ポートを指定
• --tensor-parallel-size <N>: モデルをN個のGPUに分散
• --api-key <key>: APIキー認証を有効化
• --generation-config vllm: vLLMのデフォルト生成設定を使用
• --chat-template <path>: カスタムチャットテンプレートを指定

注: vLLMのバージョンによってCLIオプション名が変わる可能性があります。利用中のバージョンでは vllm serve --help で確認してください。

Completions APIを呼び出す

cURLの例

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mistralai/Mistral-7B-Instruct-v0.1",
        "prompt": "San Francisco is a city in",
        "max_tokens": 50,
        "temperature": 0.7
    }'

Pythonの例

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",  # APIキーを設定した場合はその値を指定
    base_url="http://localhost:8000/v1"
)

completion = client.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.1",
    prompt="Explain the benefits of using vLLM:",
    max_tokens=150,
    temperature=0.5
)

print(completion.choices[0].text)

Chat Completions APIを呼び出す

cURLの例

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mistralai/Mistral-7B-Instruct-v0.1",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is the main advantage of PagedAttention in vLLM?"}
        ],
        "max_tokens": 100,
        "temperature": 0.7
    }'

Pythonの例

chat_response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.1",
    messages=[
        {"role": "system", "content": "You are a helpful programming assistant."},
        {"role": "user", "content": "Write a simple Python function to calculate factorial."}
    ],
    max_tokens=200,
    temperature=0.5
)

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

Apidogを使うと、これらのエンドポイントをAPI仕様として整理し、モック、テスト、ドキュメント化まで一貫して管理できます。LLM APIのQAやチームレビューを行う場合に便利です。

vLLM Attentionバックエンド: FlashAttention、xFormers、FlashInfer

vLLMは、速度とメモリ効率を改善するために複数のAttentionバックエンドをサポートしています。

• FlashAttention 1 / 2: 多くの最新NVIDIA GPUで高速に動作し、メモリ使用量を抑えやすい
• xFormers: 幅広い互換性があり、フォールバックとして使いやすい
• FlashInfer: 高度なバックエンド。利用には追加インストールが必要な場合があります

通常、vLLMはハードウェアとモデルに応じて適切なバックエンドを自動選択します。

バックエンドを明示的に指定したい場合は、vLLM実行前に環境変数を設定します。

export VLLM_ATTENTION_BACKEND=FLASH_ATTN
# または
export VLLM_ATTENTION_BACKEND=XFORMERS
# または
export VLLM_ATTENTION_BACKEND=FLASHINFER

一般的なvLLMの問題と対処法

1. CUDAメモリ不足エラー

CUDA out of memoryが発生する場合は、次を確認してください。

• より小さなモデルを使う
• 同時リクエスト数やバッチサイズを下げる
• AWQやGPTQなどの量子化モデルを使う
• 複数GPUに分散する

vllm serve mistralai/Mistral-7B-Instruct-v0.1 \
  --tensor-parallel-size 2

GPU上の他プロセスも確認します。

nvidia-smi

2. インストールや互換性の問題

CUDA、PyTorch、NVIDIAドライバーの組み合わせが合っていないと、インストールや実行に失敗することがあります。

確認項目:

• PyTorch互換性マトリックスを確認する
• 必要に応じてPyTorchを事前にインストールする
• セットアップを簡略化したい場合は、公式vLLM Dockerイメージを使う

3. モデル読み込みの失敗

モデルが読み込めない場合は、次を確認します。

• モデル名が正しいか
• Hugging Face Hubにアクセスできるか
• ローカルモデルの場合、パスが正しいか
• ディスク容量が足りているか
• モデルが必要とする場合、trust_remote_code=True を使う

例:

from vllm import LLM

llm = LLM(
    model="your-org/your-model",
    trust_remote_code=True
)

4. 推論が遅い

推論レイテンシが高い場合は、次を確認します。

• nvidia-smi でGPU使用率を確認する
• vLLM、依存関係、GPUドライバーを更新する
• Attentionバックエンドを変更して検証する
• max_tokens を下げる
• temperature や top_p などのサンプリングパラメータを見直す
• 不要に長いプロンプトを送っていないか確認する

5. 出力が不自然、または期待と違う

モデルの出力品質が不安定な場合は、次を確認します。

• モデルカードに記載されたプロンプト形式に合わせる
• Chat Completionsでは適切な messages 形式を使う
• temperature や top_p を調整する
• 別のモデルで再現するか確認する
• サーバー起動時のチャットテンプレート設定を確認する

次のステップ: LLM APIワークフローを改善する

vLLMを使うと、LLM搭載APIを高速にデプロイし、トラフィックに合わせてスケールしやすくなります。さらにApidogのようなAPIツールを組み合わせることで、次の作業を進めやすくなります。

• LLMエンドポイントの設計、モック、テスト
• vLLMおよびOpenAI互換APIのQA自動化
• APIドキュメントの共有と更新
• チーム間でのAPI仕様レビュー

vLLMの量子化、multi-LoRA、分散サービス、投機的デコーディングなどの高度な機能は、公式ドキュメントで確認できます。まずはローカルでOpenAI互換APIサーバーを起動し、既存クライアントやAPIテストフローから接続してみるのがおすすめです。