SGLang 源码完全拆解（六）：Overlap Scheduler 如何重叠 CPU 调度与 GPU 执行

从 KV 所有权走向在途执行#

前五篇已经把 SGLang 的请求主线推进到物理 KV 所有权：入口层把协议请求变成 token，Scheduler 维护 waiting/running 状态，PrefillAdder 决定哪些请求能进入本轮，ReqToTokenPool 与 RadixCache 再把逻辑序列映射到共享的物理 KV 槽。到这里仍暗含一个方便但昂贵的假设：CPU 只有等本轮 GPU 前向、采样和结果拷回全部结束，才开始准备下一轮。

这个假设保证时序直观，却会在每个 decode step 之间留下空隙。一次 Transformer decode 也许只需数毫秒，CPU 仍要完成请求过滤、停止条件判断、前缀树操作、KV 页分配、batch tensor 构造和 Kernel launch。若这些动作串在 GPU 前向之后，几百个输出 token 会把同一段固定开销重复几百次。模型越小、batch 越小或张量并行度越高，单轮 GPU 时间越短，CPU 气泡所占比例反而越大。

SGLang 团队在 2024 年 12 月发布 v0.4 时把这条路径称为 Zero-Overhead Batch Scheduler，并默认启用 overlap schedule。它的目标不是让 CPU 工作消失，而是让 CPU 在 batch $n$ 的 GPU 前向期间准备 batch $n+1$，把可并行的主机开销藏进设备计算窗口。官方基准在 Llama 3.2 3B、H100 的指定设置下报告相对 v0.3 约 1.1 倍吞吐提升；这个数字只说明该工作负载中气泡确实可见，不能当作所有模型的固定收益。

本文继续使用系列前文相同的固定提交 d88d5c325ad1cf28f2b804edcd8886e891a8f9b8。当前实现已比 v0.4 初版复杂得多：普通 decode、mixed chunk、结构化输出、投机解码、Mamba、分层缓存和多种并行模式都会经过同一条重叠基础设施。为了先抓住稳定不变量，主线限定为单 GPU、普通自回归生成、无投机解码；高级分支只在它改变同步边界时解释。

上一篇留下的核心问题由此变得具体：GPU 仍在读取上一轮页表时，CPU 能否回收 KV 页？上一轮 token 尚未回到 Python 时，下一轮的 input_ids 从哪里来？请求已经在设备上多算了一步，但 CPU 刚刚判定 EOS，又该如何结算？Overlap Scheduler 的难点不是“多开一条 stream”，而是把每个状态分成已计划、已发出、已物化和已提交四个时刻。

串行调度为什么会让 GPU 等 CPU#

关闭 overlap 后，event_loop_normal() 的骨架十分直接：接收请求，形成 batch，同步执行，再立刻处理结果。

1
while True:
2
    ingest_requests()
3
    plan = get_next_batch_to_run(running_batch, last_batch)
4
    batch = plan.batch_to_run
5

6
    if batch:
7
        result = run_batch(batch)
8
        process_batch_result(batch, result)
9

10
    last_batch = batch

这里的 run_batch() 不只是提交一个 CUDA Kernel。它会准备 ForwardBatch，运行模型与采样，并把下一 token、logprob 等结果转到 CPU 可读取的位置。process_batch_result() 再把结果写入 Req.output_ids，判断 EOS、长度与 stop token，发送流式输出，checkpoint 有效 KV，释放完成请求并更新指标。直到这些动作结束，循环才重新进入 get_next_batch_to_run()。

把第 $i$ 轮 GPU 时间记为 $G_i$，CPU 结果处理与下一轮调度时间记为 $C_i$，忽略首尾启动开销，串行执行 $N$ 轮的时间近似为：

GPU 利用率的理想化上界为：

如果 decode 前向是 3 ms，而 CPU 每轮暴露 1 ms，哪怕 Kernel 本身已经很快，设备利用率上界也只有 75%。这里的 1 ms 不是某个单一函数造成的：Python 队列遍历、Radix tree 匹配、页分配、小 tensor 构造、H2D/D2H 同步和采样后处理都可能贡献几十到几百微秒。优化一个函数之后，剩余动作仍会形成串行尾巴。

图源：SGLang v0.4 官方发布文章。绿色块是 CPU 的 launch、结果处理、采样发射与下一批准备，黄色块是 GPU 计算与采样。关键不在某两个方框恰好并排，而在依赖关系被重新切开：CPU 不必先得到 batch $n$ 的完整 Python 结果，才能描述 batch $n+1$ 的大部分设备工作。

理想的单步流水线把总时间改写为近似：

当每轮 $C_i\le G_{i+1}$ 时，中间 CPU 开销被全部隐藏；当 $C_i>G_{i+1}$ 时，仍会暴露 $C_i-G_{i+1}$ 的尾部。因此 “zero-overhead” 描述的是时间线上的可见开销接近零，不是 Scheduler 不再消耗 CPU。它也解释了收益边界：长 prefill 或大模型 decode 的 $G$ 足够长，本来就能掩盖很多 CPU 工作；小模型、低 batch 和高 TP 下的 $G$ 更短，重叠通常更重要。

这类优化首先由系统时间线驱动，而不是由注意力数学驱动。SGLang 官方文章指出思路与 NanoFlow 相通：把 CPU 调度放到 GPU 计算旁边形成软件流水。两者的具体对象和执行引擎不同，但共同原则都是把“必须等结果”的同步压到最小，把不依赖结果的元数据准备提前。

Overlap Scheduler 的执行时间线#

当前 event_loop_overlap() 保留了普通循环的外形，却把结果处理延迟一轮。其主干可压缩为：

1
result_queue = deque()
2

3
while True:
4
    ingest_requests()
5
    plan = get_next_batch_to_run(running_batch, last_batch)
6
    batch = plan.batch_to_run
7

8
    if must_sync(batch, last_batch):
9
        process(result_queue.popleft())
10

11
    if batch:
12
        result = run_batch(batch)
13
        result_queue.append((batch.copy(), result))
14

15
    if last_batch and not must_sync(batch, last_batch):
16
        process(result_queue.popleft())
17

18
    launch_delayed_sample_if_needed(batch, result)
19
    last_batch = batch

顺序里最容易看漏的一点是：run_batch(batch_n) 返回，不等于 batch $n$ 的全部 GPU 工作已经完成。PyTorch 在 CUDA stream 上异步排队，返回的 GenerationBatchResult 可以携带尚未物化到 host 的结果及完成事件。于是 CPU 能在 forward_stream 执行 batch $n$ 时，处理队首的 batch $n-1$。

一次稳定 decode 的时序可以写成：

1
迭代 n 的 CPU：准备 batch n -> launch batch n -> 提交 batch n-1
2
迭代 n 的 GPU：                 执行 batch n
3

4
迭代 n+1 CPU：准备 batch n+1 -> launch batch n+1 -> 提交 batch n
5
迭代 n+1 GPU：                     执行 batch n+1

这里实际有三类执行上下文：

run_batch() 进入 forward_stream_ctx 前，先让 forward stream 等待 schedule stream，确保 CPU 已经提交的 H2D 元数据和分配结果对本轮可见。模型完成后，普通 CUDA 路径让 copy_stream 等待 forward stream，再做 D2H；下一轮前向不必反过来等待整段 D2H。结果对象上的 copy_done 事件最终保证 process_batch_result() 读取 host 数据时拷贝确实完成。

官方 Nsight 轨迹展示了这种组织想达到的效果：相邻 decode batch 的 GPU Kernel 几乎首尾相接，CPU 结果处理与准备工作落在设备忙碌区间内。

图源：SGLang v0.4 官方发布文章。图中的蓝色 Kernel 带接近连续，说明该设置下主机气泡已基本隐藏；这张图使用当时的 Triton attention backend，不能据此推断所有 backend、batch shape 和硬件都没有间隙。

流水线并不允许任意乱序。源代码中的 _apply_war_barrier() 处理一类 write-after-read 风险：下一轮 CPU 可能想改写或复用某个共享元数据，而上一轮 forward 仍在读。屏障不需要把所有 stream 全局同步，只需让真正存在读写冲突的资源等到 shared read 完成。同步粒度越粗，正确但重叠越少；粒度越细，吞吐更好但必须准确描述 tensor 生命周期。

在途批次：last_batch 与 result_queue#

last_batch 与 result_queue 看似都表示上一批，职责并不相同。

last_batch 是调度视角的在途批次。get_next_batch_to_run() 需要知道上一轮是 extend 还是 decode，才能把刚完成 prefill 的请求合入 running_batch、排除仍在 chunking 的请求，并决定下一轮能否继续 decode。它回答的是“上一轮发出了什么计划”。

result_queue 是提交视角的在途结果。每个元素是 (batch_snapshot, result_handle)：前者保存解释结果所需的批次快照，后者保存异步前向与 D2H 的结果句柄。它回答的是“哪一轮结果还没有写回长期请求状态”。在普通稳定路径中队列深度约为一；同步边界、空闲、投机和某些并行模式会让代码显式排空或特殊处理。

为什么入队时必须 batch.copy()，不能直接保存当前 batch？ScheduleBatch 会在下一次调度中被 filter_batch()、merge_batch()、prepare_for_decode() 修改；请求列表、序列长度、forward mode 和输出位置都可能改变。结果返回后仍需按 batch $n$ 的行顺序把 token 归还给 batch $n$ 的请求。如果 result queue 引用同一个可变列表，下一轮删掉一个 finished request 后，旧结果就可能错配到另一条请求。

当前 copy() 只快照结果处理真正使用的字段，而不是深拷贝整个 batch。它会复制 reqs 列表本身，使后续 rebind/filter 不改变旧批次的成员顺序；列表里的 Req 对象仍然共享。这个折中避免复制大量 tensor，也引入一条纪律：任何会被下一轮提前修改、而旧结果处理还依赖的标量，都必须额外快照。例如 Mamba 分支会保存本轮 decode_batch_idx，因为共享 Req 可能已被下一轮加一。

可以把正确性条件写成：对队列中的第 $k$ 个结果，快照请求顺序 $Q_k$ 与设备结果行顺序 $R_k$ 必须保持一一对应：

这也是在重叠路径中“浅拷贝是否足够”的判断标准：不是看对象有没有变，而是看旧结果解释所依赖的字段能否被后续迭代改坏。

队列还有一个资源生命周期作用。GenerationBatchResult 可能持有 device tensor、CUDA event、延迟采样闭包或需要跨 stream 保活的引用。当前实现用双槽 batch_record_buf 把部分 tensor 至少固定两个迭代，避免 Python 引用提前消失后 caching allocator 复用其存储，而 GPU 仍在异步读取。这里的“两轮”不是业务语义，而是流水深度对应的最短保活窗口。

future token：结果未返回时怎样准备下一轮#

重叠 decode 面临一个因果依赖：batch $n+1$ 的输入正是 batch $n$ 采样出的 token。CPU 若还没执行 process_batch_result()，Req.output_ids 就没有这个 token；直接从 Python 请求对象构造下一批会读到旧值。简单解法是同步等待 D2H，再准备下一批，但这会重新制造需要消除的气泡。

SGLang 用 FutureMap 把“值未知”和“地址未知”分开。每条活动请求已经有稳定的 req_pool_idx，因此下一 token 虽然尚未产生，它未来要写入哪一行却已经知道。FutureMap.output_tokens_buf 是按 request pool row 索引的设备 tensor：batch $n$ 采样后把 token scatter 到对应行，batch $n+1$ 在 forward 入口按同一组行号 gather。数据依赖由 GPU stream 顺序和 event 保证，不必先绕到 Python list。

1
batch n
2
  req_pool_indices = [7, 19, 23]
3
        │
4
        ├─ model forward -> sample [t7, t19, t23]
5
        │
6
        └─ FutureMap.output_tokens_buf[[7,19,23]] = [t7,t19,t23]
7
                                                       │
8
batch n+1                                              │
9
  input_ids = FutureMap.output_tokens_buf[[7,19,23]] ◀─┘

ScheduleBatch.prepare_for_decode() 在 overlap 模式下可以把 batch.input_ids 留成占位状态，仍提前完成 KV 位置申请、sequence length 更新和大部分 metadata 构造。真正进入 forward_stream 时，resolve_forward_inputs() 才物化输入：纯 decode 从 output_tokens_buf[req_pool_indices] gather；prefill 从 pinned CPU staging 做异步 H2D；mixed batch 则把 prefill token 与 running request 的 future token 拼接。

核心路径可以压成以下伪代码：

1
# batch n 的设备结果发布
2
future_map.output_tokens_buf[req_pool_indices] = next_token_ids
3

4
# batch n+1 真正进入 forward stream 时解析
5
if batch.input_ids is None:
6
    batch.input_ids = future_map.output_tokens_buf[batch.req_pool_indices]

这不是预测 token，也不是先用占位值计算。batch $n+1$ 仍严格依赖 batch $n$ 的采样结果，只是依赖边停留在设备侧，由 stream 中的 producer-consumer 顺序解析。CPU 可以提前搭好“从哪些行读”的图，而不能提前知道“每行是什么值”。

为什么索引必须使用 req_pool_idx，而不是 batch 内部的第 $j$ 行？动态 batching 会不断过滤完成请求、插入新请求和合并 prefill；同一请求在相邻 batch 的局部行号可能不同。request pool row 在请求生命周期内稳定，既能作为 KV 页表行号，也能作为跨迭代 future 值邮箱。请求行释放后又可能被新请求复用，所以当前实现还维护 req_generation，让异步读者识别 ABA 式复用。

FutureMap 还保存 new_seq_lens_buf。普通单 token decode 的长度增长可提前推断，但投机解码的接受长度只有 verify 后才知道；后续 attention backend 又可能需要 CPU 侧 seq_lens 来构造 metadata。当前实现按 backend 需求决定是否把新长度经专用 D2H stream 拉到 pinned host buffer。若 backend 能走纯 GPU 长度路径，就跳过这次同步；若必须读取 CPU 镜像，resolve_seq_lens_cpu() 只等待发布事件，不让整个 schedule stream 粗暴同步。

对 mixed chunk，难点再多一层。prefill 请求的输入来自 CPU，running decode 请求的尾 token 来自 FutureMap，两者要在同一个 forward 中形成正确顺序；投机模式下 running request 的实际接受长度还会改变 out_cache_loc。resolve_mixed_spec_tails() 因而在发布栅栏之后，用已提交长度重新绑定尾部行。这里的原则与普通 decode 相同：调度阶段先固定引用，forward 入口再读取上一轮物化的值。

FutureMap 把跨迭代依赖改造成设备数据流，但没有消除同步，只把同步从“CPU 等整个结果”缩小为“消费者等特定发布事件”。如果 future row 没被上一轮写入就读取，得到的不是稍旧 token，而是未初始化数据。CI 路径会把 buffer 初始化为 -1，并在 gather 时断言非负、消费后重新 poison，用来捕获漏 publish 或重复 consume。

延迟提交：何时才能修改请求真值#

FutureMap 让设备能够继续算，CPU 上的 Req 却不能假装结果已经发生。Req.output_ids、finished_reason、流式输出和可共享缓存都属于已提交事实，只能在 process_batch_result() 读到完成结果后修改。

一轮 token 的生命周期应区分为：

1
planned     已分配下一轮页和 metadata，尚未 launch
2
in-flight   已进入 forward/copy stream，结果不可由 CPU 读取
3
materialized token 已写入 FutureMap，下一轮设备可消费
4
committed   D2H 完成，CPU 已更新 Req、停止状态与资源账本

materialized 与 committed 是 overlap 的关键分界。同一个 token 可以已经被下一轮 GPU 当输入，却尚未追加到 Req.output_ids。这听起来反直觉，实际上是典型流水线：设备数据通路向前推进，控制通路晚一拍确认。

当前 process_batch_result_decode() 首先等待 result.copy_done，然后规范化输出行，逐请求执行以下步骤：

1
for req, next_tokens in zip(batch.reqs, result.next_token_ids):
2
    if overlap and (req.finished() or req.is_retracted):
3
        continue
4

5
    req.output_ids.extend(next_tokens)
6
    req.update_finish_state(len(next_tokens))
7

8
    if req.finished():
9
        release_kv_cache(req, tree_cache, checkpoint=True)

省略的 logprob、grammar、beam 和多模态分支不会改变提交顺序：先确认 host 结果，再更新语义历史，再判断完成，最后结算资源。update_finish_state() 需要检查 max_new_tokens、EOS、stop token 等条件；字符串 stop 仍由后续 detokenizer 参与。完成原因一旦成立，Scheduler 才能向输出管线发送最终状态。

延迟提交也意味着调度阶段不能随便读取 len(req.output_ids) 推断设备精确进度。某些字段以 committed state 为准，另一些字段例如 kv_committed_len 或 batch 自身的 seq_lens 可能已经为在途轮次预推进。源码中的许多 “减一”“lookahead in (0,1)” 断言，本质上都在检查控制通路最多落后设备一拍。

缓存写回尤其不能提前。上一轮 forward 正在把 K/V 写入新分配槽时，CPU 若先把这些索引 checkpoint 到 RadixCache，另一请求可能命中尚未完成的数据；若先释放或驱逐，更会产生 use-after-free。只有结果提交点确认本轮设备工作完成，checkpoint_kv_cache() 才能把连续有效区间发布到树。上一篇讨论的 cache_protected_len 因此不仅是空间边界，也是时间边界。

同理，指标与 trace 也在结果处理处提交。当前 process_batch_result() 会在 overlap 模式下把 trace flush、负载快照、完成统计等 CPU 工作放进下一轮 GPU 前向窗口。这些动作不影响 token 数值，适合延后；但它们读取的请求状态必须对应已经提交的 batch 快照，不能混用正在准备的下一批。

Prefill、Decode 与 Chunked Prefill 的分支#

“延迟一轮处理”在稳定 decode 中最整齐，但 extend/prefill 改变了请求集合和 KV 所有权，不能机械套用同一条时间线。

Overshoot：多跑一步为什么不能直接忽略#

Overlap Scheduler 永远有一轮控制延迟。batch $n$ 采样出 EOS 时，CPU 尚未提交这个结果，batch $n+1$ 可能已经为同一请求分配 KV 并发射。batch $n+1$ 以 EOS 作为输入又计算一次，这一拍就是 overshoot。

时间线可以写成：

1
GPU batch n:    sample EOS -> publish EOS to FutureMap
2
CPU prepare:    尚不知道 EOS，仍把请求放入 batch n+1
3
GPU batch n+1:  读取 EOS，写入一个额外 KV 槽并采样 extra token
4
CPU commit n:   追加 EOS，设置 finished_reason，释放请求
5
CPU commit n+1: 发现 req 已 finished，丢弃 extra token

额外 token 不能追加到 output_ids，不能发给用户，也不能推进 stop/grammar 状态。当前 decode 结果处理器开头检查：在 overlap 模式下，如果 req.finished() 或 req.is_retracted，直接跳过这条旧快照中的结果。注释明确把这种再次出现视为 overlap 的预期路径，而不是重复完成错误。

“丢弃结果”仍不够。batch $n+1$ 已经占用物理 KV 位置，甚至可能预分配了更长尾部。完成 batch $n$ 时的 release_kv_cache() 必须知道 kv_allocated_len 可能领先语义有效长度，把 overshoot 和其他 overallocated tail 一并归还。否则用户看不到错误 token，显存却会每个完成请求泄漏一页。

对按长度结束的请求，下一轮是否会结束可以提前判断。当前 _reqs_finishing_inflight() 查看 result queue 中即将提交的请求，并用 next_output_finishes_by_length() 把确定达到 max_new_tokens 的行从下一 decode batch 排除。这能避免已知终点的 overshoot。EOS 和随机采样结果无法由 CPU 提前知道，仍允许最多一拍的 lookahead。

这给出了 overlap 安全所需的三个条件：

1. lookahead 深度有明确上界，当前普通路径按一轮设计；
2. 迟到结果处理幂等，已完成请求不会再次追加输出或释放两次；
3. 资源释放按已分配长度结算，而不是只按用户可见 token 长度结算。

若流水深度从一轮扩到多轮，这三处都必须重做。仅把 result queue 放深并不能获得免费的多步 overlap，因为请求可能连续多算多轮，KV 预留、stop 泄漏、grammar 状态和随机数消费都会改变。

投机解码让 overshoot 更复杂：一次 verify 可接受多个 token，实际长度直到设备结果产生才知道；FutureMap 还要转发 bonus token、top-k、hidden state 或草稿概率。当前 Spec V2 为这些字段建立同类 relay，并用发布 event 与 generation 保护每个请求行。它仍遵循相同原则，只是“一拍”不再等于一个 token。

缓存 checkpoint 与资源回收的安全点#

上一轮 GPU 与下一轮 CPU 并行后，任何 free 都要先问：旧 stream 是否还在读这段内存？这包括 KV slot、request row、batch metadata tensor 和统一内存搬迁源地址。

对普通完成路径，安全顺序是：

1
等待 batch n 的 copy_done
2
  -> 将 token 提交到 Req
3
  -> update_finish_state
4
  -> checkpoint 已完成且有效的 KV
5
  -> 解锁旧缓存路径
6
  -> 释放请求私有尾部与 overshoot
7
  -> 归还 req_pool row

copy_done 只直接描述结果 D2H，但它位于 forward 之后，因此也间接证明本轮对 KV 的写入已经排在前面完成。若另有独立异步传输或 offload，则不能借用这条推论，必须等待对应事件；代码中的 P/D 分离与 decode offload 分支正是额外协议。

请求行的释放也比普通循环敏感。FutureMap 以 req_pool_idx 为 key，batch snapshot 和正在运行的 Kernel 都可能保留这一行。旧请求释放后，新请求若立即复用相同行号，而旧 D2H 或异步 relay 又迟到，就会把新请求状态误当旧请求状态。除了 stream 保活，req_generation 还提供逻辑世代校验；这类问题与无锁数据结构中的 ABA 问题相似。

滑动窗口注意力提供了一个直观反例。decode 逐步前进时可以回收窗口外 KV，但第一个 overlap decode 发出时，上一轮 extend 可能仍在读取完整前缀。当前代码在 decode_batch_idx==0 时禁止相应 SWA eviction；chunked prefill 也要等足够多轮后才驱逐旧窗口。回收条件不能只看“下一轮理论上不需要”，还要看“上一轮实际上是否已经停止读取”。

当前 _forward_isolation() 还把一次 forward 包装成事务式边界：保存会被 worker 临时改写的 ScheduleBatch 字段，执行设备提交，再恢复 schedule-side 视图；overlap 路径额外把快照与保活引用放进双缓冲。这个设计避免 ModelRunner 为运行需要就地改写 batch 后，Scheduler 下一轮看到半设备态、半调度态对象。

因此，缓存安全点可以用两个条件表达。设资源 $x$ 的最后设备读写事件为 $E_x$，CPU 所有权提交为 $C_x$，只有同时满足

才能把 $x$ 归还可复用池。前者防止物理 use-after-free，后者防止语义上的重复释放或错误 checkpoint。只满足其中一个都不够。

源码主循环与关键伪代码#

1
def overlap_loop():
2
    pending = deque()
3
    last_batch = None
4

5
    while True:
6
        ingest_requests()
7

8
        # 依据 committed Req + last_batch 的在途结构准备新计划
9
        plan = schedule(running_batch, last_batch)
10
        batch = plan.batch_to_run
11

12
        # 某些边界必须先提交旧结果
13
        if needs_sync(batch, last_batch):
14
            old_batch, old_result = pending.popleft()
15
            commit(old_batch, old_result)
16

17
        if batch is not None:
18
            allocate_kv_and_build_metadata(batch)
19

20
            # forward 入口才解析上一轮产生的 token
21
            resolve_forward_inputs(batch, future_map)
22
            result = launch_forward_and_sample(batch)
23

24
            # 设备侧为下一轮发布 token/长度
25
            future_map.publish(batch.req_pool_indices, result)
26
            enqueue_d2h_on_copy_stream(result)
27

28
            pending.append((batch.copy(), result))
29

30
        # batch n 在 GPU 跑时，CPU 提交 batch n-1
31
        if last_batch is not None and not needs_sync(batch, last_batch):
32
            old_batch, old_result = pending.popleft()
33
            commit(old_batch, old_result)
34

35
        last_batch = batch

性能数字应该怎样读#

图源：SGLang v0.4 官方发布文章。图中比较 SOTA OSS baseline、SGLang v0.3 与开启重叠调度的 v0.4；原文给出的环境是 H100 上的 Llama 3.2 3B，并报告 v0.4 相对 v0.3 约 1.1 倍。这个结果验证了机制，但不能脱离模型、输入输出长度、并发和 attention backend 单独引用。

判断自己的服务是否受益，应测两种模式的同一套请求分布：默认 overlap 与 --disable-overlap。至少同时记录 output throughput、TTFT、TPOT/ITL、GPU kernel gap 和 Scheduler CPU 时间。若吞吐不变但 TTFT 恶化，可能是连续 prefill 排队策略；若 GPU gap 仍明显，可能有未被隐藏的 host sync；若 GPU 已连续而 CPU 满核，瓶颈可能转移到 tokenization、detokenization 或协议层。

不能只用平均 tokens/s 判断正确性。Overlap 改变了提交时序，测试还要比较固定随机性下的 token 序列、finish reason、流式/非流式结果、KV 空闲计数和请求结束后的 pool 恢复。速度变快但偶发多一个 token、重复 stop、页数缓慢下降，都说明流水线账本尚未闭合。

调试方法、边界条件与常见误读#

1
iteration
2
batch object id
3
forward_mode
4
rid list
5
req_pool_indices
6
seq_lens_cpu
7
out_cache_loc
8
result_queue length
9
last_batch mode
10
len(req.output_ids)
11
req.finished_reason
12
kv_committed_len / kv_allocated_len

1
rg -n "event_loop_(normal|overlap)|run_batch|process_batch_result" \
2
  python/sglang/srt/managers/scheduler.py
3

4
rg -n "class FutureMap|resolve_forward_inputs|def (publish|stash)" \
5
  python/sglang/srt/managers/overlap_utils.py
6

7
rg -n "prepare_for_decode|def copy|enable_overlap" \
8
  python/sglang/srt/managers/schedule_batch.py
9

10
rg -n "process_batch_result_decode|_handle_finish_state_updated_req" \
11
  python/sglang/srt/managers/scheduler_components/batch_result_processor.py

小结与后续路线#

SGLang Overlap Scheduler 把串行的“GPU 前向 → CPU 结果处理 → 下一批准备”改造成一拍软件流水：batch $n$ 在 forward_stream 上执行时，CPU 提交 batch $n-1$ 并准备 batch $n+1$；copy_stream 单独搬运结果，尽量不阻塞下一次前向。它消除的是时间线中的可见 CPU 气泡，不是 CPU 工作本身。

这条流水能够成立，依赖四组机制共同闭环。last_batch 保存下一轮调度所需的在途结构，result_queue 保存尚未提交的结果与批次快照；FutureMap 用稳定 request pool row 在设备侧传递下一 token 和长度，避免 CPU 为取值同步；process_batch_result() 把 token、完成原因和缓存发布收敛到唯一提交点；overshoot 与 overallocated tail 回收则吸收一拍控制延迟带来的多算。

从源码角度看，最重要的不是记住某个 event 名称，而是判断一个值处于 planned、in-flight、materialized 还是 committed。只要把这四个时刻混成一个“当前状态”，就会出现 token 错位、stop 泄漏、缓存悬空或页复用竞态。反过来，只要每个跨 stream 对象都有稳定索引、发布栅栏、快照和最终释放点，事件循环就能在保持自回归因果关系的同时，让 GPU 连续工作。

SGLang 源码系列当前进度如下：

下一篇将沿 ScheduleBatch -> ForwardBatch -> TpModelWorker -> ModelRunner 继续向设备执行层推进：调度计划怎样变成扁平 token、position、sequence length 与 attention metadata，Worker 为什么要隔离分布式与采样分支，ModelRunner 又怎样在 eager、编译和 CUDA Graph 路径之间选择。

参考资料#

1. SGLang v0.4：Zero-Overhead Batch Scheduler 官方发布文章
2. SGLang: Efficient Execution of Structured Language Model Programs（arXiv）
3. SGLang 论文（NeurIPS 2024）
4. NanoFlow: Towards Optimal Large Language Model Serving Throughput（arXiv）
5. Scheduler 主循环与设备提交源码（固定提交）
6. FutureMap 与输入延迟解析源码（固定提交）
7. Req 与 ScheduleBatch 源码（固定提交）
8. Batch Result Processor 源码（固定提交）
9. SGLang 官方 GitHub 仓库
10. SGLang v0.4 Overlap Scheduler 初始实现 PR
11. SGLang 默认启用 Overlap Scheduler 的 PR
12. SGLang 源码完全拆解（五）：KV 内存池与 RadixCache 的所有权闭环