deterministic-calculation-analysis

name	deterministic-calculation-analysis
description	执行msProbe数据比对并分析比对结果，定位确定性计算问题首个输入一致输出不一致的API。
keywords	["确定性计算","msprobe","md5比对","CRC-32","精度问题定位"]

确定性计算比对分析

技能目标

1. 数据比对 — 调用 msProbe 工具比对两份 dump 数据，生成比对结果文件
2. 结果分析 — 分析比对结果，寻找首个输入一致输出不一致的计算 API
3. 排除误检 — 支持排除特定 API 后重新分析，直至定位根因

分析流程

⚠️ 硬性规则

1. 第 1 步（用户输入数据校验）适用于所有路径类型，不可跳过。 即使是 db/csv_xlsx 路径，也必须先跑 md5_dump_files_checker.py 校验数据完整性。
2. 仅"第 2 步依赖检查（pip install）"和"第 3 步数据比对（msprobe compare/graph_visualize）"可根据路径类型跳过。

1. 用户输入数据校验

用户提供路径，支持三种输入类型：

输入类型	参数个数	说明
dump 路径	2 个	target（调试侧）和 golden（标杆侧）两份 msProbe 工具 dump 数据目录。示例：dump_path/step0。
db 路径	1 个	mix 级别比对结果文件（.vis.db）或包含该文件的目录。示例：db_path 或 db_path/compare_*.vis.db。
csv/xlsx 路径	1 个	L1 级别比对结果文件（.csv/.xlsx）或包含该文件的目录。示例：csv_path 或 csv_path/compare_*.csv。

# dump 路径（2 个参数）
python3 "<skill_root>/scripts/md5_dump_files_checker.py" <target_path> <golden_path>

# db 或 csv/xlsx 路径（1 个参数）
python3 "<skill_root>/scripts/md5_dump_files_checker.py" <db_or_csv_path>

• 校验通过 → 输出 level="L1" 或 level="mix"，继续下一步
• 校验不通过 → 输出异常原因，终止流程
• 打印内容包含“没有包含tensor的CRC-32校验值，无法分析确定性问题”、“缺失md5”相关内容 → 终止流程，提示用户必须使用包含 tensor 的 CRC-32 校验值的文件，采集数据的config.json配置必须指定task="statistics"和summary_mode="md5"

2. 依赖检查（仅 dump 路径需要）

db 和 csv/xlsx 路径已包含比对结果，无需依赖 msProbe 工具。

pip3 show mindstudio-probe || pip3 install mindstudio-probe --pre

3. 数据比对（仅 dump 路径需要）

根据第 1 步输出的 level 选择对应分支。比对等待时间最长为 600 秒。

3.1 level="L1"

msprobe compare -tp <target_path> -gp <golden_path> -o <output_path>

3.2 level="mix"

msprobe graph_visualize -tp <target_path> -gp <golden_path> -o <output_path>

4. 数据分析

根据第 1 步输出的 level 和第 1 步输入的路径类型选择对应分支。所有分支都支持 --exclude-api 排除后重分析。

4.1 输入为 dump 路径（比对结果已生成）

4.1.1 level="L1"

python3 "<skill_root>/scripts/find_first_diff_api_L1.py" <output_path>

分析特点：

• 无 Module 层级信息，仅有 API 级 md5 比对
• 找不到问题 API 时自动检测"状态跳变边界"，提示可能漏采的位置
• 支持 --exclude-api "API名称" 排除误检后重新分析

4.1.2 level="mix"

python3 "<skill_root>/scripts/find_first_diff_api_mix.py" <output_path>/compare_*.vis.db

分析特点：

• 包含 API 和 Module 两级分析，展示父子层级链路
• 当 API 级找不到结果、但 Module 级发现异常时，提示可能漏采的 API
• 支持 --exclude-api "API名称" 排除误检后重新分析

4.2 输入为 db 或 csv/xlsx 路径（跳过比对，直接分析）

已有比对结果文件，直接进行分析。

4.2.1 level="mix"（db 路径）

python3 "<skill_root>/scripts/find_first_diff_api_mix.py" <db_path>

4.2.2 level="L1"（csv/xlsx 路径）

python3 "<skill_root>/scripts/find_first_diff_api_L1.py" <csv_xlsx_path>

5. 输出

展示比对分析的结果并进行解读。

5.1 找到问题 API

展示首个输入一致输出不一致的 API，包括其 Module 层级链路（仅 mix）和 md5 比对详情：

+----------------------+------------------------------------------+
|                     Rank 0                              |
+----------------------+------------------------------------------+
| 首个问题API           | NPU.npu_rms_norm.0.backward              |
+----------------------+------------------------------------------+
| API所在Module层级     | DefaultModel [Module]                    |
|                      |   → input_layernorm.RMSNorm [Module]     |
|                      |   → NPU.npu_rms_norm.0.backward [API]    |
+----------------------+------------------------------------------+
| API分析依据           | Input MD5 (全部一致)                     |
|                      | Output MD5 (不一致)                      |
|                      |   output.1: NPU=xxx vs Bench=yyy         |
+----------------------+------------------------------------------+

找到首个问题 API 即排查结束，后续只让用户选择是否排除该 API 重新分析。如果用户选择排除，则让用户输入要排除的 API 名称（支持前缀匹配，多个以空格分隔），内部重新执行分析流程。

5.2 未找到问题 API（状态跳变）

+----------------------+------------------------------------------+
| 首个问题API           | 无                                       |
+----------------------+------------------------------------------+
| API分析依据           | 最后一个正常API: xxx                     |
|                      | 第一个输入不匹配API: yyy                 |
|                      | 两者之间的API可能被msprobe漏采           |
+----------------------+------------------------------------------+

解读: 未找到输入完全一致但输出不一致的 API，说明根因 API 可能被 msProbe 漏采。两个边界 API 之间的区域即为可疑范围，可调整 msProbe 采集配置后重新 dump 分析。

关键字段说明

db（mix 级别）

字段	说明
node_name	API/Module 名称
node_order	执行顺序，越小越先执行
node_type	0=Module, 1=API
data_source	NPU=调试侧, Bench=标杆侧
precision_index	0=pass, 1=error
up_node / sub_nodes	父子层级关系
input_data / output_data	输入/输出数据，JSON 格式，包含 md5 值
is_distributed	是否为通信算子

csv/xlsx（L1 级别）

字段	说明
NPU Name	调试侧 API 名称
Bench Name	标杆侧 API 名称
NPU MD5	调试侧 tensor CRC-32 值
BENCH MD5	标杆侧 tensor CRC-32 值
Result	比对结果（pass/fail）
NPU Tensor Shape	调试侧张量形状
Bench Tensor Shape	标杆侧张量形状

dump 路径说明

多卡场景

dump_path
└── step0
    ├── rank0
    │   ├── construct.json
    │   ├── dump.json
    │   └── stack.json
    ├── rank1
    │   ├── construct.json
    │   ├── dump.json
    │   └── stack.json
    ...
    └── rank7
        ├── construct.json
        ├── dump.json
        └── stack.json
└── step1
│   ├── ...
└── step2
...

单卡场景

dump_path
└── step0
    └── proc{pid}
        ├── construct.json
        ├── dump.json
        └── stack.json
└── step1
│   ├── ...
└── step2
...

比对说明

• level="mix"，调用msprobe graph_visualize，用户可以传入路径dump_path、dump_path/step{n}、dump_path/step{n}/rank{n}或者dump_path/step{n}/proc{pid}。
• level="L1"，调用msprobe compare，用户可以传入路径dump_path/step{n}、dump_path/step{n}/rank{n}或者dump_path/step{n}/proc{pid}，不支持比对dump_path。如果用户传入dump_path，默认比对dump_path/step0。