【vllm】vLLM v1 系统级架构分析（总）

vLLM v1 系统级架构分析

分析日期：2026-04-20
代码目录：vllm/vllm/v1

目录

1. 整体架构概览
2. 架构模式与设计思路
3. 整体运行流程
4. 子模块详细分析
   • 4.1 engine — 引擎层
   • 4.2 core/sched — 核心调度层
   • 4.3 worker — 工作执行层
   • 4.4 attention — 注意力计算层
   • 4.5 sample — 采样层
   • 4.6 spec_decode — 推测解码层
   • 4.7 executor — 执行器层
   • 4.8 pool — 池化模块
   • 4.9 structured_output — 结构化输出
   • 4.10 kv_offload — KV缓存卸载
   • 4.11 metrics — 指标监控
5. 模块调用关系与数据流
6. 架构图索引

1. 整体架构概览

vLLM v1 是 vLLM 推理引擎的第二代架构，采用六层分层架构 + 插件式后端设计。相比 v0 架构，v1 的核心改进在于：

1. 进程分离：将 EngineCore 运行在独立后台进程中，通过 ZMQ/TensorIPC 与前端通信，实现计算与 I/O 重叠
2. 统一调度：Scheduler 统一管理生成和池化请求，支持分块预填充（chunked prefill）
3. 插件式后端：Attention、SpecDecode、StructuredOutput、KVOffload 均通过注册机制 + 运行时选择实现
4. 多设备抽象：WorkerBase → GPUWorker/CPUWorker/XPUWorker 多设备后端

核心数据流

用户请求 → AsyncLLM → InputProcessor → CoreClient → [ZMQ] → EngineCore → Scheduler → SchedulerOutput → Executor → Worker → GPUModelRunner → [Model Forward + Attention + Sample] → ModelRunnerOutput → [返回路径] → EngineCore → CoreClient → OutputProcessor → RequestOutput

模块统计

2. 架构模式与设计思路

2.1 分层架构（Layered Architecture）

v1 采用严格的六层分层：

层次间通信方式：

• L1 ↔ L2：ZMQ（多进程）或直接调用（单进程 InprocClient）
• L2 ↔ L3：EngineCore 直接调用 Scheduler
• L3 ↔ L4：SchedulerOutput 通过 Executor 传递到 Worker
• L4 ↔ L5：GPUModelRunner 通过接口调用各子系统
• L4 ↔ L6：Executor 创建并管理 Worker 进程

2.2 插件式后端（Plugin Backend）

多个子系统采用抽象基类 + 注册表 + 运行时选择模式：

AttentionBackend (ABC) → FlashAttn / FlashInfer / MLA / TritonAttn / ... ↕ Registry + AttentionSelector (根据硬件/模型自动选择) Executor (ABC) → UniprocExecutor / MultiprocExecutor / RayExecutor ↕ Executor.get_class() (根据配置选择) KVOffloadManager (ABC) → CPUOffloadManager ↕ factory.py (根据配置创建) StructuredOutputBackend → xgrammar / outlines / lm_format_enforcer ↕ StructuredOutputManager (根据请求选择)

2.3 数据并行架构

v1 支持 Data Parallel (DP) 推理：

• DPCoordinator：协调多引擎的数据并行
• CoreClient：通过 CRC32 哈希将晚交互请求路由到特定引擎
• Wave机制：DP 场景下按"波"调度请求，确保同步完成

2.4 关键设计决策

1. EngineCore 独立进程：避免 GIL 限制，调度循环不阻塞 API 层
2. TensorIPC：GPU 张量零拷贝传输（通过共享内存），避免序列化开销
3. 分块预填充：长 prompt 可跨多步调度，与 decode 请求混合执行
4. Block-based KV Cache：以固定大小 block 为单位管理 KV 缓存，支持前缀共享
5. CUDA Graph 重放：将 decode 步骤捕获为 CUDA Graph，通过重放避免 CPU 开销

3. 整体运行流程

3.1 生成请求（Generation Request）完整生命周期

┌──────────────────────────────────────────────────────────────────┐ │ Phase 1: 请求接收 │ │ AsyncLLM.generate(prompt, SamplingParams) │ │ → InputProcessor.process() │ │ → Renderer: prompt → token_ids + mm_features │ │ → SamplingParams.verify() → 设置 task, temperature 等 │ │ → CoreClient.add_request(EngineCoreRequest) │ │ → ZMQ socket 发送 msgpack 编码的请求 │ ├──────────────────────────────────────────────────────────────────┤ │ Phase 2: 调度 │ │ EngineCore 调度循环: │ │ → Scheduler.schedule() │ │ → RequestQueue: 取出待调度请求 │ │ → KVCacheManager: 分配 KV cache blocks │ │ → 前缀缓存匹配（hash-based block reuse） │ │ → 构建 SchedulerOutput (NewRequestData + CachedRequestData) │ │ → Executor.execute_model(SchedulerOutput) │ ├──────────────────────────────────────────────────────────────────┤ │ Phase 3: 执行 │ │ Executor → GPUWorker → GPUModelRunner │ │ → InputBatch: 组装批量数据 │ │ → Model.forward() → hidden_states │ │ → Attention: 根据后端选择执行注意力计算 │ │ → Sampler: logits → penalties → topk_topp → sample tokens │ │ → (若 spec_decode: draft tokens → rejection sampling) │ │ → (若 pool: PoolingRunner.pool() → embedding) │ │ → (若 structured_output: grammar-guided sampling) │ │ → ModelRunnerOutput (token_ids, logprobs, pooler_output, ...) │ ├──────────────────────────────────────────────────────────────────┤ │ Phase 4: 输出处理 │ │ EngineCore.update_from_output() │ │ → Scheduler 处理完成的请求，释放 KV blocks │ │ → EngineCoreOutput → CoreClient → OutputProcessor │ │ → Detokenizer: token_ids → text │ │ → LogprobsProcessor: 格式化 logprobs │ │ → RequestOutput 返回给用户 │ └──────────────────────────────────────────────────────────────────┘

3.2 分块预填充（Chunked Prefill）

长 prompt (e.g. 4096 tokens, chunk_size=1024) │ ├─ Step 1: schedule 1024 tokens (prefill chunk 1) │ → KVCacheManager 分配 blocks 0-15 │ → Model forward (prefill attention) │ → 保存 hidden_states 到 PoolingStates（若 pool 请求） │ → 不输出任何 token（未完成全部 prefill） │ ├─ Step 2: schedule 1024 tokens (prefill chunk 2) │ → 复用 blocks 0-15, 新增 blocks 16-31 │ → Model forward │ → 仍不输出 token │ ├─ ... (chunk 3, 4) │ └─ Step 4: 最后一个 chunk 完成 → PoolingCursor.is_finished() == True → 执行池化聚合 → 输出 embedding / classification → (若是生成请求) → 开始 decode 步骤

3.3 推测解码流程

Step 1: Draft (推测) SpecDecodeProposer (Eagle/Medusa/Ngram) → 生成 k 个 draft tokens (概率分布) Step 2: Verify (验证) GPUModelRunner.execute_model() → 将 draft tokens 一起送入模型 → 模型输出每个位置的 logits Step 3: Reject (拒绝采样) RejectionSampler → 比较模型 logits vs draft 概率 → 接受匹配的 draft tokens → 拒绝不匹配的，从模型分布重新采样 → 输出最终 token 序列 + 接受长度 Metric: acceptance_rate = accepted / proposed

4. 子模块详细分析

4.1 engine — 引擎层

核心作用

engine 模块是 v1 的入口和编排层，负责请求的全生命周期管理：从 API 接收到输出返回。它是前端（API 进程）与后端（EngineCore 进程）的桥梁。

关键类/方法

数据结构

4.2 core/sched — 核心调度层

核心作用

core/sched 模块是 v1 的调度中枢，决定每个 step 处理哪些请求、分配多少 KV cache blocks、如何混合 prefill 和 decode。

关键类/方法

调度策略

1. 优先级调度：请求按 priority 排序
2. 分块预填充：长 prompt 分多个 chunk 调度，与 decode 请求混合
3. 前缀缓存：通过 block hash 匹配已有 KV cache，避免重复计算
4. 抢占：当 GPU 内存不足时，抢占低优先级请求释放 blocks
5. ALL pooling 检测：若当前批次全部为 pool 请求，跳过 decode 步骤

SchedulerOutput 数据结构

@dataclassclassSchedulerOutput:scheduled_new_reqs:list[NewRequestData]# 新请求scheduled_cached_reqs:list[CachedRequestData]# 缓存请求（有前缀命中）num_scheduled_tokens:int# 本步总 token 数total_num_scheduled_tokens:list[int]# 各组 token 数grammar_outputs:list[GrammarOutput]# 结构化输出...

4.3 worker — 工作执行层

核心作用

worker 模块是 v1 的执行引擎，负责模型加载、forward pass、CUDA Graph 捕获/重放、批量状态管理。

关键类/方法

GPUModelRunner 核心流程

execute_model(scheduler_output) → 解析 new/cached requests → InputBatch.add_request() / update() → _execute_forward() → Model.forward(hidden_states) → Attention (根据 backend) → Sampler / PoolingRunner → LateInteractionRunner.postprocess() → _execute_decode() (CUDA Graph 重放模式) → 构建 ModelRunnerOutput

GPU 子系统

4.4 attention — 注意力计算层

核心作用

attention 模块实现了 v1 的注意力计算抽象层，通过后端注册 + 运行时选择，支持多种 GPU 注意力实现。

关键类/方法

注意力操作（ops/）

MLA 子系统

MLA (Multi-head Latent Attention) 是 DeepSeek 系列模型的专用注意力机制，包含多种实现：

• flashmla.py— FlashMLA 官方 kernel
• cutlass_mla.py— CUTLASS 实现
• flashinfer_mla.py— FlashInfer MLA
• triton_mla.py— Triton 自定义
• aiter_triton_mla.py— AMD ROCm 实现
• indexer.py— MLA 索引构建

4.5 sample — 采样层

核心作用

sample 模块负责从模型 logits 中采样下一个 token，包括各种惩罚、约束和采样策略。

关键类/方法

Sampler 9步管线

1. (若请求) 计算/克隆 logprobs 2. Logits → float32 3. 应用 allowed_token_ids 白名单 4. 应用 bad_words 排除 5. 应用非 argmax-invariant 处理器（min_tokens, logit_bias） 6. 应用惩罚（repetition/frequency/presence） 7. 采样： a. 若 all_greedy → argmax b. 应用 temperature c. 应用 min_p d. 应用 top_k / top_p e. 随机采样 8. 收集 top logprobs 9. 返回 SamplerOutput

4.6 spec_decode — 推测解码层

核心作用

spec_decode 模块实现推测解码（Speculative Decoding），通过先让轻量级 draft 模型生成候选 token，再由目标模型并行验证，在不损失质量的前提下加速推理。

关键类/方法

推测解码流程

1. Proposer 生成 k 个 draft tokens 2. 将 draft tokens 与当前序列拼接 3. 一次 forward pass 并行验证所有位置 4. RejectionSampler: - 从左到右逐个验证 - 接受: draft token == target distribution 样本 - 拒绝: 从 target distribution 重新采样 5. 输出: 接受的 token + 补充采样的 token

4.7 executor — 执行器层

核心作用

executor 模块负责创建和管理 Worker 进程，是分布式推理的核心编排层。

关键类/方法

Executor 抽象接口

classExecutor(ABC):defdetermine_available_memory()->intdefinitialize_cache(num_gpu_blocks)defexecute_model(scheduler_output)->ModelRunnerOutputdefcollective_rpc(method,timeout,args)->list[Any]defcheck_health()->None

执行器选择逻辑

Executor.get_class(vllm_config): if isinstance(backend, type(Executor)): → 直接使用 elif backend == "ray": → RayExecutor elif backend == "mp": → MultiprocExecutor elif TP == 1: → UniprocExecutor else: → MultiprocExecutor (default)

4.8 pool — 池化模块

核心作用

pool 模块为池化任务（Embedding、Classification）提供元数据构建和晚交互评分。

关键类/方法

（详细分析见前一份 G-77-pool 报告）

4.9 structured_output — 结构化输出

核心作用

structured_output 模块确保模型输出符合预定义的格式约束（JSON Schema、Regex、Grammar），避免无效输出。

关键类/方法

工作原理

1. 用户请求含 json_schema / regex / grammar 约束 2. StructuredOutputManager 创建对应后端的 Grammar 3. 每个 decode 步骤: Grammar → 允许的 token mask 4. Sampler 应用 mask: 只从允许 token 中采样 5. 保证输出始终符合约束

4.10 kv_offload — KV缓存卸载

核心作用

kv_offload 模块实现KV Cache 的 CPU 卸载，将不活跃的 KV blocks 从 GPU 转移到 CPU，释放 GPU 内存以服务更多请求。

关键类/方法

卸载操作

lookup() → 查找已卸载的 block 链长度 prepare_load() → 准备加载（保护 block 不被淘汰） touch() → 标记 block 为最近使用 complete_load() → 完成加载 prepare_store() → 准备存储（可能触发淘汰） complete_store() → 完成存储（block 可被加载）

4.11 metrics — 指标监控

核心作用

metrics 模块提供运行时指标收集和导出，用于性能分析和监控。

关键类/方法

5. 模块调用关系与数据流

5.1 核心调用链

AsyncLLM.generate() → InputProcessor.process() → Renderer.encode() → token_ids → SamplingParams.verify() → CoreClient.add_request(EngineCoreRequest) → [ZMQ msgpack] → EngineCore EngineCore.step() → Scheduler.schedule() → RequestQueue.pop() → KVCacheManager.allocate() → BlockPool.get_free_block() → Prefix cache match (hash lookup) → return SchedulerOutput → Executor.execute_model(SchedulerOutput) → GPUWorker.execute_model() → GPUModelRunner.execute_model() → InputBatch.add_request() → Model.forward(hidden_states, kv_caches) → AttentionBackend.forward() → Sampler.forward(logits) → LogitsProcessor → TopKTopP → sample → [optional] LateInteractionRunner.postprocess() → return ModelRunnerOutput → Scheduler.update_from_outputs() → 释放完成的请求 blocks → 构建完成请求列表 → [TensorIPC] → CoreClient → OutputProcessor → Detokenizer.decode() → LogprobsProcessor.format() → return RequestOutput → 用户

5.2 模块间数据传递矩阵

5.3 GPU 数据流（单步执行）

SchedulerOutput │ ├─ new_reqs ──── InputBatch.add_request() │ → token_ids_cpu, seq_lens, block_ids │ → SamplingMetadata / PoolingMetadata 构建 │ ├─ cached_reqs ── InputBatch.update() │ → 复用已有 block_ids, 更新 num_computed_tokens │ └─ num_scheduled_tokens → 确定 forward batch 大小 Model.forward(input_ids, positions, kv_caches) │ ├─ hidden_states ──→ Attention.forward() │ │ │ ├─ Prefill: chunked_prefill_paged_decode │ └─ Decode: paged_attention │ └─ logits ──→ Sampler.forward() │ ├─ LogitsProcessor.apply() ├─ apply_all_penalties() ├─ TopKTopPSampler.forward() └─ 返回 SamplerOutput(token_ids, logprobs) [若 Pool 请求]: hidden_states ──→ PoolingRunner.pool() → F.normalize(last_hidden_states) → LateInteractionRunner.postprocess() → compute_maxsim_score_batched() (若晚交互) ModelRunnerOutput: ├── sampled_token_ids (GPU tensor) ├── logprobs (CPU numpy) ├── pooler_output (list[Tensor]) └── spec_decode_draft_ids (optional)