SuperAPI AI 工具集

speculative-naming

编程与开发

查看项目

更新于 10-16 05:40

技能介绍

本技能用于规范 SGLang 推测解码(Speculative Decoding)相关代码中的标识符命名,适用于新增、重命名或审查标识符的场景,覆盖范围包括 python/sglang/srt/speculative/ 目录下的代码、相关 attention backend、scheduler 累加器、IPC 字段、可观测性指标以及 CLI 参数。

一、动词形式,去掉 -ed 统一使用动词形式 accept,不使用过去分词形式 accepted。例如 num_accepted_tokens 应改为 num_accept_tokens,accepted_indices 应改为 accept_indices,accepted_token_ids 应改为 accept_tokens(同时参见规则三)。

二、额外 token 使用 bonus_token / bonus_tokens 目标模型在验证草稿之外始终额外产出的「+1」token 称为 bonus token,按规则七使用 bonus_token / bonus_tokens。例如 verified_id / verified_ids 应改为 bonus_token / bonus_tokens;在指代 bonus 时,output_id / output_ids 应改为 bonus_token / bonus_tokens。req.output_ids 表示请求的完整输出历史,与 bonus 无关,保持原样。

三、accept 包含 bonus,correct 不包含 bonus 语义区分体现在动词而非名词上。accept_* 表示包含 bonus token,correct_* 表示仅草稿、不含 bonus。可与合适的名词搭配(tokens、drafts、indices 等),没有强制搭配要求,但推荐的默认名词为 accept_tokens 和 correct_drafts:correct 在语义上描述草稿(被验证的内容),accept 描述结果 token 序列(含 bonus)。例如 accept_tokens / accept_indices 含 bonus,correct_drafts 不含 bonus,num_accept_tokens 为含 bonus 的计数,num_correct_drafts 为不含 bonus 的计数。

例外:accept_rate / accept_length 沿用论文约定。这两个指标名称在推测解码文献以及对外字段(meta_info、Prometheus)中已根深蒂固,其语义由论文定义,而非规则三定义。accept_rate 对应论文中的 α(Leviathan 2023),不含 bonus,定义为每个草稿 token 的接受概率,即 correct_drafts / proposed_drafts;accept_length 对应论文中的 τ(EAGLE),含 bonus,定义为每个验证步骤的平均 token 数,即 completion_tokens / verify_ct。内部计数器仍遵循规则三的严格语义:num_correct_drafts(不含 bonus)、num_accept_tokens(含 bonus)。

四、num_ 表示计数,_ct 表示计数器,_rate 表示比率,ID 无前缀 每种形式有各自的标记,不可混用(不使用 num_X_ct,不使用 num_accept_rate)。计数使用 num_X,表示某一时间点的快照数量(通常是张量或标量),如 num_accept_tokens、num_correct_drafts、num_proposed_drafts。计数器使用 X_ct,表示随时间单调递增的累加器,如 spec_verify_ct、forward_ct。比率 / 比例使用 X_rate,表示 [0, 1] 区间内的小数值,如 accept_rate。Tokens / 内容数组不加前缀,表示实际的 token 数据而非计数,如 accept_tokens、correct_drafts、bonus_token。

五、在 spec 范围内去掉冗余的 _token_id / _token_ids 后缀 _id / _ids 与 _token / _tokens 都可以使用,但不要组合使用——在推测解码内部 _token_id / _token_ids 是冗余的,因为 spec 代码只处理词表整数。语义随作用域不同:在框架 / 多模态 / tokenizer 作用域中,image_token_id、pad_token_id、eos_token_id、mask_token_id、bos_token_id 等,_token_id 表示某个特定命名 / 角色 token 的词表 ID,前缀命名角色,_token_id 表明该角色的整数 ID,两部分都携带信息;在推测解码作用域中,accepted_token_ids、curr_token_id、out_token_ids 是冗余的,spec 只处理词表整数,_id 在 _token 之外没有增加任何信息。重命名示例:accepted_token_ids 改为 accept_tokens(规则一 + 三),curr_token_id 改为 current_token,out_token_ids 改为 out_tokens,_resolve_spec_overlap_token_ids 改为 _resolve_spec_overlap_tokens。

六、单数与复数 任何非标量张量(形状为 [bs]、扁平或多维)用复数;仅标量(kernel tl.load 结果、单个 int 局部变量)用单数。适用于所有推测解码张量(tokens、indices 等)。示例:accept_tokens: torch.Tensor([total_accepted] 扁平,复数),accept_indices: torch.Tensor([bs, num_draft_tokens],复数),draft_tokens: torch.Tensor([bs * num_draft_tokens] 扁平,复数),bonus_tokens: torch.Tensor([bs],复数),accept_token = tl.load(...)(kernel 迭代中的 int32 标量,单数),bonus_token = tl.load(...)(kernel 内的 int32 标量,单数)。

七、不适用范围(这些名称保持原样) 这些规则适用于推测解码特有的标识符,既有的或框架级的名称予以保留。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_ids(model_runner.sample 输出)。冻结的 C++ kwargs:accept_token_num(sgl-kernel)。非 token ID:req_id、gpu_id、layer_id、program_id。_len / _lens 名称:计数优先使用 num_X(规则四),但 _len / _lens 名称可以接受,尤其是 Triton kernel 参数常使用 _lens / _len 以与 PyTorch 生态(seq_lens、cu_seqlens_q)对齐;规则一仍要求去掉 -ed 形式(accept_length 可以,accepted_length 不可以)。

以上为该技能提供的全部命名约定与适用范围说明,未提供的信息暂未提供。