vLLM PagedAttentionベースのLLMプロダクションサービング最適化と推論エンジン比較ガイド

従来の連続割り当て方式:
Request A: [████████░░░░░░░░░░░░░░░░░░░░░░░░]  実際512、最大2048を割り当て
Request B: [██████████████░░░░░░░░░░░░░░░░░░]  実際896、最大2048を割り当て
Request C: [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  実際128、最大2048を割り当て
→ 合計6,144スロット割り当て、実際の使用は1,536。無駄率75%

PagedAttentionブロック方式（ブロックサイズ = 16）:
Request A: [B0][B1]...[B31] → 32ブロックのみ割り当て（512トークン）
Request B: [B0][B1]...[B55] → 56ブロックのみ割り当て（896トークン）
Request C: [B0]...[B7]      →  8ブロックのみ割り当て（128トークン）
→ 最後のブロックの内部フラグメンテーションのみ存在。平均無駄率4%以下

def estimate_kv_cache_memory(
    num_layers: int,
    num_kv_heads: int,
    head_dim: int,
    max_seq_len: int,
    max_batch_size: int,
    dtype_bytes: int = 2,  # FP16
    block_size: int = 16,
) -> dict:
    """
    vLLM PagedAttentionベースのKV Cacheメモリ推定。
    GQAモデルではnum_kv_headsがnum_attention_headsより小さい。
    """
    # トークン1つあたりのKV Cacheバイト数
    per_token_bytes = 2 * num_layers * num_kv_heads * head_dim * dtype_bytes
    # ブロック1つのバイト数
    per_block_bytes = per_token_bytes * block_size
    # 最大同時処理時に必要な総ブロック数
    total_tokens = max_seq_len * max_batch_size
    total_blocks = (total_tokens + block_size - 1) // block_size
    total_bytes = total_blocks * per_block_bytes
    total_gb = total_bytes / (1024 ** 3)

    return {
        "per_token_kv_bytes": per_token_bytes,
        "per_block_kv_bytes": per_block_bytes,
        "total_blocks": total_blocks,
        "total_kv_cache_gb": round(total_gb, 2),
    }

# Llama 3.1 70B (GQA: 8 KV heads, 80 layers, head_dim=128)
result = estimate_kv_cache_memory(
    num_layers=80,
    num_kv_heads=8,
    head_dim=128,
    max_seq_len=4096,
    max_batch_size=64,
    dtype_bytes=2,
)
print(result)
# {'per_token_kv_bytes': 327680, 'per_block_kv_bytes': 5242880,
#  'total_blocks': 16384, 'total_kv_cache_gb': 80.0}
# → 64同時リクエスト × 4096トークンでKV Cacheだけで80GB必要

スタティックバッチング:
時間 →  ████████████████████████████████████
Req 1:  [■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■]  生成完了
Req 2:  [■■■■■■■■■■░░░░░░░░░░░░░░░░░░░░░░]  早期完了、待機中
Req 3:  [■■■■░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  早期完了、待機中
→ Req 2, 3の枠に新しいリクエストを投入できない

Continuous Batching:
時間 →  ████████████████████████████████████
Req 1:  [■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■]
Req 2:  [■■■■■■■■■■] ← 完了後即座にスロット返却
Req 4:             [■■■■■■■■■■■■■■■■■■■■■■]  ← 即座に投入
Req 3:  [■■■■] ← 完了
Req 5:       [■■■■■■■■■■■■■■] ← 即座に投入
→ GPUが常に最大負荷で動作

# 基本インストール（CUDA 12.4基準）
pip install vllm

# 特定バージョンのインストール
pip install vllm==0.7.2

# FlashInferバックエンド使用時（推奨）
pip install flashinfer-python
pip install vllm

# ソースからビルド（カスタムCUDAバージョン）
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

# インストール確認
python -c "import vllm; print(vllm.__version__)"

# 基本サーバー起動
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 1 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.90 \
  --enable-prefix-caching \
  --dtype auto

# 70Bモデルを4-GPU Tensor Parallelで実行
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.92 \
  --enable-prefix-caching \
  --max-num-seqs 256 \
  --disable-log-requests

from vllm import LLM, SamplingParams

# モデルのロード（自動的にPagedAttentionが適用される）
llm = LLM(
    model="meta-llama/Llama-3.1-8B-Instruct",
    tensor_parallel_size=1,
    max_model_len=4096,
    gpu_memory_utilization=0.90,
    enable_prefix_caching=True,
)

# サンプリングパラメータの設定
sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=1024,
    repetition_penalty=1.1,
    stop=["<|eot_id|>"],
)

# バッチ推論
prompts = [
    "KubernetesでGPUノードを管理するベストプラクティスを説明してください。",
    "Python asyncioのイベントループの動作原理を教えてください。",
    "PostgreSQLパーティショニング戦略の長所と短所を比較してください。",
]

outputs = llm.generate(prompts, sampling_params)
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt[:50]}...")
    print(f"Generated: {generated_text[:200]}...")
    print(f"Tokens: {len(output.outputs[0].token_ids)}")
    print("---")

# 公式イメージを使用したプロダクションデプロイ
docker run -d \
  --name vllm-server \
  --gpus '"device=0,1,2,3"' \
  --shm-size=16g \
  -p 8000:8000 \
  -v /data/models:/root/.cache/huggingface \
  -e HUGGING_FACE_HUB_TOKEN=${HF_TOKEN} \
  -e VLLM_ATTENTION_BACKEND=FLASHINFER \
  --restart unless-stopped \
  vllm/vllm-openai:v0.7.2 \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.92 \
  --enable-prefix-caching \
  --max-num-seqs 256 \
  --served-model-name llama-70b \
  --disable-log-requests \
  --uvicorn-log-level warning

# モデルを事前ダウンロードしてロード時間を短縮
huggingface-cli download meta-llama/Llama-3.1-70B-Instruct \
  --local-dir /data/models/llama-3.1-70b \
  --local-dir-use-symlinks False

# ローカルパスから直接ロード（ダウンロード不要）
vllm serve /data/models/llama-3.1-70b \
  --tensor-parallel-size 4 \
  --load-format safetensors \
  --max-model-len 8192

# Prefix Cachingの有効化（vLLM 0.7.xではデフォルト無効）
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --enable-prefix-caching \
  --max-model-len 8192

# Draftモデルを使用したSpeculative Decoding
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --speculative-model meta-llama/Llama-3.1-8B-Instruct \
  --num-speculative-tokens 5 \
  --speculative-disable-mqa-scorer \
  --tensor-parallel-size 4

# ngramベースのSpeculative Decoding（追加モデル不要）
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --speculative-model "[ngram]" \
  --num-speculative-tokens 5 \
  --ngram-prompt-lookup-max 4

# AWQ量子化モデルのサービング
vllm serve TheBloke/Llama-3.1-70B-Instruct-AWQ \
  --quantization awq \
  --tensor-parallel-size 2 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.90

# FP8量子化モデルのサービング（H100/L40SなどFP8対応GPU）
vllm serve neuralmagic/Llama-3.1-70B-Instruct-FP8 \
  --quantization fp8 \
  --tensor-parallel-size 4 \
  --max-model-len 8192

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-llama-70b
  namespace: llm-serving
  labels:
    app: vllm
    model: llama-70b
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
      model: llama-70b
  template:
    metadata:
      labels:
        app: vllm
        model: llama-70b
      annotations:
        prometheus.io/scrape: 'true'
        prometheus.io/port: '8000'
        prometheus.io/path: '/metrics'
    spec:
      terminationGracePeriodSeconds: 120
      containers:
        - name: vllm
          image: vllm/vllm-openai:v0.7.2
          args:
            - '--model'
            - 'meta-llama/Llama-3.1-70B-Instruct'
            - '--tensor-parallel-size'
            - '4'
            - '--max-model-len'
            - '8192'
            - '--gpu-memory-utilization'
            - '0.90'
            - '--enable-prefix-caching'
            - '--max-num-seqs'
            - '256'
            - '--served-model-name'
            - 'llama-70b'
            - '--disable-log-requests'
          ports:
            - containerPort: 8000
              name: http
          env:
            - name: HUGGING_FACE_HUB_TOKEN
              valueFrom:
                secretKeyRef:
                  name: hf-secret
                  key: token
            - name: VLLM_ATTENTION_BACKEND
              value: 'FLASHINFER'
          resources:
            requests:
              cpu: '8'
              memory: '32Gi'
              nvidia.com/gpu: '4'
            limits:
              cpu: '16'
              memory: '64Gi'
              nvidia.com/gpu: '4'
          volumeMounts:
            - name: model-cache
              mountPath: /root/.cache/huggingface
            - name: shm
              mountPath: /dev/shm
          startupProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 30
            periodSeconds: 10
            failureThreshold: 60 # モデルロードに最大10分を許容
          readinessProbe:
            httpGet:
              path: /health
              port: http
            periodSeconds: 5
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /health
              port: http
            periodSeconds: 15
            failureThreshold: 5
      volumes:
        - name: model-cache
          persistentVolumeClaim:
            claimName: model-cache-pvc
        - name: shm
          emptyDir:
            medium: Memory
            sizeLimit: 16Gi
      nodeSelector:
        nvidia.com/gpu.product: 'NVIDIA-A100-SXM4-80GB'
      tolerations:
        - key: nvidia.com/gpu
          operator: Exists
          effect: NoSchedule
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-llama-70b
  namespace: llm-serving
spec:
  selector:
    app: vllm
    model: llama-70b
  ports:
    - port: 8000
      targetPort: http
      name: http
  type: ClusterIP

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: vllm-scaler
  namespace: llm-serving
spec:
  scaleTargetRef:
    name: vllm-llama-70b
  minReplicaCount: 1
  maxReplicaCount: 8
  pollingInterval: 15
  cooldownPeriod: 300 # スケールダウン前に5分待機
  triggers:
    - type: prometheus
      metadata:
        serverAddress: http://prometheus.monitoring.svc:9090
        metricName: vllm_pending_requests
        query: |
          avg(vllm:num_requests_waiting{model_name="llama-70b"})
        threshold: '10'
    - type: prometheus
      metadata:
        serverAddress: http://prometheus.monitoring.svc:9090
        metricName: vllm_gpu_cache_usage
        query: |
          avg(vllm:gpu_cache_usage_perc{model_name="llama-70b"})
        threshold: '85'

# Prometheusクエリ例: Grafanaダッシュボード用

# 1. GPU KV Cache使用率（vLLM内部）
# vllm:gpu_cache_usage_perc{model_name="llama-70b"}

# 2. 実際のGPUメモリ使用量（DCGM）
# DCGM_FI_DEV_FB_USED{gpu="0"} / DCGM_FI_DEV_FB_TOTAL{gpu="0"} * 100

# 3. 待機リクエスト数の推移
# rate(vllm:num_requests_waiting{model_name="llama-70b"}[5m])

# 4. p99 TTFTモニタリング
# histogram_quantile(0.99, rate(vllm:time_to_first_token_seconds_bucket[5m]))

# 5. 毎秒生成トークン数
# rate(vllm:avg_generation_throughput_toks_per_s[1m])

# AlertManagerルール例
# ALERT VLLMHighCacheUsage
#   IF vllm:gpu_cache_usage_perc > 95
#   FOR 5m
#   LABELS { severity = "warning" }
#   ANNOTATIONS {
#     summary = "vLLM KV Cache使用率が95%を超過",
#     description = "{{ $labels.model_name }}モデルのKV Cache使用率が
#       {{ $value }}%です。スケールアップを検討してください。"
#   }

# OOMデバッグのためのメモリプロファイリング
VLLM_LOGGING_LEVEL=DEBUG vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --gpu-memory-utilization 0.85 \
  --max-model-len 4096 \
  --max-num-seqs 64 \
  --enforce-eager  # CUDA Graphを無効化してメモリ使用量を削減