numerics_debugging

用途

数值调试工具用于在两次本应一致的 TorchTitan 运行之间捕获并比对逐算子激活值，定位数值分歧。典型比对场景包括：eager 与 aot_fx_trace、启用 FSDP 与不启用 FSDP、某次修改前与修改后。两次运行的结果应当按位一致，或在 float32 归约顺序噪声范围内一致。

主要能力

逐算子激活捕获：在指定训练步通过 torch.utils._debug_mode.DebugMode 捕获激活值，由 Profiler 中的 ActivationCaptureProfiler 驱动，输出到 {dump_folder}/numerics/rank_{N}_activations.log。
HTML 差异报告：比对两份日志，每行配对来自两次运行的一个算子；当某项统计量出现分歧时，对应单元格变红；“Match method”标签显示四种匹配流程（override / exact key / fuzzy key / stats）中是哪一种完成了配对。
仅用标准库：compare_numerics.py 不导入 torch。

使用方式

两个脚本位于 scripts/ 目录，刻意放在 torchtitan 包之外，核心代码与 graph_trainer 均不引用它们。使用前需修改 torchtitan 以将捕获接入 Profiler（若捕获 traced 路径还需接入 graph_trainer），完成后还原修改。由于 .claude 不是合法 Python 包名，activation_tracer 通过把 scripts/ 加入 sys.path 导入，而非点号模块路径。

修改 torchtitan 接入捕获（补丁见 references/patching.md）。
为两次运行定义捕获配方，从被测配置派生并设置捕获控制项，示例：

def numerics_run_a() -> Trainer.Config:
    config = base_config_a()
    config.training.steps = 2
    config.profiler.dump_numerics = True
    config.profiler.profile_freq = 2
    config.debug.seed = 42
    config.debug.deterministic = True
    config.training.mixed_precision_param = "float32"
    return config

每个配方各捕获一次：

MODULE=my_numerics_configs CONFIG=numerics_run_a ./run_train.sh \
    --output-dir ./outputs/run_A

对 numerics_run_b 与 ./outputs/run_B 重复。捕获发生在 profile_freq 步；profile_freq=2 且 training.steps=2 时，第 1 步预热，第 2 步为快照。捕获仅在捕获步增加约 10–40% 内存（统计量以 float64 内联计算，不保留张量）。

比对两份日志：

python .claude/skills/numerics_debugging/scripts/compare_numerics.py \
    outputs/run_A/numerics/rank_0_activations.log \
    outputs/run_B/numerics/rank_0_activations.log \
    --name1 run_A --name2 run_B \
    -o diff.html

打开 diff.html 查看结果。

适用场景

用于排查本应一致的两条执行路径（eager 与 traced、FSDP 与无 FSDP、修改前后）之间的数值分歧。

限制与注意事项

被比对的两个运行必须使用相同 dtype 与种子。匹配器以 shape + float64 L1 范数为键；精度变化（bf16 与 fp32）会使每一行都分歧，匹配器退化为仅按结构统计的流程。
脚本位于 torchtitan 包之外，需手动修改 torchtitan 接入并在使用后还原，这些修改不应留在 main 上。
使用前需按 references/patching.md 完成接入修改。
排除算子、numel/dtype 过滤、哈希函数、手动覆盖文件格式与 HTML 外观均可调整，详见 references/customization.md；该文件还记录了常见的 eager 与 traced 不匹配模式（如 AC 重算导致的 FQN 漂移、逐层计数器偏移、集合通信重命名）及其覆盖表达方式。

收费与平台

资料未提供相关信息。