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보다 작다.
    """
    # 토큰 하나당 KV Cache 바이트
    per_token_bytes = 2 * num_layers * num_kv_heads * head_dim * dtype_bytes
    # 블록 하나의 바이트
    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 비활성화로 메모리 사용 감소