夜雨聆风本文基于 vllm
ba22152（2026-07-06），源码链接均指向该 commit 的固定行号。代码浏览入口：github.com/vllm-project/vllm/tree/ba22152
1. 上篇交代了初始化，这篇看数据怎么流
上一篇讲了 LLM() 初始化：权重加载到 GPU、KV Cache 分配好、调度器就位。现在来看 generate() 被调用时，数据怎么从一个字符串变成输出 token。
先把调用栈摊开来——这是整篇文章的骨架：
# LLM.generate() — vllm/entrypoints/llm.py:339defgenerate(self, prompts, sampling_params, ...): ...returnself._run_engine(use_tqdm=True)# LLM._run_engine() — vllm/entrypoints/offline_utils.py（精简）def_run_engine(self):whileself.llm_engine.has_unfinished_requests(): step_outputs = self.llm_engine.step() # 每步产出一批新 tokenfor output in step_outputs:if output.finished: outputs.append(output)returnsorted(outputs, key=lambda x: int(x.request_id))# LLMEngine.step() — vllm/v1/engine/llm_engine.pydefstep(self): engine_core_outputs = self.engine_core.step() # 调度 + GPU 执行 + 采样returnself.output_processor.process_outputs(engine_core_outputs)# EngineCore.step() — vllm/v1/engine/core.pydefstep(self): scheduler_output = self.scheduler.schedule() # 决定这步算哪些 tokenself.executor.execute_model(scheduler_output, non_block=True) # GPU forward（非阻塞） grammar_output = self.scheduler.get_grammar_bitmask(scheduler_output) # CPU 并行推进语法状态机 model_output = self.executor.sample_tokens(grammar_output) # 等 GPU + 采样self.scheduler.update_from_output(scheduler_output, model_output) # 更新状态、检查停止return engine_core_outputsEngineCore.step() 里这四行是核心：调度 → GPU forward → 采样 → 状态更新，每次循环都走一遍，直到所有请求完成。_run_engine() 末尾的排序确保第 3 条 prompt 对应第 3 条输出——调度器可能先完成后加入的短请求，顺序未必和输入一致。
本篇沿着这条路走一遍，重点拆清楚几个非直觉的地方：
model.forward()到底在哪一行被调用，调用时的输入长什么样 为什么 vllm 里 input_ids是一维的，而不是普通的[batch, seq_len]二维 tensorexecute_model和 sample_tokens为什么拆成两步，不一起做输出的 token id 怎么变回文字，为什么要用"双 token 解码"
2. 整体流程一图看懂
上面的调用栈对应到时序上就是这张图——每个方块对应后面一个章节：
沿着时序图从上往下走一遍：
① Tokenization：LLMEngine 把原始字符串 encode 成 token ids，封装进 EngineCoreRequest，送入调度器的 waiting 队列。
② Scheduler.schedule()：决定这步处理哪些请求、分配多少 KV Cache 块，输出 SchedulerOutput。Chunked Prefill 在这里发生——长 prompt 被自动切成多步，和 decode 请求混排在同一个 batch。
③ execute_model()（GPU，非阻塞）：GPUModelRunner 把 SchedulerOutput 翻译成 input_ids（1D varlen 格式）+ attn_metadata，调用 model.forward()，结果存入 execute_model_state，立即返回 None 不等结果。
④ get_grammar_bitmask()（CPU，和 GPU 并行）：如果有结构化输出请求，CPU 在这步推进语法状态机，计算哪些 token 合法。这步和 GPU forward 同时跑，GPU 完成时 bitmask 也已经算好了。
⑤ sample_tokens()：等 GPU forward 结果就绪，取出 logits，叠加 bitmask，经 Sampler 采样出下一个 token。
⑥ update_from_output()：把新 token 追加到每个请求的 output，检查停止条件（EOS / max_tokens / stop_string），完成的请求释放 KV Cache 块，完整的 KV 块写入前缀缓存。
⑦ IncrementalDetokenizer：把 token id 增量解码成文字，用双 token 解码处理 BPE 边界，逐字符推送给上层。
有了全局视角，下面逐步拆开来看。
3. 第一步：Tokenization
数据流的起点是文字变数字。InputProcessor 负责把原始字符串转成 EngineCoreRequest：
# LLM.generate() → LLM._run_engine() → LLMEngine.step()# → LLMEngine.engine_core.step() → [step() 之前] LLMEngine.input_processor.process_inputs()# InputProcessor.process_inputs() — vllm/v1/engine/input_processor.pydefprocess_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) 定义。
array_like=True 的效果是把字段名从序列化结果里抹掉。对比一下同一个对象的两种序列化：
# 默认（字典形式）——字段名随数据一起传{"request_id": "r1", "prompt_token_ids": [1, 2, 3], "sampling_params": {...}, ...}# array_like=True（数组形式）——只传值，按位置对应字段["r1", [1, 2, 3], {...}, ...]字段名字符串在每条消息里要占几十字节，在结构复杂的 Struct 里这个开销相当可观。omit_defaults=True 再进一步——采样参数里大多数字段用户根本没改，是默认值，直接从序列化结果里消失。
为什么这个细节值得关注？ 在多进程架构下，EngineCoreRequest 每次从前端进程序列化后经 ZMQ 传到 EngineCore 进程，再反序列化。高吞吐场景每秒几百条请求，序列化在关键路径上，稍有臃肿就会变成瓶颈。msgspec 加上这两个参数后比普通 dataclass + pickle 快一个数量级，是 vllm 选它的主要原因。
tokenization 完成后，请求被送进调度器的等待队列。
4. 第二步：请求入队
# LLM.generate() → LLM._run_engine() → LLMEngine.add_request()# → EngineCoreClient.add_request() → EngineCore.add_request() → Scheduler.add_request()# Scheduler.add_request() — vllm/v1/core/sched/scheduler.pydefadd_request(self, req: EngineCoreRequest): request = Request.from_engine_core_request(req) request.status = RequestStatus.WAITINGself.waiting.add(request)self.requests[request.request_id] = requestRequest 是调度器侧最核心的状态对象，后续所有调度决策都围绕它展开：
prompt_token_ids | ||
output_token_ids | [] | |
num_computed_tokens | 0 | |
status | WAITING | |
block_hashes | [] |
num_computed_tokens 这个字段是 v1 统一 prefill/decode 调度的关键——它跟踪每个请求当前计算到了哪个位置，调度器据此判断哪些 token 还没算，不再区分"是 prefill 还是 decode"。
5. 第三步：调度器 schedule()
有了请求队列，调度器每步做两件事：决定这步处理哪些请求的哪些 token，以及分配 KV Cache 块。这是 chunked prefill 的实现之处（第三篇会专门展开），这里先看骨架：
# LLM.generate() → LLM._run_engine() → LLMEngine.step()# → EngineCoreClient.step() → EngineCore.step() → Scheduler.schedule()# Scheduler.schedule() — vllm/v1/core/sched/scheduler.py:396defschedule(self):# Phase 1: 处理 running 队列for request inself.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)ifnot ok:self._preempt(request) # KV Cache 不够，踢回 waiting# Phase 2: 从 waiting 队列准入新请求for request inself.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)ifnot 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() 在这里
EngineCore.step() 拿到 SchedulerOutput 后，调用链向下穿三层：
# LLM.generate() → LLM._run_engine() → LLMEngine.step()# → EngineCoreClient.step() → EngineCore.step() → Executor.execute_model()# EngineCore.step() — vllm/v1/engine/core.pyself.executor.execute_model(scheduler_output)# ↓ Executor 广播 RPC 给所有 Worker# Worker.execute_model() — vllm/v1/worker/gpu_worker.py:955self.model_runner.execute_model(scheduler_output)# ↓ 真正干活的地方# GPUModelRunner.execute_model() — vllm/v1/worker/gpu_model_runner.py:4069GPUModelRunner.execute_model() 是重点，分 6 个子步骤：
6.1 _update_states：应用 diff
# GPUModelRunner._update_states() — gpu_model_runner.py（精简）把 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 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 槽？
是 block_size，pos 是 token 在请求中的绝对位置。这个映射由 Triton kernel 并行计算。
6.4 set_forward_context：一个优雅的解耦设计
metadata 准备好了，但有一个问题：怎么把 attn_metadata 传进模型？
# GPUModelRunner.execute_model() — vllm/v1/worker/gpu_model_runner.py:4069（精简）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 层自己去取。
为什么不直接把 attn_metadata 传进 self.model() 的参数里？
现实问题：HuggingFace 社区里跑得动的模型有几百个，每个 attention 层的 forward 签名各不相同，你没办法要求它们统一新增一个 vllm 专属参数。改完一个还好，全改一遍根本不现实，而且每次上游模型更新你都得跟着维护。
线程局部变量绕开了这个问题。vllm 把原始 attention 层的实现换掉，换成自己调 FlashAttention kernel 的版本，这个替换版知道去全局上下文里拿 attn_metadata；模型里其他所有部件——embedding、FFN、LayerNorm——完全感知不到有这么个东西，它们的接口和 HuggingFace 保持一样。这是把"外部依赖"藏进调用上下文、而不是塞进函数参数的经典做法。
碰到 attention 相关的奇怪报错，第一件事是确认 set_forward_context 有没有正确执行，以及当前使用的 attention backend 和环境是否匹配。
6.5 compute_logits：只算最后一个 token
forward 完成后，hidden_states 是 [N_tokens, d_model]，但我们实际上只关心每个请求"下一个 token 是什么"，所以只需要对每个请求的最后一个 token 的 hidden state 做 logits 投影：
# GPUModelRunner.execute_model() — gpu_model_runner.py（精简）# 只对每个请求"最后一个 token"的 hidden state 计算 logitslogits = 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, ...)returnNone# 注意这里返回 None！为什么不直接返回 logits，而是存起来等 sample_tokens() 来取？ 这个问题引出了下一节。
7. execute 和 sample 为什么拆成两步
这是 v1 里一个很精妙的优化。看 EngineCore.step() 的结构：
# EngineCore.step() — vllm/v1/engine/core.pydefstep(self): scheduler_output = self.scheduler.schedule()self.executor.execute_model(scheduler_output, non_block=True) # GPU forward（非阻塞） grammar_output = self.scheduler.get_grammar_bitmask(scheduler_output) # CPU 并行 model_output = self.executor.sample_tokens(grammar_output) # 等 GPU + 采样 ...如果用户用了结构化输出（比如要求输出必须是合法 JSON），每步都需要推进一个有限状态机来计算"哪些 token 是合法的下一步"——这是一个纯 CPU 的计算，可能需要几毫秒。
拆成两步之后：GPU 在做 forward 的同时，CPU 在推进语法状态机；GPU forward 完成时，bitmask 也已经算好了，直接进采样。如果不拆，这几毫秒的 CPU 计算就会变成 GPU 的等待时间。这个优化在"每步都有大量结构化输出请求"的场景下效果显著。即使没有结构化输出，grammar_output 为空时 bitmask 步骤是 no-op，没有任何额外开销。
8. 第五步：Sampler.forward()
回到骨架——execute_model 完成后，GPU 把 logits 存在 _execute_model_state 里；接下来 sample_tokens() 取出 logits，调用 Sampler.forward() 采样：
# LLM.generate() → LLM._run_engine() → LLMEngine.step()# → EngineCoreClient.step() → EngineCore.step() → Executor.sample_tokens() → Sampler.forward()# EngineCore.step()（精简）self.executor.execute_model(scheduler_output, non_block=True) # GPU forwardgrammar_output = self.scheduler.get_grammar_bitmask(...) # CPU 并行model_output = self.executor.sample_tokens(grammar_output) # ← 这里触发采样采样在 vllm/v1/sample/sampler.py 里，分三个阶段依次进行。
第一步采集 logprobs（如果用户要求了）：
if needs_logprobs: raw_logprobs = F.log_softmax(logits.float(), dim=-1)必须在所有修改 logits 的操作之前算——保证用户看到的是原始分布上的概率，而不是经过惩罚修正之后的。
接着是 logits 处理流水线，按顺序应用各种约束和惩罚：
# 白名单：只允许特定 tokenlogits[~allowed_token_ids_mask] = float('-inf')# 黑名单：bad_words 列表logits = apply_bad_words(logits, bad_words_token_ids)# min_tokens：未到最小长度时屏蔽 EOSif 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)处理完 logits，最后从中采样：
# Sampler.forward() — vllm/v1/sample/sampler.pyif 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 留下，其余置 ，然后 softmax 采样。K 越小越保守，K=1 就是 greedy。
Top-P（nucleus sampling）：按概率从高到低排序，取累积概率刚超过 的最小集合，其余置 ，然后采样。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() ——状态更新和停止检测
sample_tokens() 返回 model_output，下一行就是：
# LLM.generate() → LLM._run_engine() → LLMEngine.step()# → EngineCoreClient.step() → EngineCore.step() → Scheduler.update_from_output()# EngineCore.step()（精简）model_output = self.executor.sample_tokens(grammar_output)self.scheduler.update_from_output(scheduler_output, model_output) # ← 这里调度器拿到新 token，更新每个请求的状态并判断是否该停止：
# Scheduler.update_from_output() — vllm/v1/core/sched/scheduler.py:1501for 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_STOPPEDself.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
update_from_output() 结束，EngineCore.step() 把结果返回给上层的 LLMEngine.step()：
# LLM.generate() → LLM._run_engine() → LLMEngine.step()# → OutputProcessor.process_outputs() → IncrementalDetokenizer.update()# LLMEngine.step()（精简）engine_core_outputs = self.engine_core.step()returnself.output_processor.process_outputs(engine_core_outputs) # ← 这里解码process_outputs() 内部调用 IncrementalDetokenizer 把 token id 还原成文字。这件事听起来简单，实际上有个边界问题要处理：
# vllm/v1/engine/detokenizer.py（精简）classIncrementalDetokenizer:defupdate(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_textself.prev_token_id = new_token_idreturn delta为什么要双 token 解码，而不是直接 decode 新 token？
BPE tokenizer 存在边界问题：某些字节序列必须和前一个 token 一起才能正确 decode。比如中文字符"我"可能被拆成两个 byte-level token，单独 decode 其中一个会得到乱码。用双 token decode 并取差值，能正确处理这类 BPE 边界。
这也是为什么流式输出有时候会"卡一下"再出现几个字——tokenizer 在等凑够完整的字符边界。
11. 常见报错对应位置
GPUModelRunner._model_forward() | |
vllm/v1/sample/sampler.py | |
IncrementalDetokenizer | |
vllm/v1/attention/backends/flash_attn.py | |
offline_utils.pysorted()，检查 request_id 是否正确赋值 |
12. 小结
generate() 的本质是一个步进循环，每步：
调度器决定这步处理谁的哪些 token 把 token 打包成 1D varlen tensor，喂给 model.forward()（在gpu_model_runner.py:4069）从最后一层 hidden state 算 logits，经 Sampler 采样出下一个 token 更新请求状态，检查停止条件 token id 增量解码成文字
整条链路里最值得记住的两个设计决策：input_ids 用 1D varlen 而不是 padding，是为了零浪费地混合 prefill 和 decode；execute_model 和 sample_tokens 拆成两步，是为了让 GPU forward 和 CPU 语法计算真正并行。这两个决策共同指向一个目标：把每一毫秒的等待时间都消灭掉。
另外，我们团队最近出版了《动手学 AutoML：从 NAS 到大语言模型优化实战》，感兴趣的话可以看看。
动手学AutoML书籍封面
