分析操作

PyTorch Analyse工具提供分析脚本，帮助用户在执行迁移操作前，分析基于GPU平台的PyTorch训练脚本中API、三方库套件、亲和API分析以及动态shape的支持情况，四种模式区别如下：

API支持情况分析模式：用户提供待分析的PyTorch训练脚本，可快速获得该训练脚本中不支持的torch API和cuda API信息，并输出训练脚本中API精度和性能调优的专家建议。
三方库套件分析模式：用户提供待分析的三方库套件源码，可快速获得源码中不支持的三方库API和cuda信息。

三方库API是指在三方库代码中的函数，如果某函数的函数体内使用了不支持的torch算子或者cuda自定义算子，则此函数就是三方库不支持的API。如果第三方库中其他函数调用了这些不支持的API，则这些调用函数也为不支持的API。
动态shape分析模式：用户提供待分析的PyTorch训练脚本，可快速获得该训练脚本中包含的动态shape信息。
亲和API分析模式：用户提供待分析的PyTorch训练脚本，可快速获得该训练脚本中可替换的亲和API信息。

前提条件

使用PyTorch Analyse工具前须安装如下依赖。

如下命令如果使用非root用户安装，需要在安装命令后加上--user，例如：pip3 install pandas --user，安装命令可在任意路径下执行。

pip3 install pandas         #pandas版本号需大于或等于1.2.4
pip3 install libcst         #Python语法树解析器，用于解析Python文件
pip3 install prettytable    #将数据可视化为图表形式
pip3 install jedi           #三方库套件、亲和API分析时必须安装

启动分析任务

进入分析工具所在路径。

cd Ascend-cann-toolkit安装目录/ascend-toolkit/latest/tools/ms_fmk_transplt/

启动分析任务。

参考表1配置信息，执行如下命令启动分析任务。

./pytorch_analyse.sh -i 待分析脚本路径 -o 分析结果输出路径 -v 待分析脚本框架版本 [-m 分析模式]

其中“[]”表示可选参数，实际使用可不用添加。若“-m/--mode”参数指定的分析模式为dynamic_shape，分析任务完成后需参考后续操作对训练脚本进行修改，才能获取动态shape分析报告。

表1 参数说明
参数	参数说明	取值示例
-i --input	待分析脚本文件所在文件夹或三方库套件源码所在文件夹路径。必选。	/home/xxx/analysis
-o --output	分析结果文件输出路径。会在该路径下生成xxxx_analysis文件夹。必选。	/home/xxx/analysis_output
-v --version	待分析脚本或三方库套件源码的PyTorch版本。目前支持1.11.0、2.1.0、2.2.0。必选。	1.11.0 2.1.0 2.2.0
-m --mode	分析的模式。目前支持torch_apis（API支持情况分析）、third_party（三方库套件分析）、affinity_apis（亲和API分析）和dynamic_shape（动态shape分析）模式。可选。	torch_apis（默认） third_party affinity_apis dynamic_shape
-env --env-path	分析时需要增加的PYTHONPATH环境变量路径，仅安装jedi后该参数才生效。可选。	/home/xxx/transformers/src /home/xxx/transformers/utils 多个文件路径使用空格隔开。
-api --api-files	三方库不支持API的分析结果文件。可选。	/home/xxx/mmcv_analysis/full_unsupported_results.csv /home/xxx/transformers_analysis/full_unsupported_results.csv 多个文件路径使用空格隔开。
-h --help	显示帮助信息。	-

分析完成后，进入脚本分析结果输出路径，查看分析结果文件。

分析模式为“torch_apis”时，分析结果如下所示：

├── xxxx_analysis     // 分析结果输出目录
│   ├── cuda_op_list.csv             //cuda API列表
│   ├── unknown_api.csv              //支持情况存疑的API列表
│   ├── unsupported_api.csv          //不支持的API列表
│   ├── api_precision_advice.csv    //API精度调优的专家建议
│   ├── api_performance_advice.csv  //API性能调优的专家建议和和指导措施
│   ├── pytorch_analysis.txt         // 分析过程日志

分析模式为“third_party”时，分析结果如下所示：

├── xxxx_analysis     // 分析结果输出目录
│   ├── cuda_op.csv                  //cuda API列表
│   ├── framework_unsupported_op.csv //框架不支持的API列表
│   ├── full_unsupported_results.csv //全量不支持的API列表
│   ├── migration_needed_op.csv      //待迁移的API列表
│   ├── unknown_op.csv              //支持情况存疑的API列表
│   ├── pytorch_analysis.txt         // 分析过程日志

分析模式为“affinity_apis”时，分析结果如下所示：

├── xxxx_analysis // 分析结果输出目录
│   ├──  affinity_api_call.csv      // 可替换为亲和API的原生API调用列表
│   ├──  pytorch_analysis.txt       // 分析过程日志

分析模式为“dynamic_shape”时，分析结果如下所示：
```
├── xxxx_analysis     // 分析结果输出目录
│   ├── 生成脚本文件                 // 与分析前的脚本文件目录结构一致
│   ├── msft_dynamic_analysis
│         ├── hook.py         //包含动态shape分析的功能参数
│         ├── __init__.py
```
生成动态shape分析结果件后，还需要先修改训练脚本文件读取训练数据集的for循环，手动开启动态shape检测，请参考下方示例进行修改。
修改前：
```
for i, (ings, targets, paths, _) in pbar:
```
修改如下加粗字体信息：
```
for i, (ings, targets, paths, _) in DETECTOR.start(pbar):
```
运行分析修改后的训练脚本，将在分析结果件所在的根目录下生成保存动态shape的分析报告msft_dynamic_shape_analysis_report.csv。
- 动态shape分析得到的模型训练脚本文件建议在GPU上执行。若已完成模型训练脚本文件迁移且需要在NPU上运行时，则存在动态shape的算子运行时间将会较长。
- 若生成的msft_dynamic_shape_analysis_report.csv文件内容为空时，表示训练脚本中没使用动态shape。

查看分析报告

分析模式为“torch_apis”时，分析报告示例如下：
- unsupported_api.csv：不支持的API列表。对于当前框架不支持的API，可以在昇腾开源社区寻求帮助。
  图1 不支持的API列表示例
- cuda_op_list.csv：当前训练脚本包含的cuda API信息。
- unknown_api.csv：支持情况存疑的API列表，如果训练失败，可以到昇腾开源社区求助。
- api_precision_advice.csv：当前训练脚本中可以进行精度调优的专家建议，除此之外，还可以使用《精度比对工具使用指南》进行调优。
- api_performance_advice.csv：当前训练脚本中可以进行性能调优的专家建议和指导措施，除此之外，还可以使用《性能分析工具使用指南》进行调优。
  
  分析结果基于原生PyTorch框架2.2.0/2.1.0/1.11.0的API接口信息，具体请参见PyTorch框架2.2.0/2.1.0/1.11.0的API接口介绍。
分析模式为“third_party”时，分析报告示例如下：
- framework_unsupported_op.csv：框架不支持的API列表，查看三方库源码中当前框架不支持的三方库 API。对于当前框架不支持的API，可以到昇腾开源社区求助。
  图2 框架不支持的API列表示例
- cuda_op.csv：当前三方库源码包含的cuda API信息。
- full_unsupported_results.csv：全量不支持的API列表。可以在其他调用已分析三方库源码的训练脚本执行分析操作时，使用“-api”指定，帮助用户快速获得分析结果。
- migration_needed_op.csv：待迁移的API列表，列表中的API支持使用迁移工具进行迁移。
- unknown_op.csv：支持情况存疑的API列表。如果训练失败，可以到昇腾开源社区求助。
分析模式为“affinity_apis”时，分析报告affinity_api_call.csv包括原生API的调用信息，并将其分为几种类型：class（类）、function（方法）、torch（Pytorch框架API）以及special（特殊表达式）。用户可以根据分析报告，在训练脚本中将原生API手动替换为指定的亲和API，替换后的脚本在昇腾AI处理器上运行时，性能更优。分析报告示例如下。
图3 亲和API分析报告示例
分析模式为“dynamic_shape”时，分析报告msft_dynamic_shape_analysis_report.csv包括函数名称（Function Name）、调用栈（Call Stack）、输入输出的shape范围等内容，示例如下。
图4 动态shape的分析报告示例

父主题： 分析迁移工具