TensorRT-LLM 源码完全拆解（三十一）：无模型投机解码的控制面——Drafter 的批内闸门、n-gram 池、后缀自动机旁路与验收关闸

批内闸门：should_use_spec_decode

这个方法看起来只有几行，却是整个控制面最容易被忽略的一层：

1
if self.max_concurrency is None:
2
    return True
3

4
tokens_per_request = 1 + max_total_draft_tokens
5
token_cap = max_num_tokens // tokens_per_request
6
if token_cap <= 0:
7
    return False
8

9
num_effective_requests = min(len(requests), max_batch_size, token_cap)
10
return num_effective_requests <= self.max_concurrency

第一行是默认行为：用户没有配置 max_concurrency，就永远开投机。这不是偷懒，而是把「什么时候该关」交给更上层的批大小调度与关闸逻辑。

后面几行才是真正的批内闸门。max_num_tokens 是整个引擎一次前向的 token 预算；每个投机请求要占 $1+K$ 个位置（一个已确认 token 加 $K$ 个草稿），所以 token_cap 是「按 token 预算最多能装下多少个投机请求」。最终参与判断的请求数是三个上限的最小值：实际请求数、max_batch_size、token_cap。只要这个数超过 max_concurrency，本轮就不开投机。

这里有个细节值得注意：闸门比较的是请求数，不是 token 数。token_cap 已经先把 token 预算折算成请求数，后面再和并发上限比较，等价于同时受两个约束。这样写的好处是语义直观，用户配置的 max_concurrency 就是「最多允许多少个请求同时投机」；坏处是当 $K$ 很大时，token_cap 可能远小于 max_batch_size，实际关闭点会比用户以为的更早。

max_concurrency 怎么变成一张长度表

DecodingBaseConfig 里还有一个字段 draft_len_schedule，它把「batch 大小 → 草稿长度」写成分段表。两个字段互斥；如果用户只配了 max_concurrency，配置校验器会把它翻译成只有一段的表：

1
if self.max_concurrency is None:
2
    return self
3
if self.max_draft_len is None or not self.spec_dec_mode.support_dynamic_draft_len():
4
    return self
5

6
self.draft_len_schedule = {int(self.max_concurrency): int(self.max_draft_len)}
7
self._translated_from_max_concurrency = True

翻译之后，max_concurrency=4, max_draft_len=5 等价于 draft_len_schedule={4: 5}。按最终生效的 utils.get_draft_len_for_batch_size 语义，batch 不超过 4 时用 5 个草稿；超过 4 时二分落到表尾，返回 0，投机关闭。这正是 max_concurrency 的语义，但底层只剩一条查表路径，调度器不用维护两套判断。执行器预调度阶段用的是 Drafter 自己的查表函数，二分方向不同，可能先看到最后一段的 5；调度后的 update_draft_len 会按最终语义把它纠正为 0，所以占位草稿之后还会被清空一次。

用户也可以直接写多段表，例如 {4: 4, 8: 2, 32: 1}：batch 1 到 4 用 4 个草稿，5 到 8 用 2 个，9 到 32 用 1 个，33 及以上关闭（按最终生效的查表语义）。校验器要求最小的 batch 阈值必须对应 max_draft_len，并且表按阈值排序。这里要注意，长度表有两套查表函数，而且二分方向相反。Drafter.get_draft_len_for_batch_size 用 bisect_right，找的是「不大于当前 batch 的最大阈值」，即按分段下界取值；调度步里的 utils.get_draft_len_for_batch_size 则用 bisect_left，找的是「第一个不小于当前 batch 的阈值」，语义是「key 表示允许使用该长度的最大 batch」。对 {4: 4, 8: 2, 32: 1} 来说，两者在 4、8、32 这些边界上的结果相同，中间值也相同，差别只在于边界是归入本段还是上一段；但读源码时如果把两处混为一谈，就会误判 batch=5 时到底用 4 还是 2。真正决定每步草稿长度的是 _handle_dynamic_draft_len 调用的 update_draft_len，它在 prepare_resources 之前同步缓冲区，注释里强调这一步必须早于 KV 分配，否则 KV 会按上一档的草稿长度预留。

这套表还有一个与 CUDA Graph 的联动：DecodeCudaGraphConfig._merge_schedule_keys 会把表里的 batch 阈值合并进 CUDA Graph 的 batch size 列表。原因是图是按 batch 桶捕获的，而草稿长度会改变图里 KV 容量、注意力元数据和缓冲宽度；如果某个阈值没有对应的图桶，运行时就可能落进一个「形状按旧草稿长度捕获」的图。把阈值并进桶列表，等于强制在每个草稿长度档位的边界上都有一张静态图可用；批大小的跨度不同，图里的草稿长度也不同。

补齐到静态长度：pad_draft_tokens_for_cuda_graph

动态草稿长度带来一个 CUDA Graph 难题：这一步实际只投了 2 个草稿，但图是按最大 5 个草稿捕获的。解决办法是先把真实长度记下来，再把缓冲区补到静态最大值：

1
pad_to = self._static_max_total_draft_tokens
2
for req in scheduled_requests.generation_requests:
3
    num_draft_tokens = get_draft_token_length(req)
4
    req.py_draft_tokens_effective_len = num_draft_tokens
5
    req.py_draft_tokens.extend(0 for _ in range(pad_to - num_draft_tokens))

这里记下的 py_draft_tokens_effective_len 非常关键。补零之后的 py_draft_tokens 长度是静态的 5，但真正提出、真正需要验证的只有 2 个；接受率的分母必须用 2，不能用 5。注释里提到、并在 LlmRequest 中另设了一个 py_num_draft_tokens_verified 字段作为真实分母，那里的注释写得很清楚：py_draft_tokens 本身不能当分母，因为它会被 CUDA Graph padding 拉长，而且在 one-model 流程里，等结果返回时它已经装着下一步的草稿了。

对 NGram 和用户自定义 drafter，还需要在补零之后扩展 KV 容量。原因是它们的采样器用 len(py_draft_tokens) 计算 rewinding 长度，补出来的零也占了 KV 位置；如果只补 token 不补 KV，验证时就会越界。_needs_padding_kv_extension=True 就是给这类 drafter 的标记，pad_draft_tokens_for_cuda_graph 会分别对目标 KV 管理器和草稿 KV 管理器调用 extend_capacity_for_tokens。one-model 的草稿头用 SpecSampler 按 runtime_draft_len 计算 rewind，padding 不影响正确性，所以不需要这个标记。

池里存了什么

NGramPoolManager 的核心是一个从模式到候选续写的映射：

1
# 公共池：pattern -> OrderedSet(match)
2
# 私有池：request_id -> pattern -> OrderedSet(match)
3
pool: dict[tuple[int], OrderedSet[int]] | dict[int, dict[tuple[int], OrderedSet[int]]]
4
start_index: dict[int, int]   # 每个请求下次从哪个位置开始扫描

一个具体的例子是 ("I", "love") -> [("apple", "because", "it", "is"), ("banana", "and")]。同一个 key 可以对应多个 value，is_keep_all 控制是否全部保留；is_use_oldest 控制命中时取最早还是最新的候选。源码里 is_use_oldest 目前只实现了取最早的分支，注释里留着 TODO，说明更新策略还没有做完。

新请求的初次扫描

上图出自 TensorRT-LLM 官方技术博客对 NGram 的专题分析：max_matching_ngram_size=3、max_draft_len=5、输入长度为 8 时，初次扫描会往池里加入 18 个键值对。扫描的做法是枚举每个起点、每种 key 长度，把 key 后面的最多 max_draft_len 个 token 作为 value。复杂度大约是「输入长度 × 最大 key 长度」，所以初次扫描的代价与 prompt 长度成正比。

在代码里，这次扫描不是在请求到达时做的，而是延迟到第一次 prepare_draft_tokens：start_index[request_id] 初始为 0，第一次查询时 sequence = prefix[0:]，于是整个 prompt 被扫一遍；扫完后 start_index 跳到「当前位置减去 $K+M-1$」，后续每步只处理窗口内的新 token。这个 start_index 回退「当前位置减去 $K+M-1$」很重要：它保证下一次扫描的起点落在上一轮草稿能覆盖到的最早位置，既不重复扫描已经进池的 token，也不会漏掉「草稿被接受后回填进来」的那几个 token。源码里 start_index 是在查询结束后、而不是在更新结束后写的，顺序不能颠倒——查询要用旧的起点判断是否需要建池，更新要用同一个起点扫描增量，两者共用同一个值。

每步的增量更新

上图展示生成过程中新 token 到来时池子的变化：已有的 key 如果 value 长度还没到上限，就把新 token 追加进 value；同时新 token 也会作为新 key 的结尾，产生新的键值对。每次更新涉及的键值对数量约为 $K \times M$，对固定的 $K$、$M$ 来说是常数，不随历史长度增长。这就是博客里说「每 token 更新近似常数」的依据。

但「常数」不等于「免费」。这些操作全在 Python 解释器里，键是 tuple，值是 OrderedSet，每步要构造切片、做哈希、比较集合。池子大到超出 CPU 缓存后，哈希查找会频繁 miss，主机侧延迟就会显形。博客也明确提醒了这一点：查询理论上是摊还常数，但当字典超过 CPU 最快缓存后，能观察到额外延迟。

查询与生成草稿

get_draft_tokens 的查询顺序是「从最长的 key 往最短试」：

1
for size in range(min(max_matching_ngram_size, prefix_len - 1), 0, -1):
2
    pattern = tuple(prefix[-size:])
3
    if pattern not in pool:
4
        continue
5
    draft_tokens = pool[pattern][0 if is_use_oldest else -1]
6
    return list(draft_tokens)[:max_draft_token_length_this_step]
7
return []

先试最长匹配，是为了优先使用信息量最大的上下文。长度为 5 的后缀命中，通常比长度为 1 的后缀命中更可能给出正确的续写；如果先试短的，就会被大量高频短模式淹没。

草稿长度还受两个上限约束：一个是 max_draft_len，另一个是「序列剩余空间」——max_sequence_length - 1 - prefix_len。后者保证草稿不会把序列顶到 max_new_tokens 之外，否则验证批会多出无意义的行。

三笔账：内存、主机时间、命中率

NGram 的实现里还有两个容易被忽略的细节。一是 is_keep_all=False 时，同一 pattern 只保留最长的一个 match，新 match 更长就替换，否则丢弃；这意味着关闭保留全部候选后，池会偏向「最近见过的长续写」，而丢失了「同一个 key 在不同语境下有不同续写」的信息。二是池的更新在处理短候选时有一个 TODO：新 match 进来后会把同 pattern 下更短的 match 删除，而不是保留它们作为回退。这两个行为都让池更紧凑，但也让「命中但续写太短」的情况变得更常见。

NGram 的工程取舍可以归纳成三笔账。

第一笔是内存账。 公共池把所有请求的 pattern 都存进同一个字典，请求完成后也不清理（update_resources 在公共池模式下直接返回）。这意味着池子会随着服务运行时间单调增长，直到进程重启。私有池按请求清理，但每个请求都要维护一份自己的字典，短请求多的时候内存开销反而更大。公共池适合「多轮对话、请求之间共享上下文」的场景，私有池适合「请求彼此无关、内存必须可回收」的场景。

第二笔是主机时间账。 初次扫描 $O(LM)$，每步更新 $O(KM)$，查询最坏 $O(M)$ 次哈希。对短 prompt、低并发，这些都可以忽略；对长 prompt、高并发，Python 的解释器开销会成为瓶颈。SA 把匹配搬到 GPU，本质上就是在还这笔账。

第三笔是命中率账。 命中率完全由文本重复性决定，和模型能力无关。下面是官方博客在对话数据上的接受长度分布：

横轴是接受长度，1 表示一个草稿都没接受，6 表示 5 个草稿全接受。分布是双峰的：大量请求落在 1，也有相当一部分落在满接受。这意味着 NGram 的收益高度依赖请求类型，平均值会掩盖这种分化。翻译任务上的分布更极端：

翻译文本里存在大量「原文短语 → 译文短语」的稳定对应，重复片段多，接受长度可以超过 4。博客给出的数字是：对话首轮平均接受长度约 1.37，第二轮约 1.66；翻译任务可以超过 4.0。这些数字不是模型 benchmark 分数，而是「检索式草稿在这类文本上能抄到多长」的直接测量。

NGram 的结构性限制

除了弃用状态，NGram 还有几条硬限制，读源码时应该记住：

1. 只支持线性树。 max_total_draft_tokens 被强制等于 max_draft_len，因为池里每个 key 只对应一条续写序列，无法像 Medusa 那样一次验证多条候选路径。
2. 不支持 rejection sampling。 检索式草稿没有 $q(x)$，只能精确匹配；这一点在收益模型一节已经说明。
3. 草稿是主机侧 Python 对象。 它必须走 Drafter 的外部草稿路径：先占位、再生成、再补齐、再交给模型引擎。它不能像 SA 那样把匹配塞进目标模型前向的 epilogue。
4. 公共池没有淘汰。 这是实现现状，不是设计目标；源码里 update_resources 的公共池分支只有一个 TODO。长时间运行的服务需要自己评估内存增长。

也正因为这些限制，官方把 SA 定为替代路线：同样的「查历史续写」思想，但状态在 GPU、匹配在 GPU、并且能直接嵌进 one-model 前向。

为什么 NGram 的初次扫描要延迟到第一次草稿

add_request 在 NGram 里并不存在。请求到达时，执行器不碰池子；直到第一次 prepare_draft_tokens，池才会为这个请求建立 start_index=0 并扫一遍整个前缀。这种「惰性建池」有三个好处。

第一，请求可能在本轮就被抢占或中止，甚至预填充还没跑完。如果到达时立刻扫描整段 prompt，被抢占的请求等于白扫了一次，而这些请求在长 prompt、高并发的服务里并不少见。

第二，预填充是分块进行的。如果第一次调度只给了请求前 2048 个 token，此时扫描到的「前缀」并不是完整输入；等后续块到来，池里已经建立了一批基于残缺前缀的键值对。惰性建池保证首次扫描发生在第一次真正需要草稿的时刻，那时输入至少已经包含一个完整的确认 token。

第三，也是最重要的一点：草稿池的内容与「已经确认的 token」严格对齐。扫描用的 request.get_tokens(0) 返回的是已提交 token 的副本，不包含尚未验证的草稿。如果池子把草稿也当作历史，就会形成「用自己猜的内容去猜自己」的自增强循环，命中率看起来很高，实际验证时大量失败。把扫描起点和 token 提交点绑定，是检索式草稿不跑偏的前提。

公共池与私有池的淘汰账

私有池的释放时机在 update_resources：本轮调度里处于 GENERATION_COMPLETE 的请求，直接从池字典里删除条目，start_index 也一并清掉。它的复杂度是「本轮完成请求数」，与历史长度无关。

公共池则什么都不做，源码分支直接 return。这意味着所有请求的键值对长期共享一个字典，服务运行越久，池越大。好处是跨请求复用：多轮对话里第二轮的问题可能用到第一轮的问答片段；坏处是内存与哈希表容量单调增长，而且旧数据可能以极低的匹配概率仍占着内存。

如果要在一个公共池服务里评估内存，一个粗略的口径是：池中条目数约等于「所有已见 token 数 × 平均 key 长度」，每条目的 value 最多 $K$ 个 token，键值都按 Python 的 int 对象存储。Python 小整数有缓存，但长序列的 token id 大多超出缓存范围，每个 int 是一个完整的对象。真实占用要乘上解释器开销系数，而不是简单按 4 字节或 8 字节算。

这是 NGram 被弃用的原因之一：它的「共享」是在 Python 层做到的，而 SA 的共享是在 GPU 状态槽里做到的，后者可以显式设定槽位数并做 FIFO 淘汰，内存上界是可控的。

一个具体的 NGram 查表例子

设 max_matching_ngram_size=3、max_draft_len=5，当前序列的末尾是 [..., "retry", "with", "exponential", "backoff"]。查询依次尝试：

1. 长度 3 的后缀 ("exponential", "backoff")——如果池里有，直接返回后续最多 5 个 token。
2. 没有则试长度 2 的 ("backoff") 之类的最后两个 token 组合。
3. 再没有则试长度 1 的最后一个 token。

命中后，返回的 value 就是草稿候选，再按剩余空间截断。可以看到，匹配长度的优先级是硬编码的「从长到短」，没有打分、没有回退到次长匹配。如果长度 3 的 key 命中但 value 只有 1 个 token，草稿就只有 1 个，而不会改试长度 2 的 key 去拿更长的续写。这是 NGram 简单直接的代价：它不优化「草稿长度」，只优化「匹配精确度」。

SA 的 extend_ngram 在这一点上更灵活：max_ngram_size 为正时同样从长到短试，但它是在 GPU 上的一次 kernel 里完成的，且与状态扩展合并；max_ngram_size=-1 时直接取最长后缀匹配，不再受固定长度限制。

实现结构：主机建树、GPU 扩展

TensorRT-LLM 的 SA 是一个原生 C++/CUDA 算子，Python 侧只负责资源管理。SuffixAutomatonManager 的关键分工是：

1. 请求首次进入上下文阶段时，在主机上构建自动机。 add_request 调用 _sa_native.build_automaton_host(context_tokens, max_seq_len)，把整段 prompt 建成状态机。
2. 构建结果拷贝到 GPU 的一个槽位。 每个请求占一个 slot，槽位数组是 allocate_workspace(pool_size + 1, max_seq_len)；多出来的那个 slot 是 dummy slot，专门给 CUDA Graph padding 用。
3. 生成阶段每步扩展并查询。 extend / extend_ngram / extend_global 三个入口都调用原生算子，在 GPU 上把本步接受的 token 追加进自动机，同时返回最长匹配长度与对应草稿。
4. 请求结束时释放或保留槽位。 不开全局池时立即清空；开全局池时，已完成的请求可以保留状态供其他请求搜索，直到池满后按 FIFO 淘汰最老的保留项。

这里有一个需要看清的分工：主机建树、GPU 扩展。构建自动机需要逐 token 插入并维护后缀链接，分支多、不规则，放在主机上做一次是合理的；生成阶段的扩展只需要把新 token 接到已有状态后面，规则且批量，适合 GPU。源码注释明确说 extend() 与 extend_ngram() 完全在 GPU 上跑，并且 CUDA Graph 兼容。

prepare() 是每步图外的准备工作：把待拷贝的主机状态复制到 GPU、刷新全局池的 active slot mask、把本批请求映射成 slot 下标与 non-dummy mask，然后用一次 torch.cuda.current_stream().synchronize() 保证后续 kernel 能看到这些更新。这一次同步在 CUDA Graph 捕获之外，属于每步固定的主机开销；它不能省，因为 extend kernel 依赖刚写入的槽位映射。

两种匹配模式

SADecodingConfig.max_matching_ngram_size 决定匹配策略：

• -1：最长匹配。 沿自动机找当前序列能匹配的最长后缀，返回它后面的续写。信息量最大，但匹配长度不受控，长匹配可能跨越语义边界。
• 正整数 $M$：固定长度 n-gram。 只试长度不超过 $M$ 的后缀，从长到短。它把匹配长度限制在可控范围，行为更接近 NGram，但每次查询要试多个长度。

enable_global_pool 打开后，每个请求不只看自己的自动机，还会搜索池中所有 active 状态，取全局最长匹配。源码注释给出了两个硬限制：最多 1024 个并发槽位，单请求的后缀匹配最多 64 个 token。前者是 kernel 的并行度上限，后者是防止全局搜索退化成遍历整棵自动机。

全局池的动机是跨请求复用。多轮对话里，第二个用户的提问可能和第一个用户的历史高度相似；翻译任务里，不同请求的原文模板也可能重复。让请求 A 的自动机为请求 B 提供草稿，等于把「前缀缓存」的思想从 KV 层搬到了 token 层。代价是内存与淘汰策略：池子默认大小是 max(64, max_batch_size)，已完成请求的状态会保留，池满后 FIFO 淘汰。_allocate_slot 的淘汰顺序是「先取空闲槽，再取保留槽，最后报错」：空闲槽代表从未被使用或已被显式释放的槽位，保留槽代表已完成但仍在提供跨请求搜索的槽位。取保留槽时，会先调用原生算子 clear_slot 把该槽清空，并把 active mask 置 0，再把槽交给新请求。这样避免新请求继承旧请求的后缀自动机状态，导致匹配在语义上完全错位。源码里还有一个「陈旧槽」判断：如果某个请求的 GPU 拷贝尚未落盘就被移除，它的槽位直接释放而不保留，理由是槽里可能是未初始化数据，被别的请求搜到会给出不可用的草稿。它不是无限缓存，长跑服务要按并发和重复度估算所需槽位数。

为什么 SA 不用 Drafter：一条被绕开的通道

读源码时值得把 get_spec_drafter 与 get_spec_worker 并列看：

1
def get_spec_drafter(model_engine, spec_resource_manager):
2
    spec_config = model_engine.spec_config
3
    if spec_config is None:
4
        return None
5
    if spec_config.spec_dec_mode.is_user_provided():
6
        return spec_config.drafter
7
    if spec_config.spec_dec_mode.is_ngram():
8
        return NGramDrafter(spec_config, spec_resource_manager)
9
    return None

外部草稿器只认两种模式：用户自己传进来的实例，以及 NGram。SA 返回 None，然后由 get_spec_worker 在 one-engine 包装类里创建一个 SAWorker。这两条路径的资源生命周期完全不同。

外部草稿器路径下，调度器必须先为草稿预留 token 预算和 KV 页，草稿生成是本步前向之前的独立阶段。草稿 token 追加进目标请求的 KV 区间，验证后按 rewind 裁掉；如果草稿来自独立神经模型，框架还会额外维护一份草稿 KV。one-engine 路径下，草稿在目标模型最后一层之后生成，草稿 token 作为「下一步的输入」直接写进输入缓冲，没有独立的草稿 KV，回滚只涉及目标 KV 的 rewind。

SA 之所以选后者，是因为它的「草稿生成」只是一次后缀匹配，不需要单独的 KV 来容纳草稿上下文：自动机本身就是上下文结构，存在自己的槽位里，不占 KV 页。把它放进外部草稿器路径，反而要凭空创建一套草稿 KV 的账，而草稿里根本不需要写 KV。

这也解释了为什么 SA 的 prepare 要做主机到设备的拷贝。自动机的状态不在 KV 里，也不在 attention 元数据里，只能作为独立的工作区存在；每步扩展前，Python 侧必须把「本批请求映射到哪些槽」和「哪些槽是 dummy」告诉 kernel。NGram 没有这一步，因为它的状态本来就在主机上。

独立 SA：草稿在目标模型前向里完成

SA 和 NGram 最大的结构差异，是它不需要外部的 Drafter。SpeculativeDecodingMode.SA 属于 one-engine 模式：get_spec_drafter 对 SA 返回 None，模型引擎不会创建外部草稿器；取而代之的是 get_spec_worker 创建一个 SAWorker，挂在目标模型的 epilogue 上。目标模型跑完所有解码层后，SAWorker 接手 logits，完成采样、验收、扩展自动机、生成下一步草稿五件事：

1
# 1. 采样并验证上一步草稿
2
accepted_tokens, num_accepted_tokens = self._sample_and_accept_draft_tokens(...)
3
# 2. 用接受的 token 扩展 SA，查最长匹配，产出下一步草稿
4
next_draft_tokens = self._generate_draft_tokens(...)
5
# 3. 为 overlap scheduler 准备下一步输入
6
next_new_tokens = self._prepare_next_new_tokens(...)

这条路径的优点是「零草稿前向」：没有第二个模型、没有额外 KV、没有草稿 token 的外部搬运。草稿完全来自 token 序列本身，生成草稿的算力成本只有几个 GPU kernel 的匹配操作。缺点也很直接：它只能抄历史，遇到全新内容时匹配长度为 0，草稿为空，验证批退化成普通解码。

源码里有一个细节体现了 CUDA Graph 兼容性的考虑：_generate_draft_tokens 在拿到 match_len 与 draft_tokens 后，会用 (match_len > 0) 做一次掩码乘法，把没匹配上的行清零。这样即使某些请求本轮没有草稿，kernel 依然按固定形状输出，图不需要因为「这行有没有草稿」而改变。

SA Enhancer：给神经草稿器加一条旁路

SA 还可以不独立使用，而是作为神经草稿器的增强器。SAEnhancerConfig 可以挂在 EAGLE-3、MTP（Multi-Token Prediction，多 token 预测）、PARD（Parallel Draft，并行草稿）的配置上；此时草稿仍由神经头生成，但 SA 会在后台同时查一份「精确重复」的候选，匹配长度达到阈值时覆盖神经草稿。

SADraftEnhancer 的实现有三个关键设计：

第一，旁路流。 SA 的扩展与查询跑在专用 CUDA 侧流上，extend_and_prepare 先让侧流等待主流，再在侧流上启动 kernel，最后记录一个 event。主流的神经草稿前向不用等 SA，两边真正重叠。

第二，延后覆盖。 maybe_override_all_draft_tokens 要等整个草稿循环结束后才调用，不是在每一层草稿后覆盖。原因是神经草稿是逐层自回归的：第 $i$ 层的输入依赖第 $i-1$ 层的输出。如果在中间层把 token 换成 SA 的结果，后续层的隐状态就和这些 token 不匹配，草稿头的条件分布会错位。等所有层跑完再整体覆盖，神经头始终看到自己生成的 token，SA 只替换最终提交的候选。

第三，阈值门控。 只有当 match_len >= threshold 时才覆盖，默认阈值是 4。阈值越低，SA 越容易接管，命中率可能上升，但也可能用一个「只在字面上重复、语义上不合适」的续写替换掉神经头更合理的草稿；阈值越高，SA 越保守，只在长重复片段上出手。源码模块注释给出的说法是：与 MTP 结合时，SA 最多可以把接受率提升 40%。这个数字是模块作者的测量口径，不是所有模型、所有负载的通用保证。

覆盖的实现是一次向量化的 torch.where：

1
mask = (self.sa_match_len[:n] >= self.threshold).unsqueeze(1).expand_as(draft_tokens)
2
draft_tokens = torch.where(mask, self.sa_draft_tokens[:n, :K], draft_tokens)

它把「哪些请求用 SA、哪些保留神经草稿」变成一次张量选择，不引入主机分支，因此可以留在 CUDA Graph 里。阈值判断在 GPU 上做，还避免了每步把 match_len 拷回主机再决定覆盖范围的同步开销。

SA 的边界

SA 不是万能的，它的收益边界比神经草稿更窄：

1. 只对重复文本有效。 匹配长度是硬门槛，没有匹配就没有草稿；对开放式创作、全新推理，命中率会很低。
2. 精确匹配，不做概率校正。 和 NGram 一样，它没有提案分布，不能用 rejection sampling；它只保证「抄来的 token 如果被接受，就是目标模型的真实选择」，不保证草稿分布接近目标分布。
3. 状态内存与序列长度成正比。 每个 slot 按 max_seq_len 分配，默认 262144；池子有 pool_size + 1 个 slot。开全局池前要按「并发 × 序列上限」估算显存，不要只看默认值。
4. 全局池的跨请求匹配有语义风险。 字面重复不代表上下文相同；在需要严格隔离租户数据的场景，公共池不应该开。

执行器怎么喂它

PyExecutor 在构造时读取 acceptance_rate_window_size 与 acceptance_rate_threshold，两个都有效才创建 gate。采样结果落回主机后，_update_batch_acceptance_rate 做四件事：

1. 跳过不该统计的场景。 gate 不存在、已经永久关闭、处于 warmup、或者当前 rank 不是流水线最后一级，都直接返回。最后一级才有完整的采样结果，其他 rank 统计会重复。
2. 只统计真正投了草的请求。 遍历本轮 generation 请求，跳过 draft_len <= 0 和 dummy 请求，把草稿数与接受数分别累加。
3. 算批级比率。 acceptance_rate = total_accepted / total_drafted，然后喂给 gate。
4. 处理关闭。 如果本轮触发了关闭，置位 speculation_permanently_disabled，后续迭代直接走关闭分支。

这里有一个读源码时值得留意的口径问题：关闸函数累加的是 request.num_draft_tokens 与 request.py_num_accepted_draft_tokens，而统计管线使用 py_num_draft_tokens_verified 作分母，源码注释明确说后者排除了 CUDA Graph padding。如果 num_draft_tokens 在 padding 之后反映的是静态最大长度，闸门算出的接受率就会比真实值低，关闸会比实际需要更早触发。这个行为是偏保守的：宁可早关，也不要在低命中率上继续烧验证算力。读代码时不要把两个分母混为一谈。

为什么是永久关闭，而不是动态开关

SpeculationGate 的 disabled 标志 一旦置位就不再复位，reset() 只在显式重置时调用。这个设计是有意的：

• 避免震荡。 如果接受率在阈值附近波动，动态开关会让投机在开与关之间反复切换；每次切换都要重新分配草稿 KV、重建调度预算，开销可能比省下的验证成本还大。
• 关闸是负载级判断，不是单请求判断。 一个服务如果在前 100 轮里平均接受率都很低，说明当前流量类型不适合检索式草稿；继续观察的期望收益很低。
• 正确性不依赖投机。 关闭投机只是不再提前猜 token，目标模型的输出分布完全不变。所以「永久关闭」是一个安全的降级，不需要保留恢复路径。

代价是它对负载变化不敏感：如果服务先跑了一段低重复流量，后来又切到高重复流量，gate 不会自动重新打开。需要重新开启时只能重启引擎或显式重置配置。这也是为什么调参时应该先把 window 设得足够大、阈值设得足够低，把 gate 当成兜底，而不是当成主控制手段。

一个门控失效的案例推演

设 window=200、threshold=0.3，一个服务连续跑了 200 轮投机，平均每个请求投 4 个草稿。在这 200 轮里，如果接受率一直稳定在 0.25，那么 gate 在第 200 轮结束时返回「关闭」，此后所有迭代都不再投机。此时端到端的单步成本从「$1+\mathbb{E}[A]$ 个 token 摊在 $1+\gamma K$ 的成本上」变成「每次 1 个 token 摊在 1 的成本上」。

代入前面的模型，$\alpha=0.25$、$K=4$ 时，$\mathbb{E}[T]=(1-0.25^5)/0.75 \approx 1.331$；而验证批是 5 行，若高并发下 $\gamma \approx 0.3$，单步耗时约 $1+0.3 imes4=2.2$ 个单位。加速比约 $1.331/2.2 \approx 0.6$，也就是投机反而慢了将近一倍。gate 在这里关闭投机，把加速比从 0.6 拉回 1 附近，这是它存在的直接理由。

反过来，如果同样的 $\alpha=0.25$ 出现在 batch 1 的流水线上，$\gamma$ 可能只有 0.05，单步耗时约 $1.2$，加速比约 $1.1$。此时投机其实有微小正收益，但 gate 看不到 batch 大小，只看到接受率低于阈值，仍会关闭。这是 gate 的一个盲点：它用质量指标代替成本模型。补偿手段是把阈值和窗口调得更保守，或者根本不开 gate，改由 draft_len_schedule 按 batch 控制。

三种控制手段的分工

三者是串联关系：长度表先决定 $K$，批内闸门再判断容量是否允许，gate 最后用质量数据一票否决。任何一层说「不」，投机都不会发生。

先选路线，再调参数

路线选择比参数更重要：

• 流量高度重复、延迟敏感、不想加载第二个模型：优先 SA 独立模式。它没有草稿前向，成本最低，参数也最少。
• 已经有 EAGLE-3/MTP/PARD 草稿头，且文本里存在大量精确重复：加 SAEnhancerConfig。神经头负责新内容，SA 负责重复片段，两者互补。
• 只是想让服务默认快一点、不想做模型适配：用 AUTO。它选的是 SA，并且按 batch 自动关小；这也是默认的无草稿模型入口。
• 还在用 NGram：计划迁移。文档已经标注 2027 年 1 月移除；NGram 的 Python 池在高并发下会成为主机瓶颈，SA 是同一思想的 GPU 版本。

参数怎么影响行为

调参时不要只看平均接受率。更有用的三个量是：迭代延迟（验证带来的单步成本）、接受长度分布（双峰还是单峰）、端到端吞吐（关闸与调度交互后的结果）。官方博客给出的测量方式是固定请求数，对比开/关投机的端到端 runtime，同时记录每轮接受长度；这套方法可以直接复用。

下面这张图是官方在对话第二轮上的端到端加速比。它说明的不是「某个模型有多强」，而是「同一组 $k,v$ 在不同 batch 下的收益形状完全不同」：

图中 batch 1 的柱子最高，batch 32 明显变矮；这不是实现退化，而是前面 $\gamma(B)$ 模型的直接体现。调参时如果只在一个 batch 上测出「投机有效」，就把它推广到所有并发，几乎一定会失望。

几个容易踩的坑

第一，占位草稿会挤占预填充预算。 py_draft_pages_allocated 在调度前就设成 $K$，chunked prefill 的长请求会和草稿抢 token 预算。开启投机后 TTFT（Time To First Token，首 token 延迟）变差，很多时候不是草稿算得慢，而是调度器把预填充块切得更碎了。要同时看 TTFT 和 TPOT（Time Per Output Token，每 token 延迟）。

第二，动态长度表必须和 CUDA Graph 桶一起改。 只改 draft_len_schedule 不改桶列表，运行时可能落进形状不匹配的图。源码已经用 _merge_schedule_keys 自动把阈值并进桶列表，但如果你在外部生成配置文件，仍要确认桶列表覆盖了所有阈值。

第三，公共池的内存是单调的。 NGram 的公共池不清理已完成请求；SA 的全局池虽然有 FIFO 淘汰，但默认大小是 max(64, max_batch_size) 个槽位，每个槽位按 max_seq_len 分配。开之前按最坏情况算一遍显存。

第四，关闸不会重新打开。 长跑服务如果流量类型会切换，不要把 gate 当成自适应开关；它是一次性的熔断器。

第五，SA 的覆盖阈值不是越高越好。 阈值太高，SA 永远不生效，等于白开；阈值太低，SA 会覆盖掉神经头本来正确的草稿。默认 4 是一个保守起点，应该按实际文本的重复长度分布调整。