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”时，分析结果如下所示：
查看分析报告
- 分析模式为“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：当前训练脚本中可以进行性能调优的专家建议和指导措施，除此之外，还可以使用《性能分析工具使用指南》进行调优。
- unsupported_api.csv：不支持的API列表。对于当前框架不支持的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列表。如果训练失败，可以到昇腾开源社区求助。
- framework_unsupported_op.csv：框架不支持的API列表，查看三方库源码中当前框架不支持的三方库 API。对于当前框架不支持的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的分析报告示例
