serving-llms-vllm

vLLM - 高性能 LLM サービング

クイックスタート

vLLM は、PagedAttention（ブロック単位の KV キャッシュ）と継続的バッチ処理（prefill と decode のリクエストを混在させる）により、標準的な transformers と比べて 24 倍高いスループットを実現します。

インストール:

pip install vllm

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

from vllm import LLM, SamplingParams

llm = LLM(model="meta-llama/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/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/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/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/Llama-2-70b-hf \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.9 \
  --quantization awq \
  --port 8000

# For production with caching and metrics
vllm serve meta-llama/Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching \
  --enable-metrics \
  --metrics-port 9090 \
  --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 はポート 9090 で Prometheus メトリクスを公開します:

curl http://localhost:9090/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/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/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 のエコシステムを使用している場合

よくある問題

問題: モデルの読み込み中に OOM が発生する

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

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

または量子化を使用します:

vllm serve MODEL --quantization awq

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

繰り返し使われるプロンプトに対して prefix caching を有効にします:

vllm serve MODEL --enable-prefix-caching

長いプロンプトの場合は chunked prefill を有効にします:

vllm serve MODEL --enable-chunked-prefill

問題: Model not found エラー

カスタムモデルには --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

生成を高速化するために投機的デコーディングを有効にします:

vllm serve MODEL --speculative-model DRAFT_MODEL

応用トピック

サーバーのデプロイパターン: Docker、Kubernetes、ロードバランシングの構成については references/server-deployment.md を参照してください。

パフォーマンス最適化: PagedAttention のチューニング、継続的バッチ処理の詳細、ベンチマーク結果については references/optimization.md を参照してください。

量子化ガイド: AWQ/GPTQ/FP8 のセットアップ、モデルの準備、精度比較については references/quantization.md を参照してください。

トラブルシューティング: 詳細なエラーメッセージ、デバッグ手順、パフォーマンス診断については 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
• 論文：「Efficient Memory Management for Large Language Model Serving with PagedAttention」（SOSP 2023）
• コミュニティ：https://discuss.vllm.ai

エージェントの操作手順

1. 環境を確認します。 ハードウェア、フレームワークとサーバーのバージョン、モデル形式、想定負荷を確認します。
2. 入力を特定します。 データまたはユーザーに、形式、識別子、パラメーターを確認します。結果を変える値は推測せず、質問します。
3. まず小規模に実行します。 スケールアップする前に、単一のリクエストを処理または記録するか、エンドツーエンドで実行します。
4. 上記の手順と参考資料を使用して、タスク全体を実行します。
5. 結果を検証します。 レイテンシ、スループット、出力の正確性を参照値と照合して測定し、リソース使用量とコストを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を伝えます。

発生した場合	対応
サーバーが起動に失敗する、またはOOMが発生する	モデルサイズとメモリ、量子化、並列処理の設定を確認します。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適宜対応し、ユーザーに伝えます。APIを捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに質問するか、実行前に仮定を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計情報を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• サービスや認証情報を公開してはいけません。プロビジョニングの前にクラウド費用を確認します。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する操作、共有GPUやクラウドクォータを消費する操作、個人データや患者データに触れる操作、元に戻せない操作の前には、必ず確認します。

関連スキル

• tensorrt-llm：NVIDIA TensorRTを使用してLLMの推論を最適化し、スループットを最大化し、レイテンシを最小化します。
• awq-quantization：アクティベーションを考慮した重み量子化により、精度の損失を最小限に抑えながら、LLMを4ビットに圧縮して3倍高速化します。
• gptq：AutoGPTQとtransformersを使用し、グループ単位の量子化（デフォルトのグループサイズは128）でGPTQによりLLMを4ビット（3ビットにも対応）に量子化します。