5. 核心模块
本章拆解 vLLM 中每个核心模块的职责、输入、输出、生命周期、异常处理与扩展方式。当前 vLLM 默认使用 V1 引擎，因此会同时覆盖 V1 与经典引擎（V0）的模块。
1. AsyncLLMEngine / LLMEngine
职责
用户与 vLLM 推理系统交互的主入口。V1 引擎中，AsyncLLMEngine 是 vllm.v1.engine.async_llm.AsyncLLM 的别名/包装。
- 接收
add_request请求并转发给 EngineCore（V1）或 Scheduler（V0）。 - 通过
generate以异步生成器形式返回 token。 - 管理请求生命周期、输出后处理与 detokenization。
输入
- prompt / token IDs
SamplingParams- 请求 ID 与路由信息
输出
RequestOutput（包含 generated tokens、finish reason 等）
生命周期
随服务进程启动而创建，随进程退出而销毁。
异常处理
- 请求超时：按策略取消或丢弃
- EngineCore 失联：重连或报错
2. EngineCore（V1）
职责
V1 引擎中，调度与执行的核心进程。vllm/v1/engine/core.py 实现。
- 持有 Scheduler 与 ModelExecutor。
- 每轮调用
Scheduler.schedule()，再调用ModelExecutor.execute_model()。 - 支持
step_with_batch_queue，在 pipeline parallelism 下异步调度。
输入
- 来自 AsyncLLMEngine 的 Request
- 来自 GPU Worker 的 model output
输出
EngineCoreOutput：新的 token、请求状态更新、finished 请求
生命周期
服务启动时初始化，独立进程运行。
异常处理
- CUDA OOM：通过调度器减少 token budget
- 模型执行失败：上报错误并释放相关请求
3. Scheduler
职责
决定每一轮 iteration 中哪些请求进入 GPU 执行。
V1 调度器（vllm/v1/core/scheduler.py）
- 维护所有请求的统一状态：
num_computed_tokens、num_tokens_with_spec。 - 每轮计算
num_scheduled_tokens，目标让num_computed_tokens追上num_tokens_with_spec。 - 受全局
token_budget限制，天然支持 chunked prefill。 - 与
KVCacheManager交互分配 Block。
V0 调度器（vllm/core/scheduler.py）
- 维护
Waiting / Running / Swapped三个队列。 - 分别调度 prefill 与 decode。
输入
- 当前所有请求的状态
- KV Cache 预算
- token budget
输出
SchedulerOutput（V1）或SchedulerOutputs（V0）
生命周期
每轮 EngineCore.step() / LLMEngine.step() 调用一次。
异常处理
- 显存不足：触发抢占（V0）或减少本轮 token（V1）
- 请求超时：根据配置丢弃
扩展方式
可通过自定义 Scheduler 子类实现不同的调度策略（如优先级调度、公平调度）。
4. KVCacheManager / BlockManager
职责
管理 GPU 上 KV Cache Block 的分配、回收、映射与前缀缓存。
V1：vllm/v1/core/kv_cache_manager.py
- 管理
KVCacheBlock。 - 支持 hybrid block sizes：内存分配块大小与 attention kernel 块大小可以不同。
- 维护 block hash 索引，实现 prefix caching。
- 支持 Copy-on-Write 与引用计数。
V0：vllm/core/block_manager.py
- 管理
PhysicalTokenBlock。 - 维护 Block Table。
- 支持 prefix caching 与 swapping。
输入
- 请求的 token 范围
- Block 大小
- 分配 / 释放 / 拷贝请求
输出
- Block Table（V1 中为
BlockTablebuffer） - 物理 Block ID 列表
生命周期
伴随请求从创建到销毁。请求完成时回收 Block。
异常处理
- Block 不足：触发 swapping（V0）或降低调度量（V1）
- 引用计数错误：可能导致 Block 泄漏
扩展方式
V1 的 KVCacheManager 接口更统一，便于接入新的 attention backend。
5. ModelExecutor / Worker
职责
执行实际的模型推理，管理 GPU 设备。
V1：vllm/v1/executor/ + vllm/v1/worker/gpu_worker.py
ModelExecutor负责任务分发到 Worker。GPUWorker在每个 GPU 进程上运行。GPUModelRunner负责具体的 forward。
V0：vllm/executor/ + vllm/worker/worker.py
Worker执行模型 forward。ModelRunner组织 attention、MLP、sampler 调用。
输入
SchedulerOutput- 模型权重
- KV Cache 布局 / Block Table
输出
- 采样后的 token IDs
- logits / hidden states
生命周期
从 Engine 初始化时创建，到进程退出时销毁。
异常处理
- CUDA OOM：捕获并上报
- NCCL 错误：在分布式场景下需要重启
扩展方式
支持本地 Worker、Ray Worker、多节点 Worker。
6. GPUModelRunner / ModelRunner
职责
组织模型 forward 的具体执行，包括 attention、MLP、sampler 的调用顺序。
V1：vllm/v1/worker/gpu_model_runner.py
- 维护
InputBatch，根据SchedulerOutput每轮重新构造输入张量。 - 调用
attention模块与sampler。 - 自 v0.29.0（2026-09-09）起，Model Runner V2 成为默认执行层：CPU 侧单步开销更低，支持 PP 下的 MTP/EAGLE 推测解码与 prefill/decode 双 batch 重叠；MRV1 计划在 v0.32 移除。
输入
- token IDs
- positions
- Block Tables /
SchedulerOutput - attention metadata
输出
- logits
- sampled tokens
生命周期
每个 Worker 持有一个 Model Runner。
扩展方式
支持不同模型架构（Llama、Qwen、Mistral 等）通过 ModelRegistry 注册。
7. Attention Backend
职责
提供高效的注意力计算实现。
实现选项（2026 年）
- FlashAttention / FlashAttention-3
- FlashInfer
- FlashMLA（DeepSeek MLA 模型专用，v0.31.0 中为 DeepSeek-V4.1-Flash 引入 mega attention 融合 kernel）
- Triton、CUTLASS 等通用后端
选择逻辑
根据 GPU 架构（Ampere / Hopper / Blackwell）、模型注意力类型（GQA / MLA / 混合架构）、是否使用 prefix caching / chunked prefill 自动选择。
8. KV Connector / KV Cache Offloading
职责
插件化管理 KV Cache 的实例间传输与跨层卸载，是 PD 分离与分层缓存的基础设施。
主要实现
| Connector | 用途 |
|---|---|
NixlConnector | PD 分离，GPU 显存 P2P / RDMA 直传（NVIDIA NIXL） |
MooncakeStoreConnector | 接入 Mooncake 分布式 KV 池（生产验证见 Moonshot Kimi K2） |
LMCacheConnector | LMCache 生态的 CPU/磁盘/远程缓存 |
OffloadingConnector | 本机 CPU / NVMe 卸载 |
MultiConnector | 串联多个 Connector（如 NIXL + Mooncake Store） |
分层 Offloading（v0.22+）
原生分层卸载管线：所有 KV 数据经 CPU 内存（真正的 LRU/ARC 缓存）中转，再级联到文件系统、S3 与 P2P 远端；加速卡显存在数据到达主机内存后立即释放，reload 时按需回填。同一请求的不同 chunk 可以由不同层服务。配合 KV Events 上报给路由器做缓存感知调度。
9. Structured Output（结构化输出）
职责
约束模型输出符合 JSON Schema、正则或 EBNF 文法，是 Agent / Function Calling 场景的基础设施。
实现
- 代码位于
vllm/v1/structured_output/，默认后端为 xgrammar：把文法编译为 token 级掩码，逐 token 屏蔽非法选择，兼容 CUDA Graph，增量开销接近零（一次性文法编译约 20–50ms）。 - 可选后端：guidance、outlines、lm-format-enforcer。
- API 层支持
guided_json/guided_regex/guided_grammar参数与 OpenAI Structured Outputs 兼容模式。
10. Speculative Decoding（推测解码）
职责
用草稿（draft）模型快速提出候选 token，目标模型批量验证，在带宽受限的 decode 阶段换取更低 TPOT。
2025–2026 进展
- 草稿来源：独立小模型、MTP（Multi-Token Prediction，部分大模型自带预测头）、EAGLE / EAGLE-3（特征级外推草稿）。
- Adaptive Speculative Decoding：根据在线接受率动态调整草稿长度，v0.29.0 起 OpenAI API 响应返回逐请求接受率统计，便于观测与调参。
- MRV2 支持流水线并行下的 MTP/EAGLE 推测解码（v0.30.0）。
- 注意：与异步 KV offloading、某些量化格式组合时可能存在兼容性限制，需查阅对应版本的 release notes。
11. Tokenizer
职责
文本与 token ID 的相互转换。
注意点
- 不同模型的 tokenizer 不同
- detokenization 需要处理 unicode 多字节字符
- V1 中 detokenization 在 AsyncLLMEngine 端完成
9. API Server
职责
提供 OpenAI 兼容的 HTTP 接口。
输入
- HTTP 请求
输出
- HTTP 响应（流式或非流式）
扩展方式
vLLM 的 API Server 基于 FastAPI，可以自定义中间件、认证、路由。
模块协作图（V1）
本章小结
vLLM 的模块划分清晰，每个模块只负责一个明确的职责。V1 引擎通过 EngineCore 将调度与执行紧密整合，Scheduler 与 KVCacheManager 是 vLLM 性能优势的核心来源；KV Connector 与结构化输出则是 2025–2026 年支撑 PD 分离和 Agent 负载的关键新增模块。