mindstudio-probe 1.1.1__py3-none-any.whl → 1.2.2__py3-none-any.whl

msprobe/docs/21.visualization_PyTorch.md

@@ -4,23 +4,29 @@
 
 工具支持PyTorch版本：2.1/2.2
 
+## 展示示例
+
+支持重建模型的层级结构；
+
+支持两个模型的结构差异比对；
+
+支持两个模型的精度数据比对，支持疑似有精度问题节点的快速搜索，自动跳转展开节点所在的层级。
+
+![vis_show](./img/visualization/vis_showcase.png)
+
 ## 1.依赖安装
 
 分级可视化工具依赖**msprobe工具**和**tensorboard。**
 
 ### 1.1 安装msprobe工具
 
-现阶段分级可视化工具还未集成在已发布的msprobe工具中，需要从源码安装，请参考从源码安装章节。
-
 [msprobe工具安装](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/01.installation.md)
 
 ### 1.2 安装tb_graph_ascend
 
 **请安装tb_graph_ascend，否则无法解析构图结果。**
 
-[tb_graph_ascend下载](https://mindstudio-sample.obs.cn-north-4.myhuaweicloud.com/GRAPH_ASCEND/tb_graph_ascend-0.1.0-py3-none-any.whl)
-
-``pip3 install``即可。
+``pip3 install tb-graph-ascend``即可。
 
 ## 2.模型结构数据采集
 [PyTorch场景的数据采集](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/05.data_dump_PyTorch.md)
@@ -37,19 +43,35 @@ msprobe -f pytorch graph -i ./compare.json -o ./output
 ```
 **命令行参数说明**：
 
-| 参数名                    | 说明                                                                                                                                                                           | 是否必选 |
-|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
-| -i 或 --input_path      | 指定比对文件，str 类型。                                                                                                                                                               | 是    |
-| -o 或 --output_path     | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis`。                                                                                                             | 是    |
-| -lm 或 --layer_mapping  | 跨套件比对，例如同一个模型分别使用了DeepSpeed和Megatron套件的比对场景。配置该参数时表示开启跨套件Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#71-自定义映射文件layer)。 | 否    |
-| -oc 或 --overflow_check | 是否开启溢出检测模式，开启后会在输出vis文件中（`compare_{timestamp}.vis`）对每个溢出节点进行标记溢出等级，溢出等级说明参考如下                                                                                                                         | 否    |
+| 参数名                    | 说明                                                                                                                                                                                                                                                                  | 是否必选 |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
+| -i 或 --input_path      | 指定比对文件，参考[比对文件说明](#313-比对文件说明)                                                                                                                                                                                                                                      | 是    |
+| -o 或 --output_path     | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis或build_{timestamp}.vis`。                                                                                                                                                                              | 是    |
+| -lm 或 --layer_mapping  | 跨套件比对，例如同一个模型分别使用了DeepSpeed和Megatron套件的比对场景。配置该参数时表示开启跨套件Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#71-自定义映射文件layer)，如何配置自定义映射文件请参考[模型分级可视化如何配置layer mapping映射文件](./visualization/layer_mapping_example.md)。 | 否    |
+| -oc 或 --overflow_check | 是否开启溢出检测模式，开启后会在输出vis文件中（`compare_{timestamp}.vis或build_{timestamp}.vis`）对每个溢出节点进行标记溢出等级，溢出等级说明参考[溢出等级说明](#312-溢出等级说明)                                                                                                                                              | 否    |
+| -f 或 --fuzzy_match     | 是否开启模糊匹配，bool类型。模糊匹配说明参考[匹配说明](#311-匹配说明)                                                                                                                                                                                                                           | 否    |
+| -cs 或 --complete_stack | 是否使用完整的堆栈信息，bool类型。默认使用精简的堆栈信息，数据量小有助于增加流畅度。完整堆栈和精简堆栈信息参考[堆栈信息说明](#72-堆栈信息说明)                                                                                                                                                                                       | 否    |
+
+#### 3.1.1 匹配说明
+
+**注：dump名称 = 名称 + 调用次数**，例如Torch.matmul.2.forward，matmul是名称，2是调用次数
 
-**溢出等级说明**
+1.默认匹配
+- 所有节点dump名称一致
+- 节点输入输出参数数量一致，参数type、shape一致
+- 节点的层级一致（父节点们一致）
+
+2.模糊匹配
+- Module节点dump名称一致，两个匹配上的Module节点, 忽略各自节点下所有api的dump调用次数，按照名称一致+Module节点内的调用顺序进行匹配
+- ![fuzzy_match_pt.png](./img/visualization/fuzzy_match_pt.png)
+- 参数shape一致
+
+#### 3.1.2 溢出等级说明
 - medium：输入异常，输出正常场景
 - high：输入异常，输出异常；输出norm值相较于输入存在异常增大情况
 - critical：输入正常，输出异常场景
 
-**比对文件说明**：
+#### 3.1.3 比对文件说明
 以在当前目录创建 ./compare.json 为例。
 ```
 {
@@ -280,33 +302,70 @@ msprobe -f pytorch graph -i ./compare.json -o ./output
 ├── compare_stepn_rankn_{timestamp}.vis
 ```
 
+#### 3.2.4 仅模型结构比对
+
+适用场景：**主要关注模型结构而非训练过程数据**。例如，在模型迁移过程中，确保迁移前后模型结构的一致性，或在排查精度差异时，判断是否由模型结构差异所引起。
+
+使用msprobe工具对模型数据进行采集时，**可选择仅采集模型结构（task配置为structure）**，此配置将避免采集模型训练过程的数据，从而显著减少采集所需的时间。
+
+dump配置请参考[dump配置示例](./03.config_examples.md#16-task-配置为-structure)
+
+得到dump数据后，若需比较特定两个rank之间的数据，请参考[3.2.2 双图比对](#322-双图比对)；若需进行多个rank或多个step的数据批量比对，请参考[3.2.3 批量构建或比对](#323-批量构建或比对)。
+
 ## 4.启动tensorboard
 
+### 4.1 可直连的服务器
+
 将生成vis文件的路径**out_path**传入--logdir
 
 ```
 tensorboard --logdir out_path --bind_all --port [可选，端口号]
 ```
+启动后会打印日志:
+
+![tensorboard_1](./img/visualization/tensorboard_1.png)
 
-启动后会打印日志。
-``TensorBoard 2.15.1 at http://localhost.localdomain:6008/ (Press CTRL+C to quit)``
-localhost.localdomain是机器地址，6008是端口号。
+ubuntu是机器地址，6008是端口号。
 
-**如果链接打不开，可以尝试使用vscode连接服务器，在vscode终端输入：**
+**注意，ubuntu需要替换为真实的服务器地址，例如真实的服务器地址为10.123.456.78，则需要在浏览器窗口输入http://10.123.456.78:6008**
+
+### 4.2 不可直连的服务器
+**如果链接打不开（服务器无法直连需要挂vpn才能连接等场景），可以尝试使用vscode连接服务器，在vscode终端输入：**
 
 ```
 tensorboard --logdir out_path
 ```
+![tensorboard_2](./img/visualization/tensorboard_2.png)
 
-CTRL+C点击链接即可
+按住CTRL点击链接即可
 
 ## 5.浏览器查看
 
-推荐使用谷歌浏览器，在浏览器中输入机器地址+端口号回车，出现TensorBoard页面，右上方选择GRAPHS_ASCEND即可展示模型结构图。
+### 5.1 浏览器打开图
+推荐使用谷歌浏览器，在浏览器中输入机器地址+端口号回车，出现TensorBoard页面，其中/#graph_ascend会自动拼接。
+![vis_browser_1](./img/visualization/vis_browser_1.png)
+如果您切换了TensorBoard的其他功能，此时想回到模型分级可视化页面，可以点击左上方的**GRAPH_ASCEND**
+![vis_browser_2](./img/visualization/vis_browser_2.png)
+
+### 5.2 查看图
+![vis_show_info.png](./img/visualization/vis_show_info.png)
+
+### 5.3 名称搜索
+![vis_search_info.png](./img/visualization/vis_search_info.png)
+
+### 5.4 精度筛选
+![vis_precision_info.png](./img/visualization/vis_precision_info.png)
+
+### 5.5 未匹配节点筛选
+节点匹配规则：
 
-节点需要双击打开。
+1.名称一致
 
-键盘WS可放大缩小，AD可左右移动，鼠标滚轮可上下移动。
+2.节点输入输出参数数量一致，参数type、shape一致
+
+3.节点的层级一致（父节点们一致）
+
+![vis_unmatch_info.png](./img/visualization/vis_unmatch_info.png)
 
 ## 6.图比对说明
 
@@ -326,20 +385,6 @@ CTRL+C点击链接即可
 
 ``相对误差：abs（(npu统计值 - bench统计值) / bench统计值)``
 
-其中小值不使用相对误差来判断精度差异，而是使用**绝对误差**来判断精度差异
-
-**判定为小值的阈值：**
-
-   - torch.float32：e-6
-   - torch.float16：e-3
-   - torch.bfloat16：e-3
-
-**小值域的绝对误差阈值：**
-
-   - torch.float32：e-6
-   - torch.float16：e-3
-   - torch.bfloat16：e-3
-
 #### md5模式
 节点中任意输入输出的md5值不同。
 
@@ -384,3 +429,48 @@ yaml文件中只需配置待调试侧与标杆侧模型代码中功能一致但
 模型代码示例：
 
 ![ms_dump](./img/ms_layer.png)
+
+### 7.2 堆栈信息说明
+
+**精简堆栈**
+
+保留一条当前模块或api的调用信息
+
+```json
+{
+    "Module.layer1.0.bn1.BatchNorm2d.forward.0": [
+        "File /home/torchvision/models/resnet.py, line 93, in forward, \n out = self.bn1(out)"
+       ]
+}
+```
+
+**完整堆栈**
+
+当前模块或api完整的调用信息
+
+```json
+{
+    "Module.layer1.0.bn1.BatchNorm2d.forward.0": [
+        "File /home/torchvision/models/resnet.py, line 93, in forward, \n out = self.bn1(out)",
+        "File /home/torch/nn/modules/module.py, line 1568, in _call_impl, \n result = forward_call(*args, **kwargs)",
+        "File /home/torch/nn/modules/module.py, line 1518, in _wrapped_call_impl, \n return self._call_impl(*args, **kwargs)",
+        "File /home/torch/nn/modules/container.py, line 215, in forward, \n input = module(input)",
+        "File /home/torch/nn/modules/module.py, line 1568, in _call_impl, \n result = forward_call(*args, **kwargs)",
+        "File /home/torch/nn/modules/module.py, line 1518, in _wrapped_call_impl, \n return self._call_impl(*args, **kwargs)",
+        "File /home/torchvision/models/resnet.py, line 273, in _forward_impl, \n x = self.layer1(x)",
+        "File /home/torchvision/models/resnet.py, line 285, in forward, \n return self._forward_impl(x)",
+        "File /home/torch/nn/modules/module.py, line 1527, in _call_impl, \n return forward_call(*args, **kwargs)",
+        "File /home/torch/nn/modules/module.py, line 1518, in _wrapped_call_impl, \n return self._call_impl(*args, **kwargs)",
+        "File /home/visualization/resnet18.py, line 40, in <module>, \n outputs = model(inputs)"
+       ]
+}
+
+```
+# FAQ
+1. 图比对场景，节点呈现灰色，且没有精度比对数据，怎么处理？
+
+节点呈现灰色，代表左边待调试侧节点与右边标杆侧节点没有匹配上，可能有以下几点原因：
+
+- **标杆侧确实没有能与待调试侧匹配上的节点**，属于代码实现上的差异，请确认此差异是否正常，是否会影响到整网精度。
+- **节点的输入或输出type、shape不一致，参数个数不一致，节点所在层级的父层级不一致**，导致节点无法匹配，具体匹配规则见[匹配说明](#311-匹配说明)，可尝试使用模糊匹配功能，如何使用此功能请参考[构图命令行说明](#31-构图命令行说明)。如果是参数shape不一致，即使是模糊匹配功能也无法让节点匹配上，请检查参数shape不一致是否合理。
+- **节点名称不一致**，导致节点无法匹配，可使用layer mapping功能，如何使用此功能请参考[构图命令行说明](#31-构图命令行说明)，如何自定义映射文件请参考[模型分级可视化如何配置layer mapping映射文件](./visualization/layer_mapping_example.md)。

msprobe/docs/22.visualization_MindSpore.md

@@ -4,23 +4,29 @@
 
 工具支持MindSpore版本：2.4.0
 
+## 展示示例
+
+支持重建模型的层级结构；
+
+支持两个模型的结构差异比对；
+
+支持两个模型的精度数据比对，支持疑似有精度问题节点的快速搜索，自动跳转展开节点所在的层级。
+
+![vis_show](./img/visualization/vis_showcase.png)
+
 ## 1.依赖安装
 
 分级可视化工具依赖**msprobe工具**和**tensorboard。**
 
 ### 1.1 安装msprobe工具
 
-现阶段分级可视化工具还未集成在已发布的msprobe工具中，需要从源码安装，请参考从源码安装章节。
-
 [msprobe工具安装](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/01.installation.md)
 
 ### 1.2 安装tb_graph_ascend
 
 **请安装tb_graph_ascend，否则无法解析构图结果。**
 
-[tb_graph_ascend下载](https://mindstudio-sample.obs.cn-north-4.myhuaweicloud.com/GRAPH_ASCEND/tb_graph_ascend-0.1.0-py3-none-any.whl)
-
-``pip3 install``即可。
+``pip3 install tb-graph-ascend``即可。
 
 ## 2.模型结构数据采集
 [MindSpore场景的精度数据采集](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/06.data_dump_MindSpore.md)
@@ -37,13 +43,36 @@ msprobe -f mindspore graph -i ./compare.json -o ./output
 ```
 **命令行参数说明**：
 
-| 参数名               | 说明                                                                                                                                                            | 是否必选 |
-|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
-| -i 或 --input_path   | 指定比对文件，str 类型。                                                                                                                                                | 是       |
-| -o 或 --output_path  | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis`。                                                                                              | 是       |
-| -lm 或 --layer_mapping| 跨框架比对，MindSpore和PyTorch的比对场景。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#71-自定义映射文件layer)。 | 否    |
+| 参数名               | 说明                                                                                                                                                                                                                                                    | 是否必选 |
+|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+| -i 或 --input_path   | 指定比对文件，参考[比对文件说明](#313-比对文件说明)                                                                                                                                                                                                                        | 是       |
+| -o 或 --output_path  | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis或build_{timestamp}.vis`。                                                                                                                                                                | 是       |
+| -lm 或 --layer_mapping| 跨框架比对，MindSpore和PyTorch的比对场景。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#71-自定义映射文件layer), 如何配置自定义映射文件请参考[模型分级可视化如何配置layer mapping映射文件](./visualization/layer_mapping_example.md)。 | 否    |
+| -oc 或 --overflow_check | 是否开启溢出检测模式，开启后会在输出vis文件中（`compare_{timestamp}.vis或build_{timestamp}.vis`）对每个溢出节点进行标记溢出等级，溢出等级说明参考[溢出等级说明](#312-溢出等级说明)                                                                                                                                | 否    |
+| -f 或 --fuzzy_match     | 是否开启模糊匹配，bool类型。模糊匹配说明参考[匹配说明](#311-匹配说明)                                                                                                                                                                                                             | 否    |
+| -cs 或 --complete_stack | 是否使用完整的堆栈信息，bool类型。默认使用精简的堆栈信息，数据量小有助于增加流畅度。完整堆栈和精简堆栈信息参考[堆栈信息说明](#72-堆栈信息说明)                                                                                                                                                                         | 否    |
+
+#### 3.1.1 匹配说明
+
+**注：dump名称 = 名称 + 调用次数**，例如Functional.matmul.2.forward，matmul是名称，2是调用次数
+
+1.默认匹配
+- 所有节点dump名称一致
+- 节点输入输出参数数量一致，参数type、shape一致
+- 节点的层级一致（父节点们一致）
+
+2.模糊匹配
+- Cell节点dump名称一致，两个匹配上的Cell节点, 忽略各自节点下所有api的dump调用次数，按照名称一致+Cell节点内的调用顺序进行匹配
+- ![fuzzy_match_ms.png](./img/visualization/fuzzy_match_ms.png)
+- 参数shape一致
+
+#### 3.1.2 溢出等级说明
+- medium：输入异常，输出正常场景
+- high：输入异常，输出异常；输出norm值相较于输入存在异常增大情况
+- critical：输入正常，输出异常场景
+
+#### 3.1.3 比对文件说明
 
-**比对文件说明**：
 以在当前目录创建 ./compare.json 为例。
 ```
 {
@@ -274,35 +303,71 @@ msprobe -f mindspore graph -i ./compare.json -o ./output
 ├── compare_stepn_rankn_{timestamp}.vis
 ```
 
+#### 3.2.4 仅模型结构比对
+
+适用场景：**主要关注模型结构而非训练过程数据**。例如，在模型迁移过程中，确保迁移前后模型结构的一致性，或在排查精度差异时，判断是否由模型结构差异所引起。
+
+使用msprobe工具对模型数据进行采集时，**可选择仅采集模型结构（task配置为structure）**，此配置将避免采集模型训练过程的数据，从而显著减少采集所需的时间。
+
+dump配置请参考[dump配置示例](./03.config_examples.md#35-task-配置为-structure)
+
+得到dump数据后，若需比较特定两个rank之间的数据，请参考[3.2.2 双图比对](#322-双图比对)；若需进行多个rank或多个step的数据批量比对，请参考[3.2.3 批量构建或比对](#323-批量构建或比对)。
+
+
 ## 4.启动tensorboard
 
+### 4.1 可直连的服务器
+
 将生成vis文件的路径**out_path**传入--logdir
 
 ```
 tensorboard --logdir out_path --bind_all --port [可选，端口号]
 ```
+启动后会打印日志:
+
+![tensorboard_1](./img/visualization/tensorboard_1.png)
 
-启动后会打印日志。
-``TensorBoard 2.15.1 at http://localhost.localdomain:6008/#graphs (Press CTRL+C to quit)``
-localhost.localdomain是机器地址，6008是端口号。
+ubuntu是机器地址，6008是端口号。
 
-**注意，localhost.localdomain需要替换为真实的服务器地址，例如真实的服务器地址为10.123.456.78，则需要在浏览器窗口输入http://10.123.456.78:6008/#graphs**
+**注意，ubuntu需要替换为真实的服务器地址，例如真实的服务器地址为10.123.456.78，则需要在浏览器窗口输入http://10.123.456.78:6008**
 
-**如果链接打不开(例如服务器无法直连需要挂vpn才能连接的场景)，可以尝试使用vscode连接服务器，在vscode终端输入：**
+### 4.2 不可直连的服务器
+**如果链接打不开（服务器无法直连需要挂vpn才能连接等场景），可以尝试使用vscode连接服务器，在vscode终端输入：**
 
 ```
 tensorboard --logdir out_path
 ```
+![tensorboard_2](./img/visualization/tensorboard_2.png)
 
-CTRL+C点击链接即可
+按住CTRL点击链接即可
 
 ## 5.浏览器查看
 
-推荐使用谷歌浏览器，在浏览器中输入机器地址+端口号回车，出现TensorBoard页面，右上方选择GRAPHS_ASCEND即可展示模型结构图。
+### 5.1 浏览器打开图
+推荐使用谷歌浏览器，在浏览器中输入机器地址+端口号回车，出现TensorBoard页面，其中/#graph_ascend会自动拼接。
+![vis_browser_1](./img/visualization/vis_browser_1.png)
+如果您切换了TensorBoard的其他功能，此时想回到模型分级可视化页面，可以点击左上方的**GRAPH_ASCEND**
+![vis_browser_2](./img/visualization/vis_browser_2.png)
+
+### 5.2 查看图
+![vis_show_info.png](./img/visualization/vis_show_info.png)
+
+### 5.3 名称搜索
+![vis_search_info.png](./img/visualization/vis_search_info.png)
+
+### 5.4 精度筛选
+![vis_precision_info.png](./img/visualization/vis_precision_info.png)
 
-节点需要双击打开。
+### 5.5 未匹配节点筛选
+节点匹配规则：
 
-键盘WS可放大缩小，AD可左右移动，鼠标滚轮可上下移动。
+1.名称一致
+
+2.节点输入输出参数数量一致，参数type、shape一致
+
+3.节点的层级一致（父节点们一致）
+
+![vis_unmatch_info.png](./img/visualization/vis_unmatch_info.png)
 
 ## 6.图比对说明
 
@@ -322,20 +387,6 @@ CTRL+C点击链接即可
 
 ``相对误差：abs（(npu统计值 - bench统计值) / bench统计值)``
 
-其中小值不使用相对误差来判断精度差异，而是使用**绝对误差**来判断精度差异
-
-**判定为小值的阈值：**
-
-   - float32：e-6
-   - float16：e-3
-   - bfloat16：e-3
-
-**小值域的绝对误差阈值：**
-
-   - float32：e-6
-   - float16：e-3
-   - bfloat16：e-3
-
 #### md5模式
 节点中任意输入输出的md5值不同。
 
@@ -366,13 +417,6 @@ PipelineCell:
 
 Cell:
   network_with_loss: module
-
-layers:                           # 手动映射MindSpore与PyTorch模型代码中的Layer层序号
-  '5': '0'
-  '6': '1'
-  '7': '2'
-  '8': '3'
-  '9': '4'
 ```
 
 Layer层名称需要从模型代码中获取。
@@ -382,3 +426,67 @@ yaml文件中只需配置MindSpore与PyTorch模型代码中功能一致但名称
 模型代码示例：
 
 ![ms_dump](./img/ms_layer.png)
+
+### 7.2 堆栈信息说明
+
+**精简堆栈**
+
+保留一条当前模块或api的调用信息
+
+```json
+{
+    "Cell.model.language_model.embedding.word_embeddings.reduce_scatter_to_sp_region.ReduceScatterToSequenceParallelRegion.forward.0": [
+        "File /home/mindformers/experimental/distri_cores/tensor_parallel/layers.py, line 770, in construct, \n output = self.reduce_scatter_to_sp_region(output_parallel)"
+        ]
+}
+```
+
+**完整堆栈**
+
+当前模块或api完整的调用信息
+
+```json
+{
+    "Cell.model.language_model.embedding.word_embeddings.reduce_scatter_to_sp_region.ReduceScatterToSequenceParallelRegion.forward.0": [
+        "File /home/mindspore/nn/cell.py, line 507, in _run_construct, \n output = self._run_forward_hook(inputs, output)",
+        "File /home/mindspore/nn/cell.py, line 759, in _complex_call, \n output = self._run_construct(*args, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 747, in __call__, \n return self._complex_call(*args, **kwargs)",
+        "File /home/mindformers/experimental/distri_cores/tensor_parallel/layers.py, line 770, in construct, \n output = self.reduce_scatter_to_sp_region(output_parallel)",
+        "File /home/mindspore/nn/cell.py, line 2462, in _backward_hook_construct, \n outputs = self.construct(outputs, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 498, in _run_construct, \n output = self._backward_hook_construct(*inputs, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 745, in __call__, \n return self._run_construct(*args, **kwargs)",
+        "File /home/mindformers/experimental/distri_cores/transformer/language_model.py, line 151, in construct, \n embeddings = self.word_embeddings(input_ids)",
+        "File /home/mindspore/nn/cell.py, line 2460, in _backward_hook_construct, \n outputs = self.construct(*outputs, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 498, in _run_construct, \n output = self._backward_hook_construct(*inputs, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 745, in __call__, \n return self._run_construct(*args, **kwargs)",
+        "File /home/mindformers/experimental/distri_cores/transformer/language_model.py, line 391, in construct, \n text_embedding_out = self.embedding(enc_input_ids, enc_position_ids,",
+        "File /home/mindspore/nn/cell.py, line 2460, in _backward_hook_construct, \n outputs = self.construct(*outputs, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 498, in _run_construct, \n output = self._backward_hook_construct(*inputs, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 745, in __call__, \n return self._run_construct(*args, **kwargs)",
+        "File /home/model/gpt_model.py, line 104, in construct, \n lm_output = self.language_model(tokens,",
+        "File /home/mindspore/nn/cell.py, line 2460, in _backward_hook_construct, \n outputs = self.construct(*outputs, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 498, in _run_construct, \n output = self._backward_hook_construct(*inputs, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 745, in __call__, \n return self._run_construct(*args, **kwargs)",
+        "File /home/mindformers/experimental/distri_cores/pipeline_parallel/pipeline_cell.py, line 429, in construct, \n return self.model(*inputs)",
+        "File /home/mindspore/nn/cell.py, line 757, in _complex_call, \n output = self.construct(*args, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 747, in __call__, \n return self._complex_call(*args, **kwargs)",
+        "File /home/mindformers/experimental/distri_cores/pipeline_parallel/schedules.py, line 121, in run_forward, \n output_tensor = model(*input_data, recv_data=None)",
+        "File /home/mindformers/experimental/distri_cores/pipeline_parallel/schedules.py, line 735, in forward_backward_pipelining_without_interleaving, \n micro_input_data = run_forward(*micro_input_data,",
+        "File /home/mindformers/experimental/distri_cores/training.py, line 409, in forward_backward_with_pipelining, \n loss, logits, grads = forward_backward_pipelining_without_interleaving(",
+        "File /home/mindformers/experimental/distri_cores/training.py, line 533, in construct, \n (loss, _), grads = self.forward_backward_func(*inputs_tuple, loss_scale=current_step_loss_scale, **inputs_dict)",
+        "File /home/mindspore/nn/cell.py, line 757, in _complex_call, \n output = self.construct(*args, **kwargs)",
+        "File /home/mindspore/nn/cell.py, line 747, in __call__, \n return self._complex_call(*args, **kwargs)",
+        "File /home/mindformers/experimental/distri_cores/training.py, line 655, in train, \n loss, is_finite, loss_scale, learning_rate = train_one_step_cell(**data)",
+        "File /home/model/pretrain_gpt.py, line 303, in main, \n train(",
+        "File /home/model/pretrain_gpt.py, line 316, in <module>, \n main()"
+        ]
+}
+```
+# FAQ
+1. 图比对场景，节点呈现灰色，且没有精度比对数据，怎么处理？
+
+节点呈现灰色，代表左边待调试侧节点与右边标杆侧节点没有匹配上，可能有以下几点原因：
+
+- **标杆侧确实没有能与待调试侧匹配上的节点**，属于代码实现上的差异，请确认此差异是否正常，是否会影响到整网精度。
+- **节点的输入或输出type、shape不一致，参数个数不一致，节点所在层级的父层级不一致**，导致节点无法匹配，具体匹配规则见[匹配说明](#311-匹配说明)，可尝试使用模糊匹配功能，如何使用此功能请参考[构图命令行说明](#31-构图命令行说明)。如果是参数shape不一致，即使是模糊匹配功能也无法让节点匹配上，请检查参数shape不一致是否合理。
+- **节点名称不一致**，导致节点无法匹配，可使用layer mapping功能，如何使用此功能请参考[构图命令行说明](#31-构图命令行说明)，如何自定义映射文件请参考[模型分级可视化如何配置layer mapping映射文件](./visualization/layer_mapping_example.md)。

msprobe/docs/23.generate_operator_PyTorch.md

@@ -0,0 +1,107 @@
+# 单算子API自动生成脚本
+
+## 1 简介
+
+单算子API自动生成脚本通过提取dump数据中的可疑算子，对其进行单API复现，输出单API精度的比对结果。具体而言，该工具可以从dump数据中提取可疑API的前反向信息，根据前反向数据生成单API的前反向过程，最后通过**新精度标准比对法**<sup>a</sup>将 NPU/GPU 和 CPU 的结果进行比对，从而给出不同比对方法下的比对结果。本工具支持**随机生成模式和真实数据模式**<sup>b</sup>。
+
+a. 依据新精度标准，对不同的API采取不同的比对算法（包括绝对阈值法、标杆比对法、二进制一致法、ULP误差比对法和双千指标法），最终给定比对结果；
+
+b. 在生成单API脚本时可以选择由工具构造随机数获得 dump 数据或选择真实输入的数据进行单API复现。随机生成模式（对应 task: "statistics"）执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式（对应 task: "tensor"）执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。
+
+## 2 使用方式
+
+### 前提
+1. 安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。
+2. 已完成对训练过程的dump，获得dump.json文件。
+   [PyTorch场景的数据采集](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/05.data_dump_PyTorch.md)
+   
+   **目前仅支持复现API级的数据，故dump时level可选择L0（API信息）或者mix（module信息+API信息）。如需复现真实数据场景的API脚本，dump时task应选择tensor，如需复现随机数据场景的API脚本，dump时task选择statistics**。
+3. 发现某个算子疑似存在精度问题，并得知算子名，如Functional.softmax.3、Tensor.add.0、Torch.matmul.5等
+
+### 2.1 配置config_op.json
+单API复现参数配置如下（以复现softmax算子为例）：
+```
+{
+    "dump_json_path": "./dump.json",
+    "api_name": "Functional.softmax.0",
+    "extract_api_path": "./Functional.softmax.0.json",
+    "propagation": "forward", 
+    "data_mode": "random_data", 
+    "random_seed": 1234, 
+    "iter_times": 1
+}
+```
+**配置文件参数说明**
+
+   | 参数名称                     | 解释                                                         | 是否必选                           |
+   | ---------------------------- | ------------------------------------------------------------ | ---------------------------------- |
+   | dump_json_path   | dump.json的文件路径，包含所有dump算子的信息；如果已经提取了可疑算子并保存可以不指定。                                   | 否                                 |
+   | api_name             | 算子名，如Functional.softmax.3、Tensor.add.0、Torch.matmul.5等。如果已经提取了可疑算子并保存可以不指定                            | 否                                 |
+   | extract_api_path               | 提取可疑算子的json文件路径 | 是                                 |
+   | propagation | 选择复现算子的forward还是backward，默认为forward                                                | 否                                 |
+   | data_mode                 | 选择复现算子的随机数据（random_data）还是真实数据（real_data）模式，默认为random_data           | 否                                 |
+   | random_seed | 仅random_data模式有效，表示手动设定的随机种子，默认为1234 | 否 |
+   | iter_times             | 仅random_data模式有效，表示单API运行的次数 | 否                                 |
+
+ ### 2.2 运行命令生成单API脚本
+config_op.json配置好后，运行如下命令：
+```
+msprobe -f pytorch op_generate -i ./config.json -o ./
+```
+或者
+
+进入到mstt的generate_op_script文件夹
+```
+cd mstt/debug/accuracy_tools/msprobe/pytorch/api_accuracy_checker/generate_op_script
+```
+运行
+```
+python op_generator.py -i ./config_op.json -o ./
+```
+**参数说明**
+   | 参数名称                     | 解释                                                         | 是否必选                           |
+   | ---------------------------- | ------------------------------------------------------------ | ---------------------------------- |
+   | -i 或 --config_input   | config_op.json的路径                                   | 是                                 |
+   | -o 或 --api_output_path             | 单API脚本的输出路径                            | 是                                 |
+ 
+ ### 2.3 运行单API脚本
+ 运行完op_generator.py后，会在指定路径下生成api_name.py的单API脚本，例如Functional.softmax.3.backward.py、Tensor.add.0.forward.py、Torch.matmul.5.backward.py
+
+运行单API脚本即可获得不同比对方法下的比对结果
+```
+python api_name.py
+```
+
+**运行结果参数说明**
+| 字段                | 含义                                                         |
+| ------------------- | ------------------------------------------------------------ |
+| Shape            | 单API输出结果的shape       |
+| Dtype of out_device         | NPU 或 GPU 数据的 API 数据类型。                                      |
+| Dtype of out_bench        |   标杆数据的 API 数据类型。    |
+| Compare Standard               |  比对方法（包括绝对阈值法，标杆比对法、二进制一致法、ULP误差比对法和双千指标法          |
+| Relative Error Ratio          | 相对误差错误率。NPU 与标杆的正常值计算相对误差，其大于错误阈值的元素个数占正常值元素个数的比例。绝对阈值法指标。       |
+| 相对误差判定结果         | 相对误差错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 |
+| Absolute Error Ratio        | 绝对误差错误率。NPU 与标杆的小值计算绝对误差，其大于错误阈值的元素个数占小值元素个数的比例。绝对阈值法指标。NPU 或 GPU 数据与标杆数据的最大绝对误差。   |
+| 绝对误差判定结果         | 绝对误差错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 |
+| Small Value Error Proportion            | 小值域错误比值。NPU 与 CPU 的小值域的错误比率 / GPU 与 CPU 的小值域的错误比率。标杆比对法指标。 |
+| 小值域错误判定结果       | 小值域错误比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 warning，大于 2 标记为 error。 |
+| Maximum Relative Error           | 相对误差最大值比值。NPU 与 CPU 的相对误差最大值 / GPU 与 CPU 的相对误差最大值。标杆比对法指标。 |
+| 相对误差最大值判定结果   | 相对误差最大值比值小于等于 1 标记为 pass，1 ~ 10 之间标记为 warning，大于 10 标记为 error。 |
+| Mean Relative Error            | 相对误差平均值比值。NPU 与 CPU 的相对误差的平均值 / GPU 与 CPU 的相对误差的平均值。标杆比对法指标。 |
+| 相对误差平均值判定结果   | 相对误差平均值比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 warning，大于 2 标记为 error。 |
+| Root Mean Squared Error    | 均方根误差比值。NPU 与 CPU 的均方根误差 / GPU 与 CPU 的均方根误差。标杆比对法指标。 |
+| 均方根误差判定结果       | 均方根误差比值小于等于 1 标记为 pass，1~2 之间标记为 warning，大于 2 标记为 error。 |
+| Error Balance    | 误差均衡性比值。NPU 与 CPU 的误差均衡性 / GPU 与 CPU 的误差均衡性。标杆比对法指标。 |
+| 误差均衡性判定结果       | 误差均衡性比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 warning，大于 2 标记为 error。 |
+| Error Rate    | 二进制一致错误率。NPU 或 GPU 数据中每个 Tensor 精度不一致的数值的数量与 Tensor 中数值数量的比值。只有数据是 builtin 类型（bool、int、float、str）、torch.bool 和 torch 的 int 类型或者在新精度标准中使用二进制一致算法进行比对的 API 才会展示。二进制一致法指标。 |
+| 二进制一致错误率判定结果 | 二进制一致错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 |
+| Maximum ULP Error    | ULP 误差最大值<sup>a</sup>。NPU 数据与标杆数据 ULP 误差的最大值（取绝对值后）。 |
+| Mean ULP Error    | ULP 误差平均值<sup>a</sup>。NPU 数据与标杆数据 ULP 误差的平均值（取绝对值后）。 |
+| ULP Error Proportion    |ULP 误差大于阈值占比比值<sup>a</sup>。NPU 与 CPU 的 ULP 误差大于阈值占比 / GPU 与 CPU 的 ULP 误差大于阈值占比。 |
+| ULP 误差判定结果          | ULP 误差判定结果。<br/>     当 NPU 或 GPU 数据类型是 float16 或 bfloat16 时，以下两条标准满足其一标记为 pass，否则标记为 error：<br>          NPU ULP 误差大于阈值占比小于 0.001；<br/>          NPU ULP 误差大于阈值占比小于 GPU ULP 误差大于阈值占比。<br/>     当 NPU 或 GPU 数据类型是 float32 时，以下三条标准满足其一标记为 pass，否则标记为 error：<br/>          NPU ULP 误差平均值小于 64；<br/>          NPU ULP 误差大于阈值占比小于 0.05；<br/>          NPU ULP 误差大于阈值占比小于 GPU ULP 误差大于阈值占比。 |
+| Thousandth ratio    |双千精度指标。是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的个数占总元素个数的比例。测试通过标准为相对误差大于千分之一的个数占总元素个数的比例小于千分之一。仅 conv1d 和 conv2d 使用该指标。双千指标法指标。 |
+| 双千指标判定结果         | 双千指标判定结果。双千指标大于 0.999 标记为 pass，否则标记为 error。 |
+
+a：误差比对法指标。
+
+最终判定单API是否符合精度标准由开发者通过**算子精度标准**判断。

msprobe/docs/24.code_mapping_Mindspore.md

@@ -0,0 +1,28 @@
+# MindSpore 场景的数码关联工具
+
+数码关联工具，用于 MindSpore 静态图场景下将IR图与dump数据进行关联，获取 dump 数据和代码调用栈的关联关系。
+
+## 安装
+
+请参见[《msprobe 工具安装指南》](./01.installation.md)。
+
+
+## 功能说明
+
+数码关联是指数据和代码调用栈的关联，数据一般意义上指静态图`O0`,`O1`,`O2`下dump下来的数据。
+
+IR图使用推荐：IR图推荐使用`anf_after_graph_build`图。
+
+命令格式：
+
+```
+msprobe -f mindspore code_mapping --ir <ir_file> --dump_data <dump_data> [--output <output_path>]
+```
+
+
+| 参数名称     | 说明                                                                                                                                        |参数类型    | 是否必选     |
+| ---------------------------- |-------------------------------------------------------------------------------------------------------------------------------------------|---------------------- | ---------------------------------- |
+| --ir   | 指定 MindSpore 静态图运行时生成的IR图文件。                                                                                                              |  str      | 是      |
+| --dump_data    | 指定dump数据文件（支持tensor或statistic模式的dump数据）。可指定单个dump数据 文件或dump数据文件的父目录，指定父目录表示关联目录下的所有dump数据文件。                                              |   str   | 是      |
+| --output | 关联结果输出目录，默认为"./"，只在tensor模式时生效，会把数据文件路径和代码调用栈的关联关系存到output路径下的code_mapping_{时间戳}.csv中。如果关联的是statistic模式，则会把statistic.csv中每个条目加上该条目对应的代码栈。 |  str   | 否      |
+

msprobe/docs/{23.tool_function_introduction.md → 25.tool_function_introduction.md}

@@ -15,6 +15,7 @@
 | [在线精度比对<br>（online_dispatch）](./18.online_dispatch.md)                             | 训练过程中直接完成NPU和CPU的精度比对并输出比对结果。                                 | 1、执行一次就可获取NPU和CPU分别执行后的精度比对结果                                            | 暂无                                                                                                              |
 | [训练状态监控<br>（monitor）](./19.monitor.md)                                             | 收集模型训练过程中的激活值、梯度和优化器状态，助力分析计算、通信、优化器各部分异常情况。                  | 1、通过监控模块级统计量指标，快速定位异常模块位置，如loss出现nan                                     | 1、仅支持模块级别统计量指标分析<br>2、仅支持megatron、deepspeed框架<br>3、少量增加时间和显存膨胀                                                  |
 | [可视化比对<br>（visualization） ](./21.visualization_PyTorch.md)                         | 解析dump的精度数据，还原模型图结构，比对各层级精度数据，助力理解模型结构、分析精度问题。                | 1、整网精度比对定位可疑算子，通过浏览器展示比对结果，支持快速搜索到可疑算子<br>2、支持查看模型层级结果，比对模型层级结构差异        | 1、由于使用整网dump数据，定位的可疑算子受累计误差影响<br>2、当模型规模较大时，比对所需时间较长                                                            |
+| [单API自动生成脚本<br>（generate_operator） ](./23.generate_operator_PyTorch.md)                         | 解析dump的精度数据，提取可疑的API算子，自动生成单API复现脚本，并根据不同的API采用不同的比对算法，给定最终比对结果数据；帮助开发者分析算子精度问题。                | 1、该工具支持从整网dump下来的数据中提取可疑算子，并自动生成单API脚本<br>2、除了支持复现单API的前反向过程，同时会根据不同的API选择不同的比对方法，并给出比对结果                 |1、不支持通信算子<br>2、融合算子需手动修改脚本进行适配<br>3、目前比对的标杆均为和CPU进行比对，暂不支持直接NPU和GPU比对
 
 ## 2 MindSpore框架