执行摘要

• 一句话：新增 KL 一致性测试技能文档，沉淀调试与阈值方法论
• 推荐动作：建议负责确定性推理、logprob 一致性测试与相关 CI 的工程师精读，重点是两个独立条件的区分与 MoE 放大效应部分；对一般读者可略过。该文档是团队调试经验的优质沉淀，值得保留，并建议在 kl_test_utils 或确定性推理代码变动时同步更新。

功能与动机

作者在 PR body 中说明：调试高 KL 数值时，大量时间花在可避免的错误上——选错 helper、在统计上不足以支撑结论的样本数下做表征、直接放宽阈值而不定位问题、以及四种会静默失败的 dumper 设置。本 PR 将这些经验一次性写成技能文档，覆盖测试检测的内容（radix-cache 与 conv/mamba 状态复用，而非答案质量）、批次不变性问题的优先级、阈值的选取方法，以及定位分歧到单个算子的 dumper 流程。

实现拆解

1. 新增技能文件 .claude/skills/kl-consistency-test/SKILL.md，在 frontmatter 中声明 name: kl-consistency-test 与用途描述，指定该技能用于编写、校准和调试 sglang 的 KL 一致性测试。
2. 文档先定义测试目标：kl_test_utils 将同一 token 分别作为 prefill 输入 logprob 与 decode 输出 logprob 计分比较，结果反映的是状态一致性（radix-cache 前缀复现、conv/mamba 状态复用、SWA pool 驱逐等），而非答案质量；GSM8K 通过与否与 KL 检查无关。
3. 核心章节区分达到 bit-identity 所需的两个独立条件：全部算子批次不变（batch-invariant）与两条路径计算同一函数；并给出一个测量分离二者的方法——当条件 1 满足时，match 与 decode_cache_hit 恒为 0，而 prefill_cache_hit 在前缀恢复错误时保持非零。文档据此建议先解决条件 1，再解决条件 2。
4. 三个 helper 的缓存参与度被整理为表格：..._match_helper 完全不碰缓存，..._match_prefill_cache_hit_helper 先预热缓存再恢复，..._match_decode_cache_hit_helper 让 decode 侧运行在预热缓存上；单个 helper 的异常即诊断信号。随后给出按 CI 方式运行的默认参数（max_samples=32、max_new_tokens=512），并解释 avg_kl_div 是 k3 估计量、对尾部指数敏感，少量样本下均值不可用于 A/B 比较。
5. 最后按算子类别细化批次不变性要求：token-wise 算子只需固定归约顺序；跨 token 归约（attention、collective）还需固定 extent；跨调用携带状态的算子（conv、SSM）属于条件 2。文档还量化了 MoE 的放大效应（gate GEMM 切换 tiling 产生 1.6e-5 logits 差异，最终 KL 达 0.177），并补充图观测与探针经验。
6. 纯文档变更，无测试、配置或部署配套改动；提交历史显示文档结构经 4 个 commit 逐步完善（先搭框架，再围绕两个条件组织结构，随后补充图观测与探针经验，最后细化每类算子的批次不变性需求）。

关键文件：

• .claude/skills/kl-consistency-test/SKILL.md（模块 技能文档；类别 docs；类型 documentation）: 唯一的变更文件，新增 265 行技能文档，系统化沉淀 KL 一致性测试的调试方法论，是整个 PR 的核心价值所在。

关键符号：未识别

评论区精华

该 PR 没有 review 评论或讨论线程（comments_count=0，review_comments_count=0），由作者单人完成 4 次提交。没有已解决或未解决的设计争议。

• 暂无高价值评论线程

风险与影响

• 风险：无运行时风险，代码零改动。主要风险在于知识文档的时效性：kl_test_utils 的 helper 命名、默认参数（如 max_samples、max_new_tokens）或确定性推理开关的覆盖范围若随代码演进变化，文档可能过时并误导读者。此外，文档关于阈值选取的指导依赖人工判断，若被误读为“可以放宽阈值”，可能掩盖真实回归。建议后续相关代码变更时同步审阅此文档。
• 影响：影响范围限于使用 .claude/skills 的开发者工作流，主要面向维护一致性测试与确定性推理的工程师：统一对 helper 选择、阈值校准、批次不变性与状态复用问题的认知，减少高 KL 调试中的试错成本。对运行时性能、模型输出、API 行为无任何影响。
• 风险标记：文档过时风险, 阈值指导依赖人工判断

关联脉络

• PR #34168 Add deterministic logprob-consistency test for inkling-small nvfp4: 新增确定性 logprob 一致性测试，与本 PR 的技能文档直接配套，文档为该类测试提供调试方法。
• PR #33423 Deterministic gumbel sampling: clamp u=1 so masked tokens can't be sampled: 确定性采样与一致性修复，与文档中 batch-invariance 和确定性推理章节相关。
• PR #34043 [srt] Fix sconv state memory corruption on specdec: 状态复用不一致是文档中条件 2 的典型案例，该修复确保缓存复用后位级一致。
• PR #34159 Fix deterministic inference all-reduce for tp>1: 确定性推理下固定 NCCL 通道数，对应文档中固定归约顺序与跨 token 归约 shape 的讨论。