vLLM v0.20 架构深度解析：双引擎、调度器、KV Cache 与分布式推理
vLLM v0.20 架构深度解析：双引擎、调度器、KV Cache 与分布式推理
引子
vLLM 是目前生产环境中最广泛使用的大模型推理框架之一。v0.20 版本在保持向后兼容的同时，将主力执行路径完全迁移到了全新的 V1 引擎——进程分离架构、ZMQ IPC 通信、全新调度器。
本文基于 vLLM v0.20 源码，系统梳理其整体架构、数据流、核心组件和高级特性，帮助工程师快速建立完整的架构心智模型。
一、顶层目录结构
vllm_0_20/ ├── vllm/ # Python 主库（57 子目录/模块） ├── csrc/ # CUDA/C++ 高性能内核（45 项） ├── benchmarks/ # 性能基准测试 ├── examples/ # 使用示例（offline、online、tool_calling、speech_to_text 等） ├── tests/ # 测试用例 ├── docs/ # 文档 ├── docker/ # Docker 镜像定义 ├── cmake/ # CMake 构建配置 ├── requirements/ # 依赖分组（lint、test、build 等） ├── tools/ # 开发工具脚本 └── scripts/ # CI/运维脚本 核心逻辑集中在 vllm/ 下，csrc/ 负责 CUDA/C++ 高性能内核。
二、双引擎设计
vLLM v0.20 保留了双引擎设计以兼顾迁移平稳性：
| 引擎 | 路径 | 状态 | 说明 |
|---|---|---|---|
| V1 引擎 | vllm/v1/ | 主力引擎，活跃开发 | 进程分离架构，ZMQ IPC 通信 |
| Legacy 引擎 | vllm/engine/ | 向后兼容保留 | LLMEngine / AsyncLLMEngine |
V1 引擎数据流
sequenceDiagram
participant U as 用户 / Client
participant A as AsyncLLM<br/>(async_llm.py:70)
participant C as EngineCoreClient<br/>(ZMQ IPC)
participant E as EngineCore<br/>(core.py:91)
participant S as Scheduler<br/>(scheduler.py:67)
participant W as Worker / GPUModelRunner
participant D as Detokenizer
U->>A: 发送请求（prompt）
A->>C: 封装请求，ZMQ 发送
C->>E: 请求入队 InputProcessor
E->>S: 触发调度决策
S-->>E: SchedulerOutput（本轮执行批次）
E->>W: Executor 下发执行
W->>W: GPUModelRunner 前向推理
W-->>E: 模型原始输出（logits/tokens）
E->>E: OutputProcessor 后处理
E->>D: 送入 Detokenizer 流式解码
D-->>A: 已解码 token 流
A-->>U: 流式返回生成结果
进程间通信选用 ZMQ，将调度主进程与 GPU Worker 进程完全隔离，避免 GIL 争用并支持多机扩展。
三、用户入口点
| 入口 | 路径 | 用途 |
|---|---|---|
LLM 类 | entrypoints/llm.py:106 | 离线推理：generate(), chat(), encode(), embed() |
| OpenAI API | entrypoints/openai/api_server.py | 生产级 OpenAI 兼容 HTTP 服务 |
| gRPC | entrypoints/grpc_server.py | gRPC 服务端点 |
| Anthropic API | entrypoints/anthropic/ | Anthropic 格式兼容 |
| MCP | entrypoints/mcp/ | Model Context Protocol |
| SageMaker | entrypoints/sagemaker/ | AWS SageMaker 集成 |
| CLI | entrypoints/cli/ | vllm serve 等命令行工具 |
公共 API（vllm/__init__.py 延迟加载）：LLM, SamplingParams, RequestOutput, ModelRegistry, EngineArgs。
四、模型加载层
4.1 模型注册表
model_executor/models/registry.py 以 HF architectures 字符串为键懒加载对应模块，覆盖 280+ 模型文件。
核心映射（_TEXT_GENERATION_MODELS）：
"LlamaForCausalLM" → ("llama", "LlamaForCausalLM") "Qwen3ForCausalLM" → ("qwen3", "Qwen3ForCausalLM") "DeepseekV3ForCausalLM" → ("deepseek_v3", "DeepseekV3ForCausalLM") 覆盖家族：Llama、Qwen(2/2.5/3/3.5)、DeepSeek(v2/v3/v4)、Gemma、Mistral、Mixtral、Phi、Mamba 等。
_ModelInfo 数据类自动探测模型能力：多模态、PP 支持、无注意力、混合架构、转录等。
4.2 权重加载器
| 加载器 | 文件 | 格式 |
|---|---|---|
| DefaultLoader | default_loader.py | HF safetensors/bin |
| BitsAndBytesLoader | bitsandbytes_loader.py | BnB 量化 |
| GGUFLoader | gguf_loader.py | GGUF 格式 |
| ShardedStateLoader | sharded_state_loader.py | 分片检查点 |
| TensorizerLoader | tensorizer_loader.py | CoreWeave Tensorizer |
4.3 层实现
- 核心层：
linear.py,layernorm.py,activation.py,vocab_parallel_embedding.py,logits_processor.py - 注意力：
attention/,mla.py（Multi-head Latent Attention），deepseek_v4_attention.py,lightning_attn.py - MoE：
fused_moe/ - 旋转编码：
rotary_embedding/ - 量化：
quantization/（GPTQ, AWQ, SqueezeLLM, Marlin 等）
五、调度器与 KV Cache
5.1 调度器
| 文件 | 类 | 说明 |
|---|---|---|
sched/scheduler.py:67 | Scheduler(SchedulerInterface) | 主调度器，决定每步执行哪些请求 |
sched/async_scheduler.py | 异步调度器变体 | |
sched/output.py | SchedulerOutput | 调度决策输出 |
sched/request_queue.py | 请求优先队列 |
5.2 KV Cache 管理
Paged Attention 的核心抽象：
| 文件 | 类 | 说明 |
|---|---|---|
kv_cache_manager.py:106 | KVCacheManager | KV Cache 分配与回收 |
block_pool.py:130 | BlockPool | Paged Attention 核心：物理块池管理 |
block_pool.py:34 | BlockHashToBlockMap | 前缀缓存（Prefix Caching）的哈希查找 |
kv_cache_coordinator.py | KV Cache 跨层协调 | |
encoder_cache_manager.py | 编码器（多模态）缓存 |
BlockPool 将 GPU 显存切分为固定大小的物理块（block），通过哈希映射实现 Prefix Caching：相同前缀的请求可以复用已有 KV Cache 块，大幅降低 TTFT。
KV Cache 块分配与前缀缓存交互：
sequenceDiagram
participant SCH as Scheduler
participant KVM as KVCacheManager
participant BHM as BlockHashToBlockMap
participant BP as BlockPool
participant GPU as GPUModelRunner
SCH->>KVM: 新请求，申请 KV Cache 块
KVM->>BHM: 前缀哈希查找
alt 前缀缓存命中
BHM-->>KVM: 返回已有物理 Block
Note over KVM: 跳过重复 Prefill，直接复用
else 未命中
KVM->>BP: 分配新物理 Block
BP-->>KVM: 返回空闲 Block
end
KVM-->>SCH: Block 分配完成
SCH->>GPU: 下发本轮执行批次
GPU->>GPU: 前向推理，填充 KV Cache
GPU-->>KVM: 写回新 token 的 KV
loop 继续生成
SCH->>GPU: 下一步 decode
GPU-->>KVM: 追加 KV
end
KVM->>BP: 请求结束，归还 Block\n（或保留供后续前缀复用）
5.3 KV Cache 卸载
vllm/v1/kv_offload/— KV Cache 卸载到 CPU/磁盘vllm/v1/simple_kv_offload/— 简化版卸载，适用于内存充裕场景
六、注意力后端
核心抽象在 vllm/v1/attention/backend.py：
AttentionBackend(ABC)— 后端接口AttentionImpl/MLAAttentionImpl/SparseMLAAttentionImpl— 实现基类selector.py— 运行时自动选择最优后端
22+ 后端实现：
| 后端 | 文件 | 说明 |
|---|---|---|
| FlashAttention | flash_attn.py | FA2/FA3，最常用 |
| FlashInfer | flashinfer.py | FlashInfer 库 |
| Triton | triton_attn.py | Triton 内核 |
| Flex Attention | flex_attention.py | PyTorch flex_attention |
| CPU | cpu_attn.py | CPU 回退 |
| MLA 系列（16 个） | mla/ 目录 | DeepSeek MLA 专用 |
| Mamba | mamba_attn.py 等 | SSM “注意力” |
| Tree | tree_attn.py | 投机解码用 |
| ROCm | rocm_*.py | AMD GPU |
selector.py 根据硬件、模型类型、是否启用 MLA 等条件在运行时决策，用户无需手动指定。
注意力后端树形结构（selector.py 选择范围）：
graph LR
S["selector.py<br/>运行时自动选择"]
S --> MLA["MLA 系列 × 16<br/>mla/ 目录<br/>DeepSeek 专用"]
S --> SSM["Mamba / SSM<br/>mamba_attn.py"]
S --> TREE["Tree Attention<br/>tree_attn.py<br/>投机解码专用"]
S --> ROCM["ROCm 系列<br/>rocm_*.py / AMD GPU"]
S --> STD["标准 Attention 系列"]
STD --> FI["FlashInfer<br/>flashinfer.py"]
STD --> FA["FlashAttention FA2/FA3<br/>flash_attn.py"]
STD --> FLEX["Flex Attention<br/>flex_attention.py"]
STD --> TRI["Triton<br/>triton_attn.py"]
STD --> CPU["CPU 回退<br/>cpu_attn.py"]
七、分布式推理
7.1 并行策略
| 策略 | 核心文件 | 说明 |
|---|---|---|
| Tensor Parallel (TP) | parallel_state.py (GroupCoordinator:290) | 模型分片到多 GPU |
| Pipeline Parallel (PP) | parallel_state.py | 流水线并行 |
| Data Parallel (DP) | v1/worker/dp_utils.py | 数据并行 |
| Expert Parallel (EP) | distributed/elastic_ep/ | MoE 专家并行 |
| Context Parallel (CP) | v1/worker/cp_utils.py | 长上下文并行 |
初始化入口：initialize_model_parallel() 和 init_distributed_environment()。
7.2 通信后端
19 种通信后端（distributed/device_communicators/）：
- NCCL（
pynccl.py） - Custom All-Reduce（
custom_all_reduce.py） - Quick All-Reduce、FlashInfer All-Reduce
- Ray、共享内存广播（
shm_broadcast.py）、All2All
7.3 高级分布式特性
| 特性 | 路径 | 说明 |
|---|---|---|
| Disaggregated Prefill | distributed/kv_transfer/ | Prefill/Decode 分离，跨节点 KV 传输 |
| EP 负载均衡 | distributed/eplb/ | 动态 MoE 专家重平衡 |
| 弹性 EP | distributed/elastic_ep/ | 动态伸缩 EP 组 |
| 编码器缓存传输 | distributed/ec_transfer/ | 多模态编码器缓存 |
| 实时权重更新 | distributed/weight_transfer/ | 在线权重热更新 |
Disaggregated Prefill 是 v0.20 的重要进展：Prefill 节点和 Decode 节点分离部署，Prefill 完成后通过高速网络（RDMA/NVLink）将 KV Cache 传给 Decode 节点，显著提升 GPU 利用率并降低 P99 延迟。
sequenceDiagram
participant C as Client
participant P as Prefill 节点<br/>（高算力，少实例）
participant KV as KV Transfer<br/>（kv_transfer/）
participant D as Decode 节点<br/>（多实例，低延迟）
C->>P: 发送完整 prompt
P->>P: Prefill 全量计算<br/>生成 KV Cache
P->>KV: 推送 KV Cache 块
Note over KV: RDMA / NVLink<br/>高速传输
KV->>D: 接收 KV Cache 块
D->>D: Decode 自回归循环<br/>（KV Cache 已就绪）
D-->>C: 流式返回 token
Note over P,D: Prefill 与 Decode 独立扩缩容<br/>GPU 利用率显著提升
八、CUDA/C++ 内核
csrc/ 包含 45 个高性能内核目录/文件：
| 目录/文件 | 用途 |
|---|---|
attention/ | Paged Attention CUDA 内核 |
moe/ | MoE 路由与计算内核 |
quantization/ | 量化内核（GPTQ、AWQ、Marlin 等） |
mamba/ | Mamba/SSM 内核 |
cache_kernels.cu | KV Cache 操作（reshape、copy） |
layernorm_kernels.cu | LayerNorm / RMSNorm |
pos_encoding_kernels.cu | 位置编码（RoPE 等） |
sampler.cu / topk.cu | 采样内核 |
custom_all_reduce.cu | 自定义 All-Reduce |
quickreduce/ | 快速归约 |
fused_deepseek_v4_* | DeepSeek V4 融合内核 |
cutlass_extensions/ | CUTLASS 扩展 |
九、配置系统
vllm/config/ 下有 29 个模块化配置文件，全部采用 dataclass，由 VllmConfig 顶层聚合：
| 配置类 | 文件 | 核心参数 |
|---|---|---|
VllmConfig | vllm.py | 顶层聚合器，get_current_vllm_config() |
ModelConfig | model.py | model_name, dtype, max_model_len, tokenizer |
CacheConfig | cache.py | block_size, gpu_memory_utilization, swap_space |
ParallelConfig | parallel.py | tensor/pipeline/data_parallel_size |
SchedulerConfig | scheduler.py | max_num_seqs, max_num_batched_tokens, chunked_prefill |
LoadConfig | load.py | 权重加载策略 |
SpeculativeConfig | speculative.py | draft_model, num_speculative_tokens |
CompilationConfig | compilation.py | torch.compile, CUDA Graph 模式 |
AttentionConfig | attention.py | 注意力后端选择 |
LoRAConfig | lora.py | LoRA 适配器设置 |
OffloadConfig | offload.py | KV/权重卸载 |
KVTransferConfig | kv_transfer.py | Disaggregated KV 传输 |
SpeechToTextConfig | speech_to_text.py | ASR 管线配置 |
StructuredOutputsConfig | structured_outputs.py | JSON/guided generation |
十、高级特性
10.1 投机解码
vllm/v1/spec_decode/ 支持 6 种投机解码策略：
- EAGLE / EAGLE-3：Draft 模型辅助，token 接受率高
- Medusa：多头并行草稿生成
- MTP（Multi-Token Prediction）
- N-gram：无 draft 模型，纯统计匹配
- DFlash
- Suffix Decoding
投机解码通用流程（Draft → Verify 循环）：
sequenceDiagram
participant CTX as Token 序列
participant DFT as Draft 阶段<br/>EAGLE / N-gram / Medusa
participant VFY as Verify 阶段<br/>目标大模型
participant OUT as 已接受输出
loop 自回归生成
CTX->>DFT: 当前 token 序列
DFT->>DFT: 快速生成 K 个候选 token
DFT->>VFY: 将 K 个候选送入目标模型
VFY->>VFY: 单次前向并行验证全部 K 个 token
alt 全部 K 个 token 被接受
VFY-->>OUT: 追加 K 个 token + 1 个 bonus token
else 前 n 个被接受（n < K）
VFY-->>OUT: 保留前 n 个，丢弃首个被拒的 token
end
OUT->>CTX: 更新序列，进入下轮
end
Note over DFT,VFY: 相比自回归，每次前向可多输出多个 token<br/>整体吞吐提升而模型输出等价
10.2 多模态
vllm/multimodal/ 处理图像、音频、视频输入，配合 encoder_cache_manager 管理编码器输出缓存，避免重复编码。
10.3 结构化输出
vllm/v1/structured_output/ 支持 JSON Schema、正则表达式、语法约束的 guided generation。
10.4 LoRA 热切换
vllm/lora/ 支持运行时热切换 LoRA 适配器，通过 lora_model_runner_mixin.py 集成到推理循环，无需重启服务。
10.5 编译优化
vllm/compilation/ 集成 torch.compile 和 CUDA Graph 捕获，通过 CompilationConfig 控制编译策略，对 decode 阶段加速效果明显。
十一、开发关键路径
添加新模型
1. 在 vllm/model_executor/models/ 创建模型文件 2. 在 registry.py 的 _TEXT_GENERATION_MODELS 中注册 "ArchName" → ("module_name", "ClassName") 3. 实现 forward() 和 load_weights() 方法 添加新注意力后端
1. 在 vllm/v1/attention/backends/ 实现 AttentionBackend 子类 2. 在 registry.py 注册 3. 在 selector.py 添加选择逻辑 启动 OpenAI 兼容服务
vllm serve <model_name> \ --tensor-parallel-size 2 \ --max-model-len 4096 请求链路：api_server.py → AsyncLLM → EngineCore → Scheduler → Worker
小结
vLLM v0.20 的架构可以用三个关键词概括：
- 进程隔离：V1 引擎以 ZMQ IPC 将调度与执行彻底解耦，GIL 不再是瓶颈。
- Paged KV Cache：BlockPool + 前缀缓存（Prefix Caching）是高吞吐的基础。
- 可插拔后端：注意力后端、通信后端、权重加载器全部抽象为接口，新硬件和新算法可以独立接入。
对于需要在生产环境部署大模型的工程师，理解这三点就能快速定位性能瓶颈和扩展点。
基于 vLLM v0.20 源码分析，2026-04-30
This post is licensed under CC BY 4.0 by the author.