vLLMプロダクションサービング最適化完全ガイド：PagedAttentionからKubernetesデプロイまで

従来のLLMサービング（HuggingFace Transformersなど）：
├─ 各リクエストに最大シーケンス長分の連続メモリを事前割り当て
├─ 実際のシーケンスが短くても最大長のメモリを占有 → 内部フラグメンテーション
├─ リクエスト間のメモリ共有不可 → 外部フラグメンテーション
└─ 結果：GPUメモリの60〜80%が無駄に

vLLM PagedAttention：
├─ KV Cacheを固定サイズブロック（例：16トークン）に分割
├─ ブロックは非連続メモリに保存可能
├─ 必要時にブロックを動的に割り当て/解放
├─ ブロックテーブルで論理→物理マッピングを管理
└─ 結果：GPUメモリの無駄を5%未満に削減

# PagedAttentionのブロックテーブル概念
# Logical Block → Physical Block マッピング

# Request 1: "The cat sat on the mat"
# Logical:  [Block 0] [Block 1]
# Physical: [GPU Block 3] [GPU Block 7]

# Request 2: "Hello world"
# Logical:  [Block 0]
# Physical: [GPU Block 1]

# システムプロンプトが同一の場合のCopy-on-Write：
# Request 3とRequest 4が同じシステムプロンプトを使用
# → システムプロンプトの物理ブロックを共有（追加メモリ消費なし）

静的バッチング（Static Batching）：
Time →
Req A: [████████████████████]     ← 生成完了
Req B: [████████]                 ← 早く終わったがAを待つ
Req C: [████████████]             ← Bより長いがAを待つ
       ↑ バッチ開始      ↑ バッチ終了（A完了時点）

Continuous Batching：
Time →
Req A: [████████████████████]
Req B: [████████] → Req Dが即座に開始: [████████████]
Req C: [████████████] → Req Eが即座に開始: [██████]
       ↑ リクエストが終わると即座に新しいリクエストでスロット交換

┌─────────────────────────────────────────────┐
│                 vLLM Engine                  │
├─────────────────────────────────────────────┤
│  API Server (OpenAI Compatible)              │
│  ├─ /v1/completions                          │
│  ├─ /v1/chat/completions                     │
│  └─ /v1/embeddings                           │
├─────────────────────────────────────────────┤
│  Scheduler                                   │
│  ├─ Continuous Batching                      │
│  ├─ Priority Queue                           │
│  └─ Preemption (Swap/Recompute)             │
├─────────────────────────────────────────────┤
│  KV Cache Manager (PagedAttention)           │
│  ├─ Block Allocator                          │
│  ├─ Block Table                              │
│  └─ Copy-on-Write                            │
├─────────────────────────────────────────────┤
│  Model Executor                              │
│  ├─ Tensor Parallelism (Ray/NCCL)           │
│  ├─ Quantization (GPTQ/AWQ/FP8)            │
│  └─ Speculative Decoding                    │
└─────────────────────────────────────────────┘

# 単一GPU（デフォルト）
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 1

# 4 GPUテンソル並列化
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4

# 8 GPU（A100 80GB x 8ノード）
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-405B-Instruct \
  --tensor-parallel-size 8 \
  --pipeline-parallel-size 1

# Speculative Decodingの有効化
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --speculative-model meta-llama/Llama-3.2-1B-Instruct \
  --num-speculative-tokens 5 \
  --speculative-draft-tensor-parallel-size 1

従来の自己回帰生成（1トークン/ステップ）：
Step 1 → "The"
Step 2 → "weather"
Step 3 → "is"
Step 4 → "sunny"
Step 5 → "today"
= 5回のフォワードパス（大規模モデル）

Speculative Decoding：
ドラフトモデル（高速小型モデル）: "The weather is sunny today"（5トークン推測）
ターゲットモデル（1回のフォワードパス）: "The weather is sunny today" ✓ 全て承認！
= 1回のフォワードパス（小型モデル） + 1回のフォワードパス（大規模モデル）
→ 潜在的に2.5〜3倍の速度向上

# Prefix Cachingの有効化
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --enable-prefix-caching

シナリオ：全リクエストが同一の2000トークンシステムプロンプトを使用

Prefix Caching無効：
Req 1: [システムプロンプト2000トークン処理] + [ユーザー入力処理] → TTFT: 500ms
Req 2: [システムプロンプト2000トークン再処理] + [ユーザー入力処理] → TTFT: 500ms
Req 3: [システムプロンプト2000トークン再処理] + [ユーザー入力処理] → TTFT: 500ms

Prefix Caching有効：
Req 1: [システムプロンプト2000トークン処理] + [ユーザー入力処理] → TTFT: 500ms
Req 2: [キャッシュヒット！] + [ユーザー入力処理] → TTFT: 50ms（10倍改善！）
Req 3: [キャッシュヒット！] + [ユーザー入力処理] → TTFT: 50ms

# Chunked Prefillの有効化
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --enable-chunked-prefill \
  --max-num-batched-tokens 2048

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  \
  # GPUメモリ設定
  --gpu-memory-utilization 0.90 \          # GPUメモリ使用比率（0.0〜1.0）
  --max-model-len 32768 \                  # 最大コンテキスト長
  \
  # バッチおよび同時実行設定
  --max-num-seqs 256 \                     # 同時処理最大シーケンス数
  --max-num-batched-tokens 32768 \         # バッチあたり最大トークン数
  \
  # 並列化設定
  --tensor-parallel-size 1 \               # テンソル並列GPU数
  --pipeline-parallel-size 1 \             # パイプライン並列ステージ数
  \
  # 量子化設定
  --quantization awq \                     # 量子化方式（awq, gptq, fp8など）
  --dtype auto \                           # データ型（auto, float16, bfloat16）
  \
  # サーバー設定
  --host 0.0.0.0 \
  --port 8000 \
  --api-key "your-secret-key"

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 512 \
  --max-model-len 4096 \
  --enable-prefix-caching \
  --enable-chunked-prefill

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --gpu-memory-utilization 0.85 \
  --max-num-seqs 32 \
  --max-model-len 8192 \
  --num-scheduler-steps 1

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --gpu-memory-utilization 0.92 \
  --max-num-seqs 16 \
  --max-model-len 131072 \
  --enable-chunked-prefill \
  --max-num-batched-tokens 4096

素早く始めたい場合？
→ vLLM（pip install vllm → すぐにサービング）

最大性能が必要な場合？
→ TensorRT-LLM（ただしモデル変換と設定に相当な労力が必要）

HuggingFaceエコシステムを既に使用中の場合？
→ TGI（HuggingFace Hubとの自然な統合）

エンタープライズデプロイが必要な場合？
→ Triton + TensorRT-LLM（NVIDIA公式サポート、マルチモデルサービング）

# Dockerで単一GPUデプロイ
docker run --runtime nvidia --gpus '"device=0"' \
  -v /path/to/model:/model \
  -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model /model \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192

# 4 GPUテンソル並列デプロイ
docker run --runtime nvidia --gpus '"device=0,1,2,3"' \
  -v /path/to/model:/model \
  -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model /model \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.9

# vllm-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-serving
  namespace: ml-serving
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm-serving
  template:
    metadata:
      labels:
        app: vllm-serving
    spec:
      containers:
        - name: vllm
          image: vllm/vllm-openai:latest
          args:
            - '--model'
            - 'meta-llama/Llama-3.1-8B-Instruct'
            - '--gpu-memory-utilization'
            - '0.9'
            - '--max-model-len'
            - '8192'
            - '--max-num-seqs'
            - '256'
            - '--enable-prefix-caching'
            - '--port'
            - '8000'
          ports:
            - containerPort: 8000
              name: http
          resources:
            limits:
              nvidia.com/gpu: 1
              memory: '32Gi'
              cpu: '8'
            requests:
              nvidia.com/gpu: 1
              memory: '16Gi'
              cpu: '4'
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 120
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 180
            periodSeconds: 30
          env:
            - name: VLLM_USAGE_SOURCE
              value: 'production'
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
  namespace: ml-serving
spec:
  selector:
    app: vllm-serving
  ports:
    - port: 80
      targetPort: 8000
      name: http
  type: ClusterIP
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: vllm-hpa
  namespace: ml-serving
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: vllm-serving
  minReplicas: 2
  maxReplicas: 8
  metrics:
    - type: Pods
      pods:
        metric:
          name: gpu_utilization
        target:
          type: AverageValue
          averageValue: '80'

# 複数モデルを同一クラスタでサービングする場合
# 各モデルに対して別々のvLLMインスタンス + 前段にルーターを配置

# router.py（簡単な例）
from fastapi import FastAPI, Request
import httpx

app = FastAPI()

MODEL_ENDPOINTS = {
    "llama-8b": "http://vllm-8b:8000",
    "llama-70b": "http://vllm-70b:8000",
    "codellama-34b": "http://vllm-code:8000",
}

@app.post("/v1/chat/completions")
async def route_request(request: Request):
    body = await request.json()
    model = body.get("model", "llama-8b")
    endpoint = MODEL_ENDPOINTS.get(model)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{endpoint}/v1/chat/completions",
            json=body,
            timeout=120.0
        )
        return response.json()

# 主要Prometheusメトリック
# vllm:num_requests_running - 現在処理中のリクエスト数
# vllm:num_requests_waiting - 待機中のリクエスト数
# vllm:gpu_cache_usage_perc - KV Cache GPU使用率
# vllm:cpu_cache_usage_perc - KV Cache CPUスワップ使用率
# vllm:avg_prompt_throughput_toks_per_s - プロンプト処理スループット
# vllm:avg_generation_throughput_toks_per_s - 生成スループット
# vllm:e2e_request_latency_seconds - E2Eリクエストレイテンシヒストグラム
# vllm:time_to_first_token_seconds - TTFTヒストグラム
# vllm:time_per_output_token_seconds - TBTヒストグラム

# prometheus-scrape-config.yaml
scrape_configs:
  - job_name: 'vllm'
    scrape_interval: 15s
    static_configs:
      - targets: ['vllm-service:8000']
    metrics_path: '/metrics'

# prometheus-alert-rules.yaml
groups:
  - name: vllm_alerts
    rules:
      - alert: HighKVCacheUsage
        expr: vllm_gpu_cache_usage_perc > 0.95
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: 'KV Cache使用率が95%を超えました'

      - alert: HighRequestLatency
        expr: histogram_quantile(0.99, vllm_e2e_request_latency_seconds_bucket) > 30
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: 'P99リクエストレイテンシが30秒を超えました'

      - alert: HighQueueDepth
        expr: vllm_num_requests_waiting > 100
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: '待機中のリクエストが100件を超えました'

# 1. gpu-memory-utilizationを下げる
--gpu-memory-utilization 0.80  # デフォルト0.9から下げる

# 2. max-model-lenを減らす
--max-model-len 4096  # 不必要に長いコンテキストを制限

# 3. max-num-seqsを減らす
--max-num-seqs 64  # 同時処理数を減少

# 4. 量子化を適用
--quantization awq  # またはgptq, fp8

# 5. テンソル並列化（GPU追加）
--tensor-parallel-size 2

# 1. 長いプロンプト → Chunked Prefillを有効化
--enable-chunked-prefill
--max-num-batched-tokens 2048

# 2. Prefix Cachingを有効化（繰り返しプロンプトがある場合）
--enable-prefix-caching

# 3. CUDAグラフ最適化を確認
# --enforce-eagerを削除（CUDAグラフを有効化）

# 4. モデルロードの最適化
--load-format auto  # 可能な場合safetensorsを使用

# 1. バッチサイズを確認
--max-num-seqs 256  # 小さすぎるとGPU活用率が低下

# 2. メモリ使用率を確認
--gpu-memory-utilization 0.92  # 保守的すぎるとバッチサイズが制限

# 3. Speculative Decodingを試行
--speculative-model <small-model> --num-speculative-tokens 5

# 4. 量子化を適用
--quantization awq  # またはfp8（A100/H100）

# 1. 最大トークン数を制限
# APIリクエスト時にmax_tokensを適切に設定

# 2. スワップ空間を確保
--swap-space 16  # CPUメモリへのスワップを許可

# 3. プリエンプション戦略を設定
--preemption-mode recompute  # またはswap

# NVIDIA H100でFP8量子化を活用
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --quantization fp8 \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.92

# FP8はINT8と比較して：
# - より高い精度（FP範囲を維持）
# - H100 FP8 Tensor Coreの活用で最大性能
# - 別途キャリブレーション不要

# ベースモデル + 複数LoRAアダプターの同時サービング
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --enable-lora \
  --lora-modules \
    korean-chat=/path/to/korean-lora \
    code-assist=/path/to/code-lora \
    medical-qa=/path/to/medical-lora \
  --max-loras 3 \
  --max-lora-rank 64

# vLLM内蔵ベンチマークツール
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct &

# スループットベンチマーク
python -m vllm.benchmark_throughput \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --input-len 512 \
  --output-len 128 \
  --num-prompts 1000

# レイテンシベンチマーク
python -m vllm.benchmark_latency \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --input-len 512 \
  --output-len 128 \
  --batch-size 1