mindstudio-probe 1.3.0__py3-none-any.whl → 8.1.1__py3-none-any.whl

msprobe/docs/33.generate_operator_MindSpore.md

@@ -0,0 +1,181 @@
+# 单算子API自动生成脚本
+
+## 1 简介
+
+单算子API自动生成脚本通过提取dump数据中的可疑算子，对其进行单API复现，输出单API精度的比对结果。具体而言，该工具可以从dump数据中提取可疑API的前反向信息，根据前反向数据生成单API的前反向过程，最后通过**新精度标准比对法**<sup>a</sup>将 NPU 和 CPU 的结果进行比对，从而给出不同比对方法下的比对结果。本工具支持**随机生成模式和真实数据模式**<sup>b</sup>。
+
+a. 在生成单API脚本时可以选择由工具构造随机数获得 dump 数据或选择真实输入的数据进行单API复现。随机生成模式（对应 task: "statistics"）执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式（对应 task: "tensor"）执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。
+
+## 2 使用方式
+
+### 前提
+1. 安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。
+2. 已完成对训练过程的dump，获得dump.json文件。
+    [MindSpore 场景下的数据采集](./06.data_dump_MindSpore.md)章节或[Msadapter 场景下的数据采集](./29.data_dump_MSAdapter.md)章节，注意需要配置 level="L1"。
+
+3. 发现某个算子疑似存在精度问题，并得知算子名，如Mint.split.1、Functional.softmax.3、Tensor.add.0、Torch.matmul.5等,要求API入参与torch场景相同。
+
+4.（可选）当需要使用Msadapter时，由于需要环境中同时存在 Torch 与 Msadapter，所以只支持在**安装原生Torch**的场景下通过export PYTHONPATH="xx/msadapter/build/lib"等通过**环境变量使能Msadapter的方式**的环境中进行预检,预检工具能够自动索引得到所需的 Torch 与 Msadapter环境,环境安装详细参考:[msadapter官网](https://gitee.com/mindspore/msadapter)。
+
+### 2.1 dump.json 示例（由dump生成）
+```
+{
+    "task": "statistics",
+    "level": "L1",
+    "framework": "mindtorch",
+    "dump_data_dir": null,
+    "data": {
+        "Tensor.reshape.779.forward": {
+            "input_args": [
+             {
+              "type": "mindspore.Tensor",
+              "dtype": "BFloat16",
+              "shape": [
+               8192,
+               896
+              ],
+              "Max": 0.62890625,
+              "Min": -0.78515625,
+              "Mean": 0.00035858154296875,
+              "Norm": 105.0
+             },
+             {
+              "type": "int",
+              "value": -1
+             },
+             {
+              "type": "int",
+              "value": 896
+             }
+            ],
+            "input_kwargs": {},
+            "output": [
+             {
+              "type": "mindspore.Tensor",
+              "dtype": "BFloat16",
+              "shape": [
+               8192,
+               896
+              ],
+              "Max": 0.62890625,
+              "Min": -0.78515625,
+              "Mean": 0.00035858154296875,
+              "Norm": 105.0
+             }
+            ]
+           },
+           "Tensor.reshape.779.backward": {
+            "input": [
+             {
+              "type": "mindspore.Tensor",
+              "dtype": "BFloat16",
+              "shape": [
+               8192,
+               896
+              ],
+              "Max": 0.0,
+              "Min": 0.0,
+              "Mean": 0.0,
+              "Norm": 0.0
+             }
+            ],
+            "output": [
+             {
+              "type": "mindspore.Tensor",
+              "dtype": "BFloat16",
+              "shape": [
+               8192,
+               896
+              ],
+              "Max": 0.0,
+              "Min": 0.0,
+              "Mean": 0.0,
+              "Norm": 0.0
+             }
+            ]
+           }
+        }
+    }
+```
+
+### 2.2 配置config_op.json
+单API复现参数配置如下（以复现softmax算子为例）：
+```
+{
+    "dump_json_path": "./dump.json",
+    "api_name": "Tensor.reshape.779",
+    "extract_api_path": "Tensor.reshape.779",
+    "propagation": "backward",
+    "data_mode": "random_data",
+    "random_seed": 42,
+    "iter_times": 1
+}
+```
+**配置文件参数说明**
+
+   | 参数名称                     | 解释                                                                                                                                                    | 
+   | ---------------------------- |-------------------------------------------------------------------------------------------------------------------------------------------------------| 
+   | dump_json_path   | dump.json的文件路径，包含所有dump算子的信息；如果已经提取了可疑算子并保存可以不指定。                                                                                                     |
+   | api_name             | 算子名（目前MindSpore支持类型包括：Mint，Tensor，Msadapter支持类型包括：Tensor，Functional，Torch类中可自动求导api），如Mint.split.1，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模式有效，表示手动设定的随机种子，默认为42                                                                                                                    | 
+   | iter_times             | 仅random_data模式有效，表示单API运行的次数，由于安全相关原因，最大支持设置为1000                                                                                                     |
+
+ ### 2.3 运行命令生成单API脚本
+config_op.json配置好后，运行如下命令：
+```
+msprobe -f mindspore op_generate -i ./config_op.json -o ./
+```
+
+**参数说明**
+   | 参数名称                     | 解释                                                         | 是否必选                           |
+   | ---------------------------- | ------------------------------------------------------------ | ---------------------------------- |
+   | -i 或 --config_input   | config_op.json的路径                                   | 是                                 |
+   | -o 或 --api_output_path             | 单API脚本的输出路径                            | 是                                 |
+ 
+### 2.4 运行单API脚本
+ 运行完op_generator.py后，会在指定路径下生成api_name.py的单API脚本，例如Mint.split.1.forward.py、Functional.softmax.3.backward.py、Tensor.add.0.forward.py、Torch.matmul.5.backward.py
+
+运行单API脚本即可获得不同比对方法下的比对结果
+```
+python api_name.py
+```
+
+**运行结果说明**
+
+单算子脚本生成到路径`./op_result_output`的 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 文件内容详情如下：
+
+`accuracy_checking_details_{timestamp}.csv`
+
+| 字段      | 含义       |
+| ------------------- | ------------------------------------------------------------ |
+| API Name            | API 名称。                                        |
+| Bench Dtype         | 标杆数据的 API 数据类型。      |
+| Tested Dtype        | 被检验数据的 API 数据类型。                                  |
+| Shape               | API 的 Shape 信息。       |
+| Cosine              | 被检验数据与标杆数据的余弦相似度。                         |
+| MaxAbsErr           | 被检验数据与标杆数据的最大绝对误差。                       |
+| MaxRelativeErr      | 被检验数据与标杆数据的最大相对误差。                     |
+| Status              | API 预检通过状态，pass 表示通过测试，error 表示未通过。 |
+| Message             | 提示信息。            |
+
+注意：PyTorch 无法对 dtype 为整数类型的 tensor 进行反向求导，而 MindSpore 支持。反向过程的预检仅比较 dtype 为浮点型的输出。
+
+`accuracy_checking_result_{timestamp}.csv`
+
+| 字段                  | 含义      |
+| --------------------- | ----------------- |
+| API Name              | API 名称。         |
+| Forward Test Success  | 前向 API 是否通过测试，pass 为通过，error 为错误。 |
+| Backward Test Success | 反向 API 是否通过测试，pass 为通过，error 为错误，如果是空白的话代表该 API 没有反向输出。 |
+| Message               | 提示信息。         |
+
+Forward Test Success 和 Backward Test Success 是否通过测试是由 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差判定结果决定的。具体规则详见 [4.1 API 预检指标](#41-api-预检指标)。
+需要注意的是 `accuracy_checking_details_{timestamp}.csv` 中可能存在一个 API 的前向（反向）有多个输出，那么每个输出记录一行，而在 `accuracy_checking_result_{timestamp}.csv` 中的结果需要该 API 的所有结果均为 pass 才能标记为 pass，只要存在一个 error 则标记 error。
+
+### 3.1 API 预检指标
+
+   - API 预检指标是通过对 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差的数值进行判断，得出该 API 是否符合精度标准的参考指标。
+   - 余弦相似度大于 0.99，并且最大绝对误差小于 0.0001，标记“pass”，否则标记为“error”。

msprobe/docs/34.RL_collect.md

@@ -0,0 +1,92 @@
+# 强化学习数据采集
+
+## 介绍
+在强化学习训练过程中，往往存在多个模型（actor、reward、reference）和两个阶段（推理、训练），问题定界困难。
+
+本工具提供一种灵活存储强化学习训练过程中关键阶段性数据的能力，并支持对比两次采集的关键数据，以支持问题快速定界。
+
+常用关键数据示例：prompt、response、reward、log_prob、ref_log_probe、old_log_probe、kl_loss。
+
+
+## 安装教程
+
+参见 msprobe [安装教程](./01.installation.md)。
+
+## 使用说明
+
+### 数据采集
+
+用户识别脚本中需要采集数据的地方，然后通过插入代码的方式采集关键数据。
+
+当确定需要采集数据的地方，例如response，可以按如下方式对数据进行存储：
+```
+from msprobe.core import SingleSave
+SingleSave("./dump_path", fmk="pytorch")
+SingleSave.save({"response": response})
+```
+其中"./dump_path"为输出路径，没有默认值，需要自己配置；fmk可选"pytorch"或者"mindspore"，默认"pytorch"。
+
+其中"response"是可以任意指定的key，response是训练过程中的真实tensor变量。
+
+也支持一次性存储多个数据：
+```
+from msprobe.core import SingleSave
+SingleSave("./dump_path", fmk="pytorch")
+SingleSave.save({
+    "prompt": prompt,
+    "response": response
+    })
+```
+
+### 配置保存
+
+当确定需要采集数据配置json的地方，可以按如下方式对配置进行存储：
+```
+from msprobe.core import SingleSave
+SingleSave("./dump_path")
+SingleSave.save_config(configurations_json)
+```
+
+
+采集到的数据目录结构如下：
+```txt
+dump_path/
+├── data/ # 固定为data
+│   └── response/  # 关键数据名称，来自SingleSave.save的时候的key
+│           └── step0/  # step数
+│               └── rank0/   # rank数
+│                     └── micro_step0/   #micro_step数
+|                              └── response0.npy   #存储的关键数据的真实npy文件
+|                              └── response0.json  #存储的关键数据的统计量文件，包括tensor的最大、最小、均值、norm、shape
+├── configurations.json  # 配置json文件
+```
+
+### 结果比对
+
+两次采集数据之后得到dump_path1和dump_path2，可以创建一个比对脚本，例如compare.py，将两次训练的dump_path传入：
+```
+from msprobe.core import SingleComparator
+SingleComparator.compare(
+    "dump_path1", 
+    "dump_path2", 
+    "output_path")
+```
+
+会在output_path下对每种关键数据都生成excel结果表格，比如response.xlsx，形式为关键数据的名字加上.xlsx后缀。
+
+表格会体现每一个对应tensor的差异，解释：
+
+表头 | 解释 |
+|-------|---------|
+| step | 训练步数 |
+| rank | 卡号 |
+| micro_step | 梯度累计步数 |
+| id | 参数的shape |
+| shape1 | dump_path1中的数据形状 |
+| shape2 | dump_path2中的数据形状 |
+| 相同元素百分比 | 元素相同的个数占总元素个数的百分比 |
+| 首个不匹配元素索引 | 首个匹配不上的元素是第几个 |
+| 最大绝对误差 | 最大绝对误差 |
+| 最大相对误差 | 最大相对误差 |
+| 误差在千分之一内元素占比 | 误差在千分之一内元素个数占总元素个数的百分比 |
+| 误差在百分之一内元素占比 | 误差在百分之一内元素个数占总元素个数的百分比 |

msprobe/docs/35.nan_analyze.md

@@ -0,0 +1,72 @@
+# 整网首个溢出节点分析
+
+## 介绍
+在分析inf、nan的场景下，会采集多个rank下的多个step的dump数据，前面出现的异常会传播到同rank后续的节点，并通过通信算子传播到其他rank的后续节点中，因此如何分析首个nan出现的节点位置尤为重要。
+
+通过nan_analyze工具可以对pytorch的dump数据进行分析。在多卡场景下，检测到每张卡中产生inf/nan的节点。若是经过通信导致的inf/nan，可以分析并找出首个产生inf/nan的rank和节点。
+
+## 安装教程
+
+参见 msprobe [安装教程](./01.installation.md)。
+
+## 使用说明
+
+当前仅支持分析pytorch的dump数据。
+
+### 采集数据
+
+参见 [PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)。
+
+### 执行命令
+
+```commandline
+msprobe -f pytorch nan_analyze -i dump_step_path -o output_dir_path
+```
+
+| 参数                 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| -i 或 --input_path  | dump数据的目录。需指定到step层级，如`-i /xxx/dump/step0/` |
+| -o 或 --output_path | 输出文件的目录，可选，不填时默认在当前目录下创建 \"./output/" 目录。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+
+### 输出文件介绍
+
+当日志打印
+```
+Cannot find any anomaly node, no need to generate analyze file.
+```
+时，分析认为不存在异常节点，不生成分析文件。
+
+存在异常节点时，生成`anomaly_analyze_{timestamp}.json`文件，结构为：
+```json
+{
+  "rank_0": [  // 卡号
+    {
+      "op_name": "Tensor.op_name.0.forward",  // 节点名
+      "data_info": {
+        "input_args": [],  // input_args数据
+        "input_kwargs": {},  // input_kwargs数据
+        "output": []  // output数据
+      },
+      "construct_info": [],  // 节点层级数据
+      "stack_info": {}   // 堆栈数据
+    }
+  ]
+}
+```
+
+## 异常判定
+
+### 异常计算节点判定
+当某个计算节点的输入值正常，即Max或Min中不存在inf或nan，而输出值存在异常时认为从此节点开始产生了溢出，并有可能向后传递。
+
+### 异常通信节点判定
+通信节点按照功能分为有向节点，如`send`, `recv`, `scatter`, `gather`, `broadcast`, `reduce`等，以及无向节点，如`all_gather`, `all_reduce`, `reduce_scatter`, `all_to_all`等。
+
+对于有向节点，当src节点的input存在异常时，通常认为传入的数据中本身就存在异常，因此考虑异常节点发生在src节点所在rank的上一个或多个计算节点中；当src节点的input正常而output存在异常值，或dst节点的output存在异常值时，考虑是通信节点本身的操作产生了异常数据。
+
+对于无向节点，当节点input存在异常时，认为传入的数据中本身就存在异常，因此考虑异常节点发生在src节点所在rank的上一个或多个计算节点中；当input正常而output异常时，考虑是通信节点本身的操作产生了异常数据。
+
+### 顺序判定
+对于相连接的有向通信算子，认为src节点的异常发生早于dst节点；对于无向通信算子，认为异常是同时发生的。
+
+对于计算节点按照dump的顺序排序。

msprobe/docs/data_dump_MindSpore/data_dump_MindSpore_baseline.md

@@ -1,6 +1,17 @@
 # MindSpore 场景的精度数据采集基线
 
-## "tensor"模式采集数据量参考基线
+## "statistics"模式（未开启md5）采集**时间**膨胀参考基线
+
+该基线为MindSpore框架下，使用"statistics"模式采集数据性能膨胀参考基线。测试了38B语言大模型在不同采集模式8卡下的性能膨胀。
+
+| 采集模式 | 无工具 (耗时) |  加工具但未使能 Dump (耗时)   | 加工具并使能 Dump (耗时) |
+|:--------:|:-------------:|:--------------------:|:----------------:|
+| L0       | ≈340 ms       |    ≈340 ms （无膨胀）     | ≈1.2 s  （膨胀3.5倍） |
+| L1       | ≈340 ms       | ≈0.7–1.2 s  （膨胀2~4倍） | ≈3.8 s   （膨胀11倍） |
+| mix      | ≈340 ms       | ≈0.7–1.2 s  （膨胀2~4倍） | ≈5.5 s  （膨胀16倍）  |
+
+
+## "tensor"模式采集**数据量**参考基线
 
 该基线为MindSpore框架下，使用"tensor"模式采集数据量参考基线。本基线测试了38B语言大模型在不同采集模式下，不同global_batch_size下，单卡和8卡下，数据量的变化。
 

msprobe/docs/data_dump_MindSpore/dynamic_graph_quick_start_example.md

@@ -51,6 +51,7 @@ debugger = PrecisionDebugger(config_path=config_path)
 
 # 设置 MindSpore 设备上下文
 context.set_context(mode=ms.PYNATIVE_MODE, device_target="Ascend", device_id=0)
+print("Context set successfully. Please wait for the training task.")
 
 # 定义卷积层
 def conv_layer(in_channels, out_channels, kernel_size, stride=1, padding=0, pad_mode="valid", has_bias=True):
@@ -199,7 +200,7 @@ python alexnet_model.py
 
 ## 5. 数据分析
 
-在 `dump_path` 参数指定的路径下（本例中为 `./output`），会出现如下目录结构，后续精度数据分析操作可使用 msprobe 工具的精度预检和精度比对等功能，详细流程请参见[《msprobe使用手册》](../../README.md#2-精度预检)。：
+在 `dump_path` 参数指定的路径下（本例中为 `./output`），会出现如下目录结构，后续精度数据分析操作可使用 msprobe 工具的精度预检和精度比对等功能，详细流程请参见[《msprobe使用手册》](../../README.md#2-精度预检)。
 
 ```bash
 output/
@@ -208,4 +209,5 @@ output/
         ├── construct.json             # level为L0时，保存Cell的层级关系信息。当前场景为空
         ├── dump.json                  # 保存API前反向输入输出数据的统计量信息
         └── stack.json                 # 保存API的调用栈
+    ......
 ```

msprobe/mindspore/__init__.py

@@ -25,5 +25,4 @@ except ImportError:
 from msprobe.mindspore.debugger.precision_debugger import PrecisionDebugger
 from msprobe.mindspore.common.utils import seed_all, MsprobeStep, MsprobeInitStep
 from msprobe.mindspore.monitor.module_hook import TrainerMon
-
-os.environ["MS_HOOK_ENABLE"] = "on"
+from msprobe.mindspore.dump.graph_tensor_dump import save, save_grad