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

msprobe/docs/25.tool_function_introduction.md

@@ -2,28 +2,29 @@
 
 ## 1 PyTorch框架
 
-| 功能名（英文）                                                                            | 简介                                                            | 适用场景/优势                                                                  | 当前版本局限性                                                                                                         |
-|------------------------------------------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
-| [数据采集<br>（dump）](./05.data_dump_PyTorch.md)                                        | 采集模型训练过程中的API或Module层级的前反向输入输出数据，包括层次关系、统计值信息、真实数据和调用栈等。      | 1、将模型中训练的API或Module的前反向输入输出数据保存下来分析<br> 2、模型出现溢出时，可用于查看哪些API或Module出现了溢出 | 1、API级数据采集仅支持白名单列表上的API<br>2、工具会做一些同步操作，引入工具可能会导致一些同步问题消失<br>3、当前对inplace操作API或Module的支持度有限<br>4、暂不支持参数及参数梯度的采集 |
-| [离线预检<br>（api_accuracy_checker）](./07.accuracy_checker_PyTorch.md)                 | 为网络中每个API创建用例，检验其精度，并根据不同比对算法综合判定API在NPU上的精度是否达标，快速找出精度差异API。 | 1、对模型中所有的API做精度初步排查<br>2、精度排查不受模型累计误差影响                                  | 1、依赖GPU环境<br>2、不支持通信算子<br>3、仅支持部分融合算子                                                                           | 
-| [整网比对<br>（compare）](./10.accuracy_compare_PyTorch.md)                              | 计算模型整网NPU和标杆设备的精度误差指标，标记精度异常API或Module，助力快速定位精度问题根因。          | 1、整网比对定位精度可疑算子                                                           | 1、由于使用整网dump数据，定位的可疑算子受累计误差影响<br>2、当模型规模较大时，比对所需时间较长                                                            | 
-| [在线预检<br>（online_api_accuracy_checker）](./08.accuracy_checker_online_PyTorch.md)   | 通过TCP通信或共享存储空间的方式，进行在线精度预检，解决离线预检大数据量落盘、传输困难痛点。               | 1、使用离线预检，数据量较大落盘困难或传输耗时长时，可通过在线预检进行精度排查                                  | 1、依赖GPU环境，NPU和GPU能够通信<br>2、重计算模式下，不支持反向aten算子预检                                                                 | 
-| [溢出检查<br>（overflow_checker）](./12.overflow_check_PyTorch.md)                       | 检测模型计算过程的输入输出，并在溢出时落盘数据，助力用户快速定位溢出位置。                         | 1、当模型出现溢出时，用于快速定位最先溢出的API或Module<br>2、相比数据采集，性能更优，磁盘压力更小                 | 1、局限性同数据采集                                                                                                      | 
-| [数据解析<br>（parse_tool）](./14.data_parse_PyTorch.md)                                 | 互交式界面处理解析kernel层级dump数据，便于查看分析。                               | 1、比对kernel层级dump数据的一致性                                                   | 1、仅限于NPU                                                                                                        | 
-| [无标杆比对<br>（free_benchmark）](./15.free_benchmarking_PyTorch.md)                     | 不依赖标杆数据，通过对算子输入增加微小扰动，计算扰动后输出与原始输出的相对误差，识别有精度风险算子。            | 1、无标杆数据场景下的算子精度排查<br>2、对个别算子进行升精度、“to cpu”等操作，以验证其对模型loss的影响             | 1、由于需要拷贝输入进行二次执行，所以在遇到大张量的输入时容易发生显存OOM的问题, 特别是反向比对过程。建议结合白名单使用<br>2、比对会延长训练时间，整网比对可能会造成严重的耗时膨胀，建议结合白名单使用        |
-| [梯度状态监测<br>（grad_probe）](./17.grad_probe.md)                                       | 可导出模型权重梯度数据并对比相似度，助力确认训练过程精度问题step和反向中的异常。                    | 1、需要分析梯度数据时<br>2、需要定位发生问题的step时                                          | 暂无                                                                                                              | 
-| [在线精度比对<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比对
+| 功能名（英文）                                                                          | 简介                                                                                                                                                | 适用场景/优势                                                                                                                                                       | 当前版本局限性                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [数据采集<br>（dump）](./05.data_dump_PyTorch.md)                                      | 采集模型训练过程中的API或Module层级的前反向输入输出数据，包括层次关系、统计值信息、真实数据和调用栈等。                                             | 1、将模型中训练的API或Module的前反向输入输出数据保存下来分析<br> 2、模型出现溢出时，可用于查看哪些API或Module出现了溢出                                         | 1、API级数据采集仅支持白名单列表上的API<br>2、工具会做一些同步操作，引入工具可能会导致一些同步问题消失<br>3、当前对inplace操作API或Module的支持度有限<br>4、暂不支持参数及参数梯度的采集      |
+| [离线预检<br>（api_accuracy_checker）](./07.accuracy_checker_PyTorch.md)               | 为网络中每个API创建用例，检验其精度，并根据不同比对算法综合判定API在NPU上的精度是否达标，快速找出精度差异API。                                      | 1、对模型中所有的API做精度初步排查<br>2、精度排查不受模型累计误差影响                                                                                           | 1、依赖GPU环境<br>2、不支持通信算子<br>3、仅支持部分融合算子                                                                                                                                      |
+| [整网比对<br>（compare）](./10.accuracy_compare_PyTorch.md)                            | 计算模型整网NPU和标杆设备的精度误差指标，标记精度异常API或Module，助力快速定位精度问题根因。                                                        | 1、整网比对定位精度可疑算子                                                                                                                                         | 1、由于使用整网dump数据，定位的可疑算子受累计误差影响<br>2、当模型规模较大时，比对所需时间较长                                                                                                        |
+| [在线预检<br>（online_api_accuracy_checker）](./08.accuracy_checker_online_PyTorch.md) | 通过TCP通信或共享存储空间的方式，进行在线精度预检，解决离线预检大数据量落盘、传输困难痛点。                                                         | 1、使用离线预检，数据量较大落盘困难或传输耗时长时，可通过在线预检进行精度排查                                                                                       | 1、依赖GPU环境，NPU和GPU能够通信<br>2、重计算模式下，不支持反向aten算子预检                                                                                                                           |
+| [溢出检查<br>（overflow_checker）](./12.overflow_check_PyTorch.md)                     | 检测模型计算过程的输入输出，并在溢出时落盘数据，助力用户快速定位溢出位置。                                                                          | 1、当模型出现溢出时，用于快速定位最先溢出的API或Module<br>2、相比数据采集，性能更优，磁盘压力更小                                                               | 1、局限性同数据采集                                                                                                                                                                                       |
+| [数据解析<br>（parse_tool）](./14.data_parse_PyTorch.md)                               | 交互式界面处理解析kernel层级dump数据，便于查看分析。                                                                                                | 1、比对kernel层级dump数据的一致性                                                                                                                                   | 1、仅限于NPU                                                                                                                                                                                              |
+| [无标杆比对<br>（free_benchmark）](./15.free_benchmarking_PyTorch.md)                  | 不依赖标杆数据，通过对算子输入增加微小扰动，计算扰动后输出与原始输出的相对误差，识别有精度风险算子。                                                | 1、无标杆数据场景下的算子精度排查<br>2、对个别算子进行升精度、“to cpu”等操作，以验证其对模型loss的影响                                                        | 1、由于需要拷贝输入进行二次执行，所以在遇到大张量的输入时容易发生显存OOM的问题, 特别是反向比对过程。建议结合白名单使用<br>2、比对会延长训练时间，整网比对可能会造成严重的耗时膨胀，建议结合白名单使用 |
+| [梯度状态监测<br>（grad_probe）](./17.grad_probe.md)                                   | 可导出模型权重梯度数据并对比相似度，助力确认训练过程精度问题step和反向中的异常。                                                                    | 1、需要分析梯度数据时<br>2、需要定位发生问题的step时                                                                                                            | 暂无                                                                                                                                                                                                      |
+| [在线精度比对<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框架
 
-| 功能名（英文）                                                              | 简介                                                                | 适用场景/优势                                                                      | 当前版本局限性                                                                                                                                           |
-|----------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
-| [数据采集<br>（dump）](./06.data_dump_MindSpore.md)                        | 采集模型训练过程中的API或Cell层级的前反向输入输出数据，包括层次关系、统计值信息、真实数据和调用栈等。            | 1、将模型中训练的API或Cell的前反向输入输出数据保存下来分析<br> 2、模型出现溢出时，可用于查看哪些API或Cell出现了溢出         | 1、API级数据采集仅支持白名单列表上的API<br>2、当前对inplace操作API或Cell的支持度有限<br>3、暂不支持参数及参数梯度的采集                                                                       |
-| [离线预检<br>（api_accuracy_checker）](./09.accuracy_checker_MindSpore.md) | 为网络中每个API创建用例，检验其精度，并根据不同比对算法综合判定API在NPU上的精度是否达标，快速找出精度差异API。     | 1、对模型中所有的API做精度初步排查<br>2、精度排查不受模型累计误差影响                                      | 1、仅针对MindSpore.mint API                                                                                                                           |
-| [整网比对<br>（compare）](./11.accuracy_compare_MindSpore.md)              | NPU精度数据与标杆数据的比对，支持MindSpore框架内和与PyTorch跨框架的比对，助力快速定位精度异常API或Cell。 | 1、MindSpore同框架静态图比对<br>2、MindSpore同框架动态图比对<br>3、MindSpore vs PyTorch跨框架动态图比对 | 1、部分PyTorch的API关联不到MindSpore，需要手动配置映射关系                                                                                                           |
-| [溢出检查<br>（overflow_checker）](./13.overflow_check_MindSpore.md)       | 检测模型计算过程的输入输出，并在溢出时落盘数据，助力用户快速定位溢出位置。                             | 1、当模型出现溢出时，可用于定位最先溢出的API或Cell或kernel<br>2、相比数据采集，性能更优，磁盘压力更小                 | 1、除具有与数据采集功能相同的局限性外，动态图场景下，不支持 Primitive 和 Jit 类 API 的检测<br>2、动态图场景下，仅支持检测API或Cell级别溢出<br>3、静态图场景下，仅支持检测kernel级别溢出                                |
-| [无标杆比对<br>（free_benchmark）](./16.free_benchmarking_MindSpore.md)     | 不依赖标杆数据，通过对算子输入增加微小扰动，计算扰动后输出与原始输出的相对误差，识别有精度风险算子。                | 1、无标杆数据场景下的算子精度排查<br>2、对个别算子进行升精度修复，验证其对模型loss的影响                            | 1、仅支持动态图场景<br>2、由于需要拷贝输入进行二次执行，所以在遇到大张量的输入时容易发生显存OOM的问题, 特别是反向比对过程。建议结合白名单使用<br>3、比对会延长训练时间，整网比对可能会造成严重的耗时膨胀，建议结合白名单使用<br>4、不支持“to cpu”操作，不支持预热功能 |
-| [可视化比对<br>（visualization） ](./22.visualization_MindSpore.md)         | 解析dump的精度数据，还原模型图结构，比对各层级精度数据，助力理解模型结构、分析精度问题。                    | 1、整网精度比对定位可疑算子，通过浏览器展示比对结果，支持快速搜索到可疑算子<br>2、支持查看模型层级结果，比对模型层级结构差异            | 1、由于使用整网dump数据，定位的可疑算子受累计误差影响<br>2、当模型规模较大时，比对所需时间较长                                                                                              |
+| 功能名（英文）                                                               | 简介                                                                                                           | 适用场景/优势                                                                                                                     | 当前版本局限性                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [数据采集 <br>（dump）](./06.data_dump_MindSpore.md)                        | 采集模型训练过程中的API或Cell层级的前反向输入输出数据，包括层次关系、统计值信息、真实数据和调用栈等。          | 1、将模型中训练的API或Cell的前反向输入输出数据保存下来分析 <br> 2、模型出现溢出时，可用于查看哪些API或Cell出现了溢出          | 1、API级数据采集仅支持白名单列表上的API <br>2、当前对inplace操作API或Cell的支持度有限 <br>3、暂不支持参数及参数梯度的采集                                                                                                                                                      |
+| [离线预检 <br>（api_accuracy_checker）](./09.accuracy_checker_MindSpore.md) | 为网络中每个API创建用例，检验其精度，并根据不同比对算法综合判定API在NPU上的精度是否达标，快速找出精度差异API。 | 1、对模型中所有的API做精度初步排查 <br>2、精度排查不受模型累计误差影响                                                        | 1、仅针对MindSpore.mint API                                                                                                                                                                                                                                                            |
+| [整网比对 <br>（compare）](./11.accuracy_compare_MindSpore.md)              | NPU精度数据与标杆数据的比对，支持MindSpore框架内和与PyTorch跨框架的比对，助力快速定位精度异常API或Cell。       | 1、MindSpore同框架静态图比对 <br>2、MindSpore同框架动态图比对 <br>3、MindSpore vs PyTorch跨框架动态图比对                 | 1、部分PyTorch的API关联不到MindSpore，需要手动配置映射关系                                                                                                                                                                                                                             |
+| [溢出检查 <br>（overflow_checker）](./13.overflow_check_MindSpore.md)       | 检测模型计算过程的输入输出，并在溢出时落盘数据，助力用户快速定位溢出位置。                                     | 1、当模型出现溢出时，可用于定位最先溢出的API或Cell或kernel <br>2、相比数据采集，性能更优，磁盘压力更小                        | 1、除具有与数据采集功能相同的局限性外，动态图场景下，不支持 Primitive 和 Jit 类 API 的检测 <br>2、动态图场景下，仅支持检测API或Cell级别溢出 <br>3、静态图场景下，仅支持检测kernel级别溢出                                                                                      |
+| [无标杆比对 <br>（free_benchmark）](./16.free_benchmarking_MindSpore.md)    | 不依赖标杆数据，通过对算子输入增加微小扰动，计算扰动后输出与原始输出的相对误差，识别有精度风险算子。           | 1、无标杆数据场景下的算子精度排查 <br>2、对个别算子进行升精度修复，验证其对模型loss的影响                                     | 1、仅支持动态图场景 <br>2、由于需要拷贝输入进行二次执行，所以在遇到大张量的输入时容易发生显存OOM的问题, 特别是反向比对过程。建议结合白名单使用 <br>3、比对会延长训练时间，整网比对可能会造成严重的耗时膨胀，建议结合白名单使用 <br>4、不支持“to cpu”操作，不支持预热功能 |
+| [可视化比对 <br>（visualization） ](./22.visualization_MindSpore.md)        | 解析dump的精度数据，还原模型图结构，比对各层级精度数据，助力理解模型结构、分析精度问题。                       | 1、整网精度比对定位可疑算子，通过浏览器展示比对结果，支持快速搜索到可疑算子 <br>2、支持查看模型层级结果，比对模型层级结构差异 | 1、由于使用整网dump数据，定位的可疑算子受累计误差影响 <br>2、当模型规模较大时，比对所需时间较长                                                                                                                                                                                    |
+| [训练状态监控 <br>（monitor）](./19.monitor.md)                             | 收集模型训练过程中的激活值、梯度和优化器状态，助力分析计算、通信、优化器各部分异常情况。                       | 1、通过监控模块级统计量指标，快速定位异常模块位置，如loss出现nan                                                                  | 1、仅支持模块级别统计量指标分析 <br>2、仅支持megatron、deepspeed框架 <br>3、少量增加时间和显存膨胀                                                                                                                                                                             |

msprobe/docs/26.data_dump_PyTorch_baseline.md

@@ -1,8 +1,19 @@
 # PyTorch 场景的精度数据采集基线
 
+## "statistics"模式（未开启md5）采集时间膨胀参考基线
+
+该基线为PyTorch框架下，使用"statistics"模式采集数据性能膨胀的参考基线。本基线测试了LLAMA2-7B语言大模型在不同采集模式8卡下的时间膨胀。
+
+| 采集模式 | 无工具 (耗时) |  加工具但未使能 Dump (耗时)   |  加工具并使能 Dump (耗时)  |
+|:--------:|:--------:|:--------------------:|:------------------:|
+| L0       | ≈17.4 s  |    ≈17.4 s （无膨胀）     | ≈78.4 s  （膨胀4.5倍）  |
+| L1       | ≈17.4 s  |  ≈20.7 s  （膨胀1.2倍）   |  ≈353 s  （膨胀20倍）   |
+| mix      | ≈17.4 s  | ≈20.7 s  （膨胀1.2倍） | ≈430 s  （膨胀24.7 倍） |
+
+
 ## "tensor"模式采集数据量参考基线
 
-该基线为pytorch框架下，使用"tensor"模式采集数据量参考基线。本基线测试了两个模型，分别为LLAMA2-7B和LLAMA2-13B，测试了不同采集模式下，不同global_batch_size下，单卡和8卡下，数据量的变化。
+该基线为PyTorch框架下，使用"tensor"模式采集数据量参考基线。本基线测试了两个模型，分别为LLAMA2-7B和LLAMA2-13B，测试了不同采集模式下，不同global_batch_size下，单卡和8卡下，数据量的变化。
 
 ### LLAMA2-7B
 
@@ -25,8 +36,8 @@
 <table>
     <tr><th>采集模式</th><th>global_batch_size</th><th>单卡</th><th>8卡</th></tr>
     </td><td rowspan="3">L0</td><td>1</td><td>13GB</td><td>97GB</td></tr>
-    <tr><td>2</td><td>25B</td><td>194GB</td></tr>
-    <tr><td>3</td><td>37G</td><td>291GB</td></tr>
+    <tr><td>2</td><td>25GB</td><td>194GB</td></tr>
+    <tr><td>3</td><td>37GB</td><td>291GB</td></tr>
     </td><td rowspan="3">L1</td><td>1</td><td>440GB</td><td>3.4TB</td></tr>
     <tr><td>2</td><td>720GB</td><td>5.4TB</td></tr>
     <tr><td>3</td><td>960GB</td><td>7.3TB</td></tr>

msprobe/docs/27.dump_json_instruction.md

@@ -268,7 +268,7 @@ dump.json文件中包含以下数据名称：
 
 mix级别的dump.json文件同时包括L0和L1级别的dump数据，文件格式与上述示例相同。  
 
-## 2. MindSpore 场景下的 dump.json 文件 
+## 2. MindSpore 场景下的 dump.json 文件
 
 ### 2.1 L0 级别  
 

msprobe/docs/28.debugger_save_instruction.md

@@ -1,28 +1,33 @@
-# 单点保存工具 README
+# 单点保存工具
 
 ## 简介
-L0, L1, mix dump存在盲区，网络中的非api/module的输入输出不会被批量dump下来。单点保存提供类似np.save和print的功能和使用体验，可以保存指定的变量。同时针对大模型场景进行了增强，具备以下特性：
+L0, L1, mix级别的dump能力存在盲区，网络中的非API或module的输入输出不会被批量dump下来。单点保存提供类似np.save和print的功能和使用体验，可以保存指定的变量。同时针对大模型场景进行了增强，具备以下特性：
 - 可保存变量的反向梯度结果。
 - 能直接保存嵌套结构数据（如 list、dict），无需手动遍历。
-- 自动分 rank 保存。
+- 自动分 Rank 保存。
+- 可分 Step 保存数据。
 - 多次调用时会自动计数。
-- 可配置保存统计值或者张量。
+- 可配置保存统计值（MindSpore静态图暂不支持）或者张量。
+- 支持异步保存。
 
 ## 支持场景
-仅支持 PyTorch 与 MindSpore 的动态图场景。
 
-## 使能方式
+## 动态图场景（Pytorch&MindSpore）
 
-### 配置文件说明
+###  使能方式
 
-通用配置：
+#### 配置文件说明
+
+通用配置 （细节详见[通用配置说明](./02.config_introduction.md#11-通用配置) ）：
 
 | 参数     | 解释                                       | 是否必选 |
 | -------- |-------------------------------------------| -------- |
 | task     | dump 的任务类型，str 类型。 单点保存场景仅支持传入"statistics", "tensor"。    |  是     |
 | level    | dump 级别，str 类型，根据不同级别采集不同数据。单点保存场景传入"debug"。  | 是  |
-| dump_path  | 设置 dump 数据目录路径，str 类型。细节详见[通用配置说明](./02.config_introduction.md#11-通用配置)  | 是       |
-| rank        | 指定对某张卡上的数据进行采集，list[Union[int, str]] 类型。细节详见[通用配置说明](./02.config_introduction.md#11-通用配置)  | 否       |
+| dump_path  | 设置 dump 数据目录路径，str 类型。 | 是       |
+| rank        | 指定对某张卡上的数据进行采集，list[Union[int, str]] 类型。  | 否       |
+| step    |   指定采集某个 Step 的数据，list[Union[int, str]] 类型。  | 否       |
+| async_dump        | 异步 dump 开关，bool 类型。  | 否       |
 
 "statistics" 任务子配置项：
 | 参数     | 解释                                       | 是否必选 |
@@ -31,19 +36,21 @@ L0, L1, mix dump存在盲区，网络中的非api/module的输入输出不会被
 
 "tensor" 任务无子配置项。
 
-### 接口调用说明
-
-调用PrecisionDebugger.save，传入需要保存的变量，指定变量名称以及是否需要保存反向数据。接口入参说明详见[pytorch单点保存接口](./05.data_dump_PyTorch.md#19-save)，[mindspore单点保存接口](./06.data_dump_MindSpore.md#615-save)
+#### 接口调用说明
 
-### 实例（以pytorch场景为例）
+调用PrecisionDebugger.save，传入需要保存的变量，指定变量名称以及是否需要保存反向数据。接口入参说明详见[PyTorch单点保存接口](./05.data_dump_PyTorch.md#19-save)，[MindSpore单点保存接口](./06.data_dump_MindSpore.md#615-save)
 
+#### 实例
+（以PyTorch场景为例，MindSpore场景只需要从msprobe.mindspore模块导包即可）
 配置文件
 ```json
 {
     "task": "statistics",
     "dump_path": "./dump_path",
     "rank": [],
+    "step": [],
     "level": "debug",
+    "async_dump": false,
     "statistics": {
         "summary_mode": "statistics"
     }
@@ -53,7 +60,7 @@ L0, L1, mix dump存在盲区，网络中的非api/module的输入输出不会被
 初始化
 ```python
 # 训练启动py脚本
-from mindspore.pytorch import PrecisionDebugger
+from msprobe.pytorch import PrecisionDebugger
 debugger = PrecisionDebugger("./config.json")
 for data, label in data_loader:
     # 执行模型训练
@@ -64,7 +71,7 @@ for data, label in data_loader:
 初始化（无配置文件）
 ```python
 # 训练启动py脚本
-from mindspore.pytorch import PrecisionDebugger
+from msprobe.pytorch import PrecisionDebugger
 debugger = PrecisionDebugger(dump_path="dump_path", level="debug")
 for data, label in data_loader:
     # 执行模型训练
@@ -75,20 +82,104 @@ for data, label in data_loader:
 调用保存接口
 ```python
 # 训练过程中被调用py文件
-from mindspore.pytorch import PrecisionDebugger
+from msprobe.pytorch import PrecisionDebugger
 dict_variable = {"key1": "value1", "key2": [1, 2]}
 PrecisionDebugger.save(dict_variable, "dict_variable", save_backward=False)
 
 ```
 
+## 静态图场景（MindSpore）
+
+### 使能方式
+
+#### 接口调用说明
+工具提供两个对外接口`save`和`save_grad`，分别用于保存训练中的tensor以及tensor对应的反向数据
+| 接口名称 | 入参   | device         | MindSpore版本 |备注                                                         |
+| ------- | ------ | -------------- | --------------|--------------------------------------------------- |
+| save     | save_dir name, data    | Ascend   | >= 2.6.0   |  （主流场景）图模式下只支持Ascend，pynative下支持Ascend/GPU/CPU。         |
+| save_grad | save_dir, name, data | Ascend     | >= 2.6.0   |  （主流场景）图模式下只支持Ascend，pynative下支持Ascend/GPU/CPU。         |
+
+
+----
+> 函数原型:
+`save(save_dir:str, name:str, data)`
+- save_dir：表示要保存的目录。
+- name    ：表示要保存的文件标志名称。
+- data    ：表示数据入参，可以是`mindspore.Tensor`或者是`List`,`Tuple`,`Dict`等嵌套结构。
+
+> 函数原型：
+`save_grad(save_dir:str, name:str, data)`
+- save_dir：表示要保存的目录。
+- name    ：表示要保存的文件标志名称。
+- data    ：表示数据入参，**只能**是`mindspore.Tensor`。
+
+#### 实例
+
+- save接口使用：
+
+```python
+# save api usage
+# **first import**
+from msprobe.mindspore import save
+
+
+class Net(nn.Cell):
+    def construct(self, x, y, z):
+        # **use save api**
+        save("./test_dump", 'x', x)
+        return x * y * z
+
+x = Tensor([1, 2], ms.float32)
+y = Tensor([-2, 3], ms.float32)
+z = Tensor([0, 3], ms.float32)
+net = Net()
+output = grad(net, grad_position=(1, 2))(x, y, z)
+time.sleep(1)
+
+# then will generate **./test_dump/step0/rank0/x_float32_0.npy**
+```
+
+- save_grad接口使用：
+
+```python
+# save_grad usage
+# **first import**
+from msprobe.mindspore import save_grad
+class Net(nn.Cell):
+    def construct(self, x, y, z):
+        # **use save api** the return value of save_grad must be received by origin
+        z = save_grad("./test_dump", 'z', z)
+        return x * y * z
+
+x = Tensor([1, 2], ms.float32)
+y = Tensor([-2, 3], ms.float32)
+z = Tensor([0, 3], ms.float32)
+net = Net()
+output = grad(net, grad_position=(1, 2))(x, y, z)
+time.sleep(1)
+
+# then will generate **./test_dump/step0/rank0/z_grad_float32_0.npy**
+```
+**注意**save_grad需要将返回值回传给原tensor，此操作不会有精度影响，只会传递原值。
+
+
 ## 输出结果
+### 动态图场景（Pytorch&MindSpore）
   * **"task" 配置为 "statistics" 场景** ：在 dump 目录下会生成包含变量统计值信息的 `debug.json` 文件。
-  * **"task" 配置为 "tensor" 场景** ：除了在 dump 目录下生成包含变量统计值信息的 `debug.json` 文件外，还会在 dump 子目录 `dump_tensor_data` 中保存张量二进制文件，文件名称格式为 `{variable_name}{grad_flag}.{count}.tensor.{indexes}.{file_suffix}`。
+  `debug.json` 中统计值的key命名格式为 `{variable_name}{grad_flag}.{count}.debug`。
+  * **"task" 配置为 "tensor" 场景** ：除了在 dump 目录下生成包含变量统计值信息的 `debug.json` 文件外，还会在 dump 子目录 `dump_tensor_data` 中保存张量二进制文件，文件名称格式为 `{variable_name}{grad_flag}.{count}.debug.{indexes}.{file_suffix}`。
 
     - variable_name： 传入save接口的变量名称。
     - grad_flag： 反向数据标识，反向数据为"_grad"，正向数据为""。
     - count： 调用计数，多次以相同变量名称调用时的计数。
-    - indexes： 索引，在保存嵌套结构数据时的索引。例如：嵌套结构为`{"key1": "value1", "key2": ["value2", "value3"]}`，"value2"的索引为"key2.0"
-    - file_suffix：文件后缀，pytorch场景为"pt"，mindspore场景为"npy"
+    - indexes： 索引，在保存嵌套结构数据时的索引。例如：嵌套结构为`{"key1": "value1", "key2": ["value2", "value3"]}`，"value2"的索引为"key2.0"。
+    - file_suffix：文件后缀，PyTorch场景为"pt"，MindSpore场景为"npy"。
+
+### 静态图场景（MindSpore）
+在指定目录`save_dir`下生成`{step}/{rank}`目录，目录下生成指定`{name}`的npy文件，如果是save_grad接口调用，则会生成`{name}_grad`的npy文件。
+
+如`save("./test_dump", 'x', x)` -> `./test_dump/step0/rank0/x_float32_0.npy`。
+
+或如`z = save_grad("./test_dump", 'z', z)` -> `./test_dump/step0/rank0/z_grad_float32_0.npy`。
 
 

msprobe/docs/29.data_dump_MSAdapter.md

@@ -13,7 +13,7 @@ functional:  # functional为算子类别，找到对应的类别，在该类别
   - conv3d
 ```
 
-删除 API 的场景：部分模型代码逻辑会存在 API 原生类型校验，工具执行dump操作时，对封装后的模型 API 可能与模型的原生 API 类型不一致，此时可能引发校验失败，详见《[FAQ](FAQ.md)》中“异常情况”的第10和11条。
+删除 API 的场景：部分模型代码逻辑会存在 API 原生类型校验，工具执行dump操作时，对封装后的模型 API 可能与模型的原生 API 类型不一致，此时可能引发校验失败，详见《[FAQ](FAQ.md#33-异常情况)》中“异常情况”的第10和11条。
 
 ## 1. 工具安装
 
@@ -207,7 +207,7 @@ if __name__ == "__main__":
 ```
 * `rank`：设备 ID，每张卡的数据保存在对应的 `rank{ID}` 目录下。非分布式场景下没有 rank ID，目录名称为 rank。
 * `dump_tensor_data`：保存采集到的张量数据。
-* `dump.json`： 保存 API 或 Module 前反向数据的统计量信息。包含 dump 数据的 API 名称或 Module 名称，各数据的 dtype、 shape、max、min、mean、L2norm（L2范数，平方根）统计信息以及当配置 summary_mode="md5" 时的 CRC-32 数据。具体介绍可参考[dump.json文件说明](./27.dump_json_instruction.md#3-MSAdapter场景下的dump.json文件)。
+* `dump.json`： 保存 API 或 Module 前反向数据的统计量信息。包含 dump 数据的 API 名称或 Module 名称，各数据的 dtype、 shape、max、min、mean、L2norm（L2范数，平方根）统计信息以及当配置 summary_mode="md5" 时的 CRC-32 数据。具体介绍可参考[dump.json文件说明](./27.dump_json_instruction.md#3-msadapter-场景下的-dumpjson-文件)。
 * `stack.json`：API/Module 的调用栈信息。
 * `construct.json`：分层分级结构，level 为 L1 时，construct.json 内容为空。
 

msprobe/docs/30.overflow_check_MSAdapter.md

@@ -11,9 +11,9 @@ export INF_NAN_MODE_ENABLE=1
 export MS_ASCEND_CHECK_OVERFLOW_MODE="INFNAN_MODE"
 ```
 
-**a**：在处理浮点数计算溢出问题时，NPU 当前支持两种溢出模式：INF/NAN 模式与饱和模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品，默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2训练系列产品，默认为 INF/NAN 模式，且不建议使用饱和模式。对于 MindSpore 框架侧配置，仅支持对 Atlas A2 训练系列产品进行设置，默认为 INF/NAN 模式。CANN 侧 与 MindSpore 框架侧配置须一致。
+**a**：在处理浮点数计算溢出问题时，NPU 当前支持两种溢出模式：INF/NAN 模式与饱和模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品，默认为饱和模式，且不支持使用 INF/NAN 模式；Atlas A2训练系列产品，默认为 INF/NAN 模式，且不建议使用饱和模式。对于 MindSpore 框架侧配置，仅支持对 Atlas A2 训练系列产品进行设置，默认为 INF/NAN 模式。CANN 侧 与 MindSpore 框架侧配置须一致。
 
-溢出检测任务的配置示例见["**MindSpore 动态图场景 task 配置为 overflow_check**"](./03.config_examples.md#33-task配置为overflow_check)小节。
+溢出检测任务的配置示例见["**MindSpore 动态图场景 task 配置为 overflow_check**"](./03.config_examples.md#33-task-配置为-overflow_check)小节。
 
 
 ## 1 接口介绍

msprobe/docs/31.config_check.md

@@ -0,0 +1,95 @@
+# config check
+
+## 介绍
+
+该工具主要适用于对比两个环境下可能影响训练精度的配置差异，支持mindspore和pytorch两个框架，包括：
+
+- 环境变量
+- 三方库版本
+- 训练超参
+- 权重
+- 数据集
+- 随机操作
+
+
+## 安装教程
+
+参见 msprobe [安装教程](./01.installation.md)
+
+## 使用说明
+
+用户需要在两个待比对的训练的环境上分别进行数据采集, 工具会采集两个环境下影响精度的配置，采集结果上传到同一机器进行比对。
+
+### 数据采集
+
+#### 静态数据采集
+
+静态数据采集仅支持环境变量，三方库版本及训练超参采集，其中环境变量，三方库版本默认采集，训练超参采集需要用户传入启动训练的 shell 脚本路径或 yaml 配置文件，
+支持多个输入，不传入表示不采集。
+
+启动命令如下
+```shell
+msprobe -f pytorch/mindspore config_check -d **.sh **.yaml -o output_path
+```
+-f 代表训练框架，传入pytorch或mindspore，必选。
+
+-d 代表数据采集模式，可传入启动训练的 shell 脚本路径或 yaml 配置文件路径，可选，不传入代表不采集。
+
+-o 代表输出路径，可选，默认为 config_check_pack.zip。
+
+#### 动态数据采集
+
+
+在训练流程执行到的第一个python脚本开始处插入如下代码：
+```
+from msprobe.core.config_check import ConfigChecker
+ConfigChecker.apply_patches(fmk)
+```
+
+说明：
+
+- fmk：训练框架。可选 pytorch 和 mindspore ，不传默认为 pytorch。
+
+在模型初始化好之后插入如下代码：
+```
+from msprobe.core.config_check import ConfigChecker
+ConfigChecker(model, shell_path, output_zip_path, fmk)
+```
+
+说明：
+
+- model：初始化好的模型。不传或缺省就不会采集权重和数据集。
+- shell_path：动态采集模式下支持 **megatron** 训练超参自动捕获，使用 **megatron** 时推荐不传入，其他情况下可传入训练脚本路径，类型为列表，传入一个或多个训练配置/启动脚本。不传或缺省就不会采集超参。
+- output_zip_path：输出zip包的路径，不传默认为"./config_check_pack.zip"。
+- fmk：当前是什么框架。可选 pytorch 和 mindspore ，不传默认为 pytorch。
+
+采集完成后会得到一个zip包，里面包括各项[影响精度的配置](#介绍)。会分rank和step存储，其中step为micro_step。
+
+在另一个环境上执行上述操作，得到另一个zip包
+
+### 数据比对
+
+将两个zip包传到同一个环境下，使用如下命令进行比对：
+
+```shell
+msprobe -f pytorch config_check -c bench_zip_path cmp_zip_path -o output_path
+```
+
+其中**bench_zip_path** 为标杆侧采集到的数据， **cmp_zip_path** 为待对比侧采集到的数据。
+
+**output_path 会被删掉再新建**，不传默认为"./config_check_result"， 在 **output_path** 里会生成2个目录和1个文件：
+- bench：bench_zip_path里打包的数据。
+- cmp：cmp_zip_path里打包的数据。
+- result.xlsx：比对结果。里面会有多个sheet页，其中**summary**总览通过情况，其余页是具体检查项的详情。其中step为micro_step。
+
+## 通过标准
+
+以下五项检查通过：
+
+- 环境变量
+- 三方库版本
+- 训练超参
+- 权重
+- 数据集
+
+这五项检查在**精度比对**前必须保证达成。

msprobe/docs/32.ckpt_compare.md

@@ -0,0 +1,69 @@
+# Checkpoint Compare
+
+## 介绍
+在模型训练过程中或结束后，可能保存一些检查点文件(checkpoint，简称ckpt)记录当前模型、优化器等训练状态, 工具支持比较两个不同的ckpt，评估模型相似度。
+
+当前支持Megatron-LM、MindSpeed(PyTorch/MindTorch)的ckpt比较。支持TP、PP、EP、VPP模型并行；支持megatron.core、megatron.legacy、TransformerEngine的模型实现。
+
+
+## 安装教程
+
+参见 msprobe [安装教程](./01.installation.md)
+
+## 使用说明
+Megatron、MindSpeed的ckpt加载依赖megatron，请确保megatron在python环境中或megatron在当前路径下。
+
+
+启动命令如下
+```shell
+msprobe --framework pytorch config_check --compare path1 path2 -o output_path.json
+```
+
+| 参数名 | 解释 | 是否必选 |
+|--------|-------|--------|
+| -f 或 --framework | 深度学习框架，str类型。支持参数：pytorch,mindspore，注意：msadaptor场景传入mindspore。 | 是 |
+| -c 或 --compare | 2个ckpt的路径 | 是 |
+| -o 或 --output | 比对结果输出路径，默认为 ./ckpt_similarity.json。输出路径存在时将报错终止。 | 否 |
+
+Megatron-LM 和 MindSpeed 的 ckpt 目录结构如下：
+
+```txt
+directory_name/
+├── iter_0000005/ # 某个iteration时的ckpt目录。
+│   └── mp_rank_xx_xxx/  # 单个rank的ckpt目录，xx_xxx为模型并行索引。
+│       └── model_optim_rng.pt   # 包含模型参数、随机状态等的PyTorch binary文件。
+├── iter_0000010/
+├── latest_checkpointed_iteration.txt  # 记录最后一个保存的ckpt的纯文本文件。
+```
+
+对于--compare参数的两个路径，为directory_name时，工具通过latest_checkpointed_iteration.txt自动选择latest checkpoint进行比对. 为directory_name/iter_xxxxxxx时, 工具使用指定iteration的ckpt进行比对。暂不支持单个rank的比对。
+
+## 输出示例
+Checkpoint比对结果以json文件输出，内容如下示例：
+```json
+{
+    "decoder.layers.0.input_layernorm.weight": {
+        "l2": 0.0, 
+        "cos": 0.999999,
+        "numel": 128,
+        "shape": [
+            128
+        ]
+    },
+    "decoder.layers.0.pre_mlp_layernorm.weight": {
+        "l2": 0.012, 
+        "cos": 0.98,
+        "numel": 128,
+        "shape": [
+            128
+        ]
+    }
+}
+```
+
+统计量 | 解释 |
+|-------|---------|
+| l2 | 欧式距离，$\|\|a-b\|\|_2$ |
+| cos | 余弦相似度， $\frac{<a,b>}{\|\|a\|\|_2\|\|b\|\|_2}$ |
+| numel | 参数的元素个数 |
+| shape | 参数的shape |