【经验分享】MindStudio基于AscendCL应用开发流程

本教程配套有视频教程，详情请见：
哔哩哔哩视频链接： https://www.bilibili.com/video/bv1jN4y1T7Nf?vd_source=239e2a092790e50cd9036e56c5cba9c6

1. AscendCL应用简介

AscendCL（Ascend Computing Language）提供Device管理、Context管理、Stream管理、内存管理、模型加载与执行、算子加载与执行、媒体数据处理等C语言API库供用户开发深度神经网络应用，用于实现目标识别、图像分类等功能。用户可以通过第三方框架调用AscendCL接口，以便使用昇腾AI处理器的计算能力；用户还可以使用AscendCL封装实现第三方lib库，以便提供昇腾AI处理器的运行管理、资源管理能力。
在运行应用时，AscendCL调用GE执行器提供的接口实现模型和算子的加载与执行、调用运行管理器的接口实现Device管理/Context管理/Stream管理/内存管理等。
计算资源层是昇腾AI处理器的硬件算力基础，主要完成神经网络的矩阵相关计算、完成控制算子/标量/向量等通用计算和执行控制功能、完成图像和视频数据的预处理，为深度神经网络计算提供了执行上的保障。
图 1 逻辑架构图

2. Windows安装MindStudio

MindStudio可以单独安装在Windows上。在安装MindStudio前需要在Linux服务器上安装部署好Ascend-cann-toolkit开发套件包，之后在Windows上安装MindStudio，安装完成后通过配置远程连接的方式建立MindStudio所在的Windows服务器与Ascend-cann-toolkit开发套件包所在的Linux服务器的连接，实现全流程开发功能。具体安装流程可以参考Windows安装MindStudio（https://support.huaweicloud.com/devg-mindstudio304/atlasms_02_0019.html），MindStudio环境搭建指导视频（https://bbs.huaweicloud.com/forum/forum/thread-183030-1-1.html）。
本文教程基于MindStudio5.0.RC1 x64，CANN版本5.1.RC1实现。

3. 创建应用工程

3.1 新建应用工程方式

步骤一 进入工程创建页面。
首次登录MindStudio：单击New Project。
非首次登录MindStudio：在顶部菜单栏中选择File > New > Project…。
步骤二 在New Project窗口中，选择Ascend App，按图2配置工程。
图 2 工程创建图

图 3 新建配置服务器

图 4 服务器配置

图 5 选择远程CANN安装位置

非root用户按实际情况选择CANN安装路径，这里以root用户为例。上述配置完成我们点击Finish等待CANN环境导入完成然后点击Next。
步骤三 在New Project窗口中，选择工程类型。
图 6 选择项目类型

Acl Project为AscendCL空白工程，仅包括开发框架的工程，不含具体的代码逻辑。
Acl ResNet-50为AscendCL样例工程，是以acl_resnet50样例为模板的工程。
acl_resnet50样例主要是基于Caffe ResNet-50网络（单输入、单Batch）实现图片分类的功能。将Caffe ResNet-50网络的模型文件转换为适配昇腾AI处理器的离线模型（.om文件），在样例中，加载该om文件，对用户自己准备的若干张.jpg图片进行同步推理，此处以2张图片为例，可以自行准备多张，只需要修改相应代码即可，分别得到推理结果后，再对推理结果进行处理，输出top5置信度的类别标识。
图 7 ResNet-50推理过程

步骤四 单击Finish，完成工程创建。成功创建工程后，工程目录的主要结构如下，请以实际获取为准。
Acl Project（C/C++）：
├── 工程名
│ ├── .idea //IntelliJ IDEA自动创建的，用于存放项目的配置信息。
│ ├── build
│ │ ├──cmake //存放cmake依赖文件
│ ├── out //存放编译出的可执行文件。
│ ├── src
│ │ ├── CMakeLists.txt //编译脚本
│ │ ├── main.cpp //主函数的实现文件，当前主函数内无代码逻辑
│ ├── .project //工程信息文件，包含工程类型、工程描述、运行目标设备类型以及CANN版本。
│ ├── CMakeLists.txt //编译脚本，调用src目录下的CMakeLists文件。
│ ├── 工程名.iml //IntelliJ IDEA自动创建的模块文件，用于Java应用开发，存储一些模块开发相关的信息。

Acl Project（Python）：无代码目录。
 
Acl ResNet-50（C++）：
├── 工程名
│ ├── .idea //IntelliJ IDEA自动创建的，用于存放项目的配置信息。
│ ├── build
│ │ ├──cmake //存放cmake依赖文件
│ ├── data
│ ├── model
│ ├── inc
│ │ ├── model_process.h //声明模型处理相关函数的头文件
│ │ ├── sample_process.h //声明资源初始化/销毁相关函数的头文件
│ │ ├── utils.h //声明公共函数（例如：文件读取函数）的头文件
│ ├── out //存放编译出的可执行文件
│ ├── script
│ │ ├── transferPic.py //将*.jpg转换为*.bin，同时将图片从1024683的分辨率缩放为224224
│ ├── src
│ │ ├── acl.json //系统初始化的配置文件
│ │ ├── CMakeLists.txt //编译脚本
│ │ ├── main.cpp //主函数，图片分类功能的实现文件
│ │ ├── model_process.cpp //模型处理相关函数的实现文件
│ │ ├── sample_process.cpp //资源初始化/销毁相关函数的实现文件
│ │ ├── utils.cpp //公共函数（例如：文件读取函数）的实现文件
│ ├── .project //工程信息文件，包含工程类型、工程描述、运行目标设备类型、CANN版本号等
│ ├── CMakeLists.txt //编译脚本，调用src目录下的CMakeLists文件
│ ├── 工程名.iml //IntelliJ IDEA自动创建的模块文件，用于Java应用开发，存储一些模块开发相关的信息。
│ ├── readme.md //样例工程的readme文件
 
Acl ResNet-50（Python）：
├── 工程名
│ ├── .idea //IntelliJ IDEA自动创建的，用于存放项目的配置信息。
│ ├── data
│ ├── model
│ ├── src
│ │ ├── acl_net.py //运行文件
│ │ ├── constant.py //常量定义。
│ ├── .project //工程信息文件，包含工程类型、工程描述、运行目标设备类型以及CANN版本。
│ ├── 工程名.iml //IntelliJ IDEA自动创建的模块文件，用于Java应用开发，存储一些模块开发相关的信息。
3.2 导入应用工程方式
步骤一 导入工程文件。
首次登录MindStudio：在MindStudio欢迎界面中单击“Open”，选择需要导入的工程，单击“OK”确认导入。
进入工程创建页面，在顶部菜单栏中选择File > Open…，选择现有工程打开。
步骤二 若工作窗口已打开其他工程，会出现如图所示提示。
选择“This Window”，则直接在当前工作窗口打开新创建的工程；选择“New Window”，则新建一个工作窗口打开新创建的工程。
图 8 导入工程提示

4. 准备模型文件和数据

4.1 创建Acl Project工程时

根据实际应用的场景，添加用于推理的模型文件和图片数据集。
步骤一 转换模型（具体步骤参见后文章节4.3模型转换内容）。
在添加模型文件前，您需要先参见模型转换将第三方模型转换为适配昇腾AI处理器的离线模型（*.om文件）。
步骤二 添加模型文件。
请用户自行将准备好的模型om文件上传到创建的工程中。
步骤三 准备推理数据。
准备推理所用数据，并上传到应用工程文件目录下。

4.2 创建Acl ResNet-50工程时

4.2.1 RestNet-50模型介绍
本次实验我们的目标是在MindStudio上使用ResNet进行图像分类任务。ResNet曾在ILSVRC2015比赛中取得冠军，在图像分类上具有很大的潜力。 ResNet的主要思想是在网络中增加了直连通道，使得原始输入信息能够直接传输到后面的层中，ResNet的残差块的结构如下图所示。
图 9 RestNet残差块结构

ResNet会重复将残差块串联，形成多层网络。一般常见的ResNet根据层数的大小ResNet-18，ResNet-34，ResNet-50，ResNet-101等等。后面的数字代表网络的层数，此次实验以RestNet50训练模型作为演示对象。
4.2.2 开发步骤
步骤一 准备数据。
您可以从以下链接中获取ResNet-50网络的模型文件（.prototxt）、预训练模型文件（.caffemodel），并以MindStudio安装用户将获取的文件上传至MindStudio安装服务器。
ResNet-50网络的模型文件（.prototxt）：单击https://modelzoo-train-atc.obs.cn-north-4.myhuaweicloud.com/003_Atc_Models/AE/ATC%20Model/resnet50/resnet50.prototxt下载该文件。
ResNet-50网络的预训练模型文件（.caffemodel）：单击https://modelzoo-train-atc.obs.cn-north-4.myhuaweicloud.com/003_Atc_Models/AE/ATC%20Model/resnet50/resnet50.caffemodel下载该文件。
步骤二 转换模型。
在添加模型文件前，您需要先将第三方模型转换为适配昇腾AI处理器的离线模型（*.om文件）。详情请参见后文章节4.3模型转换内容。
步骤三 （可选）如果需要使用dump功能。

1. 打开MindStudio，选择“Ascend > Dump Configuration”菜单，弹出“Select Offline Model”窗口，如图10所示。
   图 10 选择模型
   

2. 选择.om模型文件，单击“OK”，展示模型文件结构，设置dump开关。如图11所示。
   如果涉及多个模型需要dump数据，则需要分别设置各个模型文件的dump配置项。
   当使用相同系列网络模型时，可能会存在因模型的Model Name值相同，造成生成的acl.json文件中dump配置混淆。
   例如，先使用yolov2进行了dump配置，然后又使用yolov3，此时虽然未对yolov3配置，但acl.json文件中已经记录了yolov2的dump配置，又因为yolov2与yolov3的Model Name值相同，这样就会出现yolov3继承了yolov2的配置。
   因此，当存在因使用相同系列网络模型造成Model Name相同时，可以通过修改Caffe模型文件prototxt中的name字段值并重新进行模型转换，使得系列模型的name字段值不同；也可以在dump配置时先选择None进行清理之前的配置，再次重新进行dump配置。
   图 11 dump配置
   

通过窗口右侧配置项，设置.om模型文件的dump配置项。
Dump Option：配置dump范围。
ALL：所有算子开启dump。
不具有输出的TBE算子、AI CPU算子，如StreamActive、NetOutput、Send、Recv、const等不会生成dump数据。
Several：自定义部分算子开启dump。
选择该项后，需要右键单击待dump数据的算子并选择“Enable Dump”。
对于关联的算子需要同时开启或关闭dump：通过ATC解析om模型文件得到算子之间的映射关系，识别出是新增算子、一对多、多对一、多对多、L1 Batch等关系。
const算子不支持开启dump。
采用dump部分算子场景下，因data算子不会在AI CPU或AI Core上执行，如果用户dump data节点算子，需要一并选择dump data节点算子的后继节点，才能dump出data节点算子数据。
不具有输出的TBE算子、AI CPU算子，如StreamActive、Send、Recv、const等不会生成dump数据；编译后的模型中部分算子并不会在AI CPU或AI Core执行，如concatD类型算子，则无法生成dump数据。
None：所有算子不开启dump。

Dump Mode：dump数据模式。
Input：dump算子的输入数据。
Output：dump算子的输出数据。
All：同时dump算子的输入、输出数据。

Dump Path：配置保存dump数据文件的路径，默认为：{project_path}/dump。如果Dump Path设置为其他路径，需要确保MindStudio安装用户对该路径具有读写权限。

AclConfig File：Acl配置文件，在dump操作中该文件保存算子的dump配置信息。一般路径为{project_path}/src/acl.json，实际路径可以在{project_path}/.project文件中查找。格式如图12或图13所示。当选择整个模型dump时，不含layer字段。
图 12 整网所有算子开启dump

图 13 部分算子开启dump

3. 设置dump完成后，分别单击MindStudio界面“Build”和“Run”菜单，重新编译和运行应用工程。（建议先检查工程文件代码，确保正确引用了设置dump配置的.om模型文件。例如检查aclmdlLoadFromFile()函数或aclmdlLoadFromFileWithMem()函数。）
   工程运行完毕后，可以在{project_path}/dump路径下查看到生成的dump数据文件。生成的路径及格式说明：
   time：dump数据回传落盘时间。格式为：YYYYMMDDhhmmss。
   device_id：Device设备ID号。
   model_name：模型名称。
   model_id：模型ID号。
   data_index：针对每个Task ID执行的次数维护一个序号，从0开始计数，该Task每dump一次数据，序号递增1。
   dump文件：命名规则如{op_type}.{op_name}.{taskid}.{timestamp}。
   如果model_name、op_type、op_name出现了“.”、“/”、“\”、空格时，转换为下划线表示。
   图 14 dump结果
   

步骤四 准备推理数据。
Linux使用场景请参照创建的应用工程根目下的README_CN.md文件中的“编译运行”下的“准备输入图片”，准备输入图片。
Windows使用场景下，也可以执行以下步骤转换图片格式。
首先我们将图片存放至项目data文件夹，结果如图 15所示。
图 15 图片存放路径

右键单击data文件夹，依次选择 Open in -> Terminal。
图 16 开启终端

在终端执行python …\script\transfer_pic.py 命令，提示操作成功证明数据准备完成。
图 17 执行图形处理脚本

图 18 图形处理结果

4.3 模型转换

用户使用Caffe/TensorFlow等框架训练好的模型，可通过ATC工具将其转换为昇腾AI处理器支持的离线模型，模型转换过程中可以实现算子调度的优化、权重数据重排、内存使用优化等，可以脱离设备完成模型的预处理，详细架构如图 19所示。
图 19 ATC工具功能架构

首先找到MindStudio顶部工具栏，选择如下Model Converter图标。
图 20 选择模型转换图标

图 21 选择模型存放位置

图 22 确定模型存放位置

配置完成后，点击OK，此处注意可能等待时间较长，我们无需操作，等待软件加载完成即可。

模型加载完成后如图23所示：

图 23 加载完成图示

点击Next继续操作。
图 24 中间过程一

继续单击Next。

图 25 中间过程二

点击Finish。

图 26 转换完成图

此时MindStudio控制台会有日志输出，当提示模型转换完成后，我们在指定model路径下便可以得到转换好的模型，效果如图。
图 27 模型存放位置

5. 应用开发
   创建应用工程后，工程的src目录下自带应用的模板代码，包含系统初始化、模型执行、模型卸载、资源销毁等代码，若想直接使用src目录下的*.cpp模板代码，则只需按照模型文件和图片的名称、所在的路径修改sample_process.cpp中的如下代码，此处只能设置相对路径，不能设置绝对路径。
6. 请根据实际情况，修改图片文件的名称以及路径。
   //此处的…表示相对路径，相对可执行文件所在的目录
   //例如，编译出来的可执行文件存放在out目录下，此处的…就表示out目录的上一级目录
   string testFile[] = {
   “…/data/dog1_1024_683.bin”,
   “…/data/dog2_1024_683.bin”
   };

图 28 配置图片路径

2. 请根据实际情况，修改*.om模型文件的名称。
   //此处的…表示相对路径，相对可执行文件所在的目录
   //例如，编译出来的可执行文件存放在out目录下，此处的…就表示out目录的上一级目录
   const char* omModelPath = “…/model/resnet50.om”;

图 29 配置模型路径

6. 编译与运行工程

6.1 C++实现

6.1.1 项目编译
a. 在MindStudio工程界面，依次选择“Build > Edit Build Configuration…”，进入编译配置页面（如Windows场景编译运行，图为配置示例），配置完成后单击“OK”保存编译配置。
图 30 编译参数配置

b. 在MindStudio工程界面，依次选择“Build > Build > Restnet50(上面编译配置里面的Name)”，或者直接点击上方工具栏锤子图标。编译过程不报错提示Done则证明编译完成。

图 31 编译完成图示

6.1.2 项目运行
a. 在MindStudio工程界面，依次选择“Run > Edit Configurations…”，进入运行配置页面。
b. 选择“Ascend App > 工程名”配置应用工程运行参数。
图 32 运行参数配置

相关配置参数如下所示：

通过Deployment功能可以将指定的文件、文件夹同步到远程指定机器的指定目录。

1. 在菜单栏选择File > Settings…。在左边的导航栏选择“Tools > Deployment”，进入图33。
   图 33 Deployment界面
   

相关参数及图标说明如下：

2. 配置远程服务器连接。
   图 34 Connection
   

相关参数及图标说明如下：

3. （必选）配置映射路径关系。
   图 35 Mappings
   

相关参数及图标说明如下：

4. （可选）配置排除路径信息，用户根据需要配置。
   图 36 Excluded Paths
   

相关参数及图标说明如下：

5. 单击“Apply”，Deployment配置生效。
   当在使用run/debug项目时，会触发Deployment同步功能。
   如果需要自动触发Deployment功能，可进行如下操作实现：
   1.在菜单栏选择File > Settings… 。
   在左边的导航栏选择“Tools > Deployment”进入Deployment界面，将指定远程服务器信息为默认远程服务器。
   2.在菜单栏选择“Tools > Deployment > Automatic Upload”。
   注意：针对上传过程，deployment会将mapping中的“Local Path”完全映射于对应的“Deployment Path”，若本地有a、b和c文件，而远端“Deployment Path”中有d文件，上传的结果是远端对应目录下只有a、b和c文件，d文件会被删除。针对下载过程，不会使用完全映射过程，如远端有a、b、c文件，本地有d文件，下载的结果是本地对应目录存在a、b、c和d文件。

c. 配置完成后，单击“Apply”保存运行配置，单击“OK”，关闭运行配置窗口。
d. 在MindStudio工程界面，依次选择“Run > Run…”。在弹出框中选择已创建好的运行配置信息，运行应用。如果在运行过程中无错误提示，且提示“Running *** finished”，则表示运行结束。如果运行过程中有错误提示，且需要查看运行环境的详细日志时，请参见准备文档中的《日志参考》：
可参见“日志文件介绍”查看日志，日志文件路径默认为“$HOME/ascend/log ”。
可参见“设置日志级别”查看或修改日志级别（默认为ERROR）。
 
图 37 运行结果

运行结果中我们可以得到输入图片置信度最高的5个分类，则证明整个项目配置编译运行完成。

6.2 Python实现

步骤一 模型转换以及准备数据参见章节4准备模型文件和数据。将数据以及模型文件添加到data以及model目录。目录结构如下图所示。
图 38 Python实现目录结构

步骤二 配置运行参数，可执行文件指向src目录下的acl_net.py文件。具体配置如下图。
图 39 Python运行参数配置

更多配置信息见此表。

步骤三 运行工程，在MindStudio工程界面，依次选择“Run > Run…”。在弹出框中选择已创建好的运行配置信息，运行应用。运行结果如下图。
图 40 Python实现运行结果

7. FAQ

1. 基于C++实现以及基于Python实现，两者实现最大的区别在哪？
   答：C++实现需要经过编译运行后才能运行，Python实现配置好即可运行，无需编译操作。

2. 程序提示运行完成，但是没有结果输出，可能是哪里有问题？
   

答：如上图输出日志所示，我们配置的可执行文件路径指向了.keep，并非编译后的可执行文件，重新配置，指向out路径下的可执行main文件即可。

3. 运行时出现如下的错误，可能是什么问题？
   

答：如上图报错信息所示，服务器无法连接，需要检查服务器连接情况，修改服务器密码或其他信息后再次执行运行操作即可。

8. 从昇腾官方体验更多内容

更多的疑问和信息可以在昇腾论坛进行讨论和交流：https://bbs.huaweicloud.com/forum/forum-726-1.html