SGLang 源码完全拆解（十一）：投机解码——草稿生成、批量验证与 token 接受如何接进同一条前向

三段式流水：draft、verify、accept

不论哪种算法，投机解码的一轮迭代都可以拆成三段：

1. Draft（草稿）：用小模型（EAGLE 头、MTP 层、N-gram 表）一次前向生成 $k$ 个候选 token 及其树状结构。
2. Verify（验证）：把 $k$ 个候选拼进 target 模型的一次前向，得到这 $k$ 个位置上 target 模型的分布（或 argmax）。
3. Accept（接受）：按接受规则决定每个请求实际接受多少候选；被接受的 token 写回 target KV Cache，序列前进 $n$ 步；顺便从未被拒绝的验证分布里再拿一个 bonus token。

三段之间传递的状态被统一抽象为 SpecInput：

1
class SpecInput(ABC):
2
    cuda_graph_compatible: bool = True
3
    ragged_verify_layout: Optional[RaggedVerifyLayout] = None
4
    num_tokens_per_req: int = -1
5
    num_tokens_for_logprob_per_req: int = -1
6
    custom_mask: Optional[torch.Tensor] = None
7
    # DSA MTP IndexShare 种子中继（EAGLE 系输入会覆写）
8
    dsa_topk_indices: Optional[torch.Tensor] = None
9
    future_dsa_topk_indices_available: bool = False
10
    dsa_seed_topk_capture: Optional[torch.Tensor] = None

SpecInputType 枚举标出每个 SpecInput 属于哪种阶段与算法：

1
class SpecInputType(IntEnum):
2
    EAGLE_DRAFT = auto()
3
    EAGLE_DRAFT_EXTEND = auto()
4
    EAGLE_VERIFY = auto()
5
    FROZEN_KV_MTP_DRAFT = auto()
6
    FROZEN_KV_MTP_VERIFY = auto()
7
    DFLASH_DRAFT = auto()
8
    DFLASH_VERIFY = auto()
9
    NGRAM_VERIFY = auto()
10
    UNO_STATE = auto()
11
    UNO_DRAFT = auto()
12
    UNO_VERIFY = auto()
13
    PP_SPEC_RELAY = auto()

这个枚举回答”当前这次前向是什么性质”，attention backend 与 ForwardBatch 的 padding 逻辑靠 is_draft_input() / is_verify_input() 分派，而不需要知道具体算法类。两个字段特别值得注意：

• num_tokens_per_req：本次前向每个请求的统一 token 宽度。draft-decode 阶段宽度是 top-k（每个请求一次前向摊 top-k 个草稿分支）；draft-extend 阶段宽度等于草稿 token 总数；verify 阶段宽度是 num_draft_tokens。DP attention 场景下它同时充当 global_num_tokens 的乘数——把”请求数”换算成”token 数”送给跨 DP rank 的同步逻辑。
• cuda_graph_compatible：本输入携带的状态是否足以支撑 CUDA Graph 重放。（九）讲过图捕获要求张量地址与形状稳定；验证阶段的行数与树结构随批变化，因此每种算法的 SpecInput 必须显式声明自己能不能进图，以及用哪套 ragged_verify 布局来参数化形状。

PP_SPEC_RELAY 是流水线并行（pipeline parallelism）下的特殊类型：最后一 stage 草稿出的树，被所有 stage 共享用于重建各自的 verify 输入——它既不是 draft 也不是 verify，不会有任何前向跑在它上面，只作为跨 stage 的状态载体存在。

SpecInput 上还有一对钩子函数 is_draft_input()、is_verify_input()，以及 pad_batch()：把本输入的设备张量 padding 到指定 batch 尺寸——这是给 CUDA Graph 的静态形状约束用的（图捕获时 batch 必须填充到桶尺寸）。create_dummy_verify_input() 则负责在捕获阶段造一棵形状匹配的假树，让图能被捕获下来。这两个函数与（九）的 breakable CUDA Graph 是配套设计：投机解码的一切动态性必须在图外消化干净，图内只允许静态形状的重复执行。

落到调度器：spec_info 与 prepare_for_decode 的分叉

三段流水在调度器侧的载体是 ScheduleBatch.spec_info：

1
    # Speculative decoding
2
    # spec_info: Optional[SpecInput] = None
3
    spec_info: Optional[SpecInput] = None

（注释保留了一行历史写法，说明这个字段经历过重构，从可选直接引用变为带类型声明的字段。）每一轮迭代，调度器决定本轮跑什么（比如 draft-decode、target-verify），把对应的 SpecInput 挂到批次上，ForwardBatch 再把它带给模型前向。

解码准备阶段有一个显式分叉。普通路径（无投机）在 prepare_for_decode 里做三件事：给每个请求分配 1 个 token 的 KV 槽（alloc_for_decode）、推进 seq_lens、更新采样计罚计数器。而投机路径直接让位给专门的准备函数：

1
        if not self.spec_algorithm.is_none():
2
            # Spec decoding owns decode preparation (allocation, seq-lens bookkeeping).
3
            from sglang.srt.speculative.spec_utils import spec_prepare_for_decode
4

5
            self.mamba_track_mask_cpu = None
6
            self.mamba_track_mask_next_cpu = None
7
            self.mamba_decode_batch_idx_cpu = None
8
            spec_prepare_for_decode(self)
9
            return

spec_prepare_for_decode 是一个小小的分派器：

1
def spec_prepare_for_decode(batch: ScheduleBatch) -> None:
2
    if get_exec().mamba.enable_mamba_extra_buffer_lazy:
3
        batch.mamba_lazy_spec_prepare(...)
4
    if batch.spec_algorithm.is_dflash_family():
5
        batch.spec_info.prepare_for_decode(batch)
6
    elif batch.spec_algorithm.is_uno():
7
        batch.spec_info.prepare_for_decode(batch)
8
    else:
9
        # eagle/ngram 共享无状态自由函数
10
        from sglang.srt.speculative.eagle_utils import eagle_prepare_for_decode
11
        eagle_prepare_for_decode(batch)

注释写得很清楚：dflash 系与 UNO 把 decode 准备做成 SpecInput 的有状态方法（准备逻辑依赖输入自身携带的张量），而 EAGLE 与 NGRAM 共享一个无状态自由函数。这是两类设计哲学的对照：有状态方法适合”输入自己就是全部上下文”的算法，自由函数适合”算法状态其实活在批次与 worker 里”的算法。后文拆 eagle_prepare_for_decode 时会看到，EAGLE 的 decode 准备确实几乎只依赖 ScheduleBatch 与全局配置。

为什么 decode 准备必须整体让位？因为普通路径假设”每请求每轮一个 token”：分配一个槽、seq_lens + 1。投机解码每一轮的节奏不同——draft-decode 轮每个请求要写入 top-k 个草稿分支的 KV；verify 轮要把 num_draft_tokens 个位置全排开；而真正提交给序列的步数由验证结果决定（接受 n 个就是 n 步，加 bonus）。这三套节奏 KV 槽位的分配算法、页对齐规则、写指针推进方式都不一样，硬塞进普通路径会到处是条件分支，因此 SGLang 选择在 prepare_for_decode 最早处整体换轨。

draft 前向的输入准备：prepare_for_draft

prepare_for_draft 负责把”这一轮 draft-decode 要跑哪些行、写到哪些 KV 槽”确定下来。它由两个 worker 变体（EAGLE 单层与多层）共享，签名里有几个关键参数：topk、num_steps、可选的 target_translator（多层草稿的 KV 索引翻译器）与 num_draft_tokens。

函数做三件事。

第一件，给草稿写入分配 KV 缓存位置。 页大小（page_size）与 top-k 的组合决定分配策略。最干净的情况是 page_size == 1 或 topk == 1：草稿树的每一行写入连续槽位，直接调 assign_draft_cache_locs_contiguous 一次算出整批 out_cache_loc。为了省一次 kernel 启动，函数甚至预分配 positions 张量并在同一个 kernel 里算出位置：

1
                if batch.seq_lens.is_cuda and topk == 1:
2
                    prepared_positions = torch.empty_like(batch.seq_lens)
3
                    ...
4
                assign_draft_cache_locs_contiguous[(bs,)](
5
                    batch.req_pool_indices,
6
                    req_to_token_pool.req_to_token,
7
                    batch.seq_lens,
8
                    batch.out_cache_loc,
9
                    req_to_token_pool.req_to_token.shape[1],
10
                    topk,
11
                    window_cols,
12
                    positions=prepared_positions,
13
                    ...
14
                    WRITE_POSITIONS=prepared_positions is not None,
15
                    ...
16
                )

代码注释里 FIXME(lsyin): align with the default code path 坦诚地标注了这条快路径与默认路径尚未统一——生产代码里这种”为 top-k=1 特化的捷径”很常见，读源码时要意识到两条路径的语义必须等价。

麻烦的情况是 page_size > 1 且 topk > 1：多分支的草稿写入必须按页对齐，每个分支的页区域内还要复制前缀尾页的真实 KV，因为整页读取的 kernel 会把页内所有槽位读进来，而分支页的前几个槽位是”洞”（逻辑上属于前缀尾页）。这正是下面这段注释在解释的事：

1
            # Each branch's page-aligned region starts with `last_page` hole slots
2
            # overlapping the prefix tail page; duplicate the real prefix-tail KV
3
            # into them so whole-page reads stay coherent (see helper docstring).
4
            duplicate_prefix_tail_to_draft_branches(
5
                draft_model_runner.token_to_kv_pool,
6
                rows, prefix_base, last_page, num_new_pages, topk, page_size,
7
            )

这段代码把（五）的页式 KV 与投机解码的耦合点暴露得很完整：分页机制本来是给 target 模型的线性序列设计的，草稿树的分叉结构借道分页时，必须付出”前缀尾页复制”的代价来保持页读取一致性。工程含义是：page_size > 1 的树式草稿在显存上不是零成本的，分支数越深、复制越多。

第二件，构造 ForwardBatch。 注意这里捕获模式的选择：

1
    capture_mode = (
2
        CaptureHiddenMode.NULL
3
        if draft_model_runner.spec_algorithm.is_standalone()
4
        else CaptureHiddenMode.LAST
5
    )

草稿前向默认需要捕获最后一层的 hidden states（LAST），供下一步草稿前向直接消费——这正是 EAGLE 论文的核心洞见：草稿模型不复用 token，而是复用 target 模型的特征。STANDALONE 模式（把草稿头当小模型独立跑）不需要这个捕获。

第三件，返回能否走 CUDA Graph。 函数返回三元组 (forward_batch, can_run_decode_cuda_graph, kv_loc_plan)。第三个元素是 chain 草稿（topk=1）的优化：当草稿退化成链时，一次迭代的整个写入窗口（跨 draft-decode、verify、draft-extend 三个子阶段的总槽位）可以被统一规划，target_translator.plan() 算出这份”KV 位置计划”，后续子阶段复用，不必各自重算。

organize_draft_results：三张表的归约

草稿逐层推进时，每一层都留下三样东西：score_list（每个候选的打分）、token_list(每个候选的 token id)、parents_list（候选与父节点的索引关系）。全部步数走完后，归约函数把它们压成最终树：

1
def organize_draft_results(score_list, token_list, parents_list, num_draft_token):
2
    # b, n, topk; n = 1 + (num_steps-1) * topk
3
    score_list = torch.cat(score_list, dim=1).flatten(1)
4
    # b, (topk + (num_steps-1) * topk)
5
    ss_token_list = torch.cat(token_list, dim=1)
6
    top_scores = torch.topk(score_list, num_draft_token - 1, dim=-1)
7
    top_scores_index = top_scores.indices
8
    top_scores_index = torch.sort(top_scores_index).values
9
    draft_tokens = torch.gather(ss_token_list, index=top_scores_index, dim=1)
10

11
    if len(parents_list) > 1:
12
        parent_list = torch.cat(parents_list[:-1], dim=1)
13
    else:
14
        parent_list = torch.empty(batch_size, 0, ...)
15
    return parent_list, top_scores_index, draft_tokens

逐句解释：

• 打分表按候选维度拼接后 flatten，得到每个请求”所有曾出现过的候选”的打分长表。
• torch.topk(score_list, num_draft_token - 1) 不是取前 k 个候选那么简单——注意 - 1：最终树的节点预算里有一个位置留给 bonus token（根），因此从候选里选 num_draft_token - 1 个。
• 选出来的索引重新排序（torch.sort）：这是为了让保留下来的节点按”出现顺序”排列，从而父节点的索引必然小于子节点索引——树结构在后续 attention kernel 里要按这个单调序处理，排序是把树”线性化”的必要步骤。
• torch.gather 取出对应的 token id。
• parent_list 的构建注意 parents_list[:-1]：丢弃最后一步的父亲记录。因为最后一步的候选没有被扩展出子节点（那需要再前向一次），对最终树没有贡献；最后一步的 score_list 之所以还参与打分选择，是因为它们作为叶子候选本身仍有被选中的价值。

三张表的形状注释（b, n, topk; n = 1 + (num_steps-1) * topk）值得咀嚼：草稿每步产生 top-k 个候选，但第一步的候选数与后续不同（第一步从根出发只有一次打分），因此候选总数是 $1 + (num\_steps - 1) \times topk$。以 num_steps=5、topk=4 为例，候选总数是 17。

要理解三张表怎么对齐，必须回到它们的产生端——spec_utils.py 里的 select_top_k_tokens。这个函数每步被调用一次，返回的 tree_info 就是三张表的一行记录。第一步（i == 0）与后续步的实现完全不同：

1
def _select_top_k_tokens_first(topk_p, topk_index, hidden_states, topk):
2
    input_ids = topk_index.flatten()
3
    if hidden_states is not None:
4
        hidden_states = hidden_states.repeat_interleave(topk, dim=0)
5
    tree_info = (
6
        topk_p.unsqueeze(1),        # (b, 1, topk)   —— 打分
7
        topk_index,                 # (b, topk)      —— token
8
        torch.arange(-1, topk, ...).expand(topk_p.shape[0], -1),  # (b, topk + 1)
9
    )
10
    return input_ids, hidden_states, topk_p, tree_info

第一步的候选来自根位置的分布：topk_p 是根分布上的 top-k 概率，topk_index 是对应的 top-k token。hidden_states.repeat_interleave(topk) 把根的一个 hidden state 复制成 top-k 份——树式草稿的第一步就是”从一个位置摊开 top-k 个分支”，因此后续前向的行数是 top-k。

后续步（_select_top_k_tokens_later）是树生长的主力。每一步拿到上一轮选出的 top-k 个当前分支（scores 是它们各自的”累积概率”），以及每个分支分布上的 top-k 采样结果（topk_index，形状 [b, topk*topk]——每个分支摊 top-k 个候选），然后把两者的概率相乘得到联合打分，再做一次跨分支的 top-k 选择：

1
    topk_sq = topk * topk
2
    expand_scores = scores.unsqueeze(2) * topk_p.view(-1, topk, topk)
3
    # (b, topk, 1) * (b, topk, topk) -> (b, topk, topk)
4
    topk_cs_p, topk_cs_index = fast_topk(
5
        expand_scores.flatten(start_dim=1), topk, dim=-1
6
    )  # (b, topk)
7
    topk_index = topk_index.view(-1, topk_sq)
8
    input_ids = torch.gather(topk_index, 1, topk_cs_index).flatten()
9
    tree_info = (
10
        expand_scores,                                  # (b, topk, topk)
11
        topk_index,                                     # (b, topk * topk)
12
        topk_cs_index + (topk_sq * (i - 1) + topk),     # (b, topk)
13
    )

这段代码信息量很大，逐点拆开：

• scores.unsqueeze(2) * topk_p.view(-1, topk, topk)：把”父链累积概率”与”子候选局部概率”相乘，得到树上的路径联合概率。EAGLE 的草稿选择按路径联合概率排序，而不是只看单步概率——这是树搜索与贪心链式采样的重要区别，保证选出的叶子在整条路径上都足够可信。
• fast_topk(..., topk) 在 [b, topk²] 的扁平空间里选 top-k 个 (分支, 子候选) 组合。这一步把树宽从 $topk \times topk$ 剪回 top-k——树宽恒定、深度递增，这就是 EAGLE 树的增长规则：每层候选空间是 top-k 平方量级，但只有路径联合概率最高的 top-k 条能进入下一层。
• input_ids = gather(topk_index.flatten(), topk_cs_index)：把选中的候选 token 排开，它们将成为下一次草稿前向的输入行。
• tree_info 第三项 topk_cs_index + (topk_sq * (i - 1) + topk)：这是父指针的全局化的核心公式。topk_cs_index 是选中的候选在本步局部展开空间 [b, topk²] 里的扁平位置；偏移量 topk_sq*(i-1) + topk 把这个局部位置换算进全局候选空间——第一块是第一步贡献的 topk 个位置，之后每步贡献 topk² 个位置。

于是三张表的长表可以对齐了：打分表每步贡献 1（第一步）或 topk（后续步）行、每行 topk 列，拼接后 [b, 1 + (num_steps-1)*topk, topk]，flatten(1) 后长度是 $topk \times (1 + (num\_steps-1)\times topk)$；token 表第一步贡献 topk 个、后续步各贡献 topk² 个，拼接后长度是 $topk + (num\_steps-1)\times topk^2$。两式恒等——打分空间与 token 空间是同构的：扁平位置 $p$ 在打分表里是该候选的子候选打分，在 token 表里是该候选自己的 token id。代码里 maybe_detect_oob(top_scores_index, 0, ss_token_list.shape[1], ...) 这行越界检测守的就是这份同构关系：top_scores_index 是打分空间里选出的位置，必须同时是 token 空间的合法下标，否则 gather 会读到非法内存。注意 token 表那行注释把第二项简写成 (num_steps-1) * topk，实际量级是 (num_steps-1) * topk²——注释是重构期的简写，以同构关系与越界检测为准。

parents_list[:-1] 丢弃最后一步的理由至此也有了更精确的解释：全局候选数组 parent_list 的长度是 $1 + (num\_steps-1)\times topk$（等于每请求的全局候选数 n），而各步父指针块的长度是”第一步 $topk+1$、后续步各 $topk$“——第一步多出的那个元素就是根哨兵 -1（见 arange(-1, topk)）。拼接时必须丢掉最后一步：最后一步的候选没有被展开，它们在父指针数组里没有对应的”被引用”位置，保留会破坏长度关系。

一句话总结这段归约：EAGLE 树的本质是一张按”出现顺序线性化”的节点表（token + 打分），加上一张长度相同的父指针表（parent_list + 全局偏移）；organize_draft_results 的职责就是在节点表上选出 top-num_draft_tokens-1 个叶子，并按父先子后的顺序重排索引，让下游的树构建 kernel 能一次性还原整棵树的结构。（后面拆 build_tree_kernel_efficient 时会看到，父指针表正是 tree mask 与位置编码的输入。）

图源：EAGLE-3 论文 EAGLE-3: Scaling up Inference Acceleration of Large Language Models via Training-Time Test（arXiv:2503.01840）。这张总览图把 EAGLE-3 的三个核心部件画在一起：草稿头的多层特征融合、逐层生长的候选树、以及 target 模型上的并行验证——本节的 draft() 主循环、下一节的 build_tree_kernel_efficient、以及”验证与接受”一节的 eagle_sample 分别对应图中的三个阶段。

草稿主循环：draft() 的步进结构

把三张表的产生逻辑放回主循环，EAGLE 草稿的全貌就清楚了。eagle_worker_v2.py 里的 draft() 结构是：

1
        score_list: List[torch.Tensor] = []
2
        token_list: List[torch.Tensor] = []
3
        parents_list: List[torch.Tensor] = []
4
        needs_draft_probs = (
5
            get_spec().speculative_use_rejection_sampling
6
            and not forward_batch.sampling_info.is_all_greedy
7
        )
8
        ...
9
        with IndexTopKShareState.mtp_iteration(...):
10
            for i in range(self.speculative_num_steps):
11
                if draft_tokens_topk1 is not None:
12
                    input_ids = topk_index.flatten()
13
                else:
14
                    input_ids, hidden_states, scores, tree_info = select_top_k_tokens(
15
                        i, topk_p, topk_index, hidden_states, scores, self.topk
16
                    )
17
                    score_list.append(tree_info[0])
18
                    token_list.append(tree_info[1])
19
                    parents_list.append(tree_info[2])
20

21
                if i == self.speculative_num_steps - 1:
22
                    break
23

24
                forward_batch.input_ids = input_ids
25
                forward_batch.out_cache_loc = out_cache_loc[i]
26
                spec_info.hidden_states = hidden_states
27
                ...

循环体里几个设计点值得展开：

• needs_draft_probs 的条件：只有”开启拒绝采样 且 批次不是全贪心”时才需要草稿分布。注释解释了另一半：Verify commits argmax for an all-greedy batch and never reads the draft distribution, so skip building it. ——全贪心批次的验证只用 argmax，草稿分布白算了也是浪费。

• select_top_k_tokens 是循环的核心：它接收当前步的子候选概率 topk_p、索引 topk_index、hidden states 与累积分数 scores，输出本次前向的输入行 input_ids、更新后的 hidden states、新的累积分数与 tree_info（三张表的本步行）。注意 i 被传入，因为第一步与后续步的实现分支不同（前面拆过 _select_top_k_tokens_first 与 _select_top_k_tokens_later）。

• hidden states 的传递：spec_info.hidden_states = hidden_states 把上一步捕获的隐状态挂回输入，下一步前向直接消费。这就是 EAGLE”复用特征而非 token”在代码里的落点，也是 CaptureHiddenMode.LAST 存在的原因。

• out_cache_loc[i] 的分步写入：草稿每步写一段 KV 槽，out_cache_loc 是二维的（步数 × 每步槽数），循环里按步取切片。这对应 prepare_for_draft 里算出的整批写入位置。

• IndexTopKShareState.mtp_iteration 上下文：这是 MTP 迭代的 top-k 索引共享状态管理器，keep_carry_seed 参数控制是否把种子 top-k 索引跨迭代保留。这套机制服务于 DeepSeek 系 MTP 草稿头（MTP 完全拆解 讲过 MTP 层的顺序模块结构），让多次草稿迭代共享同一份索引状态，避免重复计算。

• topk=1 的快路径：draft_tokens_topk1 = torch.empty((bs, num_steps)) 直接预分配整条链的 token 张量，第一步 copy_ 写入，后续步直接 input_ids = topk_index.flatten() ——链式草稿连 select_top_k_tokens 都省了，因为链没有分支选择。这就是前文 _rebuild_topk1_chain_buffers 与 _topk1_parents_prealloc 存在的场景：topk=1 时父指针与打分索引是运行时不变的（恒为线性递增），因此可以预分配并复用，代码里那段 assert self.speculative_num_draft_tokens == self.speculative_num_steps + 1 就是这条快路径的合法性前提。

验证前向的组装：一次 forward 摊平整棵树

草稿与验证之间的连接点是 ForwardBatch 的构造。验证阶段每请求要跑 num_draft_tokens 行（整棵树的节点），因此：

• 行数放大：验证批次的 token 数 = bs * num_draft_tokens，而非普通解码的 bs * 1。这是 num_tokens_per_req 在 verify 阶段取值 num_draft_tokens 的含义（resolve_num_tokens_per_req 的第三个分支）。
• custom_mask 进入注意力：EagleVerifyInput.custom_mask 就是上一节产出的 tree_mask，它被传给 attention backend 作为注意力掩码——验证前向的注意力不是因果掩码，而是树掩码。这是验证阶段与普通解码在 kernel 层最根本的差别。
• positions 驱动 RoPE：EagleVerifyInput.positions 是 build_tree_kernel_efficient 算出的树位置，模型前向用它算旋转角。同一层不同分支拿到同一位置——前文已强调这一点。
• prepared_out_cache_loc：build_eagle_verify_input 在 chain 特化路径下会连 KV 写位置一起算好（build_chain_tree 的返回项），避免验证阶段再算一遍。这是链式草稿的又一处”常数结构写死”优化。

验证前向结束、eagle_sample 判定完成之后，回到调度器做提交：推进 seq_lens、搬 KV、更新 Req.output_ids。（三）讲的”只有结果处理器完成 commit，Req.output_ids 与 finished_reason 才代表已发生事实”这条不变量在这里同样成立——投机解码只是把”一轮一个 token”变成”一轮 n 个 token”，提交语义本身没有变。

三种 mask 形态

TreeMaskMode 决定了 mask 的物理形态：

1
class TreeMaskMode(IntEnum):
2
    FULL_MASK = 0
3
    QLEN_ONLY = 1
4
    QLEN_ONLY_BITPACKING = 2
5

6
def default_tree_mask_mode():
7
    # CPU verify attention kernel (intel_amx) 直接消费 qlen x qlen 的 QLEN_ONLY mask；
8
    # FULL_MASK 是给 GPU kernel 的。
9
    return TreeMaskMode.QLEN_ONLY if _is_cpu else TreeMaskMode.FULL_MASK

• FULL_MASK：完整的 [bs * num_verify_tokens, seq_lens_sum + num_verify_tokens * bs] 布尔掩码。每一行对应一个验证 token，列覆盖”全部前缀 + 全部树内 token”。这是最直白也最占内存的形态：前缀部分全为 True（每个验证 token 都能看见全部已提交上下文），树内部分按树结构填。
• QLEN_ONLY：只保留 num_verify_tokens × num_verify_tokens 的树内掩码，前缀列由 kernel 隐式当作全可见。因为前缀对每个验证行都是”全 True”，把它真的物化出来纯属浪费——seq_lens_sum 可能上万，而树只有几十个节点。
• QLEN_ONLY_BITPACKING：把 QLEN_ONLY 按位打包成 uint8/uint16/uint32。packed_dtype_idx = ceil(log2((num_verify_tokens + 7) // 8)) 根据树宽选择打包粒度，树宽 ≤ 8 用 uint8、≤ 64 用 uint16 等。

代码里有一段对性能很关键的判断：

1
        elif tree_mask_mode == TreeMaskMode.FULL_MASK:
2
            # Only the [0, seq_len) prefix columns depend on this fill; the
3
            # kernel below writes every tree cell itself. Skip the (up to
4
            # 100s of MB) per-step memset when nothing reads the mask.
5
            if fill_prefix_mask:
6
                tree_mask.fill_(True)

注释直白地说明了 FULL_MASK 的代价量级——前缀列可能上百 MB，每步一次 memset 是实打实的开销。因此引入了 fill_prefix_mask 开关：当后端自有的 mask buffer 被复用且本步不读前缀列时，跳过整片填充。这是与（八）Attention Backend 的直接咬合点：验证 mask 的缓冲区由后端持有（target_attn_backend.verify_mask），后端告诉调用方 mode 与 is_read，调用方据此决定填不填。

邻接表：retrieve_* 三兄弟

返回值里最容易看懵的是 retrieve_index、retrieve_next_token、retrieve_next_sibling。它们来自同一个缓冲区：

1
    retrieve_buf = torch.full((3, bs, num_verify_tokens), -1, device=device, dtype=torch.long)
2
    retrieve_index, retrieve_next_token, retrieve_next_sibling = retrieve_buf

三张 [bs, num_verify_tokens] 的 int64 表，初始值全 -1（表示”无”），由 kernel 填充：

• retrieve_index：节点在扁平化验证张量中的物理位置（节点 → 行号）。
• retrieve_next_token：节点的第一个子节点编号（树的孩子链头）。
• retrieve_next_sibling：节点的下一个兄弟编号。

这三张表合起来就是一份孩子-兄弟表示法（child-sibling representation）的树：一个节点想遍历全部子节点，沿 retrieve_next_token 找到长子，再沿 retrieve_next_sibling 顺次走完兄弟链——标准的多叉树紧凑表示，不需要给每个节点分配变长子列表。后文拆接受判定时会看到 verify_tree_greedy_func 与 traverse_tree 正是靠这两张表做 DFS。

positions 的语义也在注释里给了例子：

1
    # position: where each token belongs to
2
    # e.g. if depth of each draft token is [0, 1, 1, 2] and the prompt length is 7
3
    # then, positions = [7, 8, 8, 9]

同一层的节点共享同一个绝对位置——深度为 1 的两个节点都是位置 8，因为它们是同一父节点的两个平行猜测，都接在位置 7 之后。这是树形验证与线性解码最本质的区别：position 不再是”序列下标”，而是”树深度 + 前缀长度”。RoPE 旋转角度必须按这个位置算，否则同一层不同分支会拿到不同的位置编码，注意力分布就错了（RoPE 完全拆解 里讲过位置编码如何进入注意力计算）。

平台分派与 chain 特化

kernel 调用按平台分四种：NPU 走 torch.ops.npu.build_tree_kernel_efficient，XPU 与 CPU 走 Triton 与自有实现，GPU 默认走 sgl_build_tree_kernel_efficient。这种”一份语义、多套 kernel”的组织方式是 SGLang 多硬件支持的标准姿势——语义层与 kernel 层分离，前端逻辑不必关心后端。

build_eagle_verify_input 是调用这个 kernel 并组装 EagleVerifyInput 的地方。它有一个值得注意的链式特化：

1
    if (batch.seq_lens.is_cuda
2
        and topk == 1
3
        and num_draft_tokens == num_steps + 1
4
        and draft_tokens.shape == (bs, num_steps)
5
        and mask_mode == TreeMaskMode.QLEN_ONLY):
6
        tree_outputs = build_chain_tree(
7
            draft_input.bonus_tokens, draft_tokens, batch.seq_lens,
8
            tree_mask_buf, req_pool_indices=batch.req_pool_indices,
9
            req_to_token=batch.req_to_token_pool.req_to_token,
10
            with_mrope=...,
11
        )

条件里 num_draft_tokens == num_steps + 1 就是”链而非树”的判据——链的节点数恰好是深度加一（每一步一个节点，加上根）。此时树退化成链，掩码是下三角、父指针是线性递增，build_chain_tree 能把这些常数结构直接写死，省掉通用 kernel 的树构建开销。这个特化对应（十）里提到的 speculative_eagle_topk=1 场景，也是 prepare_for_draft 里 plans_window 优化的同一前提。

组装完成的 EagleVerifyInput 就是系列的第三个 SpecInput 子类实例：

1
    return EagleVerifyInput(
2
        draft_token=draft_tokens, custom_mask=tree_mask, positions=position,
3
        retrieve_index=retrieve_index, retrieve_next_token=retrieve_next_token,
4
        retrieve_next_sibling=retrieve_next_sibling,
5
        retrieve_cum_len=None, spec_steps=num_steps, topk=topk,
6
        draft_token_num=num_draft_tokens, capture_hidden_mode=None,
7
        seq_lens_sum=None, seq_lens_cpu=None, draft_probs=draft_probs,
8
        prepared_out_cache_loc=prepared_out_cache_loc,
9
        prepared_mrope_positions=prepared_mrope_positions,
10
    )

它携带的内容正好是验证前向所需的一切：候选 token、树掩码、位置、邻接表、以及（可选的）草稿分布 draft_probs——最后这一项只在拒绝采样路径下需要，后文会讲。

图源：LMSYS 官方博客 From research to production: Accelerate OSS LLM with EAGLE-3 on Vertex。这张图画出了 EAGLE-3 草稿头与 target 模型的分工：中间层特征（图中 TTT 融合的多层 hidden states）被喂进草稿头，草稿头一次前向输出多个候选位置。SGLang 里 prepare_for_draft 的 CaptureHiddenMode.LAST 与 spec_info.hidden_states 传递链，实现的就是这张图的数据流。

eagle_sample 的骨架

eagle_sample 是 EAGLE 系的接受判定总入口。它接收 verify_input（上一节组装的树）、batch、logits_output（验证前向的输出），返回三个张量：predict（每个验证位置选出的 token）、num_correct_drafts（每请求正确草稿数）、accept_index（接受路径的索引）。开头有一段幂等处理：

1
    if batch.forward_mode.is_idle():
2
        predict = torch.empty(0, dtype=torch.int32, device=device)
3
        num_correct_drafts = torch.empty(0, dtype=torch.int32, device=device)
4
        accept_index = torch.empty(0, dtype=torch.int32, device=device)
5
        return predict, num_correct_drafts, accept_index

idle 批次（图重放时为了填满静态形状而塞的假批次）直接返回空张量，不做任何判定——这是（九）里”空批次必须能被安全跳过”这条不变量的具体体现。

接着是惩罚与偏置的对齐，这段代码揭示了投机解码里一个容易错的地方：

1
    if sampling_info.acc_additive_penalties is not None:
2
        next_token_logits.add_(
3
            torch.repeat_interleave(
4
                sampling_info.acc_additive_penalties,
5
                verify_input.draft_token_num, dim=0,
6
            )
7
        )

next_token_logits 有 bs * draft_token_num 行（每个请求的每个验证位置一行），而惩罚表是每请求一项。repeat_interleave(..., draft_token_num) 把每请求的惩罚复制成 draft_token_num 份——同一请求的所有验证位置共享同一份惩罚。注意这里的”惩罚”是 relaxed 版本（注释原话：This is a relaxed version of penalties for speculative decoding）：真实的重复惩罚需要知道”这个位置之前生成过哪些 token”，而树上的每个位置都处于不同的猜测路径，精确计算代价极高；SGLang 选择用统一的累积惩罚近似。这是投机解码与普通解码在采样语义上的一处已知偏差。

然后是三个输出张量的初始化：

1
    candidates = verify_input.draft_token.reshape(bs, verify_input.draft_token_num)
2
    predict_shape = list(next_token_logits.shape)[:-1]
3
    predict = torch.zeros(predict_shape, dtype=torch.int32, device=device).flatten()
4
    accept_index = torch.full((bs, verify_input.max_tree_depth), -1, dtype=torch.int32, device=device)
5
    num_correct_drafts = torch.empty((bs,), dtype=torch.int32, device=device)

• candidates 把扁平候选张量 reshape 回 [bs, draft_token_num]。
• accept_index 形状是 [bs, max_tree_depth]，初值 -1——一个请求最多接受 max_tree_depth 个 token（树深度为 d 意味着最长的接受链长度不超过 d），-1 表示”这个位置没有 token”。
• num_correct_drafts 每请求一个计数。

三条判定路径

判定逻辑的核心分叉：

1
    use_rejection_sampling = get_spec().speculative_use_rejection_sampling
2
    if _verify_uses_greedy(is_all_greedy=..., is_cpu=..., is_hip=...,
3
                           is_xpu=..., use_rejection_sampling=...):
4
        target_predict = torch.argmax(next_token_logits, dim=-1)
5
        target_predict = target_predict.reshape(bs, verify_input.draft_token_num)
6
        predict, accept_index, num_correct_drafts = verify_tree_greedy_func(
7
            predicts=predict, accept_index=accept_index,
8
            accept_token_num=num_correct_drafts, candidates=candidates,
9
            retrieve_index=verify_input.retrieve_index,
10
            retrieve_next_token=verify_input.retrieve_next_token,
11
            retrieve_next_sibling=verify_input.retrieve_next_sibling,
12
            target_predict=target_predict, topk=verify_input.tree_topk,
13
        )
14
        ...
15
        if tp_group.world_size > 1:
16
            tp_group.broadcast(predict, src=0)
17
            tp_group.broadcast(accept_index, src=0)
18
            tp_group.broadcast(num_correct_drafts, src=0)

路径一：贪心验证。 所有请求都是贪心采样时，target 模型的判定就是 argmax。verify_tree_greedy_func 沿树自顶向下逐层比对：某节点的 target argmax 恰好等于草稿在该位置的 token，就接受并往子节点走；不相等就停止这条路径。注意后面那段 TP broadcast——注释解释了原因：

1
            # On ROCm, the per-rank draft tokens can differ, so ranks accept a
2
            # different number of drafts, desynchronize the committed seq_lens, and
3
            # deadlock the next TP collective.

各 rank 的接受数可能不同（草稿阶段浮点非确定性导致），而”接受数”直接决定 seq_lens 推进多少——seq_lens 不一致会让下一轮的 TP 集合通信死锁。解决办法是从 rank 0 广播判定结果，强制所有 rank 接受同一个数量。这是一条正确性优先于效率的工程决策：多一次广播，换来集合通信不死锁。

路径二：UNO 稀疏树目标采样。 _can_use_sparse_uno_tree_target_sampling 成立时走这条分支，它用 sample_uno_tree_target_tokens 从 target 分布里为 UNO 的稀疏树采样目标 token，仍交给 verify_tree_greedy_func 做结构遍历，末尾同样广播。这条路径是 UNO 算法特有的优化，骨架与贪心一致。

路径三：拒绝采样（rejection sampling）。 采样请求且开启拒绝采样时走这里。先对分布做 top-k/top-p 重归一化，然后：

1
        target_probs = target_probs.reshape(bs, verify_input.draft_token_num, -1)
2
        draft_probs = (
3
            verify_input.draft_probs if use_rejection_sampling
4
            else torch.zeros_like(target_probs)
5
        )
6
        if use_rejection_sampling and (
7
            draft_probs is None or draft_probs.shape[-1] != target_probs.shape[-1]
8
        ):
9
            raise ValueError(
10
                "Rejection sampling requires a target-vocab draft proposal "
11
                "distribution; ..."
12
            )

这段断言很有信息量：拒绝采样需要草稿模型给出与 target 同词表大小的完整分布。多数草稿头为了省显存只输出 top-k 候选的 logits（词表维度被截断），此时无法做标准拒绝采样，只能退化为”贪心式接受 + 修正”（draft_probs = zeros_like(target_probs)，即把草稿分布当全零处理）。这解释了为什么 EagleDraftInput 需要携带 draft_probs、以及 draft() 里那个 needs_draft_probs 判断（避免为不需要的路径白算分布）。

拒绝采样的核心是 sampling_fn（CUDA 上是 chain_speculative_sampling_triton，NPU 上有对应实现）：

1
        sampling_fn(
2
            predicts=predict, accept_index=accept_index, accept_token_num=num_correct_drafts,
3
            candidates=candidates,
4
            retrive_index=verify_input.retrieve_index,
5
            retrive_next_token=verify_input.retrieve_next_token,
6
            retrive_next_sibling=verify_input.retrieve_next_sibling,
7
            uniform_samples=coins,
8
            uniform_samples_for_final_sampling=coins_for_final_sampling,
9
            target_probs=target_probs, draft_probs=draft_probs,
10
            threshold_single=get_spec().speculative_accept_threshold_single,
11
            threshold_acc=get_spec().speculative_accept_threshold_acc,
12
            deterministic=True,
13
        )

注意参数名的拼写：kwarg 左侧保留成 retrive_*（少一个 e）是为了匹配 sgl_kernel 的算子 schema，注释里写得很直白。读源码时看到这种”故意拼错”的地方，通常意味着跨模块的 ABI 约束，不要”顺手修正”。

两个阈值 threshold_single 与 threshold_acc 是拒绝采样的接受门限：单 token 的接受阈值与累积接受阈值，它们让接受判定可以在”更激进加速”与”更接近 target 分布”之间调节。deterministic=True 表示采样使用固定随机数序列（为了跨 rank 一致与可复现）。

随机数硬币：coins

拒绝采样需要随机性，但不能让每个 rank 各自摇随机数（否则 rank 间判定不同）。SGLang 的做法是确定性生成”硬币”：

1
        coins, coins_for_final_sampling = _verify_coins(
2
            sampling_info=sampling_info, seq_lens=batch.seq_lens,
3
            draft_token_num=verify_input.draft_token_num,
4
            candidates=candidates, device=device,
5
        )

_verify_coins 与 _seeded_verify_coins 两个 helper 的存在说明这件事有”有种子”与”无种子”两条路：开启种子时，随机数由 (请求身份, 位置) 确定性地导出，从而保证同一请求在任意 rank 上拿到同一串硬币，判定结果自然一致。这套机制是投机解码里”采样语义 + 分布式一致性”两者冲突时的标准解法。

返回值语义：num_correct_drafts + 1

函数最后一行值得单独拎出来：

1
    # `num_correct_drafts` stays drafts-only inside this function; the returned
2
    # tensor includes the trailing/bonus token via out-of-place +1 so the
3
    # name no longer flips semantics mid-function (naming doc C2).
4
    return predict, num_correct_drafts + 1, accept_index

函数内部的 num_correct_drafts 只数”草稿被接受的个数”，返回值把它 +1 表示”含 bonus token 的总推进步数”。 注释特意解释了这样做的理由：避免同一个名字在函数中途语义翻转。这是个命名规范问题（注释里引用了 naming doc C2），但对读代码的人非常关键——看到 num_correct_drafts 时必须先确认它在哪个语义区间：

• 在 eagle_sample 内部：草稿接受数，accept_index 里 -1 之外的位置数。
• 返回值与下游 move_accept_tokens_to_target_kvcache：草稿接受数 + 1，即 seq_lens 的推进量。

后文拆 KV 回写时会看到调用点用 batch.seq_lens + num_correct_drafts + 1 计算目标位置——那里的 num_correct_drafts 已经是”返回值语义”，再加 1 是给 bonus 之后的下一轮留位。这类”名字相同、语义区间不同”的坑，是读投机解码源码时最容易踩的。

模拟接受长度：为压测而生的开关

eagle_sample 末尾有一段看起来与生产逻辑无关的代码：

1
    if SIMULATE_ACC_LEN > 0:
2
        if SIMULATE_ACC_TOKEN_MODE not in ("fixed", "real-draft-token"):
3
            raise ValueError(...)
4
        if SIMULATE_ACC_TOKEN_MODE == "real-draft-token":
5
            if verify_input.tree_topk != 1:
6
                raise ValueError(
7
                    "SGLANG_SIMULATE_ACC_LEN with real draft tokens currently "
8
                    "requires speculative_eagle_topk=1."
9
                )
10
            if target_predict is None:
11
                target_predict = torch.argmax(next_token_logits, dim=-1).reshape(
12
                    bs, verify_input.draft_token_num)
13
        accept_index = generate_simulated_accept_index(
14
            accept_index=accept_index, predict=predict,
15
            num_correct_drafts=num_correct_drafts, candidates=candidates,
16
            target_predict=target_predict, simulate_acc_len=SIMULATE_ACC_LEN,
17
            simulate_acc_token_mode=SIMULATE_ACC_TOKEN_MODE, bs=bs,
18
            spec_steps=verify_input.max_tree_depth - 1,
19
        )

SGLANG_SIMULATE_ACC_LEN 是调试/压测环境变量：它把真实的接受判定替换成”假装接受了 N 个 token”。这样可以在不依赖草稿质量的前提下，测出”如果接受率是 100%，系统吞吐能到多少”，从而分离”算法质量”与”系统上限”两个变量。generate_simulated_accept_index 的注释说明它返回宽度 spec_steps + 1 的替换 accept_index，所以调用方传 max_tree_depth - 1 保持宽度一致。生产路径上这个开关必须是 0；但它的存在对理解”接受数如何驱动后续所有账本”很有帮助——整个投机解码的后续流程只依赖 accept_index 与 num_correct_drafts 两个输出，与它们是怎么算出来的无关。

图源：LMSYS 官方博客 From research to production: Accelerate OSS LLM with EAGLE-3 on Vertex。图中左侧是 target 模型的单次前向，右侧是被接受的 token 序列——一次前向验证整棵树，接受链的长度由验证结果决定，这正是 eagle_sample 与 verify_tree_greedy_func 实现的语义。

语法与树：traverse_tree 的借用-回滚遍历

（十）讲到结构化输出时留下过一个悬念：语法状态机如何与投机解码的树共存。答案在 spec_utils.py 的 traverse_tree 里。函数签名很直接：

1
def traverse_tree(retrieve_next_token, retrieve_next_sibling, draft_tokens,
2
                  grammar, allocate_token_bitmask, vocab_size=None):
3
    """Traverse the tree constructed by the draft model to generate the logits mask."""
4

5
    def dfs(curr, retrieve_next_token, retrieve_next_sibling, parent_pos):
6
        if curr == 0:
7
            # the first token generated by the target model, and thus it is always
8
            # accepted from the previous iteration
9
            is_accepted = True
10
        else:
11
            parent_bitmask = allocate_token_bitmask[parent_pos]
12
            current_token = draft_tokens[curr]
13
            if vocab_size and current_token >= vocab_size:
14
                is_accepted = False
15
            else:
16
                # 32 boolean bitmask values are packed into 32-bit integers
17
                is_accepted = (
18
                    parent_bitmask[current_token // 32] & (1 << (current_token % 32))
19
                ) != 0
20

21
        if is_accepted:
22
            if curr != 0:
23
                grammar.accept_token(int(draft_tokens[curr]))
24
            if not grammar.is_terminated():
25
                grammar.fill_vocab_mask(allocate_token_bitmask, curr)
26
                if retrieve_next_token[curr] != -1:
27
                    dfs(int(retrieve_next_token[curr]), ..., curr)
28

29
            if curr != 0:
30
                grammar.rollback(1)
31

32
        if retrieve_next_sibling[curr] != -1:
33
            dfs(int(retrieve_next_sibling[curr]), ..., parent_pos)
34

35
    dfs(0, retrieve_next_token, retrieve_next_sibling, -1)

这段 40 行的 DFS 把三件事一次性做完：

第一，树上的语法合法性判定。 一个候选 token 是否被接受，取决于它的父节点的语法状态是否允许这个 token。掩码以位图形式存在 allocate_token_bitmask 里（每 token 一位，32 位打包成一个 int32），判定就是一行位运算：parent_bitmask[current_token // 32] & (1 << (current_token % 32))。根节点（curr == 0）无条件接受——注释原话是”target 模型生成的第一个 token，上一轮已经验证过”。

第二，子树掩码的生成。 接受一个节点后，grammar.fill_vocab_mask(allocate_token_bitmask, curr) 为该节点写出”它的所有子候选必须满足的允许集”。这样即使后面的节点因为父节点被拒绝而不会走到，只要父节点被接受，子节点的掩码就已经就位，采样时直接可用。

第三，“借用-回滚”式的状态机遍历。 这是整段代码最精巧的地方：grammar 是一个单一的线性状态机，而树有多条路径。DFS 的解法是——进入一个节点时 accept_token 推进状态，遍历完它的子树后 rollback(1) 回退一步，再走兄弟节点。任何时刻状态机只保留”当前根到当前节点”这一条路径的状态，空间开销与树宽无关，只与树深度有关。rollback(1) 这个动词与（十）里语法管理器的 rollback 语义完全一致，两篇在这里合上了。

代价同样明确：整个 DFS 是串行的、宿主侧（或按算法实现）单线程的，遍历成本与树节点数成正比。这正是 supports_grammar_overlap() 存在的理由：语法遍历不能在 GPU 前向的异步流水里被”提前做”，因此带语法的批次必须走同步路径。从（十）的 grammar_needs_sync() 到本节的 traverse_tree，语法与投机解码的每一个耦合点都指向同一结论——语法约束把投机解码的并行性按下去一档，这是结构化输出的固有代价。

与调度器（三、四、六）

• prepare_for_decode 的整体让位：前文已经拆过，投机批次跳过普通解码准备，改走 spec_prepare_for_decode。
• overlap 的例外：supports_overlap 与 supports_grammar_overlap 是算法声明，调度器据此决定一个批次能否在 overlap 路径上跑。EAGLE 的验证结果决定下一轮草稿输入，天然打断 overlap 的流水线，因此多数算法在 overlap 下需要同步或特殊处理。（六）讲的 last_batch、future token、延迟提交这些机制，在投机模式下都要重新审视”什么时候可以安全地推进 seq_lens”。
• KV 预算：PrefillAdder（四）在做接纳预算时，必须为投机解码预留比一个 token 更多的未来 KV。get_alloc_reserve_per_decode() 就是这份预留量——eagle_prepare_for_decode 里 page_aligned_decode_alloc_lens(..., reserve=double_alloc, ...) 直接用它算下一轮需要多少槽位。预留不足会导致页 >1 + topk >1 的草稿写入越界，代码里那段断言就是在防这个：

1
    if page_size > 1 and (get_spec().speculative_eagle_topk or 1) > 1:
2
        max_alloc_len = int(nxt_kv_lens_cpu.max())
3
        row_width = batch.req_to_token_pool.req_to_token.shape[1]
4
        assert max_alloc_len <= row_width, (
5
            f"spec v2 page>1 topk>1 draft over-allocation ({max_alloc_len}) exceeds "
6
            f"req_to_token row width ({row_width}); page_size={page_size}. ..."
7
        )

这条断言把”页式 KV + 树式草稿 + 预分配不足”三者叠加的失败模式显式化了——req_to_token 的每行宽度必须能容纳”已提交 + 预留量”，否则写入越界，后续释放还会泄漏 KV。这是（五）讲的所有权闭环在投机解码下新增的一条边界条件。

与 attention backend（八）

• 验证掩码由后端持有：target_attn_backend.verify_mask 提供 mode、is_read、buffer 与 fits(bs)。build_eagle_verify_input 依据它决定是”写进后端预分配的 buffer”还是”临时分配”：

1
    verify_mask = target_attn_backend.verify_mask
2
    if verify_mask is None:
3
        tree_mask_buf, mask_mode, fill_mask = None, tree_mask_mode, True
4
    else:
5
        mask_mode, fill_mask = verify_mask.mode, verify_mask.is_read
6
        tree_mask_buf = verify_mask.buffer if verify_mask.fits(bs) else None

fill_mask = verify_mask.is_read 这一行的含义是：当后端本步不读前缀列时，跳过填充（对应前文讲的上百 MB memset 优化）。eager 批次超过捕获的 max_bs 时回退到临时分配——这是”图捕获尺寸之外”的降级路径。

• SpecInputType 用于后端分派：attention backend 靠 spec_info.is_draft_input() / is_verify_input() 选择对应的注意力路径，不需要知道具体算法类。这就是 SpecInputType 枚举存在的理由（源码注释原话：introduce this to distinguish the SpecInput types of multiple algorithms when asserting in attention backends）。
• num_tokens_per_req 同时是 DP attention 的乘数：spec_scale_global_num_tokens 把”每 rank 的请求数”换算成”本次前向的 token 数”，DP attention 的 global_num_tokens 同步依赖它。草稿阶段每请求宽度是 top-k、验证阶段是 num_draft_tokens，这个宽度必须准确上报，否则 DP rank 间的 token 数对不上。

与 CUDA Graph（九）

投机解码与 CUDA Graph 的冲突最尖锐：图捕获要求形状与地址稳定，而验证阶段的树形状随批、随树动态变化。SGLang 的应对有三层：

• SpecInput.cuda_graph_compatible：算法/输入级声明自己能否进图。
• ragged_verify_layout：用一套”参差不齐”的布局参数化形状——形状不再由”每请求固定宽度”决定，而是由这份布局描述，图按布局参数捕获。
• create_dummy_verify_input()：捕获阶段造形状匹配的假树（见前文引用的代码，EagleVerifyInput / DFlashVerifyInput / NgramVerifyInput 各有分支），让图能被捕获；draft_token=None 表示捕获期不需要真实候选。

草稿阶段反而容易进图：prepare_for_draft 的 topk 宽度是固定的（每请求恰好 top-k 行），因此 EAGLE_DRAFT 是形状稳定的阶段——这也解释了为什么 eagle_draft_cuda_graph_runner.py 与 eagle_draft_extend_cuda_graph_runner.py 是两个独立文件：draft-decode 与 draft-extend 的宽度不同（topk vs num_draft_tokens），必须分别捕获。

can_run_decode_cuda_graph = cuda_graph_runner and cuda_graph_runner.can_run_graph(forward_batch) 是 prepare_for_draft 的返回项之一：草稿前向能否走图，由 runner 按当前批的形状判断。这个返回值一路传到 worker，决定本次前向走 eager 还是重放。