AI Core Error问题分析工具使用指南（msaicerr工具）

在使用msaicerr工具前，可以通过source ${install_path}/latest/bin/setenv.bash命令使CANN基础环境变量生效，然后在“Toolkit包安装路径{$install_path}/tools/msaicerr”目录下获取msaicerr.py。

使用场景概述

执行业务时，若日志文件或屏幕打印信息中包含如下AI Core Error报错，此时，需要先使用故障信息收集工具asys收集故障信息，再配合使用AI Core Error分析工具msaicerr快速定位AI Core error问题的关键原因，提升开发者对AI Core Error的排查效率。

# 报错示例
there is an xx aicore error

# 或报错示例
there is an xx aivec error

使用约束

该工具仅支持本地分析使用，即部署该工具的环境应该和日志所在环境为同一环境（运行环境）。
该工具依赖python3.7.5或以上版本，在安装该工具的环境中需提前安装python。
该工具不支持在以下场景中使用：
- 不支持RC模式
- 不支持分析单算子API（例如aclnn类API）场景的AI Core问题

前提条件

已在CANN运行环境上安装toolkit包。详细安装请参见《CANN 软件安装指南》。

已配置CANN基础环境变量。安装CANN软件后，使用CANN运行用户编译、运行时，需要以CANN运行用户登录环境，执行. ${install_path}/set_env.sh命令设置环境变量。其中${install_path}为CANN软件的安装目录。

在使用msaicerr工具前，在“Toolkit包安装路径{$install_path}/tools/msaicerr”目录下获取msaicerr.py。

使用指导

以运行用户登录CANN运行环境。
使用故障信息收集工具asys收集故障信息。
使用工具收集信息后，需检查dfx/data-dump目录下是否存在dump文件、检查dfx/ops目录下是否存在算子编译信息（算子编译*.o和*.json文件）、检查dfx/log/cann目录下是否日志文件，若不存在，则无法使用msaicerr工具提取AI Core Error信息。
- 单机场景，执行asys launch命令，执行业务复跑+故障信息收集
```
asys launch --task="sh ../app_run.sh" [--output="path"]
```
  task表示要复跑的任务，output表示收集信息所存放的目录。
  
  注意：推理场景下，需先使用asys launch命令复跑ATC模型转换任务，再使用重新编译的模型、使用asys launch命令复跑推理业务。另外，还需将模型转换时收集的维测信息与推理时收集的维测信息放到一个目录下，例如：$HOME/asys_output。
- 集群场景，先配置收集故障信息相关的环境变量，再执行asys collect命令，收集故障信息
  1. 在各节点上配置以下环境变量，用于收集各节点上的关键报错信息。
    若不设置这些环境变量，会收集集群中各节点的报错信息，报错信息较多，不利于后续分析定位。
```
export DUMP_GE_GRAPH=2               # 控制dump图的内容多少，取值为2，不含有权重等数据的基础版dump
export DUMP_GRAPH_LEVEL=3            # 控制dump图的数量，取值为3，dump最后阶段的生成图
export ASCEND_GLOBAL_LOG_LEVEL=1     # 设置全局日志级别，取值为1，代表INFO
export NPU_COLLECT_PATH=$HOME/demo   # 指定路径，用于收集dump图及算子编译.o文件
```
  2. 再次执行业务，例如执行业务脚本。
  3. 在报错的节点上，执行asys collect命令，收集故障信息。
```
asys collect --task_dir="path" [--output="path"]
```
    task_dir为用于指定收集算子编译文件和dump图的目录，必须与NPU_COLLECT_PATH环境变量指定的路径保持一致；output表示收集信息所存放的目录。
使用AI Core Error分析工具msaicerr快速定位AI Core Error问题的关键原因。
进入“Toolkit包安装路径{$install_path}/tools/msaicerr”目录，根据2中获取到故障信息，执行以下命令提取AI Core Error问题相关的关键信息。
```
python3 msaicerr.py -p $HOME/asys_output
```
- 如果执行msaicerr.py脚本报错“ModuleNotFoundError: No module named 'google'”,是由于缺少protobuf库（用于存储数据的一种数据格式），需使用pip3 install protobuf --user命令安装protobuf库后，再执行脚本。
- 如果执行msaicerr.py脚本报错“ModuleNotFoundError: No module named 'chardet'”，是由于缺少chardet库（用于检测字符编码），需使用pip3 install chardet --user命令安装chardet库后，再执行脚本。
- 如果执行msaicerr.py脚本报错“ModuleNotFoundError: No module named 'bfloat16ext'”，是缺少bfloat16ext库（用于解析bf16类型的数据），需使用pip3 install bfloat16ext --user命令安装bfloat16ext库后，再执行脚本。
另外，可以使用命令python3 msaicerr.py -h，查看具体参数的含义。

以上命令中的“$HOME/asys_output”目录需根据2中存放的目录替换，执行命令成功后，在执行命令的同级目录下生成“info_{时间戳}/{aicore_{number}_{时间戳}/info.txt”文件，用户可以直接通过info.txt文件进行问题分析和定位，info.txt文件示例及各类问题的分析方法请参见使用msaicerr工具分析AI Core Error问题。若故障信息中存在多个AI Core Error问题，则msaicerr工具按日志时间解析第一次出现的AI Core Error问题。

父主题： 常用故障定位工具