L5 讲解：一个能抓住真 bug 的差分测试

① 测试的骨架

关键一步是 先舍入再分发：两边看到的是同一组 fp16 / bf16 数，差异只来自计算，不来自输入表示。忘了这一步，fp16 的 case 会因为“参考用的是没舍入的输入”而大面积误报。

② 容差：每一项都有来源

drillstolerance_for（67–77 行）：

rtol = 2·eps(dtype)            ← 输出舍入到存储 dtype（半个 ulp，留一倍余量）
     + 4·eps32·√n              ← 长度 n 的 fp32 求和（随机游走）
atol = max(eps(dtype) / n, 1e-7)   ← softmax 平均值是 1/n，接近 0 的概率看绝对误差

低精度时第一项占绝对主导；fp32 时第二项才是主角，n 越长越宽。这张表本身就是 PR 里“tolerance rationale”的好素材。

③ 三个 bug，三种结果

• tail 是“结构性”错误：误差是 O(1)，任何容差都能抓住，前提是 n 不是 64 的倍数。edge_sizes 里的 65、97、129 就是为它准备的。
• fp16_acc 是“精度”错误：误差小但系统性，只有紧容差（fp32 那一行）才看得见。fp16 输入的 case 反而能过——容差已经宽到 2e-3。
• no_max_sub 是“数值稳定性”错误：exp(x) 在 fp32 下 x > 88.7 就溢出。N(0, 3) 的输入最大也就 10 左右，永远到不了；必须专门构造大 logits（真实模型里 attention 分数很容易到这个量级）。

④ 输出：一个 Rust 测试骨架

drillsemit_rust_test（108–124 行） 把最小失败（1 × 97、fp32、seed）和容差理由写进注释：

#[test]
fn softmax_matches_reference_float32_1x97() {
    // minimized by l5_differential; input seed = ...
    // tolerance: float32: output rounding 2*eps=2.38e-07 + fp32 sum over n=97: ...
    let mut cx = Graph::new();
    let x = cx.tensor(vec![1, 97], DType::F32);
    let y = x.softmax(1).output();
    ...
    assert_close(&device, &reference, /*rtol=*/..., /*atol=*/...);
}

random_vec_seeded、run_reference、run_cuda、assert_close 是占位名，提交前要换成 crates/luminal_cuda_lite/tests/ 里实际使用的 helper（先读 luminalcublaslt_precision_matches.rs 这类文件学写法）。

⑤ Luminal 里的两个 runtime

Reference 模拟了低精度，所以对拍时可以用比“float64 参考”更紧的容差——这是 Luminal 测试设计里值得学的一点。

⑥ 源码与资料索引

• luminalLuminal softmax · luminalreference/harness.rs · luminalreference/runtime.rs
• luminalcublaslt_tf32.rs · luminalcublaslt_precision_matches.rs
• K3 的 check_close / edge_sizes

⑦ 自测