用途:AscendC 算子精度测试失败(allclose 不通过、结果偏差、输出全零或 NaN 等)时,用于调试并定位根因。
主要能力:按由浅入深的五阶段流程排查——Phase 1 误差分析(收集 shape、dtype、MaxAbsErr/MeanAbsErr/CosineSim,可基于 scripts/debug_precision_template.py 创建 csrc/ops/<op_name>/test/debug_<op_name>_precision.py 并运行,分析误差统计、首个错误元素、错误分布周期性与特殊值);Phase 2 代码审查(读取 op_host/<op_name>.cpp、op_kernel/<op_name>.cpp 和 design.md,按基本正确性、搬运对齐、Tiling 多核、API 陷阱、边界情况五层清单排查);Phase 3 实验隔离(block_dim 改 1、PipeBarrier<PIPE_ALL> 同步隔离、固定与随机输入对比、缩小 shape 二分,每次只改一个变量);Phase 4 插桩定位(用 AscendC::printf 与 AscendC::DumpTensor,仅 0 核打印、同步后读 LocalTensor、FP16 先转 float);Phase 5 修复验证(按根因套用修复模式,移除插桩,重编译并跑原失败用例与完整精度测试)。
适用场景:FP16 挂 FP32 过、输出全零或 NaN、周期= tileLength 的错误、仅尾部元素错、block_dim=1 过而多核挂、多次运行结果不同等精度异常。定位到疑似根因后可加载对应案例文件(如 examples/fp16-no-upcast.md 等),不一次性加载全部。
限制:PIPE_ALL 仅用于实验隔离,不可作为最终方案;kernel 中禁止循环打印全量 tensor,多核需加 GetBlockIdx() == 0;修复后必须移除调试代码并跑完整精度测试;最多 3 轮未定位需报告用户,禁止不分析误差分布直接改代码。输出需包含问题摘要、根因分析、修复内容、验证结果与至少 2 条关键经验。