SGLang 投机解码Speculative Decoding命名规范accept / correct / bonus 标识符编码指南【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang投机解码是 SGLang 提升推理吞吐的核心路径但散落在python/sglang/srt/speculative/、attention 后端、调度器累加器、IPC 字段与可观测性指标中的标识符历史上同时混用accepted、verified、output_id等名称语义极易混淆。本文基于 SGLang 仓库中面向投机解码开发者的命名规范文档.claude/skills/speculative-naming/SKILL.md完整梳理accept/correct/bonus三组核心动词与名词的语义边界、数量与计数器的编码规则、单复数约定并结合 投机解码目录 与 可观测性指标实现 中的真实源码佐证。读完本文你将掌握一套可在 SGLang 投机解码代码中统一落地、可被代码评审与 Agent 直接执行的命名规范。适用范围哪些代码必须遵守本规范该命名规范面向新增、重命名或评审投机解码相关标识符这一场景覆盖范围包括python/sglang/srt/speculative/目录下的全部投机解码实现EAGLE、dflash、DSpark、ngram、UNO 等与投机解码相关的 attention 后端调度器scheduler中的累加器字段IPC进程间通信字段可观测性指标observability metrics与 CLI 参数。值得注意的是这份规范不是全局改名运动而是限定在投机解码这一特定领域内的语义收敛。仓库中已经存在的框架级名称如 PyTorch 生态的seq_lens、cu_seqlens_qtokenizer 相关的pad_token_id、eos_token_id等不在改写范围内具体清单见后文范围之外章节。Rule 1一律使用动词形式accept丢弃-ed过去分词投机解码代码中涉及接受 draft token的语义时统一使用动词形式accept严禁使用过去分词accepted。核心原因是accepted描述的是已经被接受这一静态状态而投机解码场景中的标识符大多承载的是本次验证动作产生的结果这一动态语义动词形式更贴合数据流的含义。不要用Dont应该用Donum_accepted_tokensnum_accept_tokensaccepted_indicesaccept_indicesaccepted_token_idsaccept_tokens同时参见 Rule 3这条规则在仓库中有充分的实现证据。例如 eagle_info.py 中定义逐请求接受计数字段时明确注释了# Per-req accept counts. num_accept_tokens num_correct_drafts 1字段名采用num_correct_drafts与num_accept_tokens两个动词形式eagle_draft_extend_cuda_graph_runner.py 中的 CUDA Graph 缓冲区同样命名为num_correct_drafts: torch.Tensor与num_accept_tokens: torch.Tensor。Rule 2目标模型额外输出的 1 token 一律叫bonus_token/bonus_tokens投机解码中目标模型target model在验证 draft 之外总是额外输出一个 token即 1 token这个 token 在 SGLang 中的规范命名是bonus token。不要使用verified_id、output_id等名称。不要用Dont应该用Doverified_id/verified_idsbonus_token/bonus_tokensoutput_id/output_ids当指 bonus 时bonus_token/bonus_tokens需要特别强调的是req.output_ids请求的完整输出历史与 bonus 无关保持原名不动。源码中的实际使用非常普遍dflash_info_v2.py 中定义bonus_tokens: torch.Tensordflash_worker_v2.py 用bonus_tokensnext_token_ids构造 draft 输入draft_worker_common.py 中make_draft_input_v2也接收bonus_tokens参数并统一to(dtypetorch.int64)。Rule 3accept含 bonuscorrect不含 bonus —— 语义边界在动词上本规范最重要的一条accept_*与correct_*的语义区分锚定在动词上而不是枚举名词对。两者含义如下动词含义accept_*包含bonus tokencorrect_*仅统计 draft不含 bonus该语义可以自由搭配任何合适的名词tokens、drafts、indices……规范不强制配对但给出了推荐默认名词accept_tokens与correct_drafts—— 因为correct语义上描述的是被验证通过的 draft而accept描述的是最终得到的 token 序列含 bonus。形式含义accept_tokens/accept_indices包含 bonuscorrect_drafts仅 draft不含 bonusnum_accept_tokens数量包含 bonusnum_correct_drafts数量不含 bonus例外accept_rate/accept_length遵循论文惯例有两个指标名由于已深深嵌入投机解码文献与外部暴露字段meta_info、Prometheus 指标其语义由论文定义而非 Rule 3 定义属于特例名称论文术语含 bonus定义accept_rate$\alpha$Leviathan 2023否每个 draft token 的被接受概率 correct_drafts / proposed_draftsaccept_length$\tau$EAGLE是每次验证步骤的平均 token 数 completion_tokens / verify_ct注意内部计数器仍严格遵守 Rule 3 语义——num_correct_drafts不含 bonus、num_accept_tokens含 bonus。这一例外在仓库的可观测性实现中得到印证metrics_reporter.py 中spec_accept_length spec_num_accept_tokens / spec_num_forward_ct含 bonus而spec_accept_rate num_correct_drafts / total_draft_tokens不含 bonus分母为提出的 draft 总数metrics_collector.py 进一步将两者注册为 Prometheus Gaugesglang:spec_accept_lengthaccepted drafts bonus token per forward与sglang:spec_accept_rateaccepted drafts / proposed drafts与文档表格中的论文定义完全一致。Rule 4num_表数量、_ct表计数器、_rate表比率、ID 不加前缀每个形式都有专属标记严禁混用不允许num_X_ct不允许num_accept_rate形式模式含义示例数量Countnum_X某个时间点的快照数量常为 tensor 或标量num_accept_tokens、num_correct_drafts、num_proposed_drafts计数器CounterX_ct随时间单调递增的累加器spec_verify_ct、forward_ct比率Rate / ratioX_rate[0, 1]区间内的比值accept_rateToken / 内容数组无前缀真正的 token 数据本身而非数量accept_tokens、correct_drafts、bonus_token仓库中_ct后缀的真实用法集中在 dflash 与 DSpark 路径中例如 dspark_block_accept_estimator.py 中以forward_ct作为单调递增的步数参数并通过_max_forward_ct、_last_forward_ct等累加维护窗口状态。Rule 5投机解码范围内丢弃冗余的_token_id/_token_ids后缀_id/_ids与_token/_tokens单独使用都没问题但在投机解码代码中组合成_token_id/_token_ids属于冗余——因为投机解码代码只处理词表整数vocab integers_id相比_token不增加任何信息量。其语义差异取决于作用域作用域示例_token_id的含义框架 / 多模态 / tokenizerimage_token_id、pad_token_id、eos_token_id、mask_token_id、bos_token_id某个具名/角色 token 的词表 ID。前缀命名角色_token_id表明它是该角色的整数 ID两部分都有信息量投机解码accepted_token_ids、curr_token_id、out_token_ids冗余。投机解码只处理词表整数_id相对_token无额外信息重命名对照表不要用Dont应该用Do依据accepted_token_idsaccept_tokensRule 1 Rule 3curr_token_idcurrent_token—out_token_idsout_tokens—_resolve_spec_overlap_token_ids_resolve_spec_overlap_tokens—框架级_token_id名称在仓库中依然大量且正确地存在例如 cosmos3.py 配置类中定义的image_token_id: int 19以及 afmoe.py 中的pad_token_id: Optional[int] None—— 这些属于框架/多模态作用域不在重命名范围内。Rule 6单复数规则 —— 非标量 tensor 用复数标量用单数投机解码中的所有 tensor 遵循非标量一律复数标量一律单数任何非标量 tensor[bs]形状、扁平或高维用复数标量kernel 内tl.load的结果、单 int 局部变量用单数。accept_tokens: torch.Tensor # [total_accepted] flat - 复数 accept_indices: torch.Tensor # [bs, num_draft_tokens] - 复数 draft_tokens: torch.Tensor # [bs * num_draft_tokens] flat - 复数 bonus_tokens: torch.Tensor # [bs] - 复数 accept_token tl.load(...) # kernel 迭代中的 int32 标量 - 单数 bonus_token tl.load(...) # kernel 内部的 int32 标量 - 单数这一约定在 Triton kernel 实现中有直接体现dflash_utils.py 的compute_dflash_correct_drafts_and_bonus中num_correct_drafts_ptr以指针形式接收num_correct_drafts torch.empty(...)复数 tensor返回num_correct_drafts, bonus_tokens而 spec_utils.py 的验证循环中current_token draft_tokens[curr]则是单 int 标量的正确写法。范围之外这些名称保持原样以下类别的标识符不受上述规则约束应保持现状PyTorch / 生态名称seq_lens、extend_seq_lens、cu_seqlens_q框架 / 多模态词表image_token_id、pad_token_id、eos_token_id、mask_token_id、hot_token_id、bos_token_id、topk_id请求级状态req.input_ids、req.output_ids、req.origin_input_ids、next_token_idsmodel_runner.sample的输出冻结的 C kwargsaccept_token_numsgl-kernel 侧非 token 的 IDreq_id、gpu_id、layer_id、program_id_len/_lens名称计数场景优先用num_XRule 4但_len/_lens也可接受——尤其 Triton kernel 参数常用_lens/_len与 PyTorch 生态对齐seq_lens、cu_seqlens_q。注意Rule 1 仍然生效accept_length合法accepted_length不合法。快速自查清单在新增、重命名或评审投机解码标识符时对照以下要点动词优先统一accept绝不写accepted目标模型 1 输出一律bonus_token(s)不写verified_id/output_idaccept_*含 bonus、correct_*不含 bonus默认名词用accept_tokens与correct_draftsaccept_rateLeviathan 的 $\alpha$不含 bonus与accept_lengthEAGLE 的 $\tau$含 bonus遵循论文定义是特例数量用num_X、单调累加器用X_ct、比率用X_rate、token 数据无前缀禁止num_X_ct之类混用投机解码范围内不写冗余的_token_id/_token_ids非标量 tensor 复数、标量单数框架级、请求级、冻结 C kwargs 与非 token ID 不在改造范围。这套规范的价值在于把语义编码进命名任何阅读num_correct_drafts与num_accept_tokens的人无需查看上下文即可确认前者是否含 bonus任何看到spec_verify_ct的人都能立即识别它是单调计数器。对于 SGLang 这样投机解码路径横跨 CUDA Graph runner、Triton kernel、调度器指标与 Prometheus 暴露层的项目统一的命名约定是降低跨模块沟通成本、避免指标口径错配例如把不含 bonus 的 draft 数误当总接受数上报的关键工程实践。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SGLang 投机解码（Speculative Decoding）命名规范：accept / correct / bonus 标识符编码指南
SGLang 投机解码Speculative Decoding命名规范accept / correct / bonus 标识符编码指南【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang投机解码是 SGLang 提升推理吞吐的核心路径但散落在python/sglang/srt/speculative/、attention 后端、调度器累加器、IPC 字段与可观测性指标中的标识符历史上同时混用accepted、verified、output_id等名称语义极易混淆。本文基于 SGLang 仓库中面向投机解码开发者的命名规范文档.claude/skills/speculative-naming/SKILL.md完整梳理accept/correct/bonus三组核心动词与名词的语义边界、数量与计数器的编码规则、单复数约定并结合 投机解码目录 与 可观测性指标实现 中的真实源码佐证。读完本文你将掌握一套可在 SGLang 投机解码代码中统一落地、可被代码评审与 Agent 直接执行的命名规范。适用范围哪些代码必须遵守本规范该命名规范面向新增、重命名或评审投机解码相关标识符这一场景覆盖范围包括python/sglang/srt/speculative/目录下的全部投机解码实现EAGLE、dflash、DSpark、ngram、UNO 等与投机解码相关的 attention 后端调度器scheduler中的累加器字段IPC进程间通信字段可观测性指标observability metrics与 CLI 参数。值得注意的是这份规范不是全局改名运动而是限定在投机解码这一特定领域内的语义收敛。仓库中已经存在的框架级名称如 PyTorch 生态的seq_lens、cu_seqlens_qtokenizer 相关的pad_token_id、eos_token_id等不在改写范围内具体清单见后文范围之外章节。Rule 1一律使用动词形式accept丢弃-ed过去分词投机解码代码中涉及接受 draft token的语义时统一使用动词形式accept严禁使用过去分词accepted。核心原因是accepted描述的是已经被接受这一静态状态而投机解码场景中的标识符大多承载的是本次验证动作产生的结果这一动态语义动词形式更贴合数据流的含义。不要用Dont应该用Donum_accepted_tokensnum_accept_tokensaccepted_indicesaccept_indicesaccepted_token_idsaccept_tokens同时参见 Rule 3这条规则在仓库中有充分的实现证据。例如 eagle_info.py 中定义逐请求接受计数字段时明确注释了# Per-req accept counts. num_accept_tokens num_correct_drafts 1字段名采用num_correct_drafts与num_accept_tokens两个动词形式eagle_draft_extend_cuda_graph_runner.py 中的 CUDA Graph 缓冲区同样命名为num_correct_drafts: torch.Tensor与num_accept_tokens: torch.Tensor。Rule 2目标模型额外输出的 1 token 一律叫bonus_token/bonus_tokens投机解码中目标模型target model在验证 draft 之外总是额外输出一个 token即 1 token这个 token 在 SGLang 中的规范命名是bonus token。不要使用verified_id、output_id等名称。不要用Dont应该用Doverified_id/verified_idsbonus_token/bonus_tokensoutput_id/output_ids当指 bonus 时bonus_token/bonus_tokens需要特别强调的是req.output_ids请求的完整输出历史与 bonus 无关保持原名不动。源码中的实际使用非常普遍dflash_info_v2.py 中定义bonus_tokens: torch.Tensordflash_worker_v2.py 用bonus_tokensnext_token_ids构造 draft 输入draft_worker_common.py 中make_draft_input_v2也接收bonus_tokens参数并统一to(dtypetorch.int64)。Rule 3accept含 bonuscorrect不含 bonus —— 语义边界在动词上本规范最重要的一条accept_*与correct_*的语义区分锚定在动词上而不是枚举名词对。两者含义如下动词含义accept_*包含bonus tokencorrect_*仅统计 draft不含 bonus该语义可以自由搭配任何合适的名词tokens、drafts、indices……规范不强制配对但给出了推荐默认名词accept_tokens与correct_drafts—— 因为correct语义上描述的是被验证通过的 draft而accept描述的是最终得到的 token 序列含 bonus。形式含义accept_tokens/accept_indices包含 bonuscorrect_drafts仅 draft不含 bonusnum_accept_tokens数量包含 bonusnum_correct_drafts数量不含 bonus例外accept_rate/accept_length遵循论文惯例有两个指标名由于已深深嵌入投机解码文献与外部暴露字段meta_info、Prometheus 指标其语义由论文定义而非 Rule 3 定义属于特例名称论文术语含 bonus定义accept_rate$\alpha$Leviathan 2023否每个 draft token 的被接受概率 correct_drafts / proposed_draftsaccept_length$\tau$EAGLE是每次验证步骤的平均 token 数 completion_tokens / verify_ct注意内部计数器仍严格遵守 Rule 3 语义——num_correct_drafts不含 bonus、num_accept_tokens含 bonus。这一例外在仓库的可观测性实现中得到印证metrics_reporter.py 中spec_accept_length spec_num_accept_tokens / spec_num_forward_ct含 bonus而spec_accept_rate num_correct_drafts / total_draft_tokens不含 bonus分母为提出的 draft 总数metrics_collector.py 进一步将两者注册为 Prometheus Gaugesglang:spec_accept_lengthaccepted drafts bonus token per forward与sglang:spec_accept_rateaccepted drafts / proposed drafts与文档表格中的论文定义完全一致。Rule 4num_表数量、_ct表计数器、_rate表比率、ID 不加前缀每个形式都有专属标记严禁混用不允许num_X_ct不允许num_accept_rate形式模式含义示例数量Countnum_X某个时间点的快照数量常为 tensor 或标量num_accept_tokens、num_correct_drafts、num_proposed_drafts计数器CounterX_ct随时间单调递增的累加器spec_verify_ct、forward_ct比率Rate / ratioX_rate[0, 1]区间内的比值accept_rateToken / 内容数组无前缀真正的 token 数据本身而非数量accept_tokens、correct_drafts、bonus_token仓库中_ct后缀的真实用法集中在 dflash 与 DSpark 路径中例如 dspark_block_accept_estimator.py 中以forward_ct作为单调递增的步数参数并通过_max_forward_ct、_last_forward_ct等累加维护窗口状态。Rule 5投机解码范围内丢弃冗余的_token_id/_token_ids后缀_id/_ids与_token/_tokens单独使用都没问题但在投机解码代码中组合成_token_id/_token_ids属于冗余——因为投机解码代码只处理词表整数vocab integers_id相比_token不增加任何信息量。其语义差异取决于作用域作用域示例_token_id的含义框架 / 多模态 / tokenizerimage_token_id、pad_token_id、eos_token_id、mask_token_id、bos_token_id某个具名/角色 token 的词表 ID。前缀命名角色_token_id表明它是该角色的整数 ID两部分都有信息量投机解码accepted_token_ids、curr_token_id、out_token_ids冗余。投机解码只处理词表整数_id相对_token无额外信息重命名对照表不要用Dont应该用Do依据accepted_token_idsaccept_tokensRule 1 Rule 3curr_token_idcurrent_token—out_token_idsout_tokens—_resolve_spec_overlap_token_ids_resolve_spec_overlap_tokens—框架级_token_id名称在仓库中依然大量且正确地存在例如 cosmos3.py 配置类中定义的image_token_id: int 19以及 afmoe.py 中的pad_token_id: Optional[int] None—— 这些属于框架/多模态作用域不在重命名范围内。Rule 6单复数规则 —— 非标量 tensor 用复数标量用单数投机解码中的所有 tensor 遵循非标量一律复数标量一律单数任何非标量 tensor[bs]形状、扁平或高维用复数标量kernel 内tl.load的结果、单 int 局部变量用单数。accept_tokens: torch.Tensor # [total_accepted] flat - 复数 accept_indices: torch.Tensor # [bs, num_draft_tokens] - 复数 draft_tokens: torch.Tensor # [bs * num_draft_tokens] flat - 复数 bonus_tokens: torch.Tensor # [bs] - 复数 accept_token tl.load(...) # kernel 迭代中的 int32 标量 - 单数 bonus_token tl.load(...) # kernel 内部的 int32 标量 - 单数这一约定在 Triton kernel 实现中有直接体现dflash_utils.py 的compute_dflash_correct_drafts_and_bonus中num_correct_drafts_ptr以指针形式接收num_correct_drafts torch.empty(...)复数 tensor返回num_correct_drafts, bonus_tokens而 spec_utils.py 的验证循环中current_token draft_tokens[curr]则是单 int 标量的正确写法。范围之外这些名称保持原样以下类别的标识符不受上述规则约束应保持现状PyTorch / 生态名称seq_lens、extend_seq_lens、cu_seqlens_q框架 / 多模态词表image_token_id、pad_token_id、eos_token_id、mask_token_id、hot_token_id、bos_token_id、topk_id请求级状态req.input_ids、req.output_ids、req.origin_input_ids、next_token_idsmodel_runner.sample的输出冻结的 C kwargsaccept_token_numsgl-kernel 侧非 token 的 IDreq_id、gpu_id、layer_id、program_id_len/_lens名称计数场景优先用num_XRule 4但_len/_lens也可接受——尤其 Triton kernel 参数常用_lens/_len与 PyTorch 生态对齐seq_lens、cu_seqlens_q。注意Rule 1 仍然生效accept_length合法accepted_length不合法。快速自查清单在新增、重命名或评审投机解码标识符时对照以下要点动词优先统一accept绝不写accepted目标模型 1 输出一律bonus_token(s)不写verified_id/output_idaccept_*含 bonus、correct_*不含 bonus默认名词用accept_tokens与correct_draftsaccept_rateLeviathan 的 $\alpha$不含 bonus与accept_lengthEAGLE 的 $\tau$含 bonus遵循论文定义是特例数量用num_X、单调累加器用X_ct、比率用X_rate、token 数据无前缀禁止num_X_ct之类混用投机解码范围内不写冗余的_token_id/_token_ids非标量 tensor 复数、标量单数框架级、请求级、冻结 C kwargs 与非 token ID 不在改造范围。这套规范的价值在于把语义编码进命名任何阅读num_correct_drafts与num_accept_tokens的人无需查看上下文即可确认前者是否含 bonus任何看到spec_verify_ct的人都能立即识别它是单调计数器。对于 SGLang 这样投机解码路径横跨 CUDA Graph runner、Triton kernel、调度器指标与 Prometheus 暴露层的项目统一的命名约定是降低跨模块沟通成本、避免指标口径错配例如把不含 bonus 的 draft 数误当总接受数上报的关键工程实践。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考