serving-llms-vllm

vLLM - 高性能 LLM サービング

使用する場面

本番環境の LLM API をデプロイする場合、推論のレイテンシー／スループットを最適化する場合、または GPU メモリが限られた環境でモデルをサービングする場合に使用します。OpenAI 互換エンドポイント、量子化（GPTQ／AWQ／FP8）、テンソル並列処理に対応しています。

クイックスタート

vLLM は、PagedAttention（ブロックベースの KV キャッシュ）と継続的バッチ処理（プリフィル／デコードリクエストの混在）により、標準的な transformers と比べてスループットを 24 倍向上させます。

インストール：

pip install vllm

基本的なオフライン推論：

from vllm import LLM, SamplingParams

llm = LLM(model="meta-llama/Meta-Llama-3-8B-Instruct")
sampling = SamplingParams(temperature=0.7, max_tokens=256)

outputs = llm.generate(["Explain quantum computing"], sampling)
print(outputs[0].outputs[0].text)

OpenAI 互換サーバー：

vllm serve meta-llama/Meta-Llama-3-8B-Instruct

# Query with OpenAI SDK
python -c "
from openai import OpenAI
client = OpenAI(base_url='http://localhost:8000/v1', api_key='EMPTY')
print(client.chat.completions.create(
    model='meta-llama/Meta-Llama-3-8B-Instruct',
    messages=[{'role': 'user', 'content': 'Hello!'}]
).choices[0].message.content)
"

一般的なワークフロー

ワークフロー 1：本番環境への API デプロイ

このチェックリストをコピーして、進捗を記録してください。

Deployment Progress:
- [ ] Step 1: Configure server settings
- [ ] Step 2: Test with limited traffic
- [ ] Step 3: Enable monitoring
- [ ] Step 4: Deploy to production
- [ ] Step 5: Verify performance metrics

ステップ 1：サーバー設定を構成する

モデルサイズに応じて設定を選択します。

# For 7B-13B models on single GPU
vllm serve meta-llama/Meta-Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192 \
  --port 8000

# For 30B-70B models with tensor parallelism
vllm serve meta-llama/Meta-Llama-3-70B-Instruct \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.9 \
  --quantization awq \
  --port 8000

# For production with caching (Prometheus metrics are exposed
# automatically at /metrics on the API port)
vllm serve meta-llama/Meta-Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching \
  --port 8000 \
  --host 0.0.0.0

ステップ 2：トラフィックを制限してテストする

本番環境にデプロイする前に、負荷テストを実行します。

# Install load testing tool
pip install locust

# Create test_load.py with sample requests
# Run: locust -f test_load.py --host http://localhost:8000

TTFT（最初のトークンまでの時間）が 500ms 未満、スループットが 100 req/sec を超えていることを確認します。

ステップ 3：モニタリングを有効にする

vLLM は、API ポート（デフォルトは 8000）の /metrics で Prometheus メトリクスを公開します。

curl http://localhost:8000/metrics | grep vllm

モニタリングする主なメトリクス：

• vllm:time_to_first_token_seconds - レイテンシー
• vllm:num_requests_running - 実行中のリクエスト
• vllm:gpu_cache_usage_perc - KV キャッシュの使用率

ステップ 4：本番環境にデプロイする

一貫性のあるデプロイには Docker を使用します。

# Run vLLM in Docker
docker run --gpus all -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model meta-llama/Meta-Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching

ステップ 5：パフォーマンスメトリクスを確認する

デプロイが目標を達成していることを確認します。

• TTFT < 500ms（短いプロンプトの場合）
• スループット > 目標 req/sec
• GPU 使用率 > 80%
• ログに OOM エラーがない

ワークフロー 2：オフラインのバッチ推論

サーバーのオーバーヘッドなしで大規模なデータセットを処理する場合に使用します。

このチェックリストをコピーしてください。

Batch Processing:
- [ ] Step 1: Prepare input data
- [ ] Step 2: Configure LLM engine
- [ ] Step 3: Run batch inference
- [ ] Step 4: Process results

ステップ 1：入力データを準備する

# Load prompts from file
prompts = []
with open("prompts.txt") as f:
    prompts = [line.strip() for line in f]

print(f"Loaded {len(prompts)} prompts")

ステップ 2：LLM エンジンを構成する

from vllm import LLM, SamplingParams

llm = LLM(
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    tensor_parallel_size=2,  # Use 2 GPUs
    gpu_memory_utilization=0.9,
    max_model_len=4096
)

sampling = SamplingParams(
    temperature=0.7,
    top_p=0.95,
    max_tokens=512,
    stop=["</s>", "\n\n"]
)

ステップ 3：バッチ推論を実行する

vLLM は効率性を高めるため、リクエストを自動的にバッチ処理します。

# Process all prompts in one call
outputs = llm.generate(prompts, sampling)

# vLLM handles batching internally
# No need to manually chunk prompts

ステップ 4：結果を処理する

# Extract generated text
results = []
for output in outputs:
    prompt = output.prompt
    generated = output.outputs[0].text
    results.append({
        "prompt": prompt,
        "generated": generated,
        "tokens": len(output.outputs[0].token_ids)
    })

# Save to file
import json
with open("results.jsonl", "w") as f:
    for result in results:
        f.write(json.dumps(result) + "\n")

print(f"Processed {len(results)} prompts")

ワークフロー 3：量子化モデルのサービング

限られた GPU メモリに大規模モデルを収めます。

Quantization Setup:
- [ ] Step 1: Choose quantization method
- [ ] Step 2: Find or create quantized model
- [ ] Step 3: Launch with quantization flag
- [ ] Step 4: Verify accuracy

ステップ 1：量子化方式を選択する

• AWQ：70B モデルに最適で、精度の低下を最小限に抑えます
• GPTQ：幅広いモデルに対応し、優れた圧縮を実現します
• FP8：H100 GPU で最速です

ステップ 2：量子化済みモデルを見つけるか作成する

HuggingFace の量子化済みモデルを使用します。

# Search for AWQ models
# Example: TheBloke/Llama-2-70B-AWQ

ステップ 3：量子化フラグを指定して起動する

# Using pre-quantized model
vllm serve TheBloke/Llama-2-70B-AWQ \
  --quantization awq \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.95

# Results: 70B model in ~40GB VRAM

ステップ 4：精度を確認する

出力が期待される品質と一致するかテストします。

# Compare quantized vs non-quantized responses
# Verify task-specific performance unchanged

使用する場面と代替手段の比較

vLLM を使用する場面：

• 本番環境の LLM API をデプロイする（100 req/sec 以上）
• OpenAI 互換エンドポイントをサービングする
• GPU メモリは限られているが、大規模モデルが必要
• マルチユーザーアプリケーション（チャットボット、アシスタント）
• 高スループットを維持しながら低レイテンシーが必要

代替手段を使用する場面：

• llama.cpp：CPU／エッジ推論、シングルユーザー
• HuggingFace transformers：研究、プロトタイピング、単発の生成
• TensorRT-LLM：NVIDIA 専用で、絶対的な最高性能が必要
• Text-Generation-Inference：すでに HuggingFace エコシステムを利用している

よくある問題

問題：モデルの読み込み中にメモリ不足が発生する

メモリ使用量を減らします。

vllm serve MODEL \
  --gpu-memory-utilization 0.7 \
  --max-model-len 4096

または、量子化を使用します。

vllm serve MODEL --quantization awq

問題：最初のトークンが遅い（TTFT > 1 秒）

繰り返し使用するプロンプトでプレフィックスキャッシュを有効にします。

vllm serve MODEL --enable-prefix-caching

長いプロンプトの場合は、チャンク化プリフィルを有効にします。

vllm serve MODEL --enable-chunked-prefill

問題：モデルが見つからないというエラーが発生する

カスタムモデルには --trust-remote-code を使用します。

vllm serve MODEL --trust-remote-code

問題：スループットが低い（<50 req/sec）

同時実行シーケンス数を増やします。

vllm serve MODEL --max-num-seqs 512

nvidia-smi で GPU 使用率を確認します。80% を超えている必要があります。

問題：推論が予想より遅い

テンソル並列処理で 2 のべき乗の GPU 数が使用されていることを確認します。

vllm serve MODEL --tensor-parallel-size 4  # Not 3

生成を高速化するには、投機的デコードを有効にします（設定は JSON として渡します。--speculative-model は削除され、代わりに --speculative-config が使用されます）。

vllm serve MODEL \
  --speculative-config '{"model": "DRAFT_MODEL", "num_speculative_tokens": 5, "method": "draft_model"}'

高度なトピック

サーバーのデプロイパターン：references/server-deployment.md で、Docker、Kubernetes、負荷分散の構成をご覧ください。

パフォーマンスの最適化：references/optimization.md で、PagedAttention のチューニング、継続的バッチ処理の詳細、ベンチマーク結果をご覧ください。

量子化ガイド：references/quantization.md で、AWQ/GPTQ/FP8 のセットアップ、モデルの準備、精度の比較をご覧ください。

トラブルシューティング：references/troubleshooting.md で、エラーメッセージの詳細、デバッグ手順、パフォーマンス診断をご覧ください。

ハードウェア要件

• 小規模モデル（7B-13B）：A10（24GB）または A100（40GB）1 枚
• 中規模モデル（30B-40B）：テンソル並列処理を使用する A100（40GB）2 枚
• 大規模モデル（70B 以上）：A100（40GB）4 枚または A100（80GB）2 枚。AWQ/GPTQ を使用してください

対応プラットフォーム：NVIDIA（主対応）、AMD ROCm、Intel GPU、TPU

リソース

• 公式ドキュメント：https://docs.vllm.ai
• GitHub：https://github.com/vllm-project/vllm
• 論文：「PagedAttention を用いた大規模言語モデルサービングのための効率的なメモリ管理」（SOSP 2023）
• コミュニティ：https://discuss.vllm.ai