mindstudio-probe 1.1.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

msprobe/docs/16.free_benchmarking_MindSpore.md

@@ -13,6 +13,7 @@
     * **验证低精度可疑 API**，确认升精度后是否对模型 Loss 有影响。
 * 该工具的约束
     * 仅支持 MindSpore 动态图场景。支持的 API 类型为 ops、Tensor、mint 和 mint.nn.functional 类的非 inplace 计算 API，不支持 Primitive 和 Jit 类 API。
+    * 仅支持 输入输出向量为浮点数类型(BF16、FP16、FP32、FP64)的 API 比对。
     * 建议配置白名单（设置 list），控制对少量 API 进行无标杆比对。比对 API 越多，性能和显存损耗越大。
 
 ## 2 工具实现原理
@@ -79,40 +80,57 @@ D-->config.json配置
 用户需根据自己的使用场景，对照[工具实现原理](#2-工具实现原理)中几个关键步骤进行配置
 ####  3.2.1 确定比对范围
 
-| 相关参数名 | 是否必选 | 可配置项          | 适用场景                                                                                    |
-| ---------- | -------- | ----------------- | ------------------------------------------------------------------------------------------- |
-| list       | 可选     |                   | 需要通过指定 API 名来限制比对API个数 如：\["mindspore.ops.bmm"\] 会只对mindspore.ops.bmm API进行比对|
-| fuzz_stage | 可选     | "forward"（默认） | 需要进行 API **前向**计算的精度问题排查或验证|
+<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. 选择扰动因子
+####  3.2.2 选择扰动因子
 
-| 相关参数    | 是否必选 | 可配置项                     | 适用场景                                                                                                 |
-| ----------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
-| pert_mode   | 可选     | "improve_precision" （默认） | （常用）(可做验证) API 可能在**低精度**下有精度问题，扰动因子会将输入的低精度向量升精度 |
-|             |          | "add_noise"                  | API 可能在**轻微扰动**下暴露精度问题，扰动因子会为输入向量增加一个极小值 |
-|             |          | "bit_noise"                  | API 可能在**轻微扰动**下暴露精度问题，扰动因子会翻转输入向量的最后一个比特位。不支持BF16类型向量 |
-|             |          | "no_change"                  | API 可能存在**数值稳定性**精度问题，扰动因子会复制原始输入|
-|             |          | "change_value"               | API 可能存在**大数吃小数**问题，扰动因子会交换输入向量的首尾值 |
+<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. 选择处理方式
-| 相关参数名   | 是否必选 | 可配置项          | 适用场景                                                                                  |
-| ------------ | -------- | ----------------- | ----------------------------------------------------------------------------------------- |
-| handler_type | 可选     | "check"  （默认） | 要做精度问题 API 排查，输出扰动前后不符合精度标准的 API，支持所有扰动因子                  |
-|              |          | "fix"             | 要做可疑 API 验证，用扰动后输出替换原始输出，仅支持 "improve_precision" 扰动因子 |
+####  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
-from msprobe.mindspore import PrecisionDebugger  
+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')
-...
-debugger.start() # 一般在训练循环开头启动工具
-... # 循环体
-debugger.stop() # 一般在训练循环末尾结束工具
-debugger.step() # 在训练循环的最后需要重置工具，非循环场景不需要
+
+# 模型、损失函数的定义以及初始化等操作
+# ...
+model = Network()
+
+# 数据集迭代的地方往往是模型开始训练的地方
+for step, (input_ids, input_position, attention_mask) in enumerate(dataset.create_tuple_iterator()):
+    debugger.start() # 一般在训练循环开头启动工具
+    # 单步训练逻辑
+    # ...
+    debugger.stop() # 一般在训练循环末尾结束工具
+    debugger.step() # 在训练循环的最后需要重置工具，非循环场景不需要
 ```
 
 ### 3.4 查看精度风险算子
@@ -121,20 +139,21 @@ check 模式下，若存在不符合精度标准的 API，则工具会在 dump_p
 
 | 字段         | 说明                                                                                     |
 | ------------ | ---------------------------------------------------------------------------------------- |
-| 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 类型 |
+| 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.float16 | 0.002        |
-| mindspore.float32 | 0.0002       |
-| 其他              | 0.0002       |
+| 输出dtype          | 相对误差阈值 |
+| ------------------ | ------------ |
+| mindspore.bfloat16 | 0.004        |
+| mindspore.float16  | 0.002        |
+| mindspore.float32  | 0.0002       |
+| mindspore.float64  | 0.0002       |

msprobe/docs/17.grad_probe.md

@@ -5,11 +5,11 @@
 - 将模型权重的梯度数据导出。这种功能可以将模型权重的梯度值以统计量的形式采集出来，用以分析问题。
 - 将两份梯度数据进行相似度对比。在有标杆问题中，可以确认训练过程中精度问题出现的step，以及抓取反向过程中的问题。
 
-工具支持PyTorch版本：2.0/2.1/2.2；支持MindSpore版本：r2.3。
+工具支持PyTorch版本：2.0/2.1/2.2；支持MindSpore版本：r2.3。暂不支持deepspeed的zero1、zero2、zero3。
 
 ## 工具特性
 
-- 使用便捷，无需在训练流程里插入代码
+- 使用便捷，仅需在训练流程里插入少量代码
 - 可以精准定位问题出现的step
 
 ## 使用方式
@@ -39,8 +39,8 @@
    |--------------------------------|-----------------------------------|-----------------|----------|
    | task            | 填为"grad_probe"。 |  str | 是 |
    | dump_path            | 输出目录。如果不存在就会创建一个新目录。 |  str | 是 |
-   | rank                   | rank id列表，在多卡场景下，表示需要导出梯度数据的进程的rank id。列表为空就表示导出所有rank的数据。默认为空。（MindSpore静态图模式下，当前暂不支持指定rank功能） | List[int] | 否       |
-   | step                   | step列表，表示需要导出数据的step列表。列表为空就表示导出所有step的数据。默认为空。（MindSpore静态图模式下，当前暂不支持指定step功能） | List[int] | 否 |
+   | 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] | 否  |
@@ -100,11 +100,10 @@ debugger.stop()
       │        ├── step{step}
       │        │        ├── {param_name}.npy
 ```
-+ {timestamp}：梯度工具导出数据的时候会在output_path下生成一个时间戳目录，然后在这个时间戳目录下输出结果。
 + rank_{rank_id}：在分布式场景下，会记录卡的rank_id。非分布式场景下，如果是CPU则记录进程号，如果是CPU或GPU则记录卡号
 + grad_summary_{step}.csv：会分step记录每一步的梯度数据统计值。
 + step_{step}：这个目录下会存放该step的梯度的方向数据。
-+ {param_name}.pt(npy)：模型参数的梯度方向数据，PyTorch保存的是pt文件，MindSpore是npy文件。
++ {param_name}.npy：模型参数的梯度方向数据。
 
 **grad_summary_{step}.csv**