# PR #34169 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Add skill for the logprob consistency tests
- 合并时间：2026-08-10 01:33
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/34169

---

# 执行摘要

- 一句话：新增 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 的讨论。