mindstudio-probe 8.3.2__py3-none-any.whl → 26.0.0a1__py3-none-any.whl

msprobe/docs/16.free_benchmarking_MindSpore.md

@@ -1,159 +0,0 @@
-# MindSpore 场景的无标杆比对
-
-## 1 简介
-* 本工具的目标是在没有标杆数据的情况下，检测模型训练中可能存在精度问题的 API 级别算子，并提供升精度接口进行快速验证。
-* 工具基于**数值病态分析理论**：对算子的输入增加很小的扰动、从而放大输出值异常现象；检测算子原始输出和扰动后输出间误差是否符合精度标准。
-
-* 该工具的**特点**有：
-    * 不依赖标杆模型，在线对比。
-    * 提供升精度接口，对可疑算子进行快速验证。
-* 推荐使用场景（针对**API 精度问题**）：
-    * **暂无标杆数据**，模型 Loss 异常，要做精度问题 API 排查。
-    * 低精度模型效果不如高精度，要做精度问题 API 排查。
-    * **验证低精度可疑 API**，确认升精度后是否对模型 Loss 有影响。
-* 该工具的约束
-    * 仅支持 MindSpore 动态图场景。支持的 API 类型为 ops、Tensor、mint 和 mint.nn.functional 类的非 inplace 计算 API，不支持 Primitive 和 Jit 类 API。
-    * 仅支持 输入输出向量为浮点数类型(BF16、FP16、FP32、FP64)的 API 比对。
-    * 建议配置白名单（设置 list），控制对少量 API 进行无标杆比对。比对 API 越多，性能和显存损耗越大。
-
-## 2 工具实现原理
-1. **扰动算子白名单**：根据 API 名，控制需要进行无标杆比对的 API。
-
-2. **扰动因子**：基于 mindspore.nn.Cell 的 hook 机制，在注册的 hook 函数中对算子输入进行特定类型扰动。
-
-3. **误差分析**：
-    * **check**: 在 hook 函数中二次执行算子得到扰动后的算子输出、计算扰动后输出与原始输出的相对误差，查看是否符合精度标准。
-    * **fix**: 需要做验证时，可以将升精度的输出替换原始输出，观察对模型 Loss 是否有影响。
-
-4. **精度风险算子**：不达标精度标准的，最终会在输出件中展示。
-
-## 3 操作指导
-
-```mermaid
-flowchart LR
-A0[安装msprobe工具]
-subgraph config.json配置
-A1[确定比对范围]
-A2[选择扰动因子]
-A3[选择处理方式]
-A1-->A2
-A2-->A3
-end
-B(在模型脚本中开启工具)
-C(启动模型训练)
-D(查看精度风险API\n观察模型Loss曲线)
-
-A0-->
-config.json配置-->B
-B-->C
-C-->D
-D-->config.json配置
-```
-工具的推荐使用思路是：
-
-1. 配置 config.json，选择无标杆比对任务，进行精度风险 API 的排查。
-
-2. 根据精度风险 API 输出件，修改 config.json 开启验证功能，观察模型loss曲线是否改善。
-
-### 3.1 安装msprobe工具
-参照 [msprobe安装](./01.installation.md)
-### 3.2 config.json配置
-修改 [config.json](../config.json) 的 task 类型为"**free_benchmark**"开启无标杆功能。支持的配置项详见[配置文件介绍](./02.config_introduction.md)，默认配置如下：
-```json
-{
-    "task": "free_benchmark",
-    "dump_path": "./dump_path", 
-    "rank": [],  
-    "step": [],  
-    "level": "L1", 
-
-    "free_benchmark": {
-        "list": [],
-        "fuzz_device": "npu",
-        "pert_mode": "improve_precision",
-        "handler_type": "check",
-        "fuzz_level": "L1",
-        "fuzz_stage": "forward"
-    }
-}
-```
-用户需根据自己的使用场景，对照[工具实现原理](#2-工具实现原理)中几个关键步骤进行配置
-####  3.2.1 确定比对范围
-
-<table>
-    <tr><th>参数</th><th>是否必选</th><th>可配置项</th><th>适用场景</th></tr>
-    <tr><td>list</td><td>否</td><td>自定义</td><td>需要通过指定 API 名来限制比对API个数 如：["mindspore.ops.bmm"] 会只对mindspore.ops.bmm API进行比对。</td></tr>
-    <tr><td rowspan="2">fuzz_stage</td><td rowspan="2">否</td><td>"forward"（默认）</td><td>需要进行 API <b>前向</b>计算的精度问题排查或验证。</td></tr>
-    <tr><td>"backward"</td><td>需要进行 API <b>反向</b>计算的精度问题排查，不支持反向验证（前向验证包括反向）。</td></tr>
-</table>
-
-####  3.2.2 选择扰动因子
-
-<table>
-    <tr><th>参数</th><th>是否必选</th><th>可配置项</th><th>适用场景</th></tr>
-    <tr><td rowspan="5">pert_mode</td><td rowspan="5">否</td><td>"improve_precision" （默认）</td><td>（常用）(可做验证) API 可能在<b>低精度</b>下有精度问题，扰动因子会将输入的低精度向量升精度。</td></tr>
-    <tr><td>"add_noise"</td><td>API 可能在<b>轻微扰动</b>下暴露精度问题，扰动因子会为输入向量增加一个极小值。</td></tr>
-    <tr><td>"bit_noise"</td><td>API 可能在<b>轻微扰动</b>下暴露精度问题，扰动因子会翻转输入向量的最后一个比特位。不支持BF16类型向量。</td></tr>
-    <tr><td>"no_change"</td><td>API 可能存在<b>数值稳定性</b>精度问题，扰动因子会复制原始输入。</td></tr>
-    <tr><td>"change_value"</td><td>API 可能存在<b>大数吃小数</b>问题，扰动因子会交换输入向量的首尾值。</td></tr>
-</table>
-
-####  3.2.3 选择处理方式
-
-<table>
-    <tr><th>参数</th><th>是否必选</th><th>可配置项</th><th>适用场景</th></tr>
-    <tr><td rowspan="2">handler_type</td><td rowspan="2">否</td><td>"check"（默认）</td><td>要做精度问题 API 排查，输出扰动前后不符合精度标准的 API，支持所有扰动因子。</td></tr>
-    <tr><td>"fix"</td><td>要做可疑 API 验证，用扰动后输出替换原始输出，仅支持 "improve_precision" 扰动因子。</td></tr>
-</table>
-
-### 3.3 在模型脚本中开启工具
-
-通过 PrecisionDebugger 统一接口开启工具，示例如下：
-
-```python
-import mindspore as ms
-ms.set_context(mode=ms.PYNATIVE_MODE, device_target="Ascend")
-
-# 其他模块的导入
-# ...
-
-from msprobe.mindspore import PrecisionDebugger
-debugger = PrecisionDebugger(config_path='./config.json')
-
-# 模型、损失函数的定义以及初始化等操作
-# ...
-model = Network()
-
-# 数据集迭代的地方往往是模型开始训练的地方
-for step, (input_ids, input_position, attention_mask) in enumerate(dataset.create_tuple_iterator()):
-    debugger.start() # 一般在训练循环开头启动工具
-    # 单步训练逻辑
-    # ...
-    debugger.stop() # 一般在训练循环末尾结束工具
-    debugger.step() # 在训练循环的最后需要重置工具，非循环场景不需要
-```
-
-### 3.4 查看精度风险算子
-
-check 模式下，若存在不符合精度标准的 API，则工具会在 dump_path 目录下将相应 API 信息输出在文件 free_benchmark.csv 中。csv 文件字段含义如下所示：
-
-| 字段         | 说明                                                                                     |
-| ------------ | ---------------------------------------------------------------------------------------- |
-| rank         | Rank ID，int 类型。                                                                       |
-| pert_mode    | 扰动因子的类型，string 类型。                                                              |
-| stage        | 前/反向，string 类型。                                                                    |
-| step         | 迭代数，int 类型。                                                                        |
-| api_name     | API 名称，string 类型。                                                                   |
-| max_rel      | 输出对比最大相对误差，float 类型。                                                         |
-| dtype        | 输入的 dtype，string 类型。                                                               |
-| shape        | 输入的 shape，tuple 类型。                                                                |
-| output_index | 如果输出为列表或元组，其中一个元素检测不一致，则会有该元素的 index，否则为空，int 类型。        |
-
-无标杆比对使用的精度标准如下：
-
-| 输出dtype          | 相对误差阈值 |
-| ------------------ | ------------ |
-| mindspore.bfloat16 | 0.004        |
-| mindspore.float16  | 0.002        |
-| mindspore.float32  | 0.0002       |
-| mindspore.float64  | 0.0002       |

msprobe/docs/17.grad_probe.md

@@ -1,205 +0,0 @@
-# Ascend模型梯度状态监测工具
-
-梯度状态监测工具提供了两种能力：
-
-- 将模型权重的梯度数据导出。这种功能可以将模型权重的梯度值以统计量的形式采集出来，用以分析问题。
-- 将两份梯度数据进行相似度对比。在有标杆问题中，可以确认训练过程中精度问题出现的step，以及抓取反向过程中的问题。
-
-工具支持PyTorch版本：2.0/2.1/2.2；支持MindSpore版本：r2.3。暂不支持deepspeed的ZeRO-1、ZeRO-2、ZeRO-3。
-
-## 工具特性
-
-- 使用便捷，仅需在训练流程里插入少量代码
-- 可以精准定位问题出现的step
-
-## 使用方式
-
-### 梯度数据导出
-
-1. 创建配置文件config.json，样例如下：
-
-   ```json
-   {
-    "task": "grad_probe",
-    "dump_path": "./dump_path",
-    "rank": [],
-    "step": [],
-    "grad_probe": {
-        "grad_level": "L1",
-        "param_list": [],
-        "bounds": [-1, 0, 1]
-    }
-   }
-   ```
-   > step指的是优化器被调用的次数（并非模型跑的step，某些step，例如loss为nan时，不会调用优化器）
-
-   **参数说明**
-
-   | 参数                       | 说明                          | 输入类型                     | 是否必选 |
-   |--------------------------------|-----------------------------------|-----------------|----------|
-   | task            | 填为"grad_probe"。 |  str | 是 |
-   | dump_path            | 输出目录。如果不存在就会创建一个新目录。 |  str | 是 |
-   | rank                   | rank id列表，在多卡场景下，表示需要导出梯度数据的进程的rank id。列表为空就表示导出所有rank的数据。默认为空。采集特定 rank 时，须指定为训练脚本中存在的 rank_id，可逐个配置，也可以指定范围。<br/>  **配置示例**："rank": [0, 1 , 2, "4-6"]。（MindSpore静态图模式下，当前暂不支持指定rank功能） | list[Union[int, str]] | 否       |
-   | step                   | step列表，表示需要导出数据的step列表。列表为空就表示导出所有step的数据。默认为空。采集特定 step 时，须指定为训练脚本中存在的 step，可逐个配置，也可以指定范围。<br/>  **配置示例**："step": [0, 1 , 2, "4-6"]。（MindSpore静态图模式下，当前暂不支持指定step功能） | list[Union[int, str]] | 否 |
-   | grad_level                  | 输出级别。决定导出数据的详细程度，级别越大导出数据越详细。可取值：L0, L1, L2。默认L1。|str  | 否     |
-   | param_list             | 权重名称列表，表示需要监控的权重。列表为空就表示监控所有权重。默认为空。 | List[str] | 否       |
-   | bounds                 | 区间列表，用来划分区间以统计数值的分布。需要保证由数据小到大排列，并且列表中的元素需要在int64取值范围内。可以使用默认值[-1, 0, 1]。 | List[float, int] | 否  |
-
-   **不同级别的level的导出数据**
-
-
-   | 级别 | 特征数据表头                                                 | 是否有方向数据 |
-   | ---- | ------------------------------------------------------------ | -------------- |
-   | L0   | ("param_name", "MD5", "max", "min", "norm", "shape")         | 否             |
-   | L1   | ("param_name", "max", "min", "norm", "shape")         | 是             |
-   | L2   | ("param_name", *intervals, "=0", "max", "min", "norm", "shape") | 是             |
-
-   intervals就是根据值分布bounds划分出的区间。
-   MindSpore静态图模式下，L0级别中暂不支持"MD5"
-
-   **方向数据解释**
-
-   因为模型的参数往往非常大，所以存储真实数据是不可接受的，这里折衷一下，只存储梯度数据的正负号（一个布尔值），也就是方向。
-
-   **bounds和值分布解释**
-
-   + 值分布：梯度数据落在各个区间的元素个数占总元素个数的比例。
-   + bounds：一个列表，用来划分出区间以统计值分布。例如传入bounds = [-10, 0, 10]，此时有一个 grad_value: Tensor = [9.3 , 5.4, -1.0, -12.3]，依据 bounds 划分出 (-inf, -10]、(-10, 0]、(0, 10]、(10, inf) 四个区间，然后统计grad_value里的数据落在每个区间内的个数，得到 1、1、2、0。如下图所示：
-
-   ![Alt text](./img/grad_probe_image-1.png)
-
-2. 插入代码。示例代码如下：
-
-- PyTorch框架：模型构造完成后，传入config.json的路径实例化一个PrecisionDebugger对象，然后调用debugger.monitor并将`模型`作为参数传入。
-```python
-from msprobe.pytorch import PrecisionDebugger
-debugger = PrecisionDebugger("config_json_path")
-debugger.monitor(model)
-```
-- MindSpore框架：优化器构造完成后，传入config.json的路径实例化一个PrecisionDebugger对象，然后调用debugger.monitor并将`优化器`作为参数传入。
-```python
-from msprobe.mindspore import PrecisionDebugger
-debugger = PrecisionDebugger("config_json_path")
-debugger.monitor(optimizer)
-```
-
-3. 结束监控（MindSpore静态图模式下需要）
-
-   在训练结束之后，调用stop接口
-
-```python
-debugger.stop()
-```
-
-### 输出结果
-**输出目录结构**（以level配置L2为例）
-
-```bash
-{dump_path}
-      ├── rank{rank_id}
-      │        ├── grad_summary_{step}.csv
-      │        ├── step{step}
-      │        │        ├── {param_name}.npy
-```
-+ rank_{rank_id}：在分布式场景下，会记录卡的rank_id。非分布式场景下，如果是CPU则记录进程号，如果是CPU或GPU则记录卡号
-+ grad_summary_{step}.csv：会分step记录每一步的梯度数据统计值。
-+ step_{step}：这个目录下会存放该step的梯度的方向数据。
-+ {param_name}.npy：模型参数的梯度方向数据。
-
-**grad_summary_{step}.csv**
-
-样例如下：
-
-![Alt text](./img/grad_probe_image.png)
-
-| 字段                  | 含义                                                         |
-| --------------------- | ------------------------------------------------------------|
-| Param_name            | 模型参数名称。                                                |
-| MD5                   | 梯度数据的MD5值。                                            |
-| (-inf, -0.01]...[0.01, inf) | 梯度值落在区间内的元素个数占总元素的比例。               |
-| =0                    | 梯度为0的元素个数占总元素的比例。                             |
-| Max                   | 最大值。                                                      |
-| Min                   | 最小值。                                                      |
-| Norm                  | L2norm值。                                                    |
-| Shape                 | 形状。                                                        |
-
-### 梯度相似度比对
-
-会根据所导出的权重，分step比对梯度相似度，输出每个权重的梯度相似度和总的梯度相似度。单个权重的梯度相似度为两份方向数据的重合度，总的梯度相似度为每个权重的梯度相似度按元素个数加权。
-
-#### 前提条件
-
-- 相同配置下，以Level为L1或L2分别采集npu和gpu环境下的梯度数据。
-- 将两份梯度数据传到同一环境下。
-
-#### 使用方式
-
-
-新建如下Python脚本，传入npu和gpu的dump_path以及输出目录，比对结果输出目录不存在的话会新建：
-
-```python
-from msprobe import *
-GradComparator.compare_distributed("配置文件里写的dump_path",
-                                    "配置文件里写的dump_path",
-                                    "比对结果输出目录")
-```
-
-
-### 比对结果
-
-**输出目录结构**
-
-如下为多卡比对结果，单卡则没有rank_{rank_id}这一级目录。
-
-```bash
-比对结果输出目录
-      ├── rank{rank_id}
-      │         ├── similarities.csv
-      │         └── similarities_picture
-      │                     ├── {param_name}.png
-      │                     └── summary_similarities.png
-```
-
-**问题界定**
-
-原则：对于任意权重，第0步的梯度相似度低于0.97，或者某一步的梯度相似度下降超过0.03，认为这一步存在精度问题。例子如下：
-
-- 第0步相似度低于0.97
-
-![Alt text](./img/grad_probe_image-3.png)
-
-- 第3步相似度下降超过0.03
-
-![Alt text](./img/grad_probe_image-4.png)
-
-- 正常情况
-
-![Alt text](./img/grad_probe_image-2.png)
-
-这个原则是一个经验性的指标，并不是严格的标注，还需要结合实际情况具体分析。
-
-## 公开接口
-
-**接口说明**
-
-```python
-PrecisionDebugger.monitor(module)
-```
-
-| 参数  | 说明                 | 是否必选 |
-| ----- | -------------------- | -------- |
-| module |Pytorch框架下传入模型，必须是torch.nn.Module；MindSpore框架下传入优化器。 | 是       |
-
-Pytorch场景，传入的模型不能被torch.jit.trace修饰。MindSpore动态图场景，传入的优化器不能被mindspore.jit修饰。
-
-**接口说明**
-
-```python
-GradComparator.compare_distributed(dump_path1, dump_path2, output_path)
-```
-
-| 参数  | 说明                 | 数据类型 | 是否必选 |
-| ----- | -------------------- | -------- | ----- |
-| dump_path1 |需要比对的其中一个dump目录，也就是配置文件里写的dump_path。 | str | 是       |
-| dump_path2 |需要比对的其中一个dump目录，也就是配置文件里写的dump_path，与dump_path1可以互换。 | str | 是       |
-| output_path |输出结果目录，不存在会新建。 | str | 是       |

msprobe/docs/18.online_dispatch.md

@@ -1,89 +0,0 @@
-# **PyTorch NPU在线精度比对工具使用指南**
-
-PyTorch NPU在线精度比对是msprobe工具实现在PyTorch训练过程中直接完成精度比对并输出比对结果的功能。
-
-在线精度比对实现的是NPU与CPU之间的精度比对。
-
-## PyTorch NPU在线精度比对总体流程
-
-1. 准备NPU训练工程。
-
-2. 在NPU环境下安装msprobe工具。
-
-3. 在训练脚本内插入msprobe工具在线精度比对接口。
-
-4. 执行训练并获取在线精度比对NPU和CPU分别执行后的精度比对结果。
-
-5. 比对结果分析。
-
-##  PyTorch NPU在线精度比对
-### 总体说明
-- 本节主要介绍NPU精度比对所需要的函数以及示例。
-- 在线精度比对工具通过截获PyTorch框架中部分Aten Ir及其输入输出，并将输入数据转到CPU执行，最后将NPU和CPU的执行结果进行精度比对得到比对结果。
-
-### 约束
-
-- Pytorch 只支持2.0及其以上版本。
-- 只支持Aten Ir级在线精度比对，所有Aten Ir可以通过dir(torch.ops.aten)查看，其中部分IR不支持在线比对：Aten Ir无对应CPU实现、NPU和CPU同AtenIR实现逻辑不一致，导致同输入不同输出。
-- 正反向不支持同时在线精度比对，不支持跨step在线精度比对。
-
-
-### 场景示例
-1. 在NPU训练脚本中添加在线精度比对接口，示例如下：
-
-   ```python
-   from msprobe.pytorch.common import seed_all
-   from msprobe.pytorch.online_dispatch import PtdbgDispatch
-      
-      # 在main函数开始前固定随机数
-      seed_all()
-      
-     
-      ...
-      
-      # 在需要调试精度的正向或反向代码前设置
-      # 正向示例
-      with PtdbgDispatch(dump_mode="auto", dump_path="/home/dump"):
-           output = model_cpu(inputs)
-      # 反向示例
-      with PtdbgDispatch(dump_mode="auto", dump_path="/home/dump"):
-       	loss.backward() 
-   ```
-
-2. 执行训练。
-
-3. 找出精度不达标的Aten IR。
-
-   执行过程中会打屏Failed，Failed在比对结果csv中的Accuracy Reached or Not列标记为No，并在Dump目录下存盘精度不达标Aten IR的输入输出。
-
-### 计算精度评价指标
-
-1. Cosine < 0.99 且 MaxAbsError > 0.001时，精度不达标；
-2. Cosine < 0.9，精度不达标；
-3. MaxAbsError > 1，精度不达标。
-
-### 在线精度比对参数设置说明
-
-| 参数名称 | 说明                                                                                              | 是否必选 |
-| -------- |-------------------------------------------------------------------------------------------------| -------- |
-| dump_mode| dump模式，可取值"all"、"list"、"auto"、"OFF"，默认值为OFF（表示不Dump数据）。                                         | 否       |
-| api_list | dump范围，dump_mode="list"时设置，需要Dump Aten Ir API名称，默认为None，Aten Ir API名称可以通过dir(torch.ops.aten)查看。 | 否       |
-| dump_path| dump文件生成的路径。                                                                                    | 是       |
-| tag      | 传入tag字符串，成为dump文件夹名一部分，默认为None。                                                                 | 否       |
-| process_num | 多进程并发数，默认为0，最大不超过CPU核数的四分之一。                                                                                    | 否       |
-| debug       | debug信息打印，默认为False。                                                                             | 否       |
-### dump数据存盘说明
-dump数据存盘目录名格式：`msprobe_rankid_{timestamp}`。
-
-子目录下包含1个比对结果csv文件、cpu和npudump数据目录，npu目录下包含Aten IR在NPU上的输入输出的dump数据，由于CPU的输入是直接使用NPU的输入执行，因此cpu目录下只包含执行输出的dump数据。
-
-```bash
-msprobe_rank4_20230911170521
-├── compare_result_rank4_20230911170521.csv
-├── cpu
-│   ├── native_batch_norm_backward_10_output.0.npy
-│   ............
-└── npu
-    ├── native_batch_norm_backward_10_input.0.npy
-    ............
-```