vllm-server

vLLM サーバー管理

PagedAttention と継続的バッチ処理を備えた、最速のオープンソース LLM サービングエンジンである vLLM を使って、本番環境向けの LLM 推論サーバーをデプロイします。

このスキルを使う場面

次のような場合にこのスキルを使います。

• オープンソース LLM（Llama、Mistral、Qwen、Gemma）を大規模にサービングする
• セルフホストモデル向けに OpenAI 互換 API エンドポイントを構築する
• 本番環境のトラフィックに向けて LLM のスループットとレイテンシーを最適化する
• テンソル並列処理またはパイプライン並列処理を使ってマルチ GPU 推論を実行する
• GPU メモリ要件を減らすために量子化モデルをデプロイする

前提条件

• CUDA 12.1 以降を搭載した NVIDIA GPU（本番環境では A100/H100 を推奨）
• Docker または pip を使える Python 3.9 以降
• 70B モデルには 40GB 以上、7B モデルには 8GB 以上の VRAM
• Docker での GPU パススルーに必要な nvidia-container-toolkit

クイックスタート

# Install vLLM
pip install vllm

# Serve a model (OpenAI-compatible API)
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --api-key your-secret-key

# Test the endpoint
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Docker でのデプロイ

docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --api-key your-secret-key

Docker Compose（本番環境）

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - model-cache:/root/.cache/huggingface
    ports:
      - "8000:8000"
    ipc: host
    command: >
      --model meta-llama/Llama-3.1-70B-Instruct
      --tensor-parallel-size 2
      --max-model-len 32768
      --gpu-memory-utilization 0.90
      --api-key ${VLLM_API_KEY}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  model-cache:

主な設定オプション

マルチ GPU テンソル並列処理

# Split one model across 4 GPUs
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.90

量子化（VRAM の削減）

# AWQ quantization (70B on 2x A100 40GB)
vllm serve casperhansen/llama-3-70b-instruct-awq \
  --quantization awq \
  --tensor-parallel-size 2

# GPTQ quantization
vllm serve TheBloke/Llama-2-70B-Chat-GPTQ \
  --quantization gptq

# FP8 (H100 NVL native)
vllm serve meta-llama/Llama-3.1-405B-Instruct \
  --quantization fp8 \
  --tensor-parallel-size 8

構造化出力とツール

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --enable-auto-tool-choice \
  --tool-call-parser llama3_json \
  --guided-decoding-backend outlines

LoRA アダプター

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

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

# Maximize throughput for batch workloads
vllm serve <model> \
  --max-num-seqs 256 \          # max concurrent sequences
  --max-num-batched-tokens 8192 \ # tokens per batch
  --gpu-memory-utilization 0.95 \ # use 95% VRAM
  --swap-space 4                  # CPU swap (GiB)

# Minimize latency for interactive use
vllm serve <model> \
  --max-num-seqs 32 \
  --enforce-eager              # disable CUDA graph capture

ベンチマーク

# Install benchmark tool
pip install vllm

# Run throughput benchmark
python -m vllm.entrypoints.openai.run_batch \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --input-file prompts.jsonl \
  --output-file results.jsonl

# Benchmark with vllm bench
vllm bench throughput \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --num-prompts 1000 \
  --input-len 512 \
  --output-len 128

モニタリング

# Check running server stats
curl http://localhost:8000/metrics  # Prometheus metrics

# Key metrics to watch:
# vllm:num_requests_running       - active requests
# vllm:gpu_cache_usage_perc       - KV cache utilization
# vllm:generation_tokens_per_s    - throughput
# vllm:time_to_first_token_ms     - TTFT latency
# vllm:e2e_request_latency_seconds - end-to-end latency

よくある問題

問題	原因	対処方法
CUDA out of memory	モデルが VRAM に対して大きすぎる	--quantization awq を追加するか、--gpu-memory-utilization の値を下げます
コールドスタートが遅い	モデルがキャッシュされていない	huggingface-cli download <model> で事前にダウンロードします
スループットが低い	同時リクエスト数が少なすぎる	--max-num-seqs の値を増やします
KV キャッシュが満杯というエラー	コンテキスト長が長すぎる	--max-model-len の値を下げます
tokenizer error	トークナイザーが一致していない	--tokenizer を使って正しいトークナイザーを指定します

ベストプラクティス

• CUDA カーネル用に余裕を確保するため、--gpu-memory-utilization 0.90 を使います。
• 再現性のあるデプロイのため、--revision でモデルのバージョンを固定します。
• 予期しないダウンロードを防ぐため、本番環境では HF_HUB_OFFLINE=1 を設定します。
• テンソル並列処理を行う前に AWQ または GPTQ で量子化し、まず VRAM を削減します。
• 長いコンテキストを扱うワークロードでは --enable-chunked-prefill を有効にします。
• gpu_cache_usage_perc を監視します。95% を超えるとキューイングが発生します。

関連スキル

• llm-inference-scaling - vLLM デプロイメントの自動スケーリング
• gpu-server-management - GPU ドライバーのセットアップ
• llm-gateway - vLLM インスタンス間のロードバランシング
• llm-cost-optimization - コスト管理
• model-serving-kubernetes - K8s へのデプロイ