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

msprobe/docs/06.data_dump_MindSpore.md

@@ -26,18 +26,20 @@
 
 msprobe 工具通过在训练脚本中添加 `PrecisionDebugger` 接口并启动训练的方式，采集模型在运行过程中的精度数据。该工具支持对MindSpore的静态图和动态图场景进行不同Level等级的精度数据采集。
 
-dump 的"tensor"模式采集数据量大小，可以参考[数据量基线](data_dump_MindSpore/data_dump_MindSpore_baseline.md)。
+dump "statistics"模式的性能膨胀大小"与"tensor"模式采集的数据量大小，可以参考[dump基线](data_dump_MindSpore/data_dump_MindSpore_baseline.md)。
 
 ## 5. 场景介绍
 
 ### 5.1 静态图场景
-在静态图场景下，msprobe 仅支持 **L2 Level**  的数据采集。
+在静态图场景下，msprobe 支持 **L0 Level** 和 **L2 Level** 的数据采集。且当 MindSpore 版本高于 2.5.0 时，若需采集 **L2 Level** 数据，必须使用编包时添加了`--include-mod=adump`选项的 mindstudio-probe whl 包进行 msprobe 工具安装。
+- **L0 Level（Cell 级）** ：采集 `Cell` 对象的数据，适用于需要分析特定网络模块的情况。仅支持 2.7.0 及以上版本的 MindSpore 框架。
+
 - **L2 Level（Kernel 级）** ：采集底层算子的输入输出数据，适用于深入分析算子级别的精度问题。
 
 采集方式请参见[示例代码 > 静态图场景](#71-静态图场景)。详细介绍请参见[《config.json 配置文件介绍》](./02.config_introduction.md#11-通用配置)中的“level 参数”和[《config.json 配置示例》](./03.config_examples.md#2-mindspore-静态图场景) 中的“MindSpore 静态图场景”。
 
 ### 5.2 动态图场景
-在动态图场景下，msprobe 支持 **L0** 、**L1** 、**mix** 、**L2 Level**、 **debug**  的数据采集，具体分为以下几种情况：
+在动态图场景下，msprobe 支持 **L0** 、**L1** 、**mix** 、**L2**、 **debug**  的数据采集，具体分为以下几种情况：
 - **使用高阶 API（如 `Model 高阶API`）** ：
   - 需要使用 `MsprobeStep` 回调类来控制数据采集的启停，适用于 **L0** 、**L1** 、**mix** 、**L2** 数据采集。
 
@@ -46,7 +48,7 @@ dump 的"tensor"模式采集数据量大小，可以参考[数据量基线](data
 
 采集方式请参见[示例代码 > 动态图场景](#72-动态图场景)。
 
-> **注意** ：动态图模式下，使用 `PSJit` 或 `PIJit` 装饰的部分实际以静态图模式执行，此时的 **Kernel 级（L2 Level）**  数据采集方式与静态图场景相同。
+> **注意** ：动态图模式下，使用 `mindspore.jit` 装饰的部分实际以静态图模式执行，此时的 **Kernel 级（L2 Level）**  数据采集方式与静态图场景相同。
 - **L0 Level（Cell 级）** ：采集 `Cell` 对象的数据，适用于需要分析特定网络模块的情况。
 
 - **L1 Level（API 级）** ：采集 MindSpore API 的输入输出数据，适用于定位 API 层面的精度问题。
@@ -56,7 +58,7 @@ dump 的"tensor"模式采集数据量大小，可以参考[数据量基线](data
 - **debug level （单点保存）**：单点保存网络中变量的正反向数据，适用于用户熟悉网络结构的场景。
 
 
-详细介绍请参见[《config.json 配置文件介绍》](./02.config_introduction.md#11-通用配置)中的“level 参数”和[《config.json 配置示例》](./03.config_examples.md#3-mindspore-动态图场景) 中的“MindSpore 动态图场景”。
+详细介绍请参见[《config.json 配置文件介绍》](./02.config_introduction.md#11-通用配置)中的“level 参数”。
 
 
 ## 6 接口介绍
@@ -85,12 +87,15 @@ PrecisionDebugger(config_path=None, task=None, dump_path=None, level=None, step=
 **原型**：
 
 ```Python
-start(model=None)
+start(model=None, token_range=None)
 ```
 
 **参数说明**:
 
-1. model：指定需要采集数据的实例化模型，支持传入mindspore.nn.Cell、List[mindspore.nn.Cell]或Tuple[mindspore.nn.Cell] 类型, 默认未配置。Cell级别（"L0" level）dump 与 "mix" level dump 时，必须传入 model 才可以采集 model 内的所有Cell 对象数据。API级别（"L1" level）dump 时，传入 model 可以采集 model 内包含 primitive op 对象在内的所有 API 数据，若不传入 model 参数，则只采集非 primitive op 的 API 数据。
+1. model：指定需要采集数据的实例化模型，支持传入mindspore.nn.Cell、List[mindspore.nn.Cell]或Tuple[mindspore.nn.Cell] 类型，默认未配置。Cell级别（"L0" level）dump 与 "mix" level dump 时，必须传入 model 才可以采集 model 内的所有Cell 对象数据。API级别（"L1" level）dump 时，传入 model 可以采集 model 内包含 primitive op 对象在内的所有 API 数据，若不传入 model 参数，则只采集非 primitive op 的 API 数据。token_range不为None时，必须传入model参数。
+<br>对于复杂模型，如果仅需要监控一部分(如model.A，model.A extends mindspore.nn.Cell)，传入需要监控的部分(如model.A)即可。  
+注意：传入的当前层不会被dump，工具只会dump传入层的子层级。如传入了model.A，A本身不会被dump，而是会dump A.x, A.x.xx等。
+2. token_range：指定推理模型采集时的token循环始末范围，支持传入[int, int]类型，代表[start, end]，范围包含边界，默认未配置。
 
 #### 6.1.2 stop
 
@@ -110,7 +115,7 @@ stop()
 
 **功能说明**：结束一个 step 的数据采集，完成所有数据落盘并更新 dump 参数。在一个 step 结束的位置添加，且必须在 **stop** 函数之后的位置调用。
 该函数需要配合 **start** 和 **stop** 函数使用，尽量添加在反向计算代码之后，否则可能会导致反向数据丢失。
-**仅未使用 Model 高阶 API 的动态图场景支持。**
+**仅未使用 Model 高阶 API 的动态图和静态图场景支持。**
 
 **原型**：
 
@@ -144,15 +149,66 @@ save(variable, name, save_backward=True)
 **参数说明**:
 | 参数名称        | 参数含义          |        支持数据类型    |   是否必选|
 | ----------     | ------------------| ------------------- | ------------------- |
-| variable       | 需要保存的变量     |dict, list, torch.tensor, int, float, str |  是  |
+| variable       | 需要保存的变量     |dict, list, tuple, torch.tensor, int, float, str |  是  |
 | name           | 指定的名称         | str                 | 是  |
 | save_backward  | 是否保存反向数据   | boolean             | 否 |
 
 
+#### 6.1.6 set_init_step
+
+**功能说明**：设置起始step数，step数默认从0开始计数，使用该接口后step从指定值开始计数。该函数需要写在训练迭代的循环开始前，不能写在循环内。
+
+**原型**：
+
+```Python
+set_init_step(step)
+```
+
+**参数说明**:
+
+1.step: 指定的起始step数。
+
+
+#### 6.1.7 register_custom_api
+
+**功能说明**：注册用户自定义的api到工具，用于 L1 dump 。
+
+**原型**：
+
+```Python
+debugger.register_custom_api(module, api_name, api_prefix)
+```
+**参数说明**:
+
+以 torch.matmul api 为例
+
+1.module: api 所属的包，即传入 torch。
+
+2.api_name: api 名，string类型，即传入 "matmul"。
+
+3.api_prefix: [dump.json](./27.dump_json_instruction.md) 中 api 名的前缀，可选，默认为包名的字符串格式， 即 "torch"。
+
+#### 6.1.8 restore_custom_api
 
-### 6.2 msprobe.mindspore.common.utils.MsprobeStep
+**功能说明**：恢复用户原有的自定义的api，取消 dump 。
 
-**功能说明**：MindSpore Callback类，自动在每个step开始时调用start()接口，在每个step结束时调用stop()、step()接口。实现使用 Model 高阶 API 的动态图场景下 L0、L1、mix 级别的精度数据采集控制，控制粒度为单个 **Step** ，而 PrecisionDebugger.start, PrecisionDebugger.stop 接口的控制粒度任意训练代码段。
+**原型**：
+
+```Python
+debugger.restore_custom_api(module, api_name)
+```
+**参数说明**:
+
+以 torch.matmul api 为例
+
+1.module: api 所属的包，即传入 torch。
+
+2.api_name: api 名，string类型，即传入 "matmul"。
+
+
+### 6.2 msprobe.mindspore.MsprobeStep
+
+**功能说明**：MindSpore Callback类，自动在每个step开始时调用start()接口，在每个step结束时调用stop()、step()接口。实现使用 Model 高阶 API 的动态图场景下 L0、L1、mix 级别，和静态图场景下 L0级别的精度数据采集控制，控制粒度为单个 **Step** ，而 PrecisionDebugger.start, PrecisionDebugger.stop 接口的控制粒度为任意训练代码段。
 
 **原型**：
 
@@ -164,7 +220,17 @@ MsprobeStep(debugger)
 
 1. debugger：PrecisionDebugger对象。
 
-### 6.3 msprobe.mindspore.seed_all
+### 6.3 msprobe.mindspore.MsprobeInitStep
+
+**功能说明**：MindSpore Callback 类，自动获取并设置初始 step 值。仅适用于静态图 O0/O1 模式的断点续训场景。
+
+**原型**：
+
+```Python
+MsprobeInitStep()
+```
+
+### 6.4 msprobe.mindspore.seed_all
 
 **功能说明**：用于固定网络中的随机性和开启确定性计算。
 
@@ -181,12 +247,59 @@ seed_all(seed=1234, mode=False, rm_dropout=True)
 
 3. rm_dropout：控制dropout失效的开关。可配置 True 或 False，默认值：True，非必选。参数示例：rm_dropout=True。该参数设置为 True 后，将会使mindspore.ops.Dropout，mindspore.ops.Dropout2D，mindspore.ops.Dropout3D，mindspore.mint.nn.Dropout和mindspore.mint.nn.functional.dropout失效，以避免因随机dropout造成的网络随机性。建议在采集mindspore数据前开启。注意：通过rm_dropout控制dropout失效或生效需要在初始化Dropout实例前调用才能生效。
 
+## 7. 示例代码
+
+### 7.1 静态图场景
 
+#### 7.1.1 L0 级别
 
+**说明**: 静态图 L0 级别的Dump功能是基于mindspore.ops.TensorDump算子实现。在Ascend平台上的Graph模式下，可以通过设置环境变量 [MS_DUMP_SLICE_SIZE 和 MS_DUMP_WAIT_TIME](https://www.mindspore.cn/docs/zh-CN/r2.5.0/api_python/env_var_list.html) 解决在输出大Tesnor或输出Tensor比较密集场景下算子执行失败的问题。
 
-## 7. 示例代码
+##### 7.1.1.1 未使用 Model 高阶 API
 
-### 7.1 静态图场景
+
+```python
+import mindspore as ms
+ms.set_context(mode=ms.GRAPH_MODE, device_target="Ascend")
+
+from msprobe.mindspore import PrecisionDebugger
+debugger = PrecisionDebugger(config_path="./config.json")
+
+# 模型、损失函数的定义以及初始化等操作
+# ...
+model = Network()
+# 数据集迭代的地方往往是模型开始训练的地方
+for data, label in data_loader:
+    debugger.start(model) # 进行 L0 级别下Cell 对象的数据采集时调用
+    # 如下是模型每个 step 执行的逻辑
+    grad_net = ms.grad(model)(data)
+    # ...
+    debugger.step()         # 更新迭代数
+```
+
+##### 7.1.1.2 使用 Model 高阶 API
+
+
+```python
+import mindspore as ms
+from mindspore.train import Model
+ms.set_context(mode=ms.GRAPH_MODE, device_target="Ascend")
+
+from msprobe.mindspore import PrecisionDebugger
+from msprobe.mindspore.common.utils import MsprobeStep
+debugger = PrecisionDebugger(config_path="./config.json")
+
+# 模型、损失函数的定义以及初始化等操作
+# ...
+
+model = Network()
+# 进行 L0 级别下 Cell 对象的数据采集时调用
+debugger.start(model)
+trainer = Model(model, loss_fn=loss_fn, optimizer=optimizer, metrics={'accuracy'})
+trainer.train(1, train_dataset, callbacks=[MsprobeStep(debugger)])
+```
+
+#### 7.1.2 L2 级别
 
 ```python
 import mindspore as ms
@@ -198,7 +311,8 @@ debugger.start()
 # 请勿将以上初始化流程置于模型实例化或 mindspore.communication.init 调用后
 # 模型定义和训练代码
 # ...
-
+debugger.stop()
+debugger.step()
 ```
 
 ### 7.2 动态图场景
@@ -297,15 +411,43 @@ trainer = Model(model, loss_fn=loss_fn, optimizer=optimizer, metrics={'accuracy'
 trainer.train(1, train_dataset)
 ```
 
+
+#### 7.2.3 推理模型采集指定token_range
+需要配合mindtorch套件改造原推理代码，套件包装后使用方式与torch一致，唯一区别为import的是msprobe.mindspore下的PrecisionDebugger。
+
+```Python
+from vllm import LLM, SamplingParams
+from msprobe.mindspore import PrecisionDebugger, seed_all
+# 在模型训练开始前固定随机性
+seed_all()
+# 请勿将PrecisionDebugger的初始化流程插入到循环代码中
+debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path")
+# 模型定义及初始化等操作
+prompts = ["Hello, my name is"]
+sampling_params = SamplingParams(temprature=0.8, top_p=0.95)
+llm = LLM(model='...')
+model = llm.llm_engine.model_executor.driver_worker.worker.model_runner.get_model()
+# 开启数据dump, 指定采集推理模型逐字符循环推理中的第1~3次
+debugger.start(model=model, token_range=[1,3])  
+# 推理模型生成的逻辑
+output = llm.generate(prompts, sampling_params=sampling_params)
+# 关闭数据dump并落盘
+debugger.stop()
+debugger.step()
+```
+
 ## 8. dump 结果文件介绍
 
 ### 8.1 静态图场景
 
-训练结束后，数据将保存在 `dump_path` 指定的目录下。
+训练结束后，数据将保存在 `dump_path` 指定的目录下。<br/>
+L0 级别 dump 的目录结构与动态图场景下目录结构一致。<br/>
+L2 级别 dump 的目录结构如下所示：
 
-若jit_level=O2，且使用mindstudio-probe发布包或源码编包时添加了`--include-mod=adump`选项，目录结构示例如下：
+若jit_level=O2，MindSpore 版本不低于 2.5.0，且使用mindstudio-probe发布包或源码编包时添加了`--include-mod=adump`选项，目录结构示例如下：
 ```
 ├── dump_path
+│   ├── acl_dump_{device_id}.json
 │   ├── rank_0
 │   |   ├── {timestamp}
 │   |   │   ├── step_0
@@ -329,10 +471,9 @@ trainer.train(1, train_dataset)
 **说明**
 1. 若配置文件中指定落盘npy格式，但是实际数据格式不在npy支持范围内(如bf16、int4等)，则该tensor会以原始码流落盘，并不会转换为npy格式。
 2. 若原始文件全名长度超过255个字符，则文件基础名会被转换为长度为32位的随机数字字符串，原始文件名与转换后文件名的对应关系会保存在同目录下的`mapping.csv`文件中。
+3. acl_dump_{device_id}.json 为在 Dump 接口调用过程中生成的中间文件，一般情况下无需关注。
 
-
-其他场景请参见 MindSpore 官方文档中的[数据对象目录](https://www.mindspore.cn/docs/zh-CN/r2.4.0/model_train/debug/dump.html)。
-
+其他场景下，除 kernel_kbyk_dump.json（jit_level=O0/O1）、kernel_graph_dump.json（jit_level=O2）等无需关注的中间文件外的其他 dump 结果文件请参见 MindSpore 官方文档中的[ Ascend 下 O0/O1 模式 Dump 数据对象目录和数据文件介绍](https://www.mindspore.cn/docs/zh-CN/r2.5.0/model_train/debug/dump.html#%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95%E5%92%8C%E6%95%B0%E6%8D%AE%E6%96%87%E4%BB%B6%E4%BB%8B%E7%BB%8D)与[ Ascend 下 O2 模式 Dump 数据对象目录和数据文件介绍](https://www.mindspore.cn/docs/zh-CN/r2.5.0/model_train/debug/dump.html#%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95%E5%92%8C%E6%95%B0%E6%8D%AE%E6%96%87%E4%BB%B6%E4%BB%8B%E7%BB%8D-1)。
 ### 8.2 动态图场景
 
 dump 结果目录结构示例如下：
@@ -348,9 +489,9 @@ dump 结果目录结构示例如下：
 |   |   |   |    ├── Tensor.__add__.0.forward.output.0.npy
 |   |   |   |    ...
 |   |   |   |    ├── Jit.AlexNet.0.forward.input.0.npy
-|   |   |   |    ├── Primitive.conv2d.Conv2D.0.forward.input.0.npy
-|   |   |   |    ├── Cell.conv1.Conv2D.forward.0.parameters.weight.npy # 模块参数数据：命名格式为{Cell}.{cell_name}.{class_name}.forward.{调用次数}.parameters.{parameter_name}。
-|   |   |   |    ├── Cell.conv1.Conv2D.parameters_grad.weight.npy      # 模块参数梯度数据：命名格式为{Cell}.{cell_name}.{class_name}.parameters_grad.{parameter_name}。因为同一模块的参数使用同一梯度进行更新，所以参数梯度文件名不包含调用次数。
+|   |   |   |    ├── Primitive.conv2d.Conv2d.0.forward.input.0.npy
+|   |   |   |    ├── Cell.conv1.Conv2d.forward.0.parameters.weight.npy # 模块参数数据：命名格式为{Cell}.{cell_name}.{class_name}.forward.{调用次数}.parameters.{parameter_name}。
+|   |   |   |    ├── Cell.conv1.Conv2d.parameters_grad.weight.npy      # 模块参数梯度数据：命名格式为{Cell}.{cell_name}.{class_name}.parameters_grad.{parameter_name}。因为同一模块的参数使用同一梯度进行更新，所以参数梯度文件名不包含调用次数。
 |   |   |   |    └── Cell.relu.ReLU.forward.0.input.0.npy              # 命名格式为{Cell}.{cell_name}.{class_name}.{forward/backward}.{调用次数}.{input/output}.{参数序号}, 其中，“参数序号”表示该Cell的第n个参数，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该Cell的第1个参数的第1个元素。
 |   |   |   |                                                          # 当dump时传入的model参数为List[mindspore.nn.Cell]或Tuple[mindspore.nn.Cell]时，模块级数据的命名中包含该模块在列表中的索引index，命名格式为{Cell}.{index}.*，*表示以上三种模块级数据的命名格式，例如：Cell.0.relu.ReLU.forward.0.input.0.npy。
 │   |   |   ├── dump.json
@@ -372,17 +513,41 @@ dump 结果目录结构示例如下：
 
 * `rank`：设备 ID，每张卡的数据保存在对应的 `rank{ID}` 目录下。非分布式场景下没有 rank ID，目录名称为 rank。
 * `dump_tensor_data`：保存采集到的张量数据。
-* `dump.json`： 保存API或Cell前反向数据的统计量信息。包含dump数据的API名称或Cell名称，各数据的dtype、 shape、max、min、mean、L2norm（L2范数，平方根）统计信息以及当配置summary_mode="md5"时的CRC-32数据。具体介绍可参考[dump.json文件说明](./27.dump_json_instruction.md#2-dumpjson文件示例mindspore)。
+* `dump.json`： 保存API或Cell前反向数据的统计量信息。包含dump数据的API名称或Cell名称，各数据的dtype、 shape、max、min、mean、L2norm（L2范数，平方根）统计信息以及当配置summary_mode="md5"时的CRC-32数据。具体介绍可参考[dump.json文件说明](./27.dump_json_instruction.md#2-mindspore-场景下的-dumpjson-文件)。
 * `stack.json`：API/Cell的调用栈信息。
 * `construct.json`：分层分级结构，level为L1时，construct.json内容为空。
 
 dump 过程中，npy 文件在对应API或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，因此，程序异常终止时，被执行API对应的 npy 文件已被保存，但 json 文件中的数据可能丢失。
 
-动态图场景下使能 PSJit 或 PIJit，装饰特定 Cell 或 function，被装饰的部分会全部/部分使能**静态图**流程。
+动态图场景下使用 `mindspore.jit` 装饰特定 Cell 或 function 时，被装饰的部分会被编译成**静态图**执行。
 
-- PSJit 场景下 config.json 文件配置 level 为 L1 时，被 PSJit 装饰的部分也作为 API 被 dump 到对应目录；配置 level 为 L2 时，则只会 dump 用户网络中静态图流程下的相关 kernel，其结果目录同jit_level 为 O0/O1 时的静态图 dump 相同。
-- PIJit 场景下 config.json 文件配置 level 为 L1 时，会被还原为动态图，按 API 粒度进行 dump；配置 level 为 L2 时，则只会 dump 用户网络中静态图流程下的相关 kernel。
+- config.json 文件配置 level 为 L0 或 mix，且 MindSpore 版本不低于 2.7.0 时， 若存在 construct 方法被 `mindspore.jit` 装饰的 Cell 对象，则 dump_path 下将生成 `graph` 与 `pynative` 目录，分别存放 construct 方法被 `mindspore.jit` 装饰的 Cell 对象的精度数据、其它Cell 或 API 对象的精度数据。示例如下：
 
+```lua
+├── dump_path
+│   ├── graph
+│   |   ├── step0
+│   |   |   ├── rank0
+│   |   │   |   ├── dump_tensor_data
+|   |   |   |   |   ├── ...
+│   |   |   |   ├── dump.json
+│   |   |   |   ├── stack.json
+│   |   |   |   └── construct.json
+│   |   |   ├── ...
+│   ├── pynative
+│   |   ├── step0
+│   |   |   ├── rank0
+│   |   │   |   ├── dump_tensor_data
+|   |   |   |   |   ├── ...
+│   |   |   |   ├── dump.json
+│   |   |   |   ├── stack.json
+│   |   |   |   └── construct.json
+│   |   |   ├── ...
+```
+
+- config.json 文件配置 level 为 L1 时， 若 `mindspore.jit` 的 `capture_mode` 参数设置为 ast（原 PSJit 场景）, 则被装饰的部分也作为 API 被 dump 到对应目录；若 `mindspore.jit` 的 `capture_mode` 参数设置为 bytecode（原 PIJit 场景）, 则被装饰的部分会被还原为动态图，按 API 粒度进行 dump。
+
+- config.json 文件配置 level 为 L2 时， 仅会 dump 被 `mindspore.jit` 装饰部分的 kernel 精度数据，其结果目录同 jit_level 为 O0/O1 时的静态图 dump 结果相同。
 
 npy文件名的前缀含义如下：
 
@@ -393,12 +558,12 @@ npy文件名的前缀含义如下：
 | Primitive      | mindspore.ops.Primitive API数据      |
 | Mint           | mindspore.mint API数据              |
 | MintFunctional | mindspore.mint.nn.functional API数据 |
+| MintDistributed | mindspore.mint.distributed API数据 |
 | Distributed    | mindspore.communication.comm_func API数据     |
 | Jit            | 被"jit"装饰的模块或函数数据                |
 | Cell           | mindspore.nn.Cell 类（模块）数据           |
 
 
-
 ## 9.补充说明
 
 ### 9.1 修改 API 支持列表

msprobe/docs/07.accuracy_checker_PyTorch.md

@@ -13,9 +13,9 @@ b. 在预检 dump 时可以选择由工具构造随机数获得 dump 数据或
 1. 在 NPU 和 GPU 环境下分别安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。
 2. 在 NPU 训练脚本内添加 msprobe 工具 dump 接口 PrecisionDebugger，采集待预检数据。注意需要配置 level="L1"。
 3. 将 NPU 环境下 dump 的预检数据拷贝至 GPU 环境。
-4. 在 NPU 和 GPU 环境下分别执行 run_ut，生成的结果最终用于 api_precision_compare.py 函数的输入。详见 [3 离线预检操作指导](#3-离线预检操作指导)。
+4. 在 NPU 和 GPU 环境下分别执行 run_ut，生成的结果最终用于 api_precision_compare 的输入。详见 [3 离线预检操作指导](#3-离线预检操作指导)。
 5. 将 NPU 和 GPU 执行 run_ut 生成的 `accuracy_checking_details_{timestamp}.csv` 结果文件拷贝至同一环境下。
-6. 运行 api_precision_compare.py，输出结果为预检操作的最终结果。详见 [5 预检结果比对](#5-预检结果比对)章节。
+6. 运行 api_precision_compare，输出结果为预检操作的最终结果。详见 [5 预检结果比对](#5-预检结果比对)章节。
 
 ## 3 离线预检操作指导
 
@@ -107,7 +107,7 @@ msprobe -f pytorch multi_run_ut -api_info ./dump_path/step{step_number}/rank{ran
 | -save_error_data             | 保存精度未达标的 API 输入输出数据。                            | 否                                 |
 | -o 或 --out_path               | 指定 run_ut 执行结果存盘路径，默认“./”。 | 否                                 |
 | -j 或 --jit_compile            | 开启 jit 编译。                                                | 否                                 |
-| -n                           | 同时执行 run_ut 线程的数量，默认为 8，最大支持 64，但每个 Device 最大支持 8 个线程。当指定多个线程和多个 Device 时，线程数在每张卡上均分。 | 否                                 |
+| -n 或 --num_splits           | 同时执行 run_ut 线程的数量，默认为 8，最大支持 64，但每个 Device 最大支持 8 个线程。当指定多个线程和多个 Device 时，线程数在每张卡上均分。 | 否                                 |
 | -d 或 --device                 | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0，支持同时指定 0~7，共 8 个 Device。 | 否                                 |
 | -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 | run_ut 操作中断后继续执行场景下必须配置 |
 | -f 或 --filter_api             | 过滤模型中除最大值和最小值以外其他参数和结构相同的 API。适用于模型较大且重复 API 较多的场景。 | 否                                 |
@@ -295,3 +295,13 @@ a：误差比对法指标。
 - npu_scaled_masked_softmax
 
 - npu_swiglu
+
+- npu_apply_adam
+
+- npu_group_norm_silu
+
+- npu_mish
+
+- npu_moe_gating_top_k_softmax
+
+- npu_sort_v2

msprobe/docs/08.accuracy_checker_online_PyTorch.md

@@ -3,7 +3,7 @@
 ## 1 简介
 
 为了应对大模型场景下，通过离线预检方式 dump API 输入输出数据导致的存储资源紧张问题，提供在线精度预检功能。本功能实现在执行 NPU 训练操作的过程中，通过 TCP/IP 协议在 NPU
-Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据在 GPU 设备上运行，将两份输出数据进行比对，得到预检比对结果，从而减少数据 dump 的步骤，降低存储资源的占用。针对偏差较大的算子，两方比对（NPU vs. GPU）的方法缺少裁判进行裁定。 参考离线预检，在线预检场景同时支持两方比对和三方比对方式，按照 api 的精度标准要求，选择比对两方比对和三方比对。
+Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据在 GPU 设备上运行，将两份输出数据进行比对，得到预检比对结果，从而减少数据 dump 的步骤，降低存储资源的占用。针对偏差较大的算子，两方比对（NPU vs. GPU）的方法缺少裁判进行裁定。 参考离线预检，在线预检场景同时支持两方比对和三方比对方式，按照 api 的精度标准要求，选择两方比对或三方比对。
 
 ## 2 在线精度预检流程
 
@@ -37,7 +37,7 @@ Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据
 | host            | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机地址 127.0.0.1 或本机局域网 IP。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。            | 否    |
 | port            | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机可用端口。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。        | 否    |
 | rank_list       | 指定在线预检的 Rank ID，默认值为 [0]，list[int] 类型，应配置为大于等于 0 的整数，且须根据实际卡的 Rank ID 配置，若所配置的值大于实际训练所运行的卡的 Rank ID，则在线预检输出数据为空。GPU 和 NPU 须配置一致。 | 是    |
-| tls_path        | 在线预检模式局域网场景 SSL 证书路径，该路径下包含私钥文件 server.key 和公钥文件 server.crt，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。 | 否    |
+| tls_path        | 在线预检模式局域网场景 SSL 证书路径，该路径下包含私钥 server.key、证书 server.crt、自建CA证书 ca.crt、CRL吊销证书 crl.pem，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。其中 crl.pem 为非必需文件，仅当用户存在吊销记录时使用。 | 否    |
 
 
 #### 3.1.2 NPU 侧在线预检配置说明
@@ -55,21 +55,73 @@ Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据
 | nfs_path         | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host 和 port 不生效。     | 否    |
 | host             | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的局域网 IP 地址。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。     | 否    |
 | port             | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的端口号。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。        | 否    |
-| tls_path         | 在线预检模式局域网场景 SSL 证书路径，该路径下包含私钥文件 client.key 和公钥文件 client.crt，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。 | 否    |
+| tls_path         | 在线预检模式局域网场景 SSL 证书路径，该路径下包含私钥 client.key、证书 client.crt、自建CA证书 ca.crt、CRL吊销证书 crl.pem，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。其中 crl.pem 为非必需文件，仅当用户存在吊销记录时使用。 | 否    |
 | online_run_ut_recompute | 模型训练是否使用重计算机制，bool类型，默认为False，表示模型没有使用重计算。在线预检暂不支持重计算机制下反向算子的预检，当模型训练使用重计算时，跳过反向算子预检，默认模型关闭重计算。 | 否    |
 
 #### 3.1.3 局域网场景配置示例
 
-若采用 TLS1.2 协议加密传输 api 数据，需配置 SSL 证书，可参考如下生成自签名证书方法，仅供调试使用，生产环境请申请正式证书。
+若采用 TLS1.2 协议加密传输 api 数据，需配置 SSL 证书，可参考如下生成自签名证书方法。
+
+以下秘钥生成方法仅为简单示例，客户应使用与自己需求相符的秘钥生成和存储机制并保证秘钥安全性与机密性，必要时可采用分层秘钥机制。
+以下示例中加密口令仅供参考，使用时请更换为复杂口令，并保护口令安全。
 ```shell
-# 创建私钥文件server.key
-openssl genrsa -out server.key 2048
+# 生成CA证书的根私钥和证书签名请求，其中ca_password为CA私钥加密口令，仅作演示，请更换使用
+openssl req -new -newkey rsa:3072 -passout pass:ca_password -subj "/CN=*ca.com/O=ca.Inc./C=CN/ST=Zhejiang/L=Hangzhou" -keyout ca.key -out ca.csr
+# 自签发根证书
+openssl x509 -req -days 365 -in ca.csr -signkey ca.key -passin pass:ca_password -out ca.crt -extensions v3_ca -extfile <(cat <<-EOF
+[v3_ca]
+basicConstraints = critical,CA:true
+keyUsage = critical, keyCertSign, cRLSign
+EOF
+)
+
+# 生成client公私钥，其中client_password为私钥加密口令，仅作演示，请更换使用
+openssl genrsa -aes256 -passout pass:client_password -out client.key 3072
+# 基于client公私钥生成签名请求
+openssl req -new -key client.key -passin pass:client_password -subj "/CN=*example.com/O=Test, Inc./C=CN/ST=Zhejiang/L=Hangzhou" -out client.csr
+# 利用自签发的根证书，签发client证书
+openssl x509 -req -days 180 -CA ca.crt -CAkey ca.key -passin pass:ca_password -in client.csr -out client.crt -CAcreateserial -extfile <(cat <<-EOF
+[v3_server]
+basicConstraints = CA:FALSE
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+EOF
+)
+
+# 生成server公私钥，server_password
+openssl genrsa -aes256 -passout pass:server_password -out server.key 3072
+# 基于server公私钥生成签名请求
+openssl req -new -key server.key -passin pass:server_password -subj "/CN=*example.com/O=Test, Inc./C=CN/ST=Zhejiang/L=Hangzhou" -out server.csr
+# 利用自签发的根证书，签发server证书
+openssl x509 -req -days 180 -CA ca.crt -CAkey ca.key -passin pass:ca_password -in server.csr -out server.crt -CAcreateserial -extfile <(cat <<-EOF
+[v3_server]
+basicConstraints = CA:FALSE
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+EOF
+)
 
-# 创建签名请求文件server.csr
-openssl req -new -key server.key -out server.csr
+```
+
+当需要吊销已创建的SSL证书时，通过openssl命令生成CRL证书 crl.pem，示例如下：
+```shell
+# 创建证书信息的文本数据库，空文件即可
+touch index.txt
+
+# 创建ca配置文件ca.cnf，内容如下，用于吊销证书使用
+[ca]
+default_ca = CA_default
+[CA_default]
+database = ./index.txt
+default_md = sha256
+
+# 吊销证书 client.crt
+openssl ca -revoke client.crt -config ca.cnf -cert ca.crt -keyfile ca.key -passin pass:ca_password
+# 生成CRL文件
+openssl ca -gencrl -config ca.cnf -cert ca.crt -keyfile ca.key -passin pass:ca_password -out crl.pem -crldays 30
+# 查看生成的CRL文件内容：
+openssl工具的命令： openssl crl -inform PEM -in crl.pem -text
 
-# 自签名, 生成1年期公钥文件server.crt
-openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
 ```
 
 注意：配置TLS协议时，传输性能受机器环境和网络质量的影响，可能触发NPU超时中断模型训练，为避免训练和预检中断，丢弃长时间未传输的api数据，同时NPU侧配置HCCL环境变量，配置方式如下：
@@ -231,3 +283,13 @@ bash train.sh
 - npu_scaled_masked_softmax
 
 - npu_swiglu
+
+- npu_apply_adam
+
+- npu_group_norm_silu
+
+- npu_mish
+
+- npu_moe_gating_top_k_softmax
+
+- npu_sort_v2

msprobe/docs/09.accuracy_checker_MindSpore.md

@@ -2,7 +2,7 @@
 
 ## 1 简介
 
-**MindSpore 动态图精度预检**<sup>a</sup>通过扫描昇腾 NPU 上用户训练 MindSpore 模型中的所有 Mint API，输出精度情况的诊断和分析。工具以模型中所有 Mint API 前反向的 dump 结果为输入，构造相应的 API 单元测试，将 NPU 输出与标杆（CPU 高精度）比对，计算对应的精度指标，从而找出 NPU 中存在精度问题的 Mint API。本工具支持**随机生成模式和真实数据模式**<sup>b</sup>。
+**MindSpore 动态图精度预检**<sup>a</sup>通过扫描昇腾 NPU 上用户训练 MindSpore 模型中的所有 Mint API 以及 Msadapter场景下迁移的 Mindspore API，输出精度情况的诊断和分析。工具以模型中所有 API 前反向的 dump 结果为输入，构造相应的 API 单元测试，将 NPU 输出与标杆（CPU 高精度）比对，计算对应的精度指标，从而找出 NPU 中存在精度问题的 API。本工具支持**随机生成模式和真实数据模式**<sup>b</sup>。
 
 a. 支持 Mindspore 版本：2.4/2.5；
 
@@ -34,9 +34,18 @@ msprobe -f mindspore run_ut -api_info ./dump.json -o ./checker_result
 | -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。对其中的mint api以及部分Tensor api进行预检，预检支持的Tensor api列表详见 [ 预检支持列表](../mindspore/api_accuracy_checker/checker_support_api.yaml)。            |  str      | 是      |
 | -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。                                                                                                                                                              |   str   | 否      |
 | -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。  |  str   | 否      |
+| -save_error_data                    | 保存(随机数据模式)精度未达标的 API 输入输出数据。                                                                                                                                                    | 空         | 否      |
 
 预检执行结果包括 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 两个文件。`accuracy_checking_result_{timestamp}.csv` 属于 API 级，标明每个 API 是否通过测试。建议用户先查看 `accuracy_checking_result_{timestamp}.csv` 文件，对于其中没有通过测试的或者特定感兴趣的 API，根据其 API Name 字段在 `accuracy_checking_details_{timestamp}.csv` 中查询其各个输出的达标情况以及比较指标。详细介绍请参见 [4 预检结果](#4-预检结果)。
 
+随机数据模式下，如果需要保存比对不达标的输入和输出数据，可以在 run_ut 执行命令结尾添加 `-save_error_data`，例如：
+
+```bash
+msprobe -f mindspore run_ut -api_info ./dump.json -o ./checker_result -save_error_data
+```
+
+数据默认会存盘到 '{out_path}/error_data' 路径下。
+
 ### 3.2 使用 multi_run_ut 执行多线程预检
 
 multi_run_ut 脚本，可以并行在多个Device执行 run_ut 操作，从而减少预检耗时。示例如下：
@@ -45,16 +54,19 @@ multi_run_ut 脚本，可以并行在多个Device执行 run_ut 操作，从而
 msprobe -f mindspore multi_run_ut -api_info ./dump.json -d 0 1 2 3
 ```
 
-| 参数名称     | 说明                                                                                                                                                                              |参数类型    | 是否必选     |
-| ---------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------- | ---------------------------------- |
-| -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。对其中的mint api以及部分Tensor api进行预检，预检支持的Tensor api列表详见 [ 预检支持列表](../mindspore/api_accuracy_checker/checker_support_api.yaml)。                                   |  str      | 是      |
-| -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。                                                                                                                                                              |   str   | 否      |
-| -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 |  str   | 否      |
-| -d 或 --device                 | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0，支持同时指定 0 ~ Device数量 - 1 ，例如 0 1 2 3 4。                                 |                                      List[int]  | 否      |
+| 参数名称     | 说明                                                                                                                                                                              | 参数类型      | 是否必选     |
+| ---------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------| ---------------------------------- |
+| -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。对其中的mint api以及部分Tensor api进行预检，预检支持的Tensor api列表详见 [ 预检支持列表](../mindspore/api_accuracy_checker/checker_support_api.yaml)。                                 | str       | 是      |
+| -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。                                                                                                                                                              | str       | 否      |
+| -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 | str       | 否      |
+| -d 或 --device                 | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0，支持同时指定 0 ~ Device数量 - 1 ，例如 0 1 2 3 4。                                                                                                       | List[int] | 否      |
+| -save_error_data                    | 保存(随机数据模式)精度未达标的 API 输入输出数据。                                                                                                                                                    | 空         | 否      |
 
 在不同卡数下，使用38B语言大模型的预检耗时基线参考 [multi_run_ut耗时基线](accuracy_checker_MindSpore/accuracy_checker_MindSpore_baseline.md)
 
 
+数据默认会存盘到 './ut_error_data{timestamp}' 路径下
+
 ### 3.3 断点续检
 
 断点续检操作通过如下命令执行：