# CANN

青云1000开发板使用了华为昇腾`Ascend 310`AI处理器作为自身的`CPU`与`NPU`，可以享受华为`CANN`异构计算架构为AI推理带来的极致加速。

## 简介
![CANN](https://r.huaweistatic.com/s/ascendstatic/lst/as/software/cann/pc/part1/img_cann_22080810.svg)

**CANN**（Compute Architecture for Neural Networks）是华为针对AI场景推出的**异构计算架构**，角色和功能类似于`NVIDIA CUDA`。用户可以在代码中调用CANN提供的编程接口，让程序利用昇腾NPU的算力进行计算。

## 相关资源
- [CANN主页](https://www.hiascend.com/software/cann)
- [CANN中文文档](https://www.hiascend.com/zh/document)
- [CANN社区版下载](https://www.hiascend.com/software/cann/community-history)
- [CANN样例仓库](https://gitee.com/ascend/samples)
- [昇腾AI模型开源社区](https://www.hiascend.com/zh/software/modelzoo)

## 准备安装
### 确定CANN版本
在安装CANN之前，首先需要确定青云系统所支持的CANN版本。您可以在[该表格](./02快速上手.md/#获取系统镜像)中查找到不同青云镜像所支持的CANN版本。

本章以`Ubuntu 18.04`系统(固件版本`21.0.4.9`)为例，叙述`CANN 6.0.1.alpha001`的安装流程。

### 获取用户手册
CANN有着详尽的用户手册与说明文档。确定要安装的CANN版本之后，您可以访问[CANN 社区版历史版本仓库](https://www.hiascend.com/software/cann/community-history)，在仓库中找到您所需的CANN版本。

以`CANN 6.0.1.alpha001`为例，您可以在仓库中找到它对应的用户手册。我们将参考该手册进行后续的安装：
![CANN用户手册](_static/images/cann_doc.png)

### 重要概念
> *CANN（Compute Architecture for Neural Networks）是华为公司针对AI场景推出的异构计算架构，通过提供多层次的编程接口，支持用户快速构建基于昇腾平台的AI应用和业务。*

简而言之，您可以将CANN理解为**一组“工具和程序库”的集合**。用户可以：
- 使用CANN提供的**工具**来开发、调试自己的深度学习代码与模型
- 在代码中调用CANN**程序库**提供的接口，利用NPU进行运算加速

和NVIDIA CUDA类似，CANN的工具和程序库也由**开发环境**与**运行环境**两部分组成。对于**青云开发板**来说：
- 如果您只需要在开发板上训练和推理深度学习模型，**不需要进行模型的开发与转换**，您可以只在青云上安装CANN的**运行环境**
- 如果您**既需要在开发板上训练和推理深度学习模型，又需要进行模型的开发与转换**，您可以在青云上安装CANN的**开发环境**

```{tip}
**对于青云开发板而言，我们推荐您安装CANN的开发环境**。这样一来，您可以在开发板中体验到CANN的全部功能。
```

### 安装思路
以`CANN 6.0.1.alpha001`为例，在青云开发板中安装CANN**开发环境**的流程如下图所示。图片来源于[用户手册](https://www.hiascend.com/document/detail/zh/canncommercial/601/envdeployment/instg/)，其中绿色的线路为安装流程，红框是需要执行的关键步骤。

![CANN安装流程](_static/images/cann_install_flow.png)

在青云中安装CANN开发环境的大致步骤如下：
1. 下载并准备好CANN的开发环境软件包
2. 选择为哪一个用户安装CANN开发环境
3. 为操作系统安装CANN需要的系统依赖包
4. 准备好CANN需要的Python3环境
5. 安装CANN开发环境
6. 激活CANN开发环境

## 安装CANN
本节我们以`Ubuntu 18.04`和`CANN 6.0.1.alpha001`为例，演示在青云开发板上为`HwHiAiUser`用户安装`CANN开发环境`的流程。您也可以参考该流程和CANN用户手册，安装支持的其它CANN版本和环境。

### 准备开发环境软件包
[参考手册](https://www.hiascend.com/document/detail/zh/canncommercial/601/envdeployment/instg/instg_000018.html)

进入[CANN 社区版历史版本仓库](https://www.hiascend.com/software/cann/community-history)，在仓库中找到您所需的CANN版本。在筛选器中勾选`AArch64`与`run`选项，在`软件名称`一列中找到含有`toolkit`关键词的一行，这就是适用于青云的CANN开发环境安装包。
![CANN toolkit](_static/images/cann_toolkit.png)

安装包下载完毕后，您可以使用[MobaXterm](./03连接青云.md#mobaxterm)作为终端，以`HwHiAiUser`用户身份登录青云开发板的系统。在MobaXterm左侧边栏中，使用`上传按钮`或直接`拖拽文件`，将CANN开发环境安装包上传到青云系统的指定目录下。

如下图所示，CANN开发环境安装包被上传到了`/home/HwHiAiUser/`目录
![CANN上传](_static/images/cann_upload.png)

上传完毕后，为安装包添加可执行权限
```shell
chmod +x CANN开发环境安装包文件
# 如： chmod +x ./Ascend-cann-toolkit_6.0.1_linux-aarch64.run
```

### 选择安装用户
[参考手册](https://www.hiascend.com/document/detail/zh/canncommercial/601/envdeployment/instg/instg_000019.html)

在本文档中，我们选择只为`HwHiAiUser`用户安装CANN开发环境（即所谓的**用户级安装**）。CANN相关的工具和库将被默认安装至`/home/HwHiAiUser/Ascend/`目录。

### 安装系统依赖包
[参考手册](https://www.hiascend.com/document/detail/zh/canncommercial/601/envdeployment/instg/instg_000023.html)

保持青云开发板的互联网连接，然后为青云的操作系统安装以下软件包
```shell
sudo apt update
sudo apt install gcc g++ make cmake zlib1g zlib1g-dev openssl libsqlite3-dev libssl-dev libffi-dev unzip pciutils net-tools libblas-dev gfortran libblas3
```

### 配置Python3环境
[参考手册](https://www.hiascend.com/document/detail/zh/canncommercial/601/envdeployment/instg/instg_000023.html)

```{caution}
⚠️ 在安装和运行CANN的相关库与工具时，当前环境中**必须存在Python3解释器**。

⚠️ 目前CANN官方支持的Python3解释器版本为：`Python3.7` `Python3.8` `Python3.9`
```
```{tip}
如果您只为`HwHiAiUser`用户安装CANN开发环境，且操作系统中默认的Python3解释器版本不受CANN支持（如`Ubuntu 18.04`默认的Python3解释器为`python3.6`），本文推荐您使用**虚拟环境**来安装CANN。这样可以把`CANN所需的Python3解释器`与`系统自身的Python3解释器`**隔离开来**。
```

根据您的需要，为操作系统安装CANN所需的Python3解释器（`Python3.7`，`Python3.8`或`Python3.9`）
```shell
# 以Python3.7为例
sudo apt install python3.7-dev

# 也可以同时安装多个版本Python3解释器
# 在虚拟环境中，它们之间不会冲突
# sudo apt install python3.8-dev python3.7-dev
```

安装虚拟环境管理器`virtualenv`
```shell
sudo apt install virtualenv
```

#### 新建虚拟环境
作为`HwHiAiUser`用户，使用以下命令，在`/home/HwHiAiUser/`目录下新建一个名称为`cann`的虚拟环境（名称和路径可自定义）。指定刚刚安装的Python3解释器作为虚拟环境中的Python3解释器
```shell
# 以Python3.7为例
virtualenv ~/cann -p /usr/bin/python3.7
```
创建完毕后，`/home/HwHiAiUser/`目录下会多出`cann/`目录。目录中存放了一个完整的Python3环境（包括解释器与程序库），并且与系统的Python3环境隔离。

激活`cann`虚拟环境。此时命令行行首会出现`(cann)`字样，代表您已经进入`cann`虚拟环境。该环境中的Python3解释器为隔离的`Python3.7`。
```shell
# 激活cann虚拟环境
source ~/cann/bin/activate

# 查看虚拟环境中Python3解释器的位置与版本
which python3 && python3 -V

# 查看虚拟环境中Pip3包管理器的位置与版本
which pip3 && pip3 -V

# 退出虚拟环境
# deactivate
```

请保持`cann`虚拟环境的激活状态，在该虚拟环境中安装一系列CANN所需的Python包
```shell
pip3 install attrs numpy decorator sympy cffi pyyaml pathlib2 psutil protobuf scipy requests absl-py

# 如需国内镜像加速
# pip3 install attrs numpy decorator sympy cffi pyyaml pathlib2 psutil protobuf scipy requests absl-py -i https://pypi.tuna.tsinghua.edu.cn/simple
```

至此所有准备工作完成，接下来即可安装CANN开发环境本体。

### 安装CANN开发环境
[参考手册](https://www.hiascend.com/document/detail/zh/canncommercial/601/envdeployment/instg/instg_000031.html)

以`HwHiAiUser`的用户身份，保持`cann`虚拟环境的激活状态，为`HwHiAiUser`用户安装CANN开发环境
```shell
# 先切换到 CANN开发环境安装包文件 所在目录

./CANN开发环境安装包文件 --install
# 如： ./Ascend-cann-toolkit_6.0.1_linux-aarch64.run --install
```

大约等待十几分钟后，CANN开发环境安装完毕。CANN相关的工具和库将被默认安装至`/home/HwHiAiUser/Ascend/`目录。

----

<details>
<summary>点击查看CANN安装日志（仅供参考）</summary>

```
(cann) HwHiAiUser@davinci-mini:~$ ./Ascend-cann-toolkit_6.0.1_linux-aarch64.run --install
Verifying archive integrity...  100%   SHA256 checksums are OK. All good.
Uncompressing ASCEND_RUN_PACKAGE  100%
[Toolkit] [20231009-08:51:46] [INFO] change umask 0027
[Toolkit] [20231009-08:51:46] [INFO] mkdir /home/HwHiAiUser/var/log/ascend_seclog/
[Toolkit] [20231009-08:51:46] [INFO] touch /home/HwHiAiUser/var/log/ascend_seclog/ascend_toolkit_install.log
[Toolkit] [20231009-08:51:46] [INFO] LogFile:/home/HwHiAiUser/var/log/ascend_seclog/ascend_toolkit_install.log
[Toolkit] [20231009-08:51:46] [INFO] install start
[Toolkit] [20231009-08:51:46] [INFO] The installation path is /home/HwHiAiUser/Ascend.
[Toolkit] [20231009-08:51:46] [INFO] install package CANN-runtime-1.84.15.1.310-linux.aarch64.run start
[Toolkit] [20231009-08:52:13] [INFO] CANN-runtime-1.84.15.1.310-linux.aarch64.run --full --quiet --nox11 install success
[Toolkit] [20231009-08:52:13] [INFO] install package CANN-compiler-1.84.15.1.310-linux.aarch64.run start
[Toolkit] [20231009-08:55:56] [INFO] CANN-compiler-1.84.15.1.310-linux.aarch64.run --full --pylocal --quiet --nox11 install success
[Toolkit] [20231009-08:55:56] [INFO] install package CANN-opp-1.84.15.1.310-linux.aarch64.run start
[Toolkit] [20231009-08:59:51] [INFO] CANN-opp-1.84.15.1.310-linux.aarch64.run --full --quiet --nox11 install success
[Toolkit] [20231009-08:59:51] [INFO] install package CANN-toolkit-1.84.15.1.310-linux.aarch64.run start
[Toolkit] [20231009-09:03:21] [INFO] CANN-toolkit-1.84.15.1.310-linux.aarch64.run --full --pylocal --quiet --nox11 install success
[Toolkit] [20231009-09:03:21] [INFO] install package CANN-aoe-1.84.15.1.310-linux.aarch64.run start
[Toolkit] [20231009-09:03:41] [INFO] CANN-aoe-1.84.15.1.310-linux.aarch64.run --full --quiet --nox11 install success
[Toolkit] [20231009-09:03:41] [INFO] install package Ascend-mindstudio-toolkit_5.0.0_linux-aarch64.run start
[Toolkit] [20231009-09:04:11] [INFO] Ascend-mindstudio-toolkit_5.0.0_linux-aarch64.run --full --quiet --nox11 install success
[Toolkit] [20231009-09:04:11] [INFO] install package Ascend-test-ops_6.0.1_linux.run start
[Toolkit] [20231009-09:04:12] [INFO] Ascend-test-ops_6.0.1_linux.run --full --quiet --nox11 install success
[Toolkit] [20231009-09:04:12] [INFO] install package Ascend-pyACL_6.0.1_linux-aarch64.run start
[Toolkit] [20231009-09:04:13] [INFO] Ascend-pyACL_6.0.1_linux-aarch64.run --full --quiet --nox11 install success
[Toolkit] [20231009-09:04:13] [INFO] install package CANN-ncs-1.84.15.1.310-linux.aarch64.run start
[Toolkit] [20231009-09:04:33] [INFO] CANN-ncs-1.84.15.1.310-linux.aarch64.run --full --quiet --nox11 install success
[Toolkit] [20231009-09:04:34] [INFO] The /home/HwHiAiUser/Ascend/ascend_cann_install.info is written successfully.
[Toolkit] [20231009-09:04:34] [INFO] Please make sure that:
PATH includes :
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/bin:
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/compiler/ccec_compiler/bin:
LD_LIBRARY_PATH includes :
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/lib64:
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/lib64/plugin/opskernel:
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/lib64/plugin/nnengine:
PYTHONPATH includes :
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/python/site-packages:
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/opp/built-in/op_impl/ai_core/tbe:
ASCEND_AICPU_PATH includes :
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest:
ASCEND_OPP_PATH includes :
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/opp:
TOOLCHAIN_HOME includes :
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest/toolkit:
ASCEND_HOME_PATH includes :
        /home/HwHiAiUser/Ascend/ascend-toolkit/latest:
[Toolkit] [20231009-09:04:34] [INFO] If your service is started using the shell script, you can call the /home/HwHiAiUser/Ascend/ascend-toolkit/set_env.sh script to configure environment variables. Note that this script can not be executed mannually.
[Toolkit] [20231009-09:04:34] [INFO] Ascend-cann-toolkit_6.0.1_linux-aarch64 install success. The installation path is /home/HwHiAiUser/Ascend.
```

</details>

----

### 激活CANN开发环境
```{tip}
CANN相关工具依赖于Python3环境（`Python3.7`，`Python3.8`或`Python3.9`），所以请先确保相关Python3环境已经激活。
```

为`HwHiAiUser`用户安装好CANN开发环境后，如果需要使用CANN相关工具，执行以下命令激活CANN开发环境
```shell
source /home/HwHiAiUser/Ascend/ascend-toolkit/set_env.sh
```
CANN开发环境激活后，用户即可使用CANN相关的工具和程序库。

测试运行CANN模型转换工具
```shell
atc --help
```

运行pyACL深度神经网络推理库，测试NPU设备能否正常初始化
```shell
# 输出全0则测试正常
python3 -c 'import acl; print(acl.init()); print(acl.rt.set_device(0))'
```

为方便起见，您可以将自动激活CANN开发环境的命令放置到`HwHiAiUser`用户shell登录脚本`~/.bashrc`中
```shell
# 在 ~/.bashrc 中加入如下几行

# 自动激活CANN开发环境
source /home/HwHiAiUser/Ascend/ascend-toolkit/set_env.sh
```
如此操作后，每次以`HwHiAiUser`用户登录shell时，都会自动激活CANN开发环境。您只需要再手动激活相应的Python3环境，就可以使用CANN的所有功能！


#### 在新环境中使用CANN
在安装并测试完CANN的开发环境后，如果您希望在**其它的Python3虚拟环境**（而非之前创建的`cann`虚拟环境）中使用CANN，只需进行如下操作即可：
1. 按照您的需求，激活您指定的Python3虚拟环境
2. 为该环境安装CANN所需的Python3包  
`pip3 install attrs numpy decorator sympy cffi pyyaml pathlib2 psutil protobuf scipy requests absl-py`
3. 激活CANN开发环境（如在`~/.bashrc`中已经激活，则不用再次激活）  
`source /home/HwHiAiUser/Ascend/ascend-toolkit/set_env.sh`

完成上述步骤后，您就可以在其它的Python3虚拟环境中使用CANN的功能。

## 运行样例
在您按照本章内容安装并测试完CANN的开发环境后，本节将尝试在青云开发板上部署基于CANN的深度学习应用。

本节的样例来源于华为的[昇腾样例仓](https://gitee.com/ascend/samples)。

![CANN Samples](https://obs-9be7.obs.cn-east-2.myhuaweicloud.com/data/samples_pic/CANN_samples.png)
> *昇腾样例仓提供了一系列媒体数据处理（DVPP/AIPP）、算子开发与调用（Ascend C）、推理应用开发与部署（AscendCL）等场景的丰富代码样例给开发者进行参考学习，帮助开发者快速入门，进而熟练掌握CANN关键特性使用。*

### YOLOv7目标检测

[样例链接](https://gitee.com/ascend/samples/tree/master/inference/modelInference/sampleYOLOV7NMSONNX)

使用YOLOv7模型对输入图片进行预测推理。在图片上给出物体标注框，类别以及置信度，最后保存。

#### 环境准备
克隆Gitee上最新的昇腾样例仓
```shell
git clone https://gitee.com/ascend/samples.git --depth 1
```

在样例仓库中建立虚拟环境。虚拟环境使用Python3.7作为解释器
```shell
cd samples/
virtualenv ./ -p /usr/bin/python3.7
```

激活虚拟环境
```shell
source bin/activate
```

在当前虚拟环境中安装CANN所需依赖
```shell
pip3 install attrs numpy decorator sympy cffi pyyaml pathlib2 psutil protobuf scipy requests absl-py -i https://pypi.tuna.tsinghua.edu.cn/simple
```

本样例依赖于昇腾的`python-acllite`库，该库的源码位于`samples/`下的`inference/acllite/python/`目录。将该库所在的目录放入虚拟环境的库搜寻路径中
```shell
echo "$PWD/inference/acllite/python/" >> ./lib/python3.7/site-packages/acllite.pth
```

安装本样例所需的其它依赖
```shell
pip3 install opencv-python onnx Pillow -i https://pypi.tuna.tsinghua.edu.cn/simple

# opencv-python依赖于libGL.so.1
sudo apt install libgl1
```

下载测试图片`dog.jpg`到本样例的数据目录`inference/modelInference/sampleYOLOV7NMSONNX/data/`
```shell
wget https://obs-9be7.obs.cn-east-2.myhuaweicloud.com/models/sampleYOLOvxWithPostprocessOp/dog.jpg -P inference/modelInference/sampleYOLOV7NMSONNX/data/ --no-check-certificate
```
![可爱的小狗](_static/images/cann_dog.jpg)

#### 模型转换
进入本样例的根目录
```shell
cd inference/modelInference/sampleYOLOV7NMSONNX/
```

进入本样例的源码目录，创建ONNX后处理算子`postprocess.onnx`
```shell
cd src/
python3 postProcessOperator.py
```

进入样例的模型目录，下载`yolov7x.onnx`模型文件
```shell
cd ../model/
wget https://obs-9be7.obs.cn-east-2.myhuaweicloud.com/models/sampleYOLOvxWithPostprocessOp/yolov7x.onnx --no-check-certificate
```

下载AIPP模型输入预处理配置`aipp.cfg`。CANN的AIPP技术可以使用NPU加速图像预处理过程。
```shell
wget https://obs-9be7.obs.cn-east-2.myhuaweicloud.com/models/sampleYOLOvxWithPostprocessOp/aipp.cfg --no-check-certificate
```

将`yolov7x.onnx`模型和后处理算子转换为适配昇腾310处理器的离线模型（`*.om`文件）
```shell
atc --model=yolov7x.onnx --framework=5 --output=yolov7x --soc_version=Ascend310 --out_nodes="Conv_404:0;Conv_374:0;Conv_344:0" \
--input_shape="images:1,3,640,640" --insert_op_conf=aipp.cfg

atc --model=postprocess.onnx --soc_version=Ascend310 --output=postprocess --framework=5 --input_shape='img_info:1,4'
```

#### 运行推理

进入本样例的源码目录，运行推理脚本
```shell
cd ../src/
mkdir -p ../out/

python3 sampleYOLOV7NMSONNX.py
```

推理结果图片存放于`../out/`目录中
![Yolov7输出](_static/images/cann_dog_out.jpg)