vLLM 面试题

OpenAI Compatible API Server (FastAPI / uvicorn)
    │
    ├── Scheduler（调度器）
    │   ├── 请求队列管理
    │   ├── Preemption 策略（Swap / Recomputation）
    │   └── Continuous Batching（连续批处理）
    │
    ├── LLM Engine（推理引擎）
    │   ├── Worker（GPU 推理执行单元）
    │   │   ├── Model Runner
    │   │   │   ├── PagedAttention Kernel
    │   │   │   ├── Quantization Layer（AWQ / GPTQ / FP8）
    │   │   │   └── CUDA Graph Capture
    │   │   └── KV Cache Manager
    │   │       ├── Block Table（页表）
    │   │       ├── Block Allocator（显存页分配器）
    │   │       └── Prefix Cache（前缀缓存）
    │   └── Parallel Execution
    │       ├── Tensor Parallelism（Megatron-LM）
    │       └── Pipeline Parallelism
    │
    ├── Tokenizer
    │   └── HuggingFace Tokenizer（fast）
    │
    └── Model Registry
        ├── HuggingFace Model Hub
        ├── AWQ / GPTQ 量化模型
        └── Custom Model Loader

传统 KV Cache（连续分配）        PagedAttention KV Cache（分页分配）

Block Table: Seq → Block[0], Block[2], Block[5]

```mermaid
graph LR
    subgraph 传统KVCache["传统 KV Cache（连续分配）"]
        A1["Seq A"] --- A2["████"]
        B1["Seq B"] --- B2["▓▓▓▓"]
        C1["Free"] --- C2["    "]
        D1["Seq C"] --- D2["░░░░"]
        E1["Waste"] --- E2["    "]
    end

    subgraph PagedAttention["PagedAttention KV Cache（分页分配）"]
        P0["Block 0\nKV A"] --- P1["Block 1\nFree"] --- P2["Block 2\nKV A"] --- P3["Block 3\nFree"]
    end

**关键数据结构：**

```python
# 页表结构（概念）
class BlockTable:
    block_size: int = 16          # 每个 Block 管理的 token 数
    blocks: List[KVCacheBlock]    # 物理 Block 池
    block_table: Dict[int, List[int]]  # seq_id → physical_block_ids

# PagedAttention Kernel
# 通过 block_table 索引访问非连续 KV Cache
# 每个 attention head 独立计算

graph LR
    subgraph 传统KVCache["传统 KV Cache（无共享）"]
        R1["Request 1:\nThe cat sat on the mat → 完整 KV Cache"]
        R2["Request 2:\nThe cat sat on the sofa → 完整 KV Cache"]
    end

    subgraph PagedAttention["PagedAttention（Block 级共享）"]
        Shared["共享 5 个 Block\nBlock The\nBlock cat\nBlock sat\nBlock on\nBlock the"]
        Shared --> R1B["Block mat"]
        Shared --> R2B["Block sofa"]
    end

Static Batching：
时间 ──────────────────────────────────────→
Batch 1: [Req A ████████████]
Batch 2: [Req B ████████████████████████]
Batch 3: [Req C ██████]

Req B 短序列在 Batch 2 中等待 A 完成 → 资源浪费

Continuous Batching：
时间 ──────────────────────────────────────→
Step 1: [Req A] [Req B] [Req C]
Step 2: [Req A] [Req B] [Req C]
Step 3: [Req A] [Req B]        ← Req C 完成，退出
Step 4: [Req A] [Req D] [Req E] ← 新请求即时加入
Step 5: [Req A] [Req D] [Req E]
Step 6: [Req D] [Req E]         ← Req A 完成
...

graph TD
    A["1. 请求到达"] --> B["2. 请求排队 Wait Queue"]
    B --> C["3. Scheduler 检查"]
    C --> C1["GPU 显存 Block 是否可用"]
    C --> C2["Token 预算是否允许<br/>max_num_batched_tokens"]
    C1 & C2 --> D{"资源可用？"}
    D -->|"可用"| E["4. 分配 Block"]
    E --> F["5. 加入 Running Batch"]
    D -->|"不可用"| G["Preemption 策略"]
    G --> G1["Swap out<br/>交换到 CPU"]
    G --> G2["Recomputation<br/>放弃 KV Cache 重新计算"]
    G1 & G2 --> H["6. 每步迭代"]
    H --> H1["所有 Running 请求执行<br/>一次 forward pass"]
    H --> H2["检查 EOS / Stop Token"]
    H --> H3["完成请求从 batch 移除"]
    H --> H4["释放 Block 回空闲池"]
    H1 & H2 & H3 & H4 --> I["7. 循环至步骤 2"]

graph TD
    Start["新请求到达，需要分配 Block"] --> Check["显存 Block 池有可用 Block？"]
    Check -->|是| Direct["直接分配"]
    Check -->|否| Preempt["触发 Preemption"]
    Preempt --> Victim["选择 victim 序列\n1. 最晚到达的序列（FIFO 逆序）\n2. 最长序列（释放更多 Block）\n3. 优先级最低"]
    Victim --> Swapping["Swapping\nKV Cache 交换到 CPU 内存"]
    Victim --> Recomputation["Recomputation\n放弃 KV Cache 重新计算"]

graph LR
    subgraph GPU["GPU 显存"]
        VKC["Victim KV Cache\nBlock 0\nBlock 3\nBlock 7"]
    end
    subgraph CPU["CPU 内存"]
        SB["Swapped Blocks\nBlock 0 copy\nBlock 3 copy\nBlock 7 copy"]
    end
    VKC -- "D2H 拷贝" --> SB

graph TD
    A["Victim 序列的 KV Cache<br/>全部释放"] --> B["新请求获得 Block 资源<br/>开始推理"]
    B --> C["Victim 序列恢复时"]
    C --> C1["完整重新执行 Prefill 阶段"]
    C --> C2["从 Checkpoint<br/>已生成 Token 重新 prefilling"]
    C --> C3["恢复原始 KV Cache Block"]
    C1 & C2 & C3 --> D["适用：Block 数较少<br/>重计算开销 小于 交换开销<br/>代价：额外计算开销"]

# 优先级：swap > recompute
--preemption-mode swap      # 仅交换
--preemption-mode recompute # 仅重计算
# 混合策略：swap 优先，swap 空间不足时用 recompute

Request A: [System Prompt][User Question A]
Request B: [System Prompt][User Question B]
Request C: [System Prompt][User Question C]

共享：3 个请求共享 System Prompt 对应的 KV Cache Block

Prefix Caching 流程：
1. 对新请求计算 Prefix 的 Hash
2. 在 Hash 表中查找已有 Block
   ├── 命中 → 引用已有 Block（引用计数 +1）
   └── 未命中 → 新分配 Block，计算 KV Cache，写入 Hash 表
3. 后续新 Token 继续新分配 Block

# 概念示例
class PrefixCache:
    def __init__(self):
        # hash(prefix_tokens) → [block_id, ...]
        self.cache: Dict[int, List[int]] = {}
        self.block_manager: BlockManager
    
    def get_or_compute(self, tokens: List[int]) -> List[int]:
        cached_blocks = []
        for i in range(0, len(tokens), block_size):
            block_tokens = tokens[i:i + block_size]
            block_hash = hash(tuple(block_tokens))
            if block_hash in self.cache:
                cached_blocks.append(self.cache[block_hash])
            else:
                # 计算并缓存
                break  # 前缀匹配中断，后续需重新计算
        return cached_blocks

# 启动时启用 Prefix Caching
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-8B-Instruct \
    --enable-prefix-caching

原始 FFN 层（单 GPU）：

Input [B, H]
    │
    ├── W_up [H, 4H]    → [B, 4H]
    │   ↓ SiLU
    │   Gate [H, 4H]    → [B, 4H]
    │   ↓
    │   ⊙ (element-wise)
    │   ↓
    └── W_down [4H, H]  → [B, H]

Tensor Parallel（2 GPU）：

GPU 0：                              GPU 1：
W_up_0 [H, 2H]                      W_up_1 [H, 2H]
    ↓                                    ↓
Gate_0 [H, 2H]                      Gate_1 [H, 2H]
    ↓                                    ↓
W_down_0 [2H, H]                    W_down_1 [2H, H]
    ↓                                    ↓
Y_0 [B, H]                          Y_1 [B, H]
    └──────────── All-Reduce ────────────┘
                       ↓
                   Y = Y_0 + Y_1

原始 Attention（32 heads）：
Q, K, V: [B, 32, seq_len, head_dim]

Tensor Parallel（4 GPU）：
GPU 0: heads 0-7   → Q, K, V
GPU 1: heads 8-15  → Q, K, V
GPU 2: heads 16-23 → Q, K, V
GPU 3: heads 24-31 → Q, K, V

每 GPU 独立计算 attention → All-Reduce 合并

# 双 GPU Tensor Parallel
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-70B-Instruct \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.90

# 指定 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-70B-Instruct \
    --tensor-parallel-size 4

原始模型（32 层）：
Layer 0 → Layer 1 → ... → Layer 31

Pipeline Parallel（4 GPU）：
GPU 0: Layer 0-7    ──→  GPU 1: Layer 8-15   ──→  GPU 2: Layer 16-23  ──→  GPU 3: Layer 24-31
      ↑ 接收 Input         ↑ 接收 GPU 0 hidden      ↑ 接收 GPU 1 hidden      ↑ 接收 GPU 2 hidden
      ↓ 发送 hidden        ↓ 发送 hidden            ↓ 发送 hidden            ↓ 发送 hidden → Output

Pipeline 时间线（4 GPU, 4 micro-batches）：

时间 ────────────────────────────────────→

GPU 0: [F0_B0][F0_B1][F0_B2][F0_B3] [...]
GPU 1:    [B0_B0][F1_B0][F1_B1][F1_B2][F1_B3][...]
GPU 2:       [B0_B1][B0_B0][F2_B0][F2_B1][F2_B2][F2_B3]
GPU 3:          [B0_B2][B0_B1][B0_B0][F3_B0][F3_B1][F3_B2]

F = Forward, B = Backward, N = GPU index, Bn = Batch n

气泡（Bubble）：流水线启动和排空期间 GPU 空闲时间
Bubble Ratio ≈ (PP_size - 1) / num_micro_batches

# 8 GPU：TP=2 × PP=4
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-405B-Instruct \
    --tensor-parallel-size 2 \
    --pipeline-parallel-size 4

GPU 0 ←─→ GPU 1    （TP Group 0, Layer 0-7）
  ↓ NVLink            ↓ NVLink
GPU 2 ←─→ GPU 3    （TP Group 1, Layer 8-15）
  ↓ NVLink            ↓ NVLink
GPU 4 ←─→ GPU 5    （TP Group 2, Layer 16-23）
  ↓ NVLink            ↓ NVLink
GPU 6 ←─→ GPU 7    （TP Group 3, Layer 24-31）

TP 组内：NVLink 高速通信
PP 组间：P2P send/recv

AWQ 原理：
1. 分析各 Channel 的 Activation 分布
2. 根据 Activation 重要性对权重加缩放因子
3. 对高 Activation Channel 用更高精度
4. 量化前进行 Channel-wise Scaling

量化流程：
W_FP16 ──→ 分析 Activation 分布 ──→ 计算 Saliency ──→ Scaling ──→ W_INT4

# AWQ 量化模型
python -m vllm.entrypoints.openai.api_server \
    --model TheBloke/Llama-3-8B-Instruct-AWQ \
    --quantization awq \
    --dtype auto

# GPTQ 量化模型
python -m vllm.entrypoints.openai.api_server \
    --model TheBloke/Llama-3-8B-Instruct-GPTQ \
    --quantization gptq \
    --dtype auto

# FP8 量化（H100/H200）
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-70B-Instruct \
    --quantization fp8 \
    --dtype auto

# INT8 量化
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-8B-Instruct-INT8 \
    --quantization int8 \
    --dtype auto

# bitsandbytes INT4
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-8B-Instruct \
    --load-format bitsandbytes \
    --quantization bitsandbytes

python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --served-model-name qwen2.5-7b \
    --host 0.0.0.0 \
    --port 8000 \
    --api-key sk-vllm-secret \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.90 \
    --tensor-parallel-size 1

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="sk-vllm-secret",
)

# Chat Completions
response = client.chat.completions.create(
    model="qwen2.5-7b",
    messages=[
        {"role": "system", "content": "你是一个运维专家"},
        {"role": "user", "content": "如何排查 GPU OOM？"},
    ],
    temperature=0.7,
    max_tokens=1024,
    stream=True,
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

# /v1/models
models = client.models.list()
for m in models:
    print(m.id)

# 单进程仅支持单个模型，多模型需启动多个实例
# 搭配 Nginx / Envoy 做路由

upstream vllm-qwen {
    server localhost:8001;
}
upstream vllm-llama {
    server localhost:8002;
}

# LiteLLM Proxy 统一路由多个 vLLM 实例
# litellm --model qwen2.5-7b --api_base http://localhost:8001
# litellm --model llama-3-8b --api_base http://localhost:8002

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-qwen25-7b
  labels:
    app: vllm
    model: qwen2.5-7b
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vllm
      model: qwen2.5-7b
  template:
    metadata:
      labels:
        app: vllm
        model: qwen2.5-7b
    spec:
      nodeSelector:
        nvidia.com/gpu.product: NVIDIA-A100-SXM4-80GB
      containers:
        - name: vllm
          image: vllm/vllm-openai:v0.7.2
          command:
            - python3
            - -m
            - vllm.entrypoints.openai.api_server
          args:
            - --model
            - Qwen/Qwen2.5-7B-Instruct
            - --served-model-name
            - qwen2.5-7b
            - --host
            - "0.0.0.0"
            - --port
            - "8000"
            - --max-model-len
            - "8192"
            - --gpu-memory-utilization
            - "0.90"
            - --tensor-parallel-size
            - "1"
            - --dtype
            - auto
          ports:
            - containerPort: 8000
              name: http
          env:
            - name: CUDA_VISIBLE_DEVICES
              value: "0"
            - name: VLLM_API_KEY
              valueFrom:
                secretKeyRef:
                  name: vllm-api-key
                  key: api-key
            - name: HF_HOME
              value: /model-cache
          resources:
            limits:
              nvidia.com/gpu: 1
              memory: 64Gi
            requests:
              nvidia.com/gpu: 1
              memory: 32Gi
          volumeMounts:
            - name: model-cache
              mountPath: /model-cache
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 60
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 120
            periodSeconds: 30
      volumes:
        - name: model-cache
          persistentVolumeClaim:
            claimName: model-cache-pvc
apiVersion: v1
kind: Service
metadata:
  name: vllm-qwen25-7b
spec:
  selector:
    app: vllm
    model: qwen2.5-7b
  ports:
    - port: 8000
      targetPort: 8000
  type: ClusterIP
apiVersion: v1
kind: Secret
metadata:
  name: vllm-api-key
type: Opaque
stringData:
  api-key: "sk-production-secret-key"

graph TD
    Internet["Internet"] --> Ingress["Ingress / LoadBalancer"]
    Ingress --> APIGateway["API Gateway (nginx / envoy)"]
    APIGateway --> V1["vllm-1\n(qwen2.5-7b)\nGPU: A100"]
    APIGateway --> V2["vllm-2\n(qwen2.5-7b)\nGPU: A100"]
    APIGateway --> V3["vllm-3\n(qwen2.5-7b)\nGPU: A100"]
    V1 --> Monitor["Prometheus + Grafana\n监控 TTFT / TPOT / Throughput"]
    V2 --> Monitor
    V3 --> Monitor

GPU 显存总容量（如 A100-80GB = 80 GiB）
    │
    ├── CUDA Context / Driver Overhead（~0.5-1 GiB）
    │
    ├── 模型权重区（不可压缩）
    │   ├── FP16 权重：参数量 × 2 bytes
    │   ├── 量化权重：参数量 × (quant bits / 8) bytes
    │   └── 示例：Llama-3-70B FP16 → ~140 GiB（需要 TP）
    │
    ├── KV Cache Block 池（可配置）
    │   ├── Block 数 = (总显存 - 模型权重) × gpu_memory_utilization / block_size_bytes
    │   ├── 每个 Block 大小 = num_layers × num_kv_heads × head_dim × 2(K+V) × block_size × 2 bytes
    │   └── Block 不足时触发 Preemption
    │
    └── 临时工作区（CUDA Kernels，activation buffer）
        ├── 中间 Activation 值（每层计算）
        └── NCCL 通信 Buffer（TP/PP 场景）

Llama-3-8B, A100-40GB, max_model_len=8192, block_size=16

1. 权重显存：
   8B params × 2 bytes = 16 GiB

2. 可用显存：
   40 GiB - 16 GiB - 1 GiB (overhead) = 23 GiB

3. 有效 KV Cache 池（gpu_memory_utilization=0.90）：
   23 GiB × 0.90 = 20.7 GiB

4. 每 Block 大小：
   layers=32, num_kv_heads=8, head_dim=128
   每 Block = 32 × 8 × 128 × 2 × 16 × 2 bytes = 2,097,152 bytes ≈ 2 MiB

5. 最大 Block 数：
   20.7 GiB / 2 MiB ≈ 10,598 Blocks

6. 最大并发序列数（每序列平均 512 tokens = 32 Blocks）：
   10,598 / 32 ≈ 331 条序列（含 Prefill + Decode）

传统 Prefill（长 Prompt 阻塞其他请求）：

GPU ──┬──────────────────────────────────────┬──────────┬──────────┬─────
      │  Prefill Req A (long, 4096 tokens)  │ Decode A │ Decode B │ ...
      └──────────────────────────────────────┴──────────┴──────────┴─────
      其他请求在此期间全部排队等待 ← 首 Token 延迟高

Chunked Prefill（交替执行）：

GPU ──┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬─────
      │  C1  │  D1  │  C2  │  D2  │  D3  │  C3  │  D4  │  D5  │ ...
      └──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴─────
      C = Prefill Chunk（计算 Prompt KV Cache）
      D = Decode Step（生成下一个 Token）
      
      Prefill 分散到多步执行，Decode 请求不被阻塞

每步调度决策：

1. 计算当前 Batch 的可用 Token 预算：
   token_budget = max_num_batched_tokens - current_batch_tokens

2. 如果有待 Prefill 请求：
   ┌── 拆分 Prefill 为 Chunk
   │   chunk_size = min(token_budget, (max_num_batched_tokens / num_prefill_requests))
   │   prefill_chunk = prompt[offset : offset + chunk_size]
   └── 将 Chunk 加入当前 Step

3. 剩余 Token 预算分配给 Decode 请求

4. 记录 Prefill 进度（offset），下一步继续

5. Prefill 完成后，请求转为 Decode 状态

python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --enable-chunked-prefill \
    --max-num-batched-tokens 8192

1. Draft Model 快速推测 K 个 Token（如 K=5）：
   Draft Model（小模型，~100M）→ [T1, T2, T3, T4, T5]

2. Target Model 并行验证：
   Target Model（大模型，~70B）
   一次 Forward Pass 计算 [T1, T2, T3, T4, T5] 的概率分布

3. Rejection Sampling 接受/拒绝：
   对每个 Ti：
   ┌── 如果 P_target(Ti) ≥ P_draft(Ti) → 接受 Ti
   └── 如果 P_target(Ti) < P_draft(Ti) → 以概率 P_target/P_draft 接受
       否则拒绝并从 Ti 位置重新采样

4. 更新 KV Cache，继续下一轮推测

# Draft Model 方式
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-70B-Instruct \
    --speculative-model TinyLlama/TinyLlama-1.1B-Chat-v1.0 \
    --num-speculative-tokens 5 \
    --speculative-draft-tensor-parallel-size 1

Base Model（共享，不可变）
    │
    ├── Attention Layer
    │   ├── Q_proj: W_base
    │   ├── K_proj: W_base
    │   ├── V_proj: W_base
    │   └── O_proj: W_base
    │
    └── FFN Layer
        ├── Gate: W_base
        ├── Up: W_base
        └── Down: W_base

LoRA Adapter 1: Q_adapt1, V_adapt1       （任务 A）
LoRA Adapter 2: Q_adapt2, V_adapt2       （任务 B）
LoRA Adapter 3: Gate_adapt3, Down_adapt3 （任务 C）

每请求计算：output = W_base(x) + LoRA_A(LoRA_B(x)) × scaling

python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-8B-Instruct \
    --enable-lora \
    --lora-modules \
        sql-lora=/path/to/sql-lora-adapter \
        code-lora=/path/to/code-lora-adapter \
        medical-lora=/path/to/medical-lora-adapter \
    --max-lora-rank 64 \
    --max-loras 32 \
    --max-cpu-loras 64

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="sk-vllm-secret",
)

# 使用 code-lora 适配器生成代码
response = client.chat.completions.create(
    model="code-lora",
    messages=[{"role": "user", "content": "写一个快速排序的 Python 实现"}],
    max_tokens=512,
)

# LLaVA-1.5
python -m vllm.entrypoints.openai.api_server \
    --model llava-hf/llava-1.5-7b-hf \
    --max-model-len 4096 \
    --limit-mm-per-prompt image=5

# Qwen2-VL
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2-VL-7B-Instruct \
    --max-model-len 8192 \
    --limit-mm-per-prompt image=10 \
    --mm-processor-kwargs '{"max_pixels": 1003520}'

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="sk-vllm-secret",
)

response = client.chat.completions.create(
    model="Qwen2-VL-7B-Instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}},
                {"type": "text", "text": "这张图片描述了什么？"},
            ],
        }
    ],
    max_tokens=512,
)

graph TD
    REQ["请求到达"] --> WAIT["Wait Queue"]
    WAIT --> EVAL["Scheduler 评估"]
    EVAL --> C1["Token 预算是否允许"]
    EVAL --> C2["Block 是否可用"]
    EVAL --> C3["是否达到 max_num_seqs"]
    EVAL --> C4["是否达到 max_lora_served"]
    C1 & C2 & C3 & C4 --> DECISION{"可调度？"}
    DECISION -->|"可调度"| ALLOC["分配 Block<br/>加入 Running"]
    DECISION -->|"不可调度"| RETRY["继续等待<br/>或触发 Preemption"]
    ALLOC --> GEN["生成 Token<br/>检查 EOS/Stop"]
    GEN --> DONE_DECISION{"完成？"}
    DONE_DECISION -->|"完成"| RELEASE["释放 Block<br/>返回 Response"]
    DONE_DECISION -->|"继续"| GEN

python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --max-num-seqs 256 \
    --max-num-batched-tokens 8192 \
    --max-num-partial-prefills 1 \
    --scheduler-delay-factor 0.0

Ray Cluster
    │
    ├── Head Node（Driver Process）
    │   ├── Ray Head（GCS, Dashboard）
    │   └── OpenAI API Server
    │
    ├── Worker Node 1（4×A100-80G）
    │   ├── Ray Worker 1 → vLLM Worker (TP=2, GPU 0-1)
    │   ├── Ray Worker 2 → vLLM Worker (TP=2, GPU 2-3)
    │   └── Ray Worker 3 → vLLM Worker (PP stage 1)
    │
    └── Worker Node 2（4×A100-80G）
        ├── Ray Worker 4 → vLLM Worker (TP=2, GPU 0-1)
        ├── Ray Worker 5 → vLLM Worker (TP=2, GPU 2-3)
        └── Ray Worker 6 → vLLM Worker (PP stage 2)

# 1. 启动 Ray 集群
ray start --head --port=6379
ray start --address='<head-ip>:6379' --num-gpus=4

# 2. 多节点推理
python -m vllm.entrypoints.openai.api_server \
    --model deepseek-ai/DeepSeek-V3 \
    --tensor-parallel-size 2 \
    --pipeline-parallel-size 4 \
    --distributed-executor-backend ray \
    --gpu-memory-utilization 0.90

节点间通信：
├── NCCL over RDMA（InfiniBand / RoCEv2）
│   延迟 ~1-3 μs，带宽 200-400 GB/s
├── NCCL over TCP（以太网）
│   延迟 ~20-50 μs，带宽 25-100 Gbps
└── GLOO（备份后端）

TP 组内通信模式：
├── All-Reduce（每层 2 次）
├── All-Gather（Attention 输出合并）
└── Reduce-Scatter（部分场景）

# 安装 benchmark 工具
pip install vllm[benchmark]

# 离线基准测试（不需要启动 API Server）
python -m vllm.entrypoints.openai.run_batch \
    --model Qwen/Qwen2.5-7B-Instruct \
    --input-len 1024 \
    --output-len 512 \
    --num-prompts 100

# 在线服务性能测试
python benchmarks/benchmark_serving.py \
    --backend vllm \
    --model Qwen/Qwen2.5-7B-Instruct \
    --dataset-name sharegpt \
    --dataset-path ShareGPT_V3_unfiltered_cleaned_split.json \
    --num-prompts 1000 \
    --request-rate 4.0

# benchmark_serving.py 关键参数
--request-rate        # 每秒发送请求数（控制 QPS）
--num-prompts         # 总请求数量
--burstiness          # 请求突发性系数
--seed                # 随机种子（可复现）
--result-filename     # 结果输出 JSON 文件
--percentile-metrics  # 分位数指标（如 "ttft_p99,tpot_p95"）

# prometheus.yml
scrape_configs:
  - job_name: "vllm"
    scrape_interval: 15s
    static_configs:
      - targets:
          - "vllm-1:8000"
          - "vllm-2:8000"
        labels:
          cluster: "production"
          model: "qwen2.5-7b"

# KV Cache 使用率
rate(vllm:gpu_cache_usage_perc[5m])

# TTFT P99
histogram_quantile(0.99, rate(vllm:time_to_first_token_seconds_bucket[5m]))

# TPOT P50
histogram_quantile(0.50, rate(vllm:time_per_output_token_seconds_bucket[5m]))

# 吞吐量（每秒 Token）
sum(rate(vllm:request_generation_tokens_sum[1m]))

# 排队请求数
vllm:num_requests_waiting

# Prefix Cache 命中率
sum(rate(vllm:prefix_cache_hit_total[5m]))
  /
sum(rate(vllm:prefix_cache_query_total[5m]))
* 100

# 环境变量控制日志级别
export VLLM_LOGGING_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR
export VLLM_TRACE_FUNCTION=1     # 启用函数调用追踪

# 方式 1：命令行指定
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --api-key sk-vllm-production-secret

# 方式 2：环境变量
export VLLM_API_KEY="sk-vllm-production-secret"
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct

# 请求头 Authorization: Bearer sk-vllm-production-secret
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="sk-vllm-production-secret",
)

graph TD
    A["Client"] --> B["TLS Termination<br/>nginx / envoy"]
    B --> B1["验证 API Key"]
    B --> B2["速率限制"]
    B --> B3["请求日志"]
    B1 & B2 & B3 --> C["vLLM Server<br/>不对外暴露<br/>仅内网可访问"]

upstream vllm_backend {
    server vllm-1:8000 max_fails=3 fail_timeout=30s;
    server vllm-2:8000 max_fails=3 fail_timeout=30s;
}

# 速率限制
limit_req_zone $binary_remote_addr zone=vllm_limit:10m rate=10r/s;

server {
    listen 443 ssl;
    ssl_certificate     /etc/ssl/certs/vllm.crt;
    ssl_certificate_key /etc/ssl/private/vllm.key;

    location /v1/ {
        limit_req zone=vllm_limit burst=20 nodelay;
        proxy_pass http://vllm_backend;
        proxy_set_header Host $host;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;

        # 移除客户端 API Key，使用服务端固定 Key
        proxy_set_header Authorization "Bearer sk-vllm-internal";
    }
}

response = client.chat.completions.create(
    model="qwen2.5-7b",
    messages=[{"role": "user", "content": "写一首关于秋天的诗"}],
    temperature=0.9,
    top_p=0.95,
    top_k=50,
    repetition_penalty=1.1,
    frequency_penalty=0.3,
    presence_penalty=0.2,
    max_tokens=256,
    seed=42,
    stop=["</s>", "###"],
)

Repetition Penalty 工作方式：
对于已生成的 Token t，其 logits 除以 repetition_penalty

logits_penalized[t] = logits[t] / repetition_penalty  （repetition_penalty > 1.0）

效果：
- repetition_penalty = 1.0: 无惩罚
- repetition_penalty = 1.1: 轻微惩罚
- repetition_penalty = 1.2: 中度惩罚（常见推荐值）
- repetition_penalty = 1.5: 强力惩罚（可能影响流畅度）

Frequency Penalty 工作方式：
logits[t] = logits[t] - frequency_penalty × count(t)

Presence Penalty 工作方式：
logits[t] = logits[t] - presence_penalty × (1 if count(t) > 0 else 0)

Client                           vLLM Server
  │                                   │
  │──→ POST /v1/chat/completions      │
  │    {"stream": true, ...}           │
  │                                    │
  │←── data: {"choices":[{"delta":     │
  │    {"role":"assistant"},"index":0}]│}
  │                                    │
  │←── data: {"choices":[{"delta":     │
  │    {"content":"你"},"index":0}]}   │
  │                                    │
  │←── data: {"choices":[{"delta":     │
  │    {"content":"好"},"index":0}]}   │
  │                                    │
  │←── ...                             │
  │                                    │
  │←── data: {"choices":[{"delta":     │
  │    {"content":"。"},"index":0},    │
  │    "finish_reason":"stop"}]}       │
  │                                    │
  │←── data: [DONE]                    │

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="sk-vllm-secret")

stream = client.chat.completions.create(
    model="qwen2.5-7b",
    messages=[{"role": "user", "content": "解释 Kubernetes Operator 模式"}],
    stream=True,
    stream_options={"include_usage": True},  # 可以获取 usage 统计
)

full_response = ""
for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta
        if delta.content:
            print(delta.content, end="", flush=True)
            full_response += delta.content
    if hasattr(chunk, "usage") and chunk.usage:
        print(f"\n--- Usage: {chunk.usage}")

# 使用 httpx / aiohttp 直接处理 SSE
# 流解析时需要考虑 network chunk 与 SSE event 不是一一映射

import time
import random
from openai import OpenAI, APIError, APITimeoutError, APIConnectionError

def retry_chat_completion(client, max_retries=3, base_delay=1.0, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except APITimeoutError:
            if attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)
        except APIConnectionError:
            if attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt)
            time.sleep(delay)
        except APIError as e:
            if e.status_code == 503 and attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt) + random.uniform(0, 2)
                time.sleep(delay)
            else:
                raise

# vLLM 收到 SIGTERM 后的行为：
# 1. 停止接受新请求
# 2. 等待现有请求完成（或超时）
# 3. 释放 GPU 显存
# 4. 退出进程

# Kubernetes Pod Graceful Shutdown 配置
spec:
  terminationGracePeriodSeconds: 120
  containers:
    - name: vllm
      lifecycle:
        preStop:
          exec:
            # SIGTERM 前先通知 LoadBalancer 摘除
            command: ["/bin/sh", "-c", "sleep 15"]

# 保守的显存配置
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --gpu-memory-utilization 0.85 \
    --max-model-len 4096 \
    --enforce-eager \           # 禁用 CUDA Graph（节省部分显存）
    --max-num-seqs 128          # 限制最大并发

GPU 显存约束：

total_gpu_mem × gpu_memory_utilization
    = model_weights_mem
    + kv_cache_block_pool_mem
    + workspace_mem

kv_cache_block_pool_mem
    ≈ max_num_seqs × max_model_len / block_size × block_bytes

推论：
- max_model_len ↑ → 每序列最多 Block 数 ↑ → 可支持的 max_num_seqs ↓
- max_num_seqs ↑ → 总并行序列 ↑ → 每序列最大长度 ↓
- block_size 固定时，显存限制了一条帕累托前沿

1. 分析业务流量特征：
   ├── 绝大多数请求 Prompt 长度？
   ├── 是否需要长上下文（RAG、文档分析）？
   └── 并发量级预估？

2. 确定 max_model_len：
   └── max_model_len = P99 请求长度 × 1.2（安全余量）

3. 计算 Block 容量：
   总 Block 数 = kv_cache_pool_mem / block_bytes
   每序列 Block 数 = max_model_len / block_size
   理论最大并发 = 总 Block 数 / 每序列 Block 数

4. 设置 max_num_seqs：
   └── max_num_seqs = min(256, 理论最大并发 × 0.8)

5. 压测验证：
   └── 固定 max_model_len，逐渐增加并发，观察显存 Usage 和延迟

PagedAttention（vLLM）：
Block 表管理，Hash 查找前缀缓存

RadixAttention（SGlang）：
Radix Tree 组织 KV Cache，自动前缀匹配

           root
        /   |    \
      "你" "我" "请"
      /       \
    "好"      "是"
              /  \
           "AI"  "谁"

同一路径共享 KV Cache，新请求自动匹配最长前缀

SGlang 调度器优先调度共享前缀的请求到同一 Batch：
- 最大化 Prefix Cache 命中率
- 减少冗余 Prefill 计算
- 对 Chat 多轮对话和 Batch API 场景显著提升吞吐

# SGlang 结构化生成
import sglang as sgl

@sgl.function
def multi_turn_qa(s, question):
    s += sgl.system("你是一个运维专家")
    s += sgl.user(question)
    s += sgl.assistant(sgl.gen("answer", max_tokens=256))

# 约束生成（JSON 模式）
@sgl.function
def extract_info(s, text):
    s += sgl.user(f"Extract from: {text}")
    s += sgl.gen("json", regex=r'\{"name": "\w+", "age": \d+\}')

vLLM：
1. pip install vllm
2. python -m vllm.entrypoints.openai.api_server --model xxx
（1 分钟内完成）

TensorRT-LLM：
1. git clone TensorRT-LLM + 编译 C++ 库
2. 编写模型配置（config.json）
3. 用 checkpoint 构建 TRT Engine（5-30 分钟）
4. 启动 Triton Inference Server
5. 加载 TRT Engine
（首次 >30 分钟）

AWQ 离线量化：

1. 准备校准数据（代表性样本，通常 128-256 条）
2. AutoAWQ 分析每层的 Activation 分布
3. 计算 Channel-wise Saliency（显着性）
4. 应用 Scaling Factor 保护重要 Channel
5. 对 Weights 执行 INT4 量化
6. 保存量化模型（兼容 HF 格式）

GPTQ 离线量化：

1. 准备校准数据
2. AutoGPTQ 逐层量化
3. 对每层使用 Optimal Brain Quantization（OBQ）算法
4. 量化后进行调整以补偿误差
5. 保存量化模型

from awq import AutoAWQForCausalLM
from transformers import AutoTokenizer

model_path = "Qwen/Qwen2.5-7B-Instruct"
quant_path = "Qwen2.5-7B-Instruct-AWQ"

# 加载模型
model = AutoAWQForCausalLM.from_pretrained(
    model_path,
    low_cpu_mem_usage=True,
    use_cache=False,
)
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)

# 量化配置
quant_config = {
    "zero_point": True,
    "q_group_size": 128,
    "w_bit": 4,
    "version": "GEMM",
}

# 加载校准数据
from datasets import load_dataset
calib_data = load_dataset("mit-han-lab/pile-val-backup", split="validation")

# 执行量化
model.quantize(
    tokenizer,
    quant_config=quant_config,
    calib_data=calib_data,
)

# 保存
model.save_quantized(quant_path)
tokenizer.save_pretrained(quant_path)

from auto_gptq import AutoGPTQForCausalLM, BaseQuantizeConfig
from transformers import AutoTokenizer

model_path = "Qwen/Qwen2.5-7B-Instruct"
quant_path = "Qwen2.5-7B-Instruct-GPTQ"

tokenizer = AutoTokenizer.from_pretrained(model_path, use_fast=True)

# GPTQ 量化配置
quantize_config = BaseQuantizeConfig(
    bits=4,                # 4-bit 量化
    group_size=128,        # Group Size
    damp_percent=0.01,     # 阻尼因子
    desc_act=False,        # 是否按 Activation 排序
    sym=True,              # 对称量化
    true_sequential=True,  # 逐层量化
)

# 加载模型
model = AutoGPTQForCausalLM.from_pretrained(
    model_path,
    quantize_config=quantize_config,
)

# 加载校准数据
from datasets import load_dataset
calib_dataset = load_dataset("wikitext", "wikitext-2-raw-v1", split="test")
examples = [tokenizer(ex["text"]) for ex in calib_dataset.select(range(128))]

# 执行量化
model.quantize(examples)

# 保存
model.save_quantized(quant_path)
tokenizer.save_pretrained(quant_path)

# AWQ
python -m vllm.entrypoints.openai.api_server \
    --model ./Qwen2.5-7B-Instruct-AWQ \
    --quantization awq \
    --dtype auto

# GPTQ
python -m vllm.entrypoints.openai.api_server \
    --model ./Qwen2.5-7B-Instruct-GPTQ \
    --quantization gptq \
    --dtype auto

# Docker 方式（推荐）
docker run --rm -it \
    --device=/dev/kfd --device=/dev/dri \
    --group-add video \
    vllm/vllm-openai:rocm \
    python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --dtype auto \
    --tensor-parallel-size 1

# 或直接 pip 安装（ROCm 环境）
pip install vllm
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct

# Gaudi 基础镜像
docker pull vault.habana.ai/gaudi-docker/1.18.0/ubuntu22.04/habanalabs/pytorch-installer-2.4.0:latest

# vLLM 需从源码编译
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --device hpu

# 生产 Dockerfile 示例
FROM vllm/vllm-openai:v0.7.2

ENV VLLM_LOGGING_LEVEL=INFO
ENV CUDA_MODULE_LOADING=LAZY
ENV OMP_NUM_THREADS=1

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# 非 root 运行
USER 1000:1000

ENTRYPOINT ["python3", "-m", "vllm.entrypoints.openai.api_server"]

python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-72B-Instruct \
    --served-model-name qwen2.5-72b \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.90 \
    --max-model-len 8192 \
    --max-num-seqs 128 \
    --enable-prefix-caching \
    --enable-chunked-prefill \
    --max-num-batched-tokens 8192 \
    --swap-space 4 \
    --dtype auto \
    --api-key sk-production-secret \
    --disable-log-requests \
    --disable-log-stats

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-prod
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    spec:
      # 反亲和：分布到不同节点
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchLabels:
                  app: vllm
              topologyKey: kubernetes.io/hostname
      # 服务质量保证
      terminationGracePeriodSeconds: 120
      containers:
        - name: vllm
          resources:
            limits:
              nvidia.com/gpu: 4
              memory: 256Gi
            requests:
              nvidia.com/gpu: 4
              memory: 128Gi
          startupProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 30
            failureThreshold: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 10
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 60
            periodSeconds: 15
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: vllm-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: vllm-prod
  minReplicas: 2
  maxReplicas: 8
  metrics:
    - type: Prometheus
      prometheus:
        metric: avg(vllm:num_requests_waiting) / avg(vllm:num_requests_running)
        target:
          type: AverageValue
          averageValue: "0.5"

Step 1：启动新版本 Pod（1 个）
    ├── 验证健康检查通过
    └── 检查 /metrics 指标正常

Step 2：接入 10% 流量（Canary）
    ├── 观察 15 分钟
    ├── 对比新旧版本 P50/P99 Latency
    └── 对比 Throughput

Step 3：接入 50% 流量
    ├── 观察 30 分钟
    └── 检查错误率

Step 4：全量切换
    ├── 滚动更新所有 Pod
    └── 保留一个旧 Pod 作为快速回滚目标

Step 5：稳定运行 1 小时后清理旧 Pod

# Prometheus Alert Rules
groups:
  - name: vllm
    rules:
      - alert: VLLMKVCacheHigh
        expr: vllm:gpu_cache_usage_perc > 85
        for: 5m
        annotations:
          summary: "vLLM GPU KV Cache 使用率超过 85%"

      - alert: VLLMQueueHigh
        expr: vllm:num_requests_waiting > 50
        for: 3m
        annotations:
          summary: "vLLM 排队请求超过 50"

      - alert: VLLMTTFTP99High
        expr: histogram_quantile(0.99, rate(vllm:time_to_first_token_seconds_bucket[5m])) > 1
        for: 5m
        annotations:
          summary: "vLLM TTFT P99 超过 1 秒"

      - alert: VLLMSwappedRequests
        expr: vllm:num_requests_swapped > 0
        for: 1m
        annotations:
          summary: "vLLM 有请求被交换到 CPU"