[issue4] AllReduce/Reduce-Scatter bitwise 复现性诊断工具

[shsaihdsaiudh]

关联 Issue

#4

提交内容

src/code/issue4/reproducibility_diagnoser.py：集合通信 bitwise 可复现性诊断工具。对完全相同的输入张量重复执行 AllReduce 或 Reduce-Scatter，按 run / call / rank 三级粒度记录逐位摘要并互相比对。

发现差异时报告给出：

• 首次出现位级差异的调用点（run / call / rank）与该次调用的耗时；
• 首个差异元素的 flat index、差异元素总数；
• 最大绝对误差与最大相对误差；
• 差异随后续 run/call 的演化记录（供判断是一次性抖动还是持续放大）；
• 环境快照：Python / PyTorch / CUDA runtime / NCCL 版本、GPU 型号，以及影响 NCCL 选择的环境变量取值。

设计上的两个要点：

1. 每次运行内部对相同输入做多轮对照，避免把输入侧随机性误判成通信差异；
2. --env 可在进程内固定 NCCL_ALGO / NCCL_PROTO / NCCL_NVLS_ENABLE 等，从而逐项定位是哪个算法/协议配置引入了不确定性。

验证

不需要 GPU 的自检（演示 FP32 归约顺序为何改变结果位模式）：

python src/code/issue4/reproducibility_diagnoser.py --self-test --output reports/order-demo.json
python -m pytest src/code/issue4/test_reproducibility_diagnoser.py -q   # 3 passed

单卡真实 NCCL 冒烟测试（本机 RTX 5060 Ti，PyTorch 2.13.0+cu130，NCCL 2.29.7）：

torchrun --standalone --nproc-per-node=1 src/code/issue4/reproducibility_diagnoser.py \
  --runs 3 --calls 20 --output reports/single-gpu.json

AllReduce 与 Reduce-Scatter 两种原语均跑通，结果见 results/single_gpu_all_reduce.json、results/single_gpu_reduce_scatter.json。

定位链路验证——在 run 1 / call 3 / rank 0 注入 1 ULP：

torchrun --standalone --nproc-per-node=1 src/code/issue4/reproducibility_diagnoser.py \
  --runs 2 --calls 8 --inject-difference 1:3:0 --expect-difference \
  --output reports/injection.json

工具准确定位到 run=1, call=3, rank=0，mismatched_elements=1，max_rel_diff≈9.44e-08（FP32 1 ULP 量级），见 results/single_gpu_injection.json。

当前边界

本 PR 提交的是验收要求 1 的诊断工具本身，并已在真实 NCCL 上验证采集与定位链路可用。

--inject-difference 是工具自检手段，不是 NCCL 不确定性的证据，报告与 README 中均已标注。

验收要求 2（给出至少一个可复现的真实 non-determinism 案例，并定位到具体算法/协议配置）需要 ≥2 GPU：world_size=1 时不存在跨 rank 归约顺序变化，原理上无法暴露该类问题，报告的 limitations 字段会显式声明这一点。提交者当前为单卡环境。多卡验收命令已写入 README-2026.md，在多卡机器上可直接执行。