企业官网建设流程全解析

如何用好TokenSpeed投机解码：EAGLE3与树形草稿的完整实战指南

【免费下载链接】tokenspeedTokenSpeed is a speed-of-light LLM inference engine.项目地址: https://gitcode.com/gh_mirrors/to/tokenspeed

TokenSpeed 是一款速度接近理论极限（speed-of-light）的 LLM 推理引擎，其内置的**投机解码（Speculative Decoding）**支持 EAGLE3、MTP 等草稿模型。本文将带你掌握 TokenSpeed 投机解码的完整用法：从 EAGLE3 链式草稿的 4 个启动参数，到树形草稿（draft tree）的节点预算与后端要求，再到草稿概率拒绝采样，帮助你在不改变输出分布的前提下显著提升解码吞吐。

一、为什么投机解码能提速？

LLM 解码阶段是内存带宽瓶颈：每生成一个 token 都要把整个模型权重读一遍。投机解码的思路是：

1. 用一个小得多的**草稿模型（drafter）**快速连续提出多个候选 token；
2. 目标大模型一次前向同时验证这些候选；
3. 验证通过的 token 全部保留，被拒绝处按目标模型分布重采样。

关键保证：TokenSpeed 的验证规则确保最终输出分布与目标模型完全一致——草稿模型再"离谱"，也不影响正确性，只影响接受率。

TokenSpeed 目前支持四类草稿器（见 docs/configuration/server.md）：

二、EAGLE3 链式草稿：四步启用

最简单的用法是链式草稿（chain）：每个草稿深度只提一个 token。只需在启动命令上追加 4 个参数：

tokenspeed serve nvidia/MiniMax-M3-NVFP4 \ --attention-backend trtllm \ --kv-cache-dtype fp8 \ --moe-backend flashinfer_trtllm \ --speculative-algorithm EAGLE3 \ --speculative-draft-model-path Inferact/MiniMax-M3-EAGLE3 \ --speculative-num-steps 3 \ --speculative-eagle-topk 1 \ --speculative-num-draft-tokens 4

这条配方来自官方模型手册 docs/recipes/models.md。记住一条核心规则：

链式草稿下，--speculative-num-draft-tokens必须等于--speculative-num-steps + 1（默认 3 步对应 4 个草稿 token）。

以 Kimi K2.5 为例，官方 agentic 压测中每个并行布局都固定带上：--speculative-algorithm EAGLE3 --speculative-num-steps 3 --speculative-eagle-topk 1 --speculative-num-draft-tokens 4，配置脚本见 test/agentic_benchmark/kimi_k2.5/tokenspeed/，压测流程说明见 test/agentic_benchmark/kimi_k2.5/tokenspeed/README.md。

三、投机解码参数速查表

以下是 EAGLE3 / 树形草稿相关的核心参数（完整说明见 docs/configuration/server.md）：

官方建议配方式启动时优先用--speculative-config（JSON 配置），把方法、草稿模型和 token 数放在一起，更不易出错。

四、树形草稿进阶：--speculative-eagle-topk > 1

链式草稿每步只有 1 个候选，一旦某步被拒，后面的草稿就浪费了。树形草稿让每个节点保留最优 K 个候选，一次目标前向最多验证 N 个节点（N ≤ 64），目标模型接受哪条路径就走哪条。

如何切换到树形

把--speculative-eagle-topk调大到 1 以上，同时必须显式指定节点预算：

--speculative-algorithm EAGLE3 \ --speculative-draft-model-path <eagle3-draft> \ --speculative-num-steps 3 \ --speculative-eagle-topk 4 \ --speculative-num-draft-tokens 10

注意预算约束（不满足会在启动时直接报错）：

• topk 范围 1..16，steps 范围 1..10；
• 每请求每步的 lane 槽位为(steps - 1) * topk，必须落在节点预算内；
• 节点总数（含根）最多64；
• 树形草稿下--speculative-num-draft-tokens是节点预算（含根），不再是 steps + 1。

树形草稿的硬性前提

树形路径有明确的适用范围（详见设计文档 docs/design/tree-speculation.md）：

• 注意力后端：需要trtllm注意力后端（bf16 KV、全历史缓存组），前缀走 trtllm-gen 解码核、树窗口走专用小核；
• 采样后端：greedy或triton（其 Gumbel-max 按位置取噪声，树形验证才能与纯解码逐位一致）；
• 暂不支持：结构化输出、混合批次、流水线并行、Prefill/Decode 分离、注意力数据并行、目标/草稿层的滑动窗口与 attention sinks。

任何一条不满足，executor 会在启动时明确拒绝并给出原因（由resolve_tree_support汇总报告），不会静默降级——这一点排查问题时很有用。

五、提升接受率：草稿概率拒绝采样

默认规则下，链式草稿器提出 logits 的 argmax，目标模型按p(x)概率接受。当请求是带温度采样时，草稿的 argmax 往往不是目标分布最可能的 token，接受率偏低。

开启--enable-speculative-sampling后切换为经典规则：草稿步按自身分布q采样并记录概率，验证时用coin * q(x) < p(x)接受、拒绝时从norm(relu(p - q))重采样。文档指出该规则可接受1 - TV(p, q)比例的草稿，在温度采样场景显著高于只接受 argmax。

使用注意：

• 要求链式草稿（--speculative-eagle-topk 1）、算法为EAGLE3或MTP；
• 需要--sampling-backend flashinfer或flashinfer_full；
• 会记录全词表分布，占额外显存：80 并发、4 草稿 token、129K 词表约330 MB，从--gpu-memory-utilization余量中扣除；
• PD 分离部署时只传给 decode 角色（prefill 角色会拒绝该标志）。

六、源码与验证资料导航

• 草稿器基类与工厂：python/tokenspeed/runtime/execution/drafter/base.py、python/tokenspeed/runtime/execution/factory.py
• LLaMA 系 EAGLE3 草稿模型实现：python/tokenspeed/runtime/models/llama_eagle3.py
• 树形草稿设计契约（不变量与测试矩阵）：docs/design/tree-speculation.md
• 各模型完整启动配方：docs/recipes/models.md
• 树形验证内核测试：tokenspeed-kernel/test/ops/test_tree_speculative.py、test/runtime/test_draft_tree.py

七、效果如何度量？

压测输出中最直接的指标是Decoded Tok/Iter（每次迭代实际提交 token 数）——投机解码的价值就体现在这个数字上，理想情况下接近草稿预算 4。官方 MiniMax M3 配方还做了精度对照：4x GB300 上 gsm8k 开投机解码后mean_acc0.9719，不开 0.9704，差异在运行噪声之内，草稿不改变答案质量。

八、常见启动错误自查清单

1. 链式草稿 token 数不对：num-draft-tokens必须等于num-steps + 1，树形则需显式给节点预算；
2. 树形草稿启动即被拒：检查是否为trtllm注意力 +greedy/triton采样，以及是否命中上文列出的不支持场景；
3. DFlash/DSpark 宽度不匹配：块草稿器的block_size与 steps/tokens 有严格约定（DFlash 存验证宽度 = steps + 1，DSpark 存起草数 = steps），不匹配会在启动时快速失败；
4. 温度采样接受率低：考虑开启--enable-speculative-sampling（仅限链式 + flashinfer 采样后端）；
5. 线性注意力目标（GDN/Mamba2）：默认启用 ReplaySSM 管理树形验证的循环状态，如需每位置暂存状态可用--disable-replay-ssm。

把 EAGLE3 链式草稿当作默认起点，再按负载把 topk 调成树形、按采样模式打开草稿概率拒绝采样，基本就能把 TokenSpeed 的投机解码红利吃满。更多模型级配方请继续参考 docs/recipes/models.md。

【免费下载链接】tokenspeedTokenSpeed is a speed-of-light LLM inference engine.项目地址: https://gitcode.com/gh_mirrors/to/tokenspeed