F2 精度调试：结果不对怎么定位到算子

编制：观澜｜日期：2026-10-06｜级别：T2 标准级 层级：F 层 · 场景实战（F 层第 2 课；紧接 F1《模型迁移》）素材来源：昇腾官方 MindStudio 文档《精度调试 msProbe》（《PyTorch 场景快速入门》《PyTorch 场景精度数据采集》《PyTorch 场景精度比对》《PyTorch 场景的分级可视化构图比对》《整网首个溢出节点分析》《msProbe 工具安装指南》《配置文件介绍》）　　　　　＋官方《精度调试流程》（模型迁移 · 精度调试）本课定位：F1 解决的是「脚本搬过来能不能跑动」，本课解决的是「跑动了，但结果和参考平台对不上」。　　　　　这是 F1 的下一环：迁移之后必然遇到的第一件事。

第一段章前定位

F1 一课把脚本从 GPU / CPU 搬到了昇腾上，判据是「开始打印迭代日志」「能成功保存权重」。

但 F1 结尾留了一个尾巴：

「迭代日志在打印」只说明跑得动；「结果和参考平台对得上」才说明跑对了。

这两件事不是一回事。 本课处理后面那件。

精度问题最阴的地方在于——它不像 F1 的报错那样会「喊」出来。官方《精度调试流程》原文把这件事描述得非常准：

用户迁移后的模型在 AI 处理器（简称 NPU）上训练，功能已调通，但可能会遇到精度不达标或者收敛效果差的问题，用户模型在 AI 处理器上执行时，包括但不限于： - loss 曲线与参考基准差异不符合预期 - 验证准确度与参考基准差异不符合预期

这些精度问题由于具有以下特征导致定位困难： - 训练正常结束 - 日志无任何异常 - 仅在与参考基准对比时才发现结果不符合预期

三句话连起来读就是本课的题眼：没有报错、没有崩溃、训练还「正常」跑完了—— 你手上唯一的问题描述是「结果不对」，而它不告诉你是哪一步不对。

本课的任务，就是把「结果不对」这四个字，一步步缩到「是第 N 层的第几个算子不对」。

本课不教什么（先说清，免得跑偏）：

不教模型迁移——那是 F1，本课默认你已经有一份能在昇腾上跑起来的脚本；
不教性能调优（Profiling 采集与分析）——那是 F4，本课只关心「数值对不对」，不关心「快不快」（虽然 msProbe 也能给出部分性能数字，但本课不展开）；
不教多卡与分布式——那是 F3；本课的命令在多卡场景下能用，但多卡的通信定位只讲到「怎么把结果读出来」为止。

第二段学习目标

学完这一课，你应该能：

✅ 说出精度问题为什么比报错更难定位——三条特征（训练正常结束 / 日志无异常 / 只有对比才发现）
✅ 说出官方给的精度调试六步思路，并知道整网数据比对处在哪一步
✅ 用 msProbe 在昇腾侧和参考平台侧各采集一份精度数据（dump），并知道 level 和 task 两个参数各选什么
✅ 跑出精度比对结果，会读 Result 列和 Err_Message 列，并知道 Cosine > 0.99、MaxAbsErr < 0.001 这两条官方阈值
✅ 用首差异算子节点识别（-da）把问题缩到第一个出错的算子，再用堆栈信息回溯到训练代码
✅ 遇到 inf / nan 时，知道用溢出检测找「第一个溢出的节点」，而不是盯着后面一大堆被污染的结果看
✅ 知道官方没给的那几件事（通用「精度不准算子清单」、整网通过的统一阈值）——不编、不猜，现场自己测

第三段全景：精度问题怎么从「结果不对」缩到「一个算子」

3.1 先记一个判断：先定「两侧」，再谈「哪一层」

F1 的迁移是「换执行设备」；本课的精度比对是「同一件事，两个平台各算一遍，逐算子对照」。

所以动手前必须先想清楚一件事：

我的「参考基准」（官方叫 Bench / golden）是哪一侧？

官方《PyTorch 场景精度比对》把两个参数定得很死：

-tp（target_path）= 待调试侧 = 昇腾（NPU）侧的数据；
-gp（golden_path）= 标杆侧 = CPU 或 GPU 侧的数据。

这一步不能省：-tp 和 -gp 传反了，工具一样能跑出结果，但你看到的「差异」是反向的—— 它会把你引到完全相反的方向上去。

3.2 官方给的六步思路（本课的核心地图）

官方《精度调试流程》把精度调试排成了六步，顺序本身就是难点所在：

步	官方名称	干什么	本课覆盖
①	调优前检查	检查迁移前的脚本（排除参考基准本身的问题）；检查迁移后的脚本（排除迁移引入的问题）	第四段（第 0 步）
②	精度分析工具部署	在 NPU 训练环境部署精度分析工具	第五段
③	浮点异常检测	Loss Scale 下降次数多或直接降到 1 → 分析溢出数据	第六段（溢出检测）
④	融合异常检测	系统会按内置融合规则融合算子，可能漏考虑场景 → 尝试关融合，定界是不是融合引起的	第七段（排查表）
⑤	整网数据比对	采集各算子运算结果（dump），与业界标准算子结果做偏差对比，快速定位到具体算子的精度问题	第六段（本课主线）
⑥	随机错误检测	相同输入给出不同输出 → 跑两次训练分别 dump，比对找出导致随机的算子层	第七段（排查表）

⭐ 第 ⑤ 步「整网数据比对」就是本课的主线，官方原话把它要干的事说得没有一点含糊：「通过采集训练过程中各算子的运算结果（即 dump 数据），然后和业界标准算子（如 TensorFlow）运算结果进行数据偏差对比，快速定位到具体算子的精度问题。」

注意第 ① 步排在最前——这和 F1「迁移前必须先在 GPU/CPU 上跑通」是同一条纪律的延伸： 在怀疑算子之前，先排除「你的参考基准本身就是错的」和「迁移引入了问题」这两种可能。 跳过它，你会花一整天去追一个根本不存在的算子问题。

3.3 本课的路线（一张图）

① 先在参考平台（GPU/CPU）跑通、采集标杆数据    ← 基准，不能省
② 在昇腾（NPU）上跑同一模型，采集待调试数据
③ 两侧逐算子比对（msprobe compare）→ 得到可疑算子清单
④ 缩到「第一个出错的算子」（-da 首差异算子节点）
⑤ 回溯：用堆栈信息把算子接回训练代码
⑥ 收口：不是「比出一堆差异」就算完，而是「定位到一个算子并解释它」

第 ① 步的位置是本课和 F1 呼应最紧的一处： F1 说「迁移前必须先在参考平台跑通」；本课接着补一句—— 光「跑通」还不够，还要把那次运行的数据「留下来」，因为它就是你后面比对用的标杆。

3.4 msProbe 是什么（官方定义）

msProbe（MindStudio Probe）是 AI 模型精度调试工具。 可以定位模型训练或推理中的精度问题。

官方《快速入门》把它要解决的场景列得很直白：「帮助您掌握数值溢出、Loss 异常、模型不收敛等典型精度问题的排查方法与分析思路。」

它提供的两件核心能力，正好对上本课路线的 ② 和 ③：

能力	官方子命令 / 接口	产出
数据采集（dump）	`PrecisionDebugger` 接口	每个算子的输入输出统计量 / 真实数据 / 校验值
精度比对（compare）	`msprobe compare`	`compare_result_*.csv`，逐算子给出比对结论

采集有两个关键旋钮（官方《PyTorch 场景精度数据采集》原文）：

旋钮	取值	说明
`level`	`L0`（模块级）/ `L1`（API 级，默认）/ `L2`（kernel 级）/ `mix`（L0+L1）	决定采集多细
`task`	`statistics`（仅统计量）/ `tensor`（统计量＋全量真实数据）/ `nan_check`（NaN/Inf 检测）/ `structure` / `acc_check`	决定采什么

⭐ 一句话记住这两个旋钮： level 管「采到哪一层」（模块 / 算子 / kernel），task 管「采多厚」（只采统计量 / 连真实张量一起采）。 初查用 level=mix + task=statistics（省磁盘、够定位）；要精确定位再上 task=tensor。

3.5 比对结果里，什么算「不对」

很多人的卡点在这里：比完了，一屏差异，哪个才算「问题」？

官方给了明确的判据——比对结果分三类，优先级 error > warning > pass：

结论	官方含义
`error`	明确异常（如 NaN/Inf、dtype/shape 不一致、CRC-32 不一致、梯度计算不一致等）
`warning`	可疑（如 output 的 norm 相对误差是 input 的 10 倍）
`pass`	通过

官方还给了两个「可接受阈值」（用于人工判断指标）：

Cosine（余弦相似度）：实际可接受阈值为大于 0.99——越接近 1 越相似；
MaxAbsErr（最大绝对误差）：实际可接受阈值为小于 0.001——越接近 0 误差越小。

⚠️ 阈值不等于整网通过标准：官方说的是单个指标的「实际可接受阈值」， 官方没有给出「整网比对通过」的统一标准（不同模型、不同算子可接受的误差本就不一样）。 这一处本课不替你定死——按官方口径，判定的落点始终是 Result 列＋人工结合实际情况判断。

第四段【如果我来做】——从「结果不对」到「定位到一个算子」

这一节是本课的核心。 前三段讲的是「精度问题为什么难、官方给了哪六步」，这一节讲的是：如果现在把这件事交给我，我从哪里开始、按什么顺序做、每一步凭什么判断。

4.0 先亮结论：我会按这个顺序做

为什么顺序不能反：

一上来就 dump + 比对，结果是一屏差异，而你不知道这屏差异里哪些是「真问题」—— 因为官方明说：「NPU 与 CPU 或 GPU 的计算结果误差可能会随着模型的执行不断累积」，你看到的差异里，绝大多数是误差累积，不是某个算子算错了；
真正有用的是「第一个出错的算子」——所以正确做法是用 -da 直接找首差异节点，而不是从头到尾一条条比对。

我会按这个顺序做（顺序 = 我「手伸进去」的顺序，不是教科书的顺序）：

① 先排除两类假问题：确认参考基准本身没问题、确认不是迁移引入的（官方第 ① 步「调优前检查」） ② 定两侧：确定谁是 -tp（昇腾侧）、谁是 -gp（参考平台侧），绝不能传反 ③ 装工具并自检：装 msProbe，跑一条环境检查命令，先确认工具本身是好的 ④ 采昇腾侧数据：写 config.json → 训练脚本里挂 PrecisionDebugger → 跑 → 看 dump 落盘 ⑤ 采参考平台侧数据：同样一套采集配置，在 GPU/CPU 上跑一遍 —— 这是标杆 ⑥ 粗查（整网比对）：msprobe compare 出结果，只看 Result 列和 Err_Message 列 ⑦ 精查（首差异算子）：加 -da 拿到首个出错算子节点；是 NaN/Inf 就上 overflow_check 找首溢出节点 ⑧ 回溯并收口：用 NPU_Stack_Info / stack.json 把算子接回训练代码；能说清「是哪个算子、为什么错」，才算完

下面把中间的每一步展开。

4.1 第 0 步：先把两类「假问题」排掉（不装任何工具）

目的：在怀疑算子之前，先把不可能是算子问题的两种情况排掉。

官方《精度调试流程》第 ① 步「调优前检查」原文要点：

检查迁移前的脚本，排除参考基准的问题。

检查迁移后的脚本，排除模型迁移时存在的问题。

我会具体查这三件：

参考基准是不是可信的：GPU/CPU 侧那次运行本身，loss/准确度是不是正常的？ —— 如果参考平台自己都不对，你后面比的「标杆」是错的；
是不是数据/超参变了：两次运行是不是同一份数据、同一个 batch 顺序、同一个随机种子？ —— 官方在采集接口里专门给了 seed_all（用于固定网络中的随机性和开启确定性计算），就是为了消掉这一类差异；
是不是迁移引入的：如果 F1 迁移时动过代码（比如自动迁移替换了接口）， 先确认那些替换没有改变语义 —— 这一条回 F1 对照。

为什么先做这一步：这三件事都是「不查清就会把你带偏一整天」的不变量。它们的共同点是——查起来只要几分钟，但一旦是它们的问题，你追算子能追一整天。

4.2 第 1 步：定两侧（谁是靶子、谁是标杆）

决策依据（就是第三段 3.1 那条，这里落成动作）：

参数	官方定义	我这次填什么
`-tp`	NPU 环境下的 `dump.json` 路径（单卡）或 dump 目录（多卡）	昇腾侧那份 dump
`-gp`	CPU、GPU 或 NPU 环境下的 `dump.json` 路径（单卡）或 dump 目录（多卡）	参考平台侧那份 dump

⭐ 一个我每次都会念一遍的自检：-tp 是「我要查的」那边（昇腾），-gp 是「我信的」那边（参考平台）。 ——记成「target = 我要修的」最不容易反。

4.3 第 2 步：装工具 + 立刻自检

工具是 mindstudio-probe 这个 Python 包，装完先跑自检命令（第五段给命令）。

为什么装完立刻自检：msProbe 的采集是挂进训练脚本里的。如果工具本身没装好，你会把「工具没装好」误判成「模型精度有问题」—— 先证明工具是好的，后面看到的差异才归因得到模型身上。

4.4 第 3、4 步：采两侧数据（同一套配置，各跑一遍）

采集的关键不是命令，是「两侧配置要一致」：

两侧都写 config.json，level 和 task 用同一套；
采集接口都加 seed_all() 固定随机性；
两侧 dump 到不同目录（官方在多卡/训推场景专门提示过「需保证两次 dump 的路径不同，否则会导致 dump 数据覆盖」）。

具体命令、config.json 写法、脚本怎么挂接口——全在第五段。

4.5 第 5 步：粗查——先只看两列

比对命令跑完会产出 compare_result_{timestamp}.csv。

官方给的查看顺序，我原样照做（《快速入门》原文）：

筛选异常：根据 Result 列筛选未通过的 API；

排查错误：查看 Err_Message，判断是否存在 API 未匹配、数据类型或形状不一致等问题；

比对统计：针对已匹配但精度差异较大的 API，对比 Max、Min、Mean、L2 Norm 等统计量及相对误差；

回溯代码：结合 NPU_Stack_Info 或 NPU 侧 stack.json，定位可疑 API 对应的训练代码。

⭐ 第 1、2 步先做，第 3 步后做——这是很多人做反的地方。 Result 列是工具已经替你判好的结论（pass/warning/error），先看它成本最低；一上来就对着几百行统计量手算误差，是把工具已经做完的事重做一遍。

4.6 第 6 步：精查——把「一屏差异」缩成「一个算子」

这是本课最值钱的一步。 官方给了两个专门的子命令：

找「第一个出错的算子」 → msprobe compare 加 -da（首差异算子节点识别），产出 diff_analyze_{timestamp}.json，里面直接给你算子节点名、算子类型、算子位置；
遇到 inf / nan，找「第一个溢出的节点」 → msprobe overflow_check -i ... -o ...，产出 anomaly_analyze_{timestamp}.json。

为什么必须找「第一个」：官方在《整网首个溢出节点分析》里把原因写透了：

在分析 inf、nan 的场景下，前面出现的异常会传播到同 rank 后续的节点，并通过通信算子传播到其他 rank 的后续节点中，因此如何分析首个 nan 出现的节点位置尤为重要。

换句话说：一个算子溢出，后面几十个算子都会跟着算错。你如果不找「第一个」，就会看到几十个 error，然后在几十个里瞎挑—— 找第一个，是为了让其余几十个都不用看。

4.7 第 7 步：收口——什么才算「做完了」

不是「比出一堆差异」就算完。 我会按这个标准收口：

✅ 定位到一个具体的算子（有名字、有类型、有位置）；
✅ 能回溯到训练代码（用 NPU_Stack_Info / stack.json 指出是脚本里的哪一处）；
✅ 能解释这个差异（是 dtype 不一致？shape 不一致？还是数值误差累积？）；
✅ 官方没给答案的地方（比如「这个算子差异算不算超标」），留一句「这里要现场判断」，不硬编一个结论。

4.8 这一节的方法论（它比具体命令更耐用）

① 先排假问题：确认参考基准可信、不是迁移引入的 —— 把「不可返工的事」在这里查出来 ② 定两侧：谁是 target（昇腾）、谁是 golden（参考平台），传反了全盘皆错 ③ 先证明工具是好的，再相信它报出来的差异 ④ 两侧用同一套采集配置：level / task 一致、都固定随机种子、dump 到不同目录 ⑤ 先看工具判好的结论（Result / Err_Message），再看原始统计量 ⑥ 专找「第一个」：首差异算子（-da）、首溢出节点（overflow_check）—— 后面的都不用看 ⑦ 收口到一个算子 + 一句解释，而不是「一屏差异」 ⑧ 诚实：官方没给通用「不准算子清单」、没给整网通过标准 —— 明说「这里要自己测」，不编

第 ⑥ 条和第 ⑧ 条是本课最容易被跳过的两条：第 ⑥ 条——很多人卡在「差异太多不知道看哪个」，其实一个 -da 就把它缩成一行；第 ⑧ 条——定位完被问「这个差异正常吗」，官方没给整网标准就如实说「要按模型判断」，不编一个阈值。

第五段采集：把 msProbe 装好，两侧各采一份数据

5.1 前置：先有 CANN，再装 msProbe

官方《msProbe 工具安装指南》第一句就把前置写死了：

使用本工具前需要安装 CANN，具体操作请参见《CANN 快速安装》安装昇腾 NPU 驱动和 CANN 软件（包含 Toolkit 和 ops 包），并配置环境变量。

也就是说：驱动 + CANN（Toolkit + ops）是前提，没装好先回 A1 / B1 / B2。

5.2 装 msProbe（官方三种方式）

方式一：在线安装（最简，先试它）

命令　pip install mindstudio-probe==26.1.0.post1

含义：从 Python 包源在线安装 msProbe（MindStudio Probe）精度调试工具拆解：pip install（Python 包安装）＋ mindstudio-probe（包名，注意是连字符）＋ ==26.1.0.post1（锁定版本——官方示例就是钉死这个版本）用法：在 NPU 训练环境里执行；官方明确「如需单独升级本工具或使用最新版本」用这条路期望：打印 Successfully installed mindstudio-probe-26.1.0.post1 不过会怎样：报连不上源 → 换内网源；或改走方式二离线安装； ⚠️ 官方注明：在线安装包「不包含 aclgraph_dump、nan_check 和 xor_checksum 功能」——要用这三个功能必须走方式三源码安装

方式二：离线安装（无公网时用）

命令　sha256sum {name}.whl

含义：校验从官方 Release 下载的 whl 安装包是否完整、是否被篡改拆解：{name}（whl 文件名，照你实际下载到的文件名替换，不要照抄大括号）＋ .whl（Python 安装包扩展名）用法：先到 msProbe Release 页（https://gitcode.com/Ascend/msprobe/releases）下载 whl 软件包和对应数字签名文件（.sha256）；在 whl 所在目录执行本命令，再把打印的 {sha256} 与 .sha256 文件里的值逐位比对 期望：打印一行 {sha256} {name}.whl，与签名文件里的校验码一致 不过会怎样：两个校验码不一致 → 官方原话「请不要使用该软件包」，重新下载或提工单；校验通过后执行 pip install ./mindstudio_probe-{version}-py3-none-any.whl 安装（覆盖安装加 --force-reinstall）

⚠️ 名称别写错：下载页的文件名是 mindstudio_probe-...（下划线），pip 包名是 mindstudio-probe（连字符）——两者官方都用，不要以为有一个写错了。

方式三：源码安装（要用 nan_check 等可选功能时才走）

命令　python3 build.py -e include-mod=nan_check -e no-check=true

含义：在源码目录里编译出带 nan_check 模块的 whl 包（在线/离线包不含该功能）拆解：-e / --extra（额外构建选项，KEY=VALUE 格式）＋ include-mod=nan_check（指定可选模块；溢出检测 nan_check 要走这条）＋ no-check=true（跳过第三方依赖下载时的证书校验）用法：官方完整步骤是 git clone https://gitcode.com/Ascend/msprobe.git -b 26.1.0 → cd msprobe → pip install uv → 执行本命令 → cd ./artifacts → pip install ./mindstudio_probe*.whl；多个模块用逗号连（如 -e include-mod=tb_graph_ascend,trend_analyzer）期望：./artifacts 下生成 whl，安装后打印 Successfully installed mindstudio-probe-26.1.0.post1 不过会怎样：报缺第三方依赖（GCC / CMake 等）→ 按官方「指定 atb_probe 模块时」的依赖清单补齐； ⚠️ 官方提示：这样编出的 whl「仅限编译时使用的 Python 版本和处理器架构可用」

📌 分级可视化插件：要用后面的「构图比对」命令，编译时要带 --include-mod tb_graph_ascend；官方另提示：若环境已装旧版 tb_graph_ascend，先 pip uninstall tb_graph_ascend 卸载以免冲突报错。

5.3 装完先自检（官方环境检查命令）

命令　python3 -c 'import torch, torch_npu; assert torch.npu.is_available(), "NPU is unavailable"; import msprobe; print("PyTorch:", torch.__version__)' && msprobe --help >/dev/null && tensorboard --help >/dev/null && echo -e "\e[32m[PASS] NPU environment, msProbe and TensorBoard check passed.\e[0m"

含义：一条命令同时验四件事——NPU 可用 / msProbe 装好 / TensorBoard 装好（构图比对要看图，离不开它）拆解：import torch, torch_npu（框架 + 昇腾插件，见 C1）→ assert torch.npu.is_available()（卡认不认得）→ import msprobe（工具装没装）→ msprobe --help / tensorboard --help（两个命令行能不能跑）用法：装完 msProbe 后立刻执行；官方快速入门里原样给了这条（照抄即可）期望：打印 PyTorch: 2.7.1+... 之类版本信息，最后输出 [PASS] NPU environment, msProbe and TensorBoard check passed. 不过会怎样：卡在 NPU is unavailable → 是环境问题不是精度问题，回 C1 / B1；卡在 import msprobe → 工具没装好，回 5.2；卡在 tensorboard → 补装 TensorBoard

5.4 写采集配置 config.json

PrecisionDebugger 靠 config.json 决定采什么。官方示例（照抄，只改路径）：

{
    "task": "statistics",
    "dump_path": "/home/data_dump",
    "rank": [],
    "step": [],
    "level": "mix",
    "async_dump": false,
    "extra_info": true,

    "statistics": {
        "scope": [],
        "list": [],
        "tensor_list": [],
        "data_mode": ["all"],
        "summary_mode": "statistics"
    }
}

几个我每次都会动的字段（官方说明）：

字段	我会怎么设	官方理由
`level`	初查 `"mix"`（模块＋API）；只关心算子用 `"L1"`	`mix`=L0+L1；构图比对要求 `level` 为 `L0` 或 `mix`（否则 `construct.json` 为空）
`task`	初查 `"statistics"`（省磁盘）；精查改 `"tensor"`	`statistics` 仅统计量；`tensor` 才会把真实张量也落盘
`step`	先 `[0, 1]` 两个迭代就够	官方：指定采集某个 step；默认未配置＝采所有 step（太大）
`rank`	单卡必须 `[]`	官方：单卡训练时 rank 必须为 `[]`（空列表）
`dump_path`	两侧必须不同	官方：两次 dump 路径相同会数据覆盖

💡 想省事：官方快速入门直接给了 cat > ~/config.json << EOF ... EOF 的写法，可以把上面 JSON 原样粘进去。

5.5 在训练脚本里挂采集接口（官方三个接口）

官方给的插入方式（PrecisionDebugger / seed_all / start / stop / step）：

from msprobe.pytorch import PrecisionDebugger, seed_all

seed_all()                                  # 训练开始前固定随机性、开启确定性计算
debugger = PrecisionDebugger(config_path="./config.json")   # 加载采集配置

for data, label in data_loader:
    debugger.start(model)                   # 开启数据采集
    output = model(data)
    loss.backward()
    optimizer.step()
    debugger.stop()                         # 关闭采集（同一 step 内可再开）
    debugger.step()                         # 结束本 step，数据落盘

⭐ stop 和 step 的区别（官方原文）： debugger.stop() = 关闭数据 dump，可继续开启数据 dump，采集数据会记录在同一个 step 中； debugger.step() = 结束数据 dump，若继续开启数据 dump，采集数据将记录在下一个 step 中。

5.6 跑起来，看数据落没落盘

命令　python3 ${HOME}/precision_sample.py --gpu 0

含义：拉起训练，触发第 0、1 个 step 的精度数据采集拆解：precision_sample.py（你的训练脚本，官方快速入门里是 ResNet-50 样例）＋ --gpu 0（用 0 号卡；官方提示：这卡不可用就换成目标卡 ID）用法：官方脚本里已挂好 PrecisionDebugger；采集完 step0/step1 后可 Ctrl + C 安全终止——官方明确：提前终止不影响已采集数据的完整性 期望：日志打印 dump.json is at .../step1. 与 msprobe ends successfully. 不过会怎样：没打印 dump.json is at → 采集没生效，查 config.json 的 level/task/step 与接口调用顺序；报 No module named 'msprobe' → 回 5.2 装工具

命令　tree -L 3 "${HOME}/msprobe_dump_npu"

含义：看一眼采集出来的目录结构，确认文件齐不齐拆解：tree（树形列目录）＋ -L 3（只展开 3 层，免得刷屏）＋路径（你的 dump_path）用法：把路径换成你 config.json 里 dump_path 的值期望：看到官方文档里的结构——单卡在 proc{pid} 下（多卡在 rank{ID} 下），每个 step 目录里有 dump.json / stack.json / construct.json 不过会怎样：目录里只有 dump.json 没有 construct.json → extra_info 被关了或 level 不是 L0/mix（构图比对依赖它）；只有 proc{pid} 没有 rank{ID} → 正常，说明当前是非分布式场景

官方对几个文件的说明（后面回溯全靠它们）：

文件	说明
`dump.json`	API/Module 前反向统计量（dtype、shape、max、min、mean、L2norm）——比对的核心输入
`stack.json`	API/Module 的调用栈信息——用于从可疑 API 回溯至训练代码
`construct.json`	分层分级结构；`level` 为 L1 时内容为空
`dump_error_info.log`	仅 dump 报错时生成
`dump_tensor_data/`	采集到的张量数据（`task=tensor` 才有）

第六段定位：三个动作，把问题缩到一个算子

A · 动作一：整网比对（先只看两列）

命令　msprobe compare -tp "${NPU_DUMP_JSON}" -gp "${GPU_DUMP_JSON}" -o "${HOME}/accuracy_compare"

含义：把昇腾侧（-tp）和参考平台侧（-gp）的 dump 逐算子比对，输出结论表拆解：msprobe compare（比分子命令）＋ -tp/--target_path（必选，NPU 环境下的 dump.json 路径）＋ -gp/--golden_path（必选，CPU/GPU/NPU 环境下的 dump.json 路径）＋ -o/--output_path（可选，结果落盘目录，默认当前目录建 output）用法：单卡填到 dump.json；多卡要填到 step 层级（即 rank 的上一层），如 -tp /target_dump/step0 -gp /golden_dump/step0；想要 Excel 输出加 --xlsx 期望：打印 msprobe compare ends successfully.，输出目录生成 compare_result_{timestamp}.csv（多卡是 compare_result_rank{rank_id}_{timestamp}.csv） 不过会怎样：-tp / -gp 传反 → 结果照出但方向相反（这是最隐蔽的错，回 4.2 自检）；结果里一堆 Err_Message 提示 API 未匹配 → 看下面「两条注意事项」； ⚠️ 官方提示：output 目录下与结果文件同名的文件会被删除覆盖

结果怎么看（官方《快速入门》给的四步顺序，照做）：

按 Result 列筛选未通过的 API；
看 Err_Message，判断是否存在 API 未匹配、数据类型或形状不一致；
对已匹配但差异较大的，对比 Max、Min、Mean、L2 Norm 统计量及相对误差；
结合 NPU_Stack_Info 或 stack.json，定位可疑 API 对应的训练代码。

官方给的两条「别自己吓自己」的注意事项：

NPU 自研 API，在 CPU 或 GPU 侧若没有对应的 API，该 API 的 dump 数据不比对；

NPU 与 CPU 或 GPU 的计算结果误差可能会随着模型的执行不断累积，最终会出现同一个 API 因为输入的数据差异较大而无法比对的情况。

⭐ 第二条是本课反复强调的「误差累积」：所以比对结果里「一大片差异」不等于「一大片算子都错了」—— 这正是下一步要收紧的原因。

B · 动作二：首差异算子节点识别（把「一屏差异」缩成「一行」）

命令　msprobe compare -tp "${NPU_DUMP_JSON}" -gp "${GPU_DUMP_JSON}" -o ./output -da

含义：在比对基础上，自动识别网络中「第一个出现差异的算子节点」——这是本课最值钱的一条命令拆解：前面参数同动作一；-da / --diff_analyze（自动识别网络中首差异节点，支持 md5、统计量等 dump 数据，支持单卡/多卡）用法：官方要求采集时 level 配 L0 或 L1、task 配 tensor 或 statistics（也可 summary_mode 配 md5）并指定需要 dump 的 API 或模块名；单卡直接跑，多卡把 -tp/-gp 填到 step 层级期望：输出目录生成 compare_result_rank{rank_id}_{timestamp}.json 和 diff_analyze_{timestamp}.json—— 后者包含首差异算子节点识别结果：算子节点名、算子类型、算子位置 不过会怎样：没生成 diff_analyze_*.json → 检查是否漏写 -da；节点太多看不出首节点 → 回到动作一先看 Result，或收紧 config.json 的 list 只 dump 相关 API

⭐ 为什么这条比逐条比对有用：官方原话说误差会累积—— 找到了第一个错的，后面那一大片就可以整片不看。 这一步直接决定你是查「一个算子」还是查「一百个算子」。

C · 动作三：遇到 NaN / Inf，找「第一个溢出的节点」

命令　msprobe overflow_check -i /xxx/dump/step0 -o ./output

含义：分析 dump 数据，在多卡场景下检测每张卡中产生 inf/nan 的节点，并找出首个产生 inf/nan 的 rank 和节点 拆解：msprobe overflow_check（整网首个溢出节点分析子命令）＋ -i/--input_path（必选，dump 数据目录，需指定到 step 层级）＋ -o/--output_path（可选，输出目录，默认当前目录建 output）用法：-i 一定要指到 step0 这一层（如 -i /xxx/dump/step0）；当前仅支持分析 PyTorch 场景的 dump 数据 期望：存在异常节点时生成 anomaly_analyze_{timestamp}.json，结构是「按 rank 分组」的节点清单，每个节点带 op_name（节点名）、input_args / output（数据）、construct_info（层级）、stack_info（堆栈） 不过会怎样：打印 Cannot find any anomaly node, no need to generate analyze file. → 无异常节点，不生成文件（这不是失败，是「这一侧没溢出」）；报不支持 → 检查是不是拿 MindSpore 的 dump 来跑（官方约束：仅支持 PyTorch）

官方给的溢出判定口径（决定了你怎么读那份 json）：

异常计算节点：某节点输入正常（Max/Min 无 inf/nan）而输出异常 → 认为从此节点开始产生溢出；

异常通信节点：有向节点看 src 的 input——input 本身异常则问题在上游计算节点；input 正常而 output 异常则通信节点本身产生了异常数据。

另外两条一眼可用的溢出检测入口：

命令　msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path -oc

含义：生成双图比对文件，并把溢出等级标注到图节点上（可视化看差异）拆解：msprobe graph_visualize（构图比对子命令）＋ -tp（必选，待调试侧路径）＋ -gp（标杆侧路径，双图比对要）＋ -o（必选，输出目录，产物 compare_{timestamp}.vis.db）＋ -oc/--overflow_check（开启溢出检测模式，对每个溢出节点标记溢出等级）用法：官方要求采集时 level 为 L0 或 mix（construct.json 内容不能为空）；想要单图+溢出检测可用 msprobe graph_visualize -tp ./target_path -o ./output_path -oc 期望：输出目录生成 compare_{timestamp}.vis.db；开启 -oc 后每个图节点带上溢出等级：medium（输入异常、输出正常）/ high（输入异常、输出异常）/ critical（输入正常、输出异常） 不过会怎样：提示模型结构为空 → 官方排查：确认 NPU 和 GPU 采集配置的 level 均为 mix 或均为 L0，并检查两侧 construct.json 是否为空；用了旧版插件报冲突 → pip uninstall tb_graph_ascend 后重装

命令　tensorboard --logdir "${HOME}/graph_visualize_output" --bind_all

含义：把上面生成的图结构文件用 TensorBoard 打开，在浏览器里逐层看差异拆解：tensorboard（可视化服务）＋ --logdir（指向上一步的输出目录）＋ --bind_all（绑定所有网卡，让外部浏览器能访问）用法：终端会打印形如 http://hostname:6006/ 的地址；浏览器访问 http://服务器IP:6006/；被防火墙挡住就参考官方 FAQ 用 VS Code / SSH 端口转发期望：浏览器里看到双图比对结果——模型结构、结构差异、每个节点的精度比对指标（指标差异越大颜色越深） 不过会怎样：页面打不开 → 端口被防火墙拦（官方 FAQ 收了这个场景）；图是空的 → 回上一步查 level 与 construct.json

D · 顺带：多卡结果汇总（多卡才用）

命令　msprobe merge_result -i <input_dir> -o <output_dir>

含义：把多卡比对结果里的通信算子数据提取汇总，输出整理好的通信算子多卡精度表拆解：msprobe merge_result（汇总子命令）＋ -i（比对结果输入目录）＋ -o（输出目录）用法：官方适用场景是「已完成精度比对、拿到多卡结果，但通信算子数据分散在多个结果文件里」期望：输出一份汇总后的通信算子多卡比对精度表 不过会怎样：报格式不支持 → 官方两条硬约束：不支持 MD5 比对结果、仅支持 xlsx 格式的 compare 结果，不支持 csv（所以前面要用 --xlsx）

第七段出问题怎么查

排障原则：先定「卡在六步里的哪一步」，再看技术细节。 官方六步思路就是本课的排查顺序——别一上来就比对，那是第 ⑤ 步。

现象	大概是什么	先查什么
参考平台自己也跑不出正常结果	第 ① 步没做：参考基准本身有问题	回 4.1：先确认 GPU/CPU 侧那次运行 loss/准确度是否正常
两侧都是对的，但一比就一堆差异	可能是数据/种子不一致（两边不是同一份输入）	回 4.4：两侧 `config.json` 的 `level/task` 是否一致、是否都调了 `seed_all()`、`dump_path` 是否分开
比对结果里一堆 API 提示未匹配	常见，不一定是故障	官方：两侧 API 名称须相同、输入输出 Tensor 数量须相同才算同一个 API；NPU 自研 API 无对应侧则不比对；可加 `-fm` 模糊匹配（同层级命名相同仅调用次数不同）
差异太多，不知道该看哪个	没找「第一个」	加 `-da` 拿首差异算子节点；是数值溢出就走 `overflow_check`
loss 里出现 inf / nan，Loss Scale 一直降	第 ③ 步：浮点异常	用 `overflow_check` 找首个溢出节点；判定口径见 6.C
关了算子融合就对了 / 不关就不对	第 ④ 步：融合异常	官方建议：尝试关闭融合规则，定界是不是融合导致
同样输入，两次训练结果不同	第 ⑥ 步：随机错误	官方：执行两次训练分别采集 dump，比对定位导致随机的算子层
能定位到算子，但不知道对应哪行代码	没回溯	看结果文件里的 `NPU_Stack_Info`，或 NPU 侧 `stack.json`（官方：用于从可疑 API 回溯至训练代码）
`level` 采了 L1，构图比对打不开	结构数据没采到	官方：构图比对要求 `level` 为 `L0` 或 `mix`（`level` 为 `L1` 时 `construct.json` 内容为空）
只采到 `proc{pid}` 没有 `rank{ID}`	正常	官方：非分布式（单进程/单卡）没有 rank 信息，存在 `proc{pid}`；此类数据比对、分级可视化、溢出检测都支持

⭐ 一个判断法：

结果完全对不上（差得离谱）→ 先想「是不是比错了对象」：-tp/-gp 传反 / 参考基准本身有问题
结果大体对、只有小差异   → 找「第一个差异算子」(-da)，而不是逐个看
出现 inf / nan           → 走溢出路线：overflow_check 找首个溢出节点
两次跑结果不一样         → 走随机错误路线：跑两次分别 dump 比对

⭐ 按官方六步排的排查顺序（不要跳步）：

① 调优前检查    → 参考基准可信吗？是不是迁移引入的？
② 工具部署      → msProbe 自检过了吗？（先证明工具是好的）
③ 浮点异常检测  → 有 inf/nan 吗？找首个溢出节点
④ 融合异常检测  → 关融合还错吗？
⑤ 整网数据比对  → 两侧 dump → compare → -da 找首差异算子   ← 本课主线
⑥ 随机错误检测  → 跑两次，对比两次 dump

第八段常见报错清单

精度阶段的「报错」和 F1 不同——很多不是命令报错，而是「结果不对」这种软故障。下表按现象给排查方向。命令类的报错原文，请到官方案例库按报错里的稳定特征词检索： https://www.hiascend.com/document/caselibrary

报错 / 现象	大概属于	先查什么
`ModuleNotFoundError: No module named 'msprobe'`	环境	工具没装好：回 5.2；在线/离线包不含的可选功能要走源码安装
环境自检卡在 `NPU is unavailable`	环境	不是精度问题：NPU/框架环境没配好，回 C1 / B1
环境自检卡在 `msprobe --help` / `tensorboard --help`	环境	对应的包没装或没进 PATH
日志没打印 `dump.json is at ...`	采集没生效	查 `config.json` 的 `level/task/step` 是否为有效值、`PrecisionDebugger` 是否在导包处实例化
`dump.json` 里统计量全是 `null`	数据格式	官方：当 Tensor 数据格式为 NZ 格式时，max/min/mean/L2norm 均为 null；且仅当 dtype 为 float32/float16/bfloat16 时才计算 mean/L2norm，其它类型只算 max/min
采集完 `construct.json` 是空的	级别配错	官方：`level` 为 L1 时 `construct.json` 内容为空；构图比对要求 L0 或 mix
`msprobe compare` 报一堆 API 未匹配	匹配条件	官方匹配条件：名称相同 + 输入输出 Tensor 数量相同；NPU 自研 API 无对应侧不比对；可试 `-fm` 模糊匹配或 `-dm` 自定义映射
比对结果里出现 `inf` / `nan`（在 MaxRelativeErr 等）	数据里有 0 或 nan	官方原文：当 dump 数据中存在 0 或 nan 时，比对结果中最大相对误差出现 inf 或 nan 的情况，属于正常现象
`cosine` 计算结果为 `nan`	单侧向量为 0	官方：在计算中可能会存在 nan，主要由于可能会出现其中一个向量为 0
`msprobe overflow_check` 打印 `Cannot find any anomaly node, no need to generate analyze file.`	非故障	官方：分析认为不存在异常节点，故不生成分析文件
`overflow_check` 报不支持当前数据	框架	官方约束：当前仅支持分析 PyTorch 场景的 dump 数据
`graph_visualize` 提示模型结构为空	结构没采到	官方排查：确认 NPU/GPU 两侧 `level` 均为 `mix` 或均为 `L0`，并查 `construct.json` 是否为空
装了旧版可视化插件导致冲突报错	插件冲突	官方：`pip uninstall tb_graph_ascend` 后重装 msProbe
`merge_result` 报格式不支持	输入格式	官方两条约束：不支持 MD5 比对结果；仅支持 xlsx 格式（前面要用 `--xlsx`）
用 `nan_check` 采样但结果异常	版本/模式	官方要求：CANN ≥ 8.5.0、`level` 须为 `L1`、须用编译时带 `--include-mod=nan_check` 的工具包、并设 `INF_NAN_MODE_FORCE_DISABLE=1`
用了 msProbe 之后 loss/gnorm 变了	工具副作用	官方说明：可能是工具中的 item 操作引入同步、PyTorch 框架的 hook 机制等原因导致，详见官方 FAQ「模型计算结果改变原因分析」

⭐ 检索技巧（E1 讲过，这里再用一次）：去掉具体化信息。不要搜「精度对不上怎么办」，要搜报错原文里的稳定特征词（错误码、函数名、算子名、库名）。

第九段小结与下一课

这一课要带走的三句话：

精度问题难在「它不喊」——训练正常结束、日志无异常，只有对比才发现；所以排查的起点不是读日志，是先排出参考基准和迁移这两个假问题。
官方六步里，本课的主线是第 ⑤ 步「整网数据比对」——采两侧 dump → msprobe compare 比对 → -da 找首差异算子 → 用堆栈回溯代码。
专找「第一个」：一个算子出错，后面几十个都会被带着一起错（误差还会顺着通信传到别的 rank）；找到第一个，其余都不用看——这条决定了你是查一个算子还是查一百个。

本课的路线（串联全课）：

① 排假问题（参考基准可信？迁移没引错？）
② 定两侧（-tp=昇腾 / -gp=参考平台，别传反）
③ 装 msProbe + 自检（先证明工具是好的）
④ 两侧各采一份 dump（level/task 一致、seed_all、路径分开）
⑤ msprobe compare 粗查（只看 Result / Err_Message）
⑥ -da 找首差异算子 / overflow_check 找首溢出节点
⑦ 回溯到训练代码 + 说清「是哪个算子、为什么」

下一课预告（F3）：本课所有命令在单卡上走通了。下一课处理多卡与分布式—— 当卡数一多，通信算子本身也会成为问题源（本课已埋了伏笔：overflow_check 的「异常通信节点判定」、merge_result 的多卡汇总），以及分布式训练里「结果不对」和「跑不起来」经常同时出现时怎么拆。

附录 A · 本课引用的官方出处

内容	来源文档
精度问题三条特征（训练正常结束 / 日志无异常 / 仅对比才发现）、六步精度调试思路（调优前检查 / 工具部署 / 浮点异常检测 / 融合异常检测 / 整网数据比对 / 随机错误检测）、整网数据比对定义、随机错误检测做法	《精度调试流程》（TensorFlow 模型迁移 · 精度调试）
msProbe 定义（MindStudio Probe，AI 模型精度调试工具）、完整 NPU/GPU 采集与比对流程、环境自检命令、`config.json` 示例、`PrecisionDebugger` 脚本、`msprobe compare` / `graph_visualize` / `tensorboard` 命令、比对结果四步分析顺序	《msProbe PyTorch 场景快速入门》
`level`（L0/L1/L2/mix）与 `task`（statistics/tensor/nan_check/…）、`PrecisionDebugger`/`seed_all`/`start`/`stop`/`step` 接口、dump 目录结构（`proc{pid}` / `rank{ID}`）、`dump.json`/`stack.json`/`construct.json`/`dump_error_info.log` 说明、NZ 格式与 dtype 对统计量的影响、`risk_level`	《PyTorch 场景精度数据采集》
`msprobe compare` 命令与完整参数表、`-tp`/`-gp` 定义、API 匹配条件与命名规则、三种数据模式、指标定义与公式、`Cosine > 0.99` / `MaxAbsErr < 0.001` 阈值、`Result` 三类与 `Err_Message` 判定条件、`-da` 首差异算子节点、`merge_result` 多卡汇总、误差累积与 API 匹配注意事项	《PyTorch 场景精度比对》
分级可视化构图比对（单图/双图、`graph_visualize` 参数、`-oc` 溢出等级 medium/high/critical、`level` 须 L0/mix、`tb_graph_ascend` 插件与冲突卸载）	《PyTorch 场景的分级可视化构图比对》
整网首个溢出节点分析（`overflow_check` 命令与参数、`anomaly_analyze_*.json` 结构、异常计算节点/通信节点判定、顺序判定）	《整网首个溢出节点分析》
三种安装方式（在线 `pip install mindstudio-probe==26.1.0.post1` / 离线 whl + sha256 / 源码 `build.py`）、可选模块 `--include-mod`（tb_graph_ascend / nan_check / xor_checksum 等）、CANN 前置	《msProbe 工具安装指南》
`config.json` 全部参数（`task` / `dump_path` / `rank` / `step` / `level` / `async_dump` / `dump_enable` / `extra_info` / `precision` / `risk_level`）、`nan_check` 注意事项（CANN ≥ 8.5.0、`level` 须 L1、`INF_NAN_MODE_FORCE_DISABLE=1`）、`pip show mindstudio-probe` 定位路径	《配置文件介绍》

本课未做的事（官方未给出，故不写）：

未给「哪些算子精度一定不准」的通用清单——不存在这样的通用清单；精度问题必须针对具体模型实测比对（这一点与 F1 的「不支持算子清单由工具实时生成」同理）。
未给「整网比对通过」的统一阈值——官方只给了单个指标的「实际可接受阈值」（Cosine > 0.99、MaxAbsErr < 0.001），没有整网通过标准；判定落点是 Result 列 + 人工结合实际情况判断。
未写 msProbe「NPU 侧操作」在裸机/虚拟机上的部署步骤——官方《快速入门》明确：NPU 侧操作仅支持在标准化 CANN 容器中执行，不支持裸机/虚机/非标准容器；容器镜像选择、启动脚本等步骤随官方教程版本变化，本课不抄死。
未给 GPU 侧采集的完整分步命令——官方《快速入门》对 GPU 侧采集写的是「自行探索操作」，并建议直接使用预置示例数据；本课按官方口径只讲「两侧配置要一致」，不编造 GPU 侧的分步命令。
未给 -s/其它未列出的隐藏参数——msProbe 各子命令的参数以官方文档为准；本课附录 B 只列官方文档中明确给出的参数。
未展开性能类数字——msProbe 官方给出了比对速度（比对数据量较小时 0.1 GB/s、较大时 0.3 GB/s，及推荐环境配置），本课照录；但未给训练加速/精度提升类数字，官方文档中亦无，故不编造。

附录 B · 命令与参数逐条详解

B.1 本课命令一览

命令	干什么	段
`pip install mindstudio-probe==26.1.0.post1`	在线装 msProbe	5.2
`sha256sum {name}.whl`	校验离线 whl 包完整性	5.2
`python3 build.py -e include-mod=nan_check -e no-check=true`	源码编译带可选模块的 whl	5.2
环境自检一行命令（`python3 -c 'import torch, torch_npu; ...'`）	验 NPU/msProbe/TensorBoard	5.3
`python3 ${HOME}/precision_sample.py --gpu 0`	拉起训练触发采集	5.6
`tree -L 3 "${HOME}/msprobe_dump_npu"`	看采集目录结构	5.6
`msprobe compare -tp ... -gp ... -o ...`	整网精度比对	6.A
`msprobe compare ... -da`	首差异算子节点识别	6.B
`msprobe overflow_check -i ... -o ...`	找首个溢出节点	6.C
`msprobe graph_visualize -tp ... -gp ... -o ... -oc`	双图比对 + 溢出等级标注	6.C
`tensorboard --logdir ... --bind_all`	浏览器看构图比对结果	6.C
`msprobe merge_result -i ... -o ...`	多卡通信算子结果汇总	6.D

B.2 `msprobe compare` 参数表（官方）

参数	可选/必选	说明
`-tp` / `--target_path`	必选	NPU 环境下的 `dump.json` 路径（单卡）或 dump 目录（多卡）
`-gp` / `--golden_path`	必选	CPU、GPU 或 NPU 环境下的 `dump.json` 路径（单卡）或 dump 目录（多卡）
`-o` / `--output_path`	可选	结果落盘目录，默认当前目录建 `output`；默认输出 csv，格式 `compare_result_{timestamp}.csv`
`--xlsx`	可选	输出改为 xlsx 格式（`merge_result` 只吃 xlsx）
`-fm` / `--fuzzy_match`	可选	模糊匹配：同层级命名相同、仅调用次数不同的 API 可匹配比对
`-dm` / `--data_mapping`	可选	自定义映射关系比对，需 `*.yaml`（API/模块无法自动匹配时用；仅支持逐卡比对）
`-cm` / `--cell_mapping`	可选	不同平台、不同配置的模块比对，需 `*.yaml`
`-da` / `--diff_analyze`	可选	自动识别网络中首差异节点，支持 md5、统计量等 dump 数据，支持单卡/多卡
`-tensor_log` / `--is_print_compare_log`	可选	打印单个模块或 API 的日志，仅支持 tensor 数据
`--consistent_check` / `--backend`	可选	verl 训推一致性比对（`--backend` 取 `fsdp` 或 `megatron`，须先开 `--consistent_check`）

B.3 `msprobe graph_visualize` 参数表（官方）

参数	可选/必选	说明
`-tp` / `--target_path`	必选	待调试侧比对路径；工具按路径格式自动进行单 rank / 多 rank / 多 step 批量构建
`-o` / `--output_path`	必选	构图结果目录，产物 `build_{timestamp}.vis.db`
`-oc` / `--overflow_check`	可选	开启溢出检测模式，对每个溢出节点标记等级（medium / high / critical）
`-tensor_log`	可选	打印单个模块/API 日志，仅支持 tensor 数据
`-progress_log`	可选	打印任务详细进度日志

B.4 `overflow_check` 参数表与输出结构（官方）

参数	可选/必选	说明
`-i` / `--input_path`	必选	dump 数据目录，需指定到 step 层级，如 `-i /xxx/dump/step0`
`-o` / `--output_path`	可选	输出目录，默认当前目录建 `output`

输出 anomaly_analyze_{timestamp}.json 的结构：

字段	含义
`rank_0` …	卡号（按 rank 分组的节点清单）
`op_name`	节点名
`data_info`	`input_args` / `input_kwargs` / `output` 数据
`construct_info`	节点层级数据
`stack_info`	堆栈数据（回溯代码用）

B.5 比对指标与阈值（官方）

指标	含义	官方给出的可接受阈值
`Cosine`	tensor 余弦相似度，越接近 1 越相似	大于 0.99
`EucDist`	tensor 欧氏距离，越接近 0 越相似	—
`MaxAbsErr`	tensor 最大绝对误差	小于 0.001
`MaxRelativeErr`	tensor 最大相对误差	—
`One/Five Thousandth Err Ratio`	相对误差小于千分之一 / 千分之五的元素比例	仅作趋势参考，不参与是否通过的判定

比对结果 Result 三类：pass / warning / error，优先级 error > warning > pass。

B.6 `config.json` 关键字段（官方）

字段	取值	说明
`task`	`statistics` / `tensor` / `acc_check` / `nan_check` / `structure`	采什么；默认 `statistics`
`dump_path`	路径	必选；两侧必须不同，否则数据覆盖
`level`	`L0`（模块级）/ `L1`（API 级，默认）/ `L2`（kernel 级）/ `mix`（L0+L1）/ `debug`	采到哪一层
`rank`	`[]` 或 `[1, "4-6"]`	单卡训练时必须为 `[]`
`step`	`[0, 1, "4-6"]`	默认未配置＝采所有 step
`async_dump`	`true` / `false`	异步 dump；task=tensor 时必须配 `list`（有显存溢出风险）
`extra_info`	`true` / `false`	是否生成 `stack.json` 和 `construct.json`（默认 true）
`precision`	`high` / `low`	统计值计算精度；`high` 用 float32，可能显存溢出
`risk_level`	`ALL` / `CORE` / `FOCUS`	API 风险级别过滤（L1/mix 生效），默认 `FOCUS`

B.7 dump 目录里各文件的用途（回溯链条）

采集产物
├── dump.json        统计量（比对的核心输入）
├── stack.json       API/Module 调用栈 ← 从可疑 API 回溯到训练代码靠它
├── construct.json   分层分级结构（level=L1 时为空；构图比对依赖它）
└── dump_tensor_data/  真实张量（task=tensor 才有）

回溯一句话记：dump.json 告诉你「哪个算子不对」，stack.json / NPU_Stack_Info 告诉你「它在代码的哪一行」。 两者缺一不可。