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 forward passes (대형 모델)

Speculative Decoding:
Draft model (빠른 소형 모델): "The weather is sunny today" (5 토큰 추측)
Target model (1 forward pass): "The weather is sunny today" ✓ 전부 수락!
= 1 forward pass (소형 모델) + 1 forward pass (대형 모델)
→ 잠재적으로 2.5~3x 속도 향상

# 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 (10x 개선!)
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