MA-Advisor使用指导

工具安装

1. 下载ma-advisor安装包至开发环境中。
2. （可选）完成软件包签名校验。
   1. 下载软件包签名校验文件。
   2. 安装openssl并进行软件一致性验证，具体签名校验命令如下：

   openssl cms -verify -binary -in ma_advisor-latest-py3-none-any.whl.cms -inform DER -content ma_advisor-latest-py3-none-any.whl  -noverify > ./test

   签名校验结果如下所示则完成软件的一致性验证。

   图1 一致性验证
   

3. 执行安装命令。

   pip install ma_advisor-latest-py3-none-any.whl

工具使用流程

代码迁移性能调优流程主要如下：

MA-Advisor命令总览

MA-Advisor当前支持如下四种命令：

• analyze：根据Profiling单卡数据进行相关调优分析，并给出调优建议。
• query：根据Profiling单卡timeline数据，输入算子相关参数，查询出算子详细信息。
• env：对当前昇腾环境进行运行前预检查，分析出相关环境问题，并给出环境检查修复建议。
• update: 更新用于分析的知识库，将云端知识库同步至分析环境中。
• auto-completion：自动补全模式，在终端中自动完成MA-Advisor命令补全，支持“bash（默认）/zsh/fish”。

在执行任何命令前，如果对其参数有疑问，可执行-h进行查看帮助，例如：

ma-advisor analyze -h

图4 查看帮助

analyze命令详解

• all：同时进行融合算子图调优、亲和API替换调优、AICPU调优、算子调优等分析，并输出相关简略建议到执行终端中，并生成“ma_advisor_**.html”文件可供用户在浏览器中进行预览：

  ma-advisor analyze all --data-dir='/temp/profiling_dir'

  图5 命令样例
  

  命令执行后同时会生成各场景优化建议的html，相关算子问题概览会按照不同建议进行汇总。

  图6 生成结果
  

  表1 参数解释

  参数	缩写	是否必填	说明
  --data-dir	-d	必填	代表存储Profiling单卡性能数据的目录，目前暂不支持同时分析多卡Profiling目录，Profiling数据可通过如下方法获取： 在执行推理或训练程序时，完成Profiling数据的采集、解析与导出（您可以在昇腾文档页面左上角切换版本，选择对应版本的指导文档）。数据采集时需要配置“aic-metrics”参数为“PipeUtilization”，“aicpu”参数为“on”。 MA-Advisor依赖Profiling工具解析后的timeline数据、summary数据以及info.json*文件，请确保指定的“profiling_dir”目录下存在以上文件。
  --cann_version	-cv	选填	使用Profiling工具采集时对应的CANN软件版本，可通过在环境中执行如下命令获取其version字段，目前配套的兼容版本为“6.3.RC2”，“7.0.RC1”和“7.0.0”，此字段不填默认按“7.0.RC1”版本数据进行处理，其余版本采集的Profiling数据在分析时可能会导致不可知问题： cat /usr/local/Ascend/ascend-toolkit/latest/aarch64-linux/ascend_toolkit_install.info
  --torch_version	-tv	选填	运行环境的torch版本，默认为1.11.0，支持torch1.11.0和torch2.1.0，当运行环境torch版本为其他版本如torch1.11.3时，可以忽略小版本号差异选择相近的torch版本如1.11.0。
  --debug	-D	选填	工具执行报错时可打开此开关，将会展示详细保存堆栈信息。
  --help	-h，-H	选填	在需要查询当前命令附属子命令或相关参数时，给出帮助建议。

• graph：单独对推理dump的子图数据进行调优，并在分析完成后，给出相关建议到终端中，并生成“ma_advisor_graph_**.html”文件到执行目录中，目前暂不支持同时分析多卡推理性能数据：

  ma-advisor analyze graph --data-dir='/temp/profiling_dir'

  图7 命令样例
  

  命令执行后生成融合算子优化建议的HTML，相关融合算子问题概览会按照不同融合算子类型进行汇总。

  图8 生成结果
  

  表2 参数解释

  参数	缩写	是否必填	说明
  --data-dir	-d	必填	代表存储Profiling单卡性能数据的目录，目前暂不支持同时分析多卡Profiling目录，Profiling数据可通过如下方法获取： 在执行推理或训练程序时，完成Profiling数据的采集、解析与导出（您可以在昇腾文档页面左上角切换版本，选择对应版本的指导文档）。数据采集时需要配置“aic-metrics”参数为“PipeUtilization”，“aicpu”参数为“on”， “with_stack”参数为True。 MA-Advisor依赖Profiling工具解析后的timeline数据、summary数据以及info.json*文件，请确保指定的“profiling_dir”目录下存在以上文件。
  --cann_version	-cv	选填	使用Profiling工具采集时对应的CANN软件版本，可通过在环境中执行如下命令获取其version字段，目前配套的兼容版本为“6.3.RC2”，“7.0.RC1”和“7.0.0”，此字段不填默认按“7.0.RC1”版本数据进行处理，其余版本采集的Profiling数据在分析时可能会导致不可知问题： cat /usr/local/Ascend/ascend-toolkit/latest/aarch64-linux/ascend_toolkit_install.info
  --debug	-D	选填	工具执行报错时可打开此开关，将会展示详细保存堆栈信息。
  --help	-h，-H	选填	在需要查询当前命令附属子命令或相关参数时，给出帮助建议。

• profiling：单独对推理、训练Profiling性能数据进行算子调优分析，在分析完成后，给出相关分析说明到执行终端中，并生成“ma_advisor_profiling_**.html”文件到执行目录中，目前暂不支持同时分析多卡Profiling性能数据。

  ma-advisor analyze profiling --data-dir='/temp/profiling_dir'

  图9 命令样例
  

  命令执行后生成AICORE算子使用AOE配置优化建议、AICPU算子优化建议的HTML，目前由于AOE优化不支持动态shape算子优化，因此如果检测到算子均为动态shape时，将不会推荐AOE调优；除此之外，单算子问题概览会按照不同算子类型进行汇总，同时根据耗时大小进行降序显示。

  图10 生成结果
  

  表3 参数解释

  参数	缩写	是否必填	说明
  --data-dir	-d	必填	代表存储Profiling单卡性能数据的目录，目前暂不支持同时分析多卡Profiling目录，Profiling数据可通过如下方法获取： 在执行推理或训练程序时，完成Profiling数据的采集、解析与导出（您可以在昇腾文档页面左上角切换版本，选择对应版本的指导文档）。数据采集时需要配置“aic-metrics”参数为“PipeUtilization”，“aicpu”参数为“on”。MA-Advisor依赖Profiling工具解析后的timeline数据、summary数据以及info.json*文件，请确保指定的“profiling_dir”目录下存在以上文件。
  --cann_version	-cv	选填	使用Profiling工具采集时对应的CANN软件版本，可通过在环境中执行如下命令获取其version字段，目前配套的兼容版本为“6.3.RC2”，“7.0.RC1”和“7.0.0”，此字段不填默认按“7.0.RC1”版本数据进行处理，其余版本采集的Profiling数据在分析时可能会导致不可知问题： cat /usr/local/Ascend/ascend-toolkit/latest/aarch64-linux/ascend_toolkit_install.info
  --ntework_type	-t	选填	“train”或者“infer”，不填默认为“train”。
  --debug	-D	选填	工具执行报错时可打开此开关，将会展示详细保存堆栈信息。
  --help	-h，-H	选填	在需要查询当前命令附属子命令或相关参数时，给出帮助建议。

• timeline：单独对推理、训练timeline性能数据进行亲和API调优分析，在分析完成后，给出相关亲和API分析说明到执行终端中，并生成“ma_advisor_timeline_**.html”文件到执行目录中，目前暂不支持同时分析多卡Profiling性能数据。

  ma-advisor analyze timeline --data-dir='/temp/profiling_dir'

  图11 命令样例
  

  命令执行后生成亲和API相关优化建议的html，将会按建议替换的亲和API进行汇总聚类，同时给出对应待替换API的堆栈信息。

  图12 生成结果
  

  表4 参数解释

  参数	缩写	是否必填	说明
  --data-dir	-d	必填	代表存储Profiling单卡性能数据的目录，目前暂不支持同时分析多卡Profiling目录，Profiling数据可通过如下方法获取： 在执行推理或训练程序时，完成Profiling数据的采集、解析与导出（您可以在昇腾文档页面左上角切换版本，选择对应版本的指导文档）。数据采集时需要配置“aic-metrics”参数为“PipeUtilization”，“aicpu”参数为“on”， “with_stack”参数为True。 MA-Advisor依赖Profiling工具解析后的timeline数据、summary数据以及info.json*文件，请确保指定的“profiling_dir”目录下存在以上文件。
  --cann_version	-cv	选填	使用Profiling工具采集时对应的CANN软件版本，可通过在环境中执行如下命令获取其version字段，目前配套的兼容版本为“6.3.RC2”，“7.0.RC1”和“7.0.0”，此字段不填默认按“7.0.RC1”版本数据进行处理，其余版本采集的Profiling数据在分析时可能会导致不可知问题： cat /usr/local/Ascend/ascend-toolkit/latest/aarch64-linux/ascend_toolkit_install.info
  --debug	-D	选填	工具执行报错时可打开此开关，将会展示详细保存堆栈信息。
  --help	-h，-H	选填	在需要查询当前命令附属子命令或相关参数时，给出帮助建议。

query命令详解

timeline：单独对推理、训练timeline性能数据进行单算子详情查询，根据算子名称以及任务类型（AI_CPU|AI_CORE）进行查询，算子查询统计信息输出到运行终端，并在执行目录下的"log/ma_advisor.xlsx"文件中给出相关算子详细信息。

ma-advisor query timeline --data-dir='/temp/profiling_dir' --op_name='Mul' --task_type='AI_CPU'

auto-completion命令详解

支持自动补全模式，在终端中自动完成ma-advisor命令补全，支持“bash（默认）/zsh/fish”。

ma-advisor auto-completion Bash

图15 提示

根据提示，在terminal中输入对应的命令即可开启在bash中对MA-Advisor相关命令自动补全功能，例如，执行如下命令后，即可在bash命令行中，后续执行ma-advisor相关命令时，使用Tab键即可自动补全：

eval "$(_MA_ADVISOR_COMPLETE=bash_source ma-advisor)"

update命令详解

获取云端知识库至本地，可基于最新的知识库进行调优建议分析。

ma-advisor update rule

图16 提示

根据提示，在terminal中，可以通过“ADVISOR_RULE_PATH”环境变量设置知识库的本地路径。

工具扫描结果解读

• AI CPU算子分析和处理

  MA-Advisor工具分析结果的html文件中会有下述链接，提供AI CPU算子相关问题的修复指导和案例。

  图17 AI CPU算子分析和处理
  

• 亲和API替换

  MA-Advisor工具分析结果的html文件中会有下述链接，提供亲和API替换相关问题的修复指导和代码样例。

  图18 亲和API替换