vllm v1 源码精读（二）：generate() 计算流——model.forward() 在哪里被调用？

本文基于 vllm ba22152（2026-07-06），源码链接均指向该 commit 的固定行号。 代码浏览入口：github.com/vllm-project/vllm/tree/ba22152

1. 上篇交代了初始化，这篇看数据怎么流

上一篇讲了 LLM() 初始化：权重加载到 GPU、KV Cache 分配好、调度器就位。整个 generation 过程是一个循环——每次循环产出一个新 token，直到遇到 EOS 或达到最大长度。

一次循环里，数据经过这几个环节：

用户 prompt (str)
  ① InputProcessor.process_inputs()     vllm/v1/engine/input_processor.py
     → EngineCoreRequest（token ids）
  ② Scheduler.schedule()                vllm/v1/core/sched/scheduler.py:396
     → SchedulerOutput（本步处理哪些请求的哪些 token，KV 块分配）
  ③ GPUModelRunner.execute_model()      vllm/v1/worker/gpu_model_runner.py:4069
     → model.forward(input_ids, positions) → logits
  ④ Sampler.forward()                   vllm/v1/sample/sampler.py
     → sampled token ids
  ⑤ IncrementalDetokenizer.update()     vllm/v1/engine/detokenizer.py:30
     → 增量文本（delta str）

本篇沿着这条路走一遍，重点拆清楚几个非直觉的地方：

• model.forward() 到底在哪一行被调用，调用时的输入长什么样
• 为什么 vllm 里 input_ids 是一维的，而不是普通的 [batch, seq_len] 二维 tensor
• execute_model 和 sample_tokens 为什么拆成两步，不一起做
• 输出的 token id 怎么变回文字，为什么要用”双 token 解码”

2. 整体流程一图看懂

先建立全局视角，每个步骤后面会逐个展开：

整个 generate() 本质上是一个 while 循环，每次循环走完上图的 ①-⑧，直到所有请求都完成：

# vllm/entrypoints/offline_utils.py（精简）
while self.llm_engine.has_unfinished_requests():
    step_outputs = self.llm_engine.step()
    for output in step_outputs:
        if output.finished:
            outputs.append(output)
# 按 request_id 排序，保证输出顺序和输入一致
return sorted(outputs, key=lambda x: int(x.request_id))

注意最后的排序——调度器可能先完成后加入的短请求，排序才能保证你的第 3 条 prompt 对应第 3 条输出。有了全局视角，下面逐步拆开来看。

3. 第一步：Tokenization

数据流的起点是文字变数字。InputProcessor 负责把原始字符串转成 EngineCoreRequest：

# vllm/v1/engine/input_processor.py（精简）
def process_inputs(self, request_id, inputs, params):
    prompt_token_ids = self.tokenizer.encode(inputs.prompt)  # str → list[int]
    # 超过 max_model_len 时截断或报错
    _validate_token_ids(prompt_token_ids, self.model_config)
    return EngineCoreRequest(
        request_id=request_id,
        prompt_token_ids=prompt_token_ids,
        sampling_params=params,
        arrival_time=time.monotonic(),
    )

EngineCoreRequest 是整个 v1 系统的”请求载体”，用 msgspec.Struct(array_like=True, omit_defaults=True) 定义。

为什么用 msgspec 而不是普通 dataclass？

array_like=True 让结构体序列化成数组而不是字典，省掉字段名 key；omit_defaults=True 让默认值字段不序列化。这两个参数加在一起，让 msgpack 的序列化结果非常紧凑。在高吞吐 HTTP serving 场景下，每秒可能有几百个新请求，序列化开销直接影响吞吐——这是一个看起来不起眼但实际上很关键的工程细节。

tokenization 完成后，请求被送进调度器的等待队列。

4. 第二步：请求入队

# vllm/v1/core/sched/scheduler.py（精简）
def add_request(self, req: EngineCoreRequest):
    request = Request.from_engine_core_request(req)
    request.status = RequestStatus.WAITING
    self.waiting.add(request)
    self.requests[request.request_id] = request

Request 是调度器侧最核心的状态对象，后续所有调度决策都围绕它展开：

num_computed_tokens 这个字段是 v1 统一 prefill/decode 调度的关键——它跟踪每个请求当前计算到了哪个位置，调度器据此判断哪些 token 还没算，不再区分”是 prefill 还是 decode”。

5. 第三步：调度器 schedule()

有了请求队列，调度器每步做两件事：决定这步处理哪些请求的哪些 token，以及分配 KV Cache 块。这是 chunked prefill 的实现之处（第三篇会专门展开），这里先看骨架：

# vllm/v1/core/sched/scheduler.py:396（精简）
def schedule(self):
    # Phase 1: 处理 running 队列
    for request in self.running:
        num_new_tokens = request.num_tokens - request.num_computed_tokens
        num_new_tokens = min(num_new_tokens, remaining_token_budget)
        ok = self.kv_cache_manager.allocate_slots(request, num_new_tokens)
        if not ok:
            self._preempt(request)  # KV Cache 不够，踢回 waiting
    
    # Phase 2: 从 waiting 队列准入新请求
    for request in self.waiting:
        # 查前缀缓存命中
        computed_blocks = self.kv_cache_manager.get_computed_blocks(request)
        request.num_computed_tokens = len(computed_blocks) * block_size
        
        num_new = min(remaining_prompt_tokens, remaining_token_budget)
        ok = self.kv_cache_manager.allocate_slots(request, num_new,
                                                   new_computed_blocks=computed_blocks)
        if not ok:
            break  # KV Cache 不够，后面的请求等下一步
        
        self.running.append(request)
        self.waiting.remove(request)
    
    return SchedulerOutput(num_scheduled_tokens={...}, ...)

SchedulerOutput 是调度结果的载体：

• NewRequestData：第一次被调度的请求，带完整数据
• CachedRequestData：后续步骤，只带 diff（新分配的块 id、新 token）
• num_scheduled_tokens：每个请求本步要处理多少 token

这里有个重要的设计决策：CachedRequestData 只传 diff，而不是每步都传完整请求。这意味着 Worker 侧需要自己维护每个请求的状态（通过 _update_states 应用 diff）。好处是序列化开销接近零；代价是 Worker 侧的状态管理变复杂了——这是一个典型的”以复杂性换性能”的工程取舍。

调度结果出来之后，就可以交给 GPU 执行了。

6. 第四步：execute_model() ——model.forward() 在这里

调用链：

Executor.execute_model()
  → Worker.execute_model()         [gpu_worker.py:955]
      → GPUModelRunner.execute_model()  [gpu_model_runner.py:4069]

GPUModelRunner.execute_model() 是重点，分 6 个子步骤：

6.1 _update_states：应用 diff

把 SchedulerOutput 里的 diff 应用到 InputBatch（模型运行器维护的 CPU 状态结构）：

• 新请求：分配 InputBatch 中的槽位，初始化 block table 行
• 结束请求：释放槽位
• 新 KV 块：更新 block table

状态更新完成，才能准备这步的 GPU 输入。

6.2 _prepare_inputs：为什么是 1D？

这一步把 CPU 侧的 InputBatch 打包成 GPU tensor，输出两个核心 tensor：

input_ids: torch.Tensor   # shape [N_tokens]
positions: torch.Tensor   # shape [N_tokens]

注意：是 1D 的，不是 [batch, seq_len] 的 2D。为什么？

同一个 batch 里，不同请求当前步的 token 数差异极大：prefill 中的请求可能有几百个 token，decode 中的请求只有 1 个。如果 padding 成 [batch, max_len]，灰色的 PAD 位置全是无效计算，浪费率极高。

vllm 的做法是把所有请求的 token 直接拼成 1D，配合 cu_seqlens（各序列长度的累积前缀和）告诉 attention 层每个请求的边界在哪里。4 个请求（5+1+3+1 个 token）拼成 [10]，只有 10 次有效计算，零浪费。

FlashAttention（一种 IO-aware 的高效注意力算法）的 2/3 版本原生支持这种 varlen 格式（flash_attn_varlen_func），这是两者的配合点。

6.3 _build_attention_metadata：寻址 KV Cache 的关键

有了 1D 的输入，还需要告诉 attention 层每个 token 对应的 KV Cache 在哪里：

attn_metadata = FlashAttentionMetadataBuilder.build(
    block_table=block_table_gpu,  # [num_reqs, max_blocks]
    slot_mapping=slot_mapping,    # [N_tokens]
    seq_lens=seq_lens,
    ...
)

其中 slot_mapping 是 KV Cache 寻址的核心——每个 token 写入哪个物理 KV Cache 槽？

$B$ 是 block_size，pos 是 token 在请求中的绝对位置。这个映射由 Triton kernel 并行计算。

6.4 set_forward_context：一个优雅的解耦设计

metadata 准备好了，但有一个问题：怎么把 attn_metadata 传进模型？

# vllm/v1/worker/gpu_model_runner.py（精简）
with set_forward_context(attn_metadata, self.vllm_config):
    hidden_states = self.model(
        input_ids=input_ids,   # [N_tokens]
        positions=positions,   # [N_tokens]
    )

注意：attn_metadata 没有作为参数传给 self.model()。它被存入了线程局部变量（set_forward_context 是个 context manager），模型内部的 attention 层自己去取。

为什么这么设计？

标准 HuggingFace 模型的 attention 层签名是 forward(hidden_states, attention_mask, ...)，不认识 vllm 的 attn_metadata。如果要把 attn_metadata 作为参数传进去，就需要改所有模型的 forward 签名——几百个模型，改不完。

用线程局部变量传递的好处：vllm 替换了 attention 层的实现（调用 FlashAttention kernel 的版本），这些 attention 层知道去全局上下文里取 attn_metadata；但模型的其他部分（embedding、FFN、layernorm）完全不知道有这个东西，接口和 HuggingFace 保持一致。这是依赖注入的一种变体——把依赖藏在上下文里而不是参数里。

遇到 “attention metadata not found” 或者 attention 相关的奇怪报错，先检查 set_forward_context 是否正确设置了，以及 attention backend 是否匹配。

6.5 compute_logits：只算最后一个 token

forward 完成后，hidden_states 是 [N_tokens, d_model]，但我们实际上只关心每个请求”下一个 token 是什么”，所以只需要对每个请求的最后一个 token 的 hidden state 做 logits 投影：

# 只对每个请求"最后一个 token"的 hidden state 计算 logits
logits = self.model.compute_logits(hidden_states[logits_indices])
# logits: [N_req, vocab_size]

logits_indices 是每个请求”当前步最后一个 token 在 input_ids 中的位置”。prefill 请求取 prompt 最后一个 token，decode 请求取其唯一 token。这一步把维度从 [N_tokens, d_model] 压缩到 [N_req, vocab_size]，减少了大量不必要的投影计算。

6.6 存入 ExecuteModelState，返回 None

self._execute_model_state = ExecuteModelState(logits=logits, ...)
return None   # 注意这里返回 None！

为什么不直接返回 logits，而是存起来等 sample_tokens() 来取？ 这个问题引出了下一节。

7. execute 和 sample 为什么拆成两步

这是 v1 里一个很精妙的优化。看 EngineCore.step() 的结构：

def step(self):
    scheduler_output = self.scheduler.schedule()
    
    # ④a: GPU forward（非阻塞，把 logits 存起来）
    self.executor.execute_model(scheduler_output, non_block=True)
    
    # ④b: CPU 计算语法 bitmask（与 GPU forward 并行！）
    grammar_output = self.scheduler.get_grammar_bitmask(scheduler_output)
    
    # ⑤: 等 GPU forward 完成，然后采样
    model_output = self.executor.sample_tokens(grammar_output)
    ...

如果用户用了结构化输出（比如要求输出必须是合法 JSON），每步都需要推进一个有限状态机来计算”哪些 token 是合法的下一步”——这是一个纯 CPU 的计算，可能需要几毫秒。

拆成两步之后：GPU 在做 forward 的同时，CPU 在推进语法状态机；GPU forward 完成时，bitmask 也已经算好了，直接进采样。如果不拆，这几毫秒的 CPU 计算就会变成 GPU 的等待时间。这个优化在”每步都有大量结构化输出请求”的场景下效果显著。即使没有结构化输出，grammar_output 为空时 bitmask 步骤是 no-op，没有任何额外开销。

8. 第五步：Sampler.forward()

采样在 vllm/v1/sample/sampler.py 里，执行顺序：

① 先采集 logprobs（如果用户要求了）

if needs_logprobs:
    raw_logprobs = F.log_softmax(logits.float(), dim=-1)

必须在所有修改 logits 的操作之前算——保证用户看到的是原始分布上的概率，而不是经过惩罚修正之后的。

② Logits 处理流水线

# 白名单：只允许特定 token
logits[~allowed_token_ids_mask] = float('-inf')
# 黑名单：bad_words 列表
logits = apply_bad_words(logits, bad_words_token_ids)
# min_tokens：未到最小长度时屏蔽 EOS
if not_yet_min_tokens:
    logits[:, eos_token_id] = float('-inf')
# logit_bias：用户直接调整某些 token 的分数
logits += logit_bias
# 重复惩罚 / 频率惩罚 / 存在惩罚
logits = apply_all_penalties(logits, prompt_ids, output_ids, penalties)

③ 采样

if all_greedy:
    # 快速路径：所有请求都是 greedy，直接 argmax
    sampled = logits.argmax(dim=-1, keepdim=True)   # [N_req, 1]

elif all_random:
    # 随机采样路径
    logits = apply_temperature(logits, temperatures)  # logits /= T
    logits = apply_min_p(logits, min_p)               # 过滤极低概率 token
    sampled = top_k_top_p_sampler(logits, top_k, top_p)

else:
    # 混合：按请求分别处理，用 torch.where 合并
    greedy = logits.argmax(dim=-1)
    random = top_k_top_p_sampler(logits, ...)
    sampled = torch.where(is_greedy_mask, greedy, random)

Top-K / Top-P 的直觉

Top-K：把 vocab 里分数最高的 K 个 token 留下，其余置 $-\infty$，然后 softmax 采样。K 越小越保守，K=1 就是 greedy。

Top-P（nucleus sampling）：按概率从高到低排序，取累积概率刚超过 $p$ 的最小集合，其余置 $-\infty$，然后采样。P=1.0 就是全 vocab 采样，P=0.9 通常能过滤掉大量低概率的长尾 token。

实现上用的是 Gumbel-max trick：给每个 logit 加 Gumbel(0,1) 噪声，然后 argmax——数学上等价于从 softmax 分布采样，但比显式 softmax + multinomial 更快更稳定。

sample_tokens() 最后把采样结果通过异步 D2H（Device to Host）拷贝转到 CPU，组装成 ModelRunnerOutput 返回给调度器。

9. 第六步：update_from_output() ——状态更新和停止检测

采样结果回来之后，调度器要更新每个请求的状态，并判断是否该停止：

# vllm/v1/core/sched/scheduler.py:1501（精简）
for req_id, new_token_id in model_output.sampled_token_ids.items():
    request = self.requests[req_id]
    
    # 追加新 token
    request.output_token_ids.append(new_token_id)
    request.num_computed_tokens += num_scheduled_tokens[req_id]
    
    # 检查停止条件
    is_eos = (new_token_id == tokenizer.eos_token_id)
    is_max = (len(request.output_token_ids) >= sampling_params.max_tokens)
    is_stop = _check_stop_strings(request, new_token_id)
    
    if is_eos or is_max or is_stop:
        request.status = RequestStatus.FINISHED_STOPPED
        self.kv_cache_manager.free(request)   # 释放 KV 块
    
    # 完整的 KV 块写入前缀缓存（供后续请求复用）
    self.kv_cache_manager.cache_blocks(request)

前缀缓存在这里更新：当一个 KV 块被完整填满（block_size 个 token 都已计算），其内容 hash 就确定了，写入前缀缓存 map。后续遇到相同前缀的请求，get_computed_blocks() 能直接命中，跳过 prefill。这是”算过的不再算”的核心机制。

10. 第七步：输出还原——IncrementalDetokenizer

有了 token id，最后一步是还原成文字。这件事听起来简单，实际上有个边界问题要处理：

# vllm/v1/engine/detokenizer.py（精简）
class IncrementalDetokenizer:
    def update(self, request, new_token_id):
        # 用双 token 解码
        new_text = self.tokenizer.decode(
            [self.prev_token_id, new_token_id],
            skip_special_tokens=True,
        )
        # 去掉上一次已经输出的部分，只返回新增字符
        delta = new_text[len(self.prev_decoded_text):]
        self.prev_decoded_text = new_text
        self.prev_token_id = new_token_id
        return delta

为什么要双 token 解码，而不是直接 decode 新 token？

BPE tokenizer 存在边界问题：某些字节序列必须和前一个 token 一起才能正确 decode。比如中文字符”我”可能被拆成两个 byte-level token，单独 decode 其中一个会得到乱码。用双 token decode 并取差值，能正确处理这类 BPE 边界。

这也是为什么流式输出有时候会”卡一下”再出现几个字——tokenizer 在等凑够完整的字符边界。

11. 完整数据流：一个请求的生死

"给我讲个笑话"  (str)
      │ tokenize
[29999, 2769, 26742, ...]  (list[int])
      │ EngineCoreRequest
      │ Scheduler.add_request()  → waiting
      │
      ┌─ Step 1 (prefill) ─────────────────────────────────────┐
      │  input_ids = [29999, 2769, 26742, ...]  (1D, N tok)    │
      │  positions = [0, 1, 2, ...]                            │
      │  model.forward() → hidden_states [N, d]                │
      │  compute_logits(hidden_states[-1]) → logits [1, V]     │
      │  sample → 为什么 (token_id=2627)                        │
      │  num_computed_tokens = N                                │
      └────────────────────────────────────────────────────────┘
      │
      ┌─ Step 2 (decode) ──────────────────────────────────────┐
      │  input_ids = [2627]  (只有新 token，1D，1个)            │
      │  positions = [N]     (接着上一步的位置)                 │
      │  model.forward() → hidden_states [1, d]                │
      │  compute_logits → logits [1, V]                        │
      │  sample → 鸡 (token_id=2354)                            │
      └────────────────────────────────────────────────────────┘
      │
      ... 继续 decode，直到 EOS 或 max_tokens
      │
      update_from_output() → finished=True → free KV blocks
      IncrementalDetokenizer → "为什么鸡要过马路？..."  (str)
      │
RequestOutput(prompt="给我讲个笑话", outputs[0].text="为什么鸡要过马路？...")

12. 常见报错对应位置

13. 小结

generate() 的本质是一个步进循环，每步：

1. 调度器决定这步处理谁的哪些 token
2. 把 token 打包成 1D varlen tensor，喂给 model.forward()（在 gpu_model_runner.py:4069）
3. 从最后一层 hidden state 算 logits，经 Sampler 采样出下一个 token
4. 更新请求状态，检查停止条件
5. token id 增量解码成文字

整条链路里最值得记住的两个设计决策：input_ids 用 1D varlen 而不是 padding，是为了零浪费地混合 prefill 和 decode；execute_model 和 sample_tokens 拆成两步，是为了让 GPU forward 和 CPU 语法计算真正并行。这两个决策共同指向一个目标：把每一毫秒的等待时间都消灭掉。

下一篇：vllm v1 源码精读（三）：KV Cache 管理、Chunked Prefill 与在线 Serving

如果这篇文章涉及的 LLM 推理效率和系统设计你想深入研究，可以看看我们之前出版的《动手学 AutoML：从 NAS 到大语言模型优化实战》，书里 LLM 推理效率那章正好和本文讲的推理框架设计有直接关联。