vLLM 源码完全拆解（二）：从 add_request 到 EngineCore.step，一次请求如何穿过 V1 引擎

从“模块地图”走进一次真实请求#

上一篇 vLLM 源码完全拆解（一）：整体架构与模块全景 建立了入口层、引擎层、执行层和 Kernel 层的地图，并把下一站定在引擎的核心循环。现在沿着一个最普通的离线生成请求向下追踪：它从 LLM.generate() 出发，怎样变成引擎内部的数据结构，怎样进入调度器，怎样触发一次 GPU 前向，又怎样变回用户看到的文字。

本文以 2026 年 9 月 26 日访问到的 vLLM main 分支 V1 源码为基线。vLLM 的内部接口迭代很快，因此学习时应抓住稳定的职责边界，而不是死记行号。源码里还有一个尤其容易误读的点：当前 V1 同时存在前端的 LLMEngine.step() 和核心进程里的 EngineCore.step()。前者主要接收并加工结果，后者才执行“调度—模型执行—状态更新”事务。把两者混成一个函数，会从一开始就看错控制流。

vLLM 源于 UC Berkeley 团队 2023 年发表在 SOSP 的 PagedAttention 工作。V1 架构的公开设计在 2024 年启动，目标是在保留模型实现与高性能 Kernel 的同时，重构调度器、KV Cache 管理、Worker、采样器和服务端之间的边界。本文不讨论某一个注意力 Kernel，而是回答更基础的问题：一轮引擎迭代到底是什么。

先看全路径：三个循环，而不是一个循环#

图源：vLLM 官方架构文档 entrypoints.excalidraw.png。图中离线 LLM 和在线 OpenAI 兼容 API 最终都会进入引擎，但在线路径多了一层异步服务封装。

从用户代码到 GPU，至少要区分三个循环：

1. 离线排空循环：OfflineInferenceMixin._run_engine() 反复调用前端 LLMEngine.step()，直到没有未完成请求。
2. 核心忙循环：多进程部署下，EngineCoreProc.run_busy_loop() 持续接收入站消息并推进引擎。
3. 单步事务：EngineCore.step() 在一轮中完成调度、执行和状态提交。

它们对应三种不同的“持续运行”：第一个回答“何时把整批离线任务跑完”，第二个回答“服务进程如何一直活着”，第三个回答“一个迭代步具体做什么”。后文会反复用到这个区分。

一条简化后的调用链如下：

1
LLM.generate()
2
  -> OfflineInferenceMixin._run_completion()
3
     -> _add_completion_requests()
4
        -> LLMEngine.add_request()
5
           -> InputProcessor.process_inputs()
6
           -> OutputProcessor.add_request()
7
           -> EngineCoreClient.add_request()
8
              -> EngineCore.add_request()
9
                 -> Scheduler.add_request()
10

11
  -> OfflineInferenceMixin._run_engine()
12
     -> LLMEngine.step()
13
        -> EngineCoreClient.get_output()
14
           -> EngineCore.step()
15
              -> Scheduler.schedule()
16
              -> Executor.execute_model()
17
              -> Scheduler.update_from_output()
18
        -> OutputProcessor.process_outputs()
19
        -> RequestOutput

这条链里有两条方向相反的数据流。请求向下时，文本逐步变成 token、参数对象、核心请求和调度状态；结果向上时，采样 token 逐步变成核心输出、增量文本和用户级 RequestOutput。V1 的关键设计不是把所有事情塞进一个“大引擎类”，而是让输入处理、核心调度和输出处理拥有各自的数据模型。

第一道边界：LLM.generate() 不负责生成 token#

对离线 API 而言，入口通常只有几行：

1
from vllm import LLM, SamplingParams
2

3
llm = LLM(model="Qwen/Qwen3-8B")
4
outputs = llm.generate(
5
    ["PagedAttention 的核心思想是"],
6
    SamplingParams(max_tokens=64, temperature=0.0),
7
)

直觉上，generate() 似乎应该包含生成循环。实际源码中，它先检查当前 runner 是否支持生成任务，补齐默认采样参数，然后转入 _run_completion()。后者只做两件事：先把所有 prompt 加入引擎，再调用 _run_engine() 排空请求。

核心伪代码可以压缩为：

1
def run_completion(prompts, params):
2
    add_completion_requests(prompts, params)
3
    return run_engine()
4

5
def run_engine():
6
    outputs = []
7
    while llm_engine.has_unfinished_requests():
8
        for output in llm_engine.step():
9
            if output.finished:
10
                outputs.append(output)
11
    return sort_by_request_id(outputs)

这里有三个值得注意的设计。

第一，离线接口也经过统一引擎，而不是另写一套静态批处理实现。所谓“自动批处理”来自调度器每一步重新选择请求，并不来自 generate() 预先把输入拼成一个固定 batch。

第二，完成顺序与提交顺序可以不同。短请求可能先结束，长请求后结束，所以 _run_engine() 最后按 request ID 排序，恢复离线 API 承诺的输入顺序。在线流式服务则不需要等待全体结束，应尽快把每个请求的增量输出发回客户端。

第三，当前离线路径会把 SamplingParams.output_kind 设成 FINAL_ONLY。内部每一步仍然产生 token，但离线调用者只收集最终结果。是否流式输出是前端策略，不改变核心调度器按迭代推进请求的事实。

请求入队：同一个请求为什么要保存两份状态#

图源：vLLM 官方架构文档 llm_engine.excalidraw.png。这张图适合建立职责地图，但阅读 V1 源码时还要进一步把前端处理与 Engine Core 分开。

LLMEngine.add_request() 是第一个真正重要的入口。它接收 prompt、采样参数、优先级、LoRA 请求和到达时间等外部信息，然后建立两份状态：

• OutputProcessor 中的 RequestState：面向用户输出，保存 detokenizer、logprobs 处理器、原始 prompt、流式队列以及父子请求关系。
• EngineCore 中的 Request：面向调度与执行，保存 token、已计算位置、输出 token、KV Cache 相关状态、优先级、到达时间和运行状态。

这不是无意义的重复。两份状态服务于不同一致性域。前端关心字符串停止条件、流式片段怎样拼接、输出是否包含 prompt；核心关心还欠多少 token 计算、占了哪些 KV block、能否被抢占。在线多进程模式下，两份状态本来就位于不同进程，试图让它们共享一个可变对象，反而会造成锁、序列化和故障隔离问题。

第二道边界：EngineCoreClient 隔离进程拓扑#

图源：vLLM 官方架构文档 v1_process_architecture_tp4.png。在四卡张量并行示例中，API Server、Engine Core 与四个 GPU Worker 一共是六个进程；API Server 和 Engine Core 通过 ZMQ 交换请求与结果。

LLMEngine 不直接调用一个固定的 EngineCore 实例，而是持有 EngineCoreClient。这层抽象把“我要提交请求、拿回结果”与“核心究竟在本进程还是另一个进程”分开。

1
def add_request(request):
2
    req, request_wave = engine_core.preprocess_add_request(request)
3
    engine_core.add_request(req, request_wave)
4

5
def get_output():
6
    outputs, model_executed = engine_core.step_fn()
7
    engine_core.post_step(model_executed)
8
    return outputs.get(0, EngineCoreOutputs())

核心忙循环：服务为什么不会空转烧满一个 CPU 核#

多进程模式下，EngineCoreProc.run_busy_loop() 的结构非常短：

1
while engine_is_running:
2
    process_input_queue()
3
    publish_request_counts_if_needed()
4
    process_engine_step()
5
    publish_request_counts_if_needed()

当核心没有工作时，_process_input_queue() 可以阻塞等待输入消息；有请求、待完成 batch 或数据并行 wave 时，循环才继续推进。一次核心 step 没有执行模型但仍有等待状态时，例如正在等远端 KV 到达，代码会短暂让出执行权，让后台传输线程获得进展机会。

这个细节揭示了 busy loop 的准确含义：它是常驻事件循环，不等于无条件自旋。系统既要尽快发起下一次 GPU 工作，又不能在没有请求时白白占满 CPU。

输入队列还承载 ADD、ABORT、UTILITY、WAKEUP 等控制消息。也就是说，请求到达、客户端取消、缓存重置等操作会在核心进程的控制平面汇合。核心在模型执行完成后、提交输出前还会再处理 abort 队列，避免已经取消的请求因为并发时序又被错误提交一个 token。

EngineCore.step()：一次迭代只有三项主任务#

当前源码中的核心函数可以摘成下面这段。省略了统计与错误记录，但保留了控制流：

1
def step(self):
2
    if not self.scheduler.has_requests():
3
        return {}, False
4

5
    scheduler_output = self.scheduler.schedule(
6
        self._should_throttle_prefills()
7
    )
8
    future = self.model_executor.execute_model(
9
        scheduler_output,
10
        non_block=True,
11
    )
12
    grammar_output = self.scheduler.get_grammar_bitmask(
13
        scheduler_output
14
    )
15

16
    model_output = future.result()
17
    if model_output is None:
18
        model_output = self.model_executor.sample_tokens(grammar_output)
19

20
    self._process_aborts_queue()
21
    outputs = self.scheduler.update_from_output(
22
        scheduler_output,
23
        model_output,
24
    )
25
    return outputs, scheduler_output.total_num_scheduled_tokens > 0

它的主干只有三步：

1. schedule()：决定本轮哪些请求计算多少 token，并准备 KV block 等执行元数据。
2. execute_model()：让 Executor 和 Worker 执行模型，返回采样 token、logprobs、连接器结果等。
3. update_from_output()：把执行结果提交回请求状态，判断完成条件，释放资源并生成核心输出。

这个函数短，并不意味着系统简单。恰恰相反，V1 把复杂度推到三个边界清晰的组件里，让 step() 成为可检查的事务骨架。读源码时应先证明自己能解释这三步的输入与输出，再进入任意一个组件的细节。

调度器不再硬分 prefill 队列与 decode 队列#

理解 Scheduler.schedule() 的钥匙，是源码中的一句注释：调度器没有独立的“prefill phase”和“decode phase”。每个请求只记录已经计算的 token 数与当前应覆盖的 token 数，然后尝试让前者追上后者。

可把本轮欠账写成：

1
待计算 token 数
2
= prompt token 数
3
 + 已生成但尚待计算的 token 数
4
 + speculative token 数
5
 + 异步流水中的占位 token 数
6
 - 已计算 token 数

普通 prefill 请求刚入队时，已计算数为 0，欠账接近 prompt 长度；普通 decode 请求每轮通常只多欠 1 个 token；chunked prefill 会把长 prompt 的欠账分多轮偿还；投机解码则一次加入多个 draft token。统一的 token 欠账模型避免为每项特性复制一套调度分支。

执行阶段：为什么先拿 Future，再准备 grammar#

EngineCore.step() 调用 execute_model(..., non_block=True) 得到 Future，随后才从调度器获取结构化输出 grammar bitmask，最后等待 future.result()。这段顺序不是随意排列。

模型执行包含 Worker 调度、输入张量准备、GPU forward 等工作。非阻塞提交后，核心 CPU 可以并行准备采样约束，减少 GPU 工作前后的串行空洞。如果执行后端直接返回已经采样的结果，future.result() 给出完整 ModelRunnerOutput；在某些异步调度路径中，forward 与采样可能被拆开，返回 None 后再用 grammar mask 调用 sample_tokens()。

从接口角度看，ModelRunnerOutput 不是单个 logits 张量。它可以包含：

• request ID 到 batch 行的映射；
• 每个请求采样得到的 token IDs；
• logprobs 与 prompt logprobs；
• pooling 模型输出；
• KV Connector 与 Encoder Cache Connector 的执行结果；
• 投机解码草稿及其接受信息；
• CUDA Graph 等执行统计。

调度器需要的不是“神经网络算完了”这一布尔事件，而是足以完成状态提交的结构化结果。Executor 屏蔽单卡、多进程张量并行和其他执行后端的差异，使 EngineCore.step() 不必知道每个 GPU Worker 如何通信。

update_from_output()：token 生成之后，事务还没有结束#

GPU 得到 token 并不等于本轮结束。Scheduler.update_from_output() 必须把乐观执行计划变成已提交状态。这是理解请求生命周期最容易漏掉的一半。

前端 LLMEngine.step()：它做的是输出语义收尾#

现在回到另一个同名函数。当前 V1 的 LLMEngine.step() 主干如下：

1
def step(self):
2
    outputs = self.engine_core.get_output()
3
    processed = self.output_processor.process_outputs(
4
        outputs.outputs,
5
        engine_core_timestamp=outputs.timestamp,
6
    )
7
    self.engine_core.abort_requests(processed.reqs_to_abort)
8
    record_stats_if_needed()
9
    return processed.request_outputs

它没有再执行一次模型，而是做四件事：拿核心输出、转成用户输出、回传需要终止的请求、记录统计。OutputProcessor.process_outputs() 被设计成整批输出唯一的一次 Python 全量遍历，目的是控制 CPU 开销。

用一个 6-token prompt 走两轮#

假设只有一个请求，prompt 长 6 个 token，max_tokens=2，未命中前缀缓存，当前 token budget 足够。忽略 block size 和特殊 token 后，可以把状态变化写成下表：

这里最反直觉的是 num_computed_tokens 与已生成 token 数不是同一个概念。第 1 轮结束时已经采样出一个新 token，但这个 token 作为下一位置的输入，要到第 2 轮 forward 才真正进入模型并产生后继 token。调度器通过“当前 token 总数减已计算 token 数”自然得到下一轮欠账为 1。

若 prompt 长度超过本轮 token budget，第 1 轮只处理其中一个 chunk，不一定采样输出 token；若命中前缀缓存，num_computed_tokens 会从缓存命中位置起步；若启用投机解码，一轮可能验证多个 draft token。场景不同，但欠账模型不变。

四个必须守住的正确性不变量#

读引擎源码时，与其记住每个分支，不如持续检查四个不变量。

源码调试：从哪里打断点最有效#

第一次跟踪不应在完整在线服务和多卡环境里开始。先用单卡离线请求、确定性采样和很短的输出，把进程拓扑压到最简单，然后观察以下位置：

1
sampling_params = SamplingParams(
2
    temperature=0.0,
3
    max_tokens=2,
4
)

推荐的断点顺序是：

1. LLMEngine.add_request()：确认外部输入何时变为 EngineCoreRequest。
2. Scheduler.add_request()：查看请求初始状态、prompt token 数与 waiting 队列。
3. EngineCore.step()：记录每轮 SchedulerOutput.total_num_scheduled_tokens。
4. Scheduler.schedule()：比较 num_computed_tokens 与 num_tokens_with_spec。
5. Scheduler.update_from_output()：观察新 token、状态迁移和完成条件。
6. OutputProcessor.process_outputs()：确认 token 如何增量解码、何时触发 stop string。

每轮建议只记一行状态：

1
step=3 req=0 status=RUNNING
2
computed=10 total=11 scheduled=1
3
new_tokens=[1234] finished=False

如果进入多进程模式后断点像“失效”一样，先检查函数运行在哪个进程。前端断点抓不到核心进程中的 EngineCore.step() 是正常现象。可以临时使用进程内客户端理解逻辑，再切回多进程验证 IPC；也可以给日志加 PID、request ID 与 step 序号，重建跨进程时间线。

性能分析时还要避免在热循环里打印完整 block table 或全部 token。日志序列化本身就可能扩大迭代间隙，制造并不存在于正常运行中的 CPU 瓶颈。更可靠的办法是记录计数、时间戳和少量 request ID，在异常步骤再有条件地导出详细状态。

常见误读与源码中的真实答案#

这一篇之后，应该能读懂什么#

一次 vLLM V1 请求可以概括为两次翻译和一次核心事务：

• 输入翻译：prompt 与采样配置变成 EngineCoreRequest，前端和核心分别建立自己的请求状态；
• 核心事务：schedule() 生成执行计划，Executor 执行，update_from_output() 提交状态；
• 输出翻译：EngineCoreOutput 经增量解码、stop 检查和父子聚合，变成 RequestOutput。

最重要的源码认识有三点。第一，LLMEngine.step() 与 EngineCore.step() 不在同一层；第二，调度器用 token 欠账统一描述 prefill、decode、chunked prefill 和投机 token；第三，GPU forward 只处于事务中间，状态提交与资源回收同样决定系统正确性。

下一篇将继续深入 Scheduler.schedule()，专门拆解 running 与 waiting 队列、token budget、chunked prefill、前缀缓存命中、KV block 分配和抢占。到那时，本文的调用链会成为定位每个调度分支的坐标系。

参考资料#

1. vLLM 官方架构总览
2. vLLM V1 用户指南
3. vLLM V1 Engine Architecture 设计讨论
4. EngineCore 源码：vllm/v1/engine/core.py
5. 前端 LLMEngine 源码：vllm/v1/engine/llm_engine.py
6. EngineCoreClient 源码：vllm/v1/engine/core_client.py
7. V1 Scheduler 源码：vllm/v1/core/sched/scheduler.py
8. V1 Request 数据结构：vllm/v1/request.py
9. V1 OutputProcessor 源码：vllm/v1/engine/output_processor.py
10. PagedAttention 论文：Efficient Memory Management for Large Language Model Serving with PagedAttention