旭日X3派算法工具链入门指南

参考：旭日X3派用户手册算法工具链开发指南入门指南

环境安装

1. 开发机中执行如下命令，获取模型转换资料包：

wget -c ftp://xj3ftp@vrftp.horizon.ai/ai_toolchain/ai_toolchain.tar.gz --ftp-password=xj3ftp@123$%

wget -c ftp://xj3ftp@vrftp.horizon.ai/model_convert_sample/yolov5s_v2.0.tar.gz --ftp-password=xj3ftp@123$%
1
2
3

2. 创建模型转换环境

conda create -n horizon_bpu python=3.8.10 -y
1

3. 进入模型转换环境

conda activate horizon_bpu
1

4. 解压模型转换环境和示例模型安装包并进行相关依赖的安装：

tar -xzvf yolov5s_v2.0.tar.gz
1

出现：

gzip: stdin: not in gzip format
tar: Child returned status 1
tar: Error is not recoverable: exiting now
1
2
3

查了下说tar包压缩的时候用cvf参数，解压的时候用xvf参数，使用命令：

tar -vxf yolov5s_v2.0.tar.gz
1

即可，继续命令：

tar -vxf ai_toolchain.tar.gz
pip install ai_toolchain/h* -i https://mirrors.aliyun.com/pypi/simple
pip install pycocotools -i https://mirrors.aliyun.com/pypi/simple
1
2
3

在顺利完成安装后，您可以键入 hb_mapper –help 命令验证是否可以正常得到帮助信息，若打印如下信息，说明环境已安装完成：

Usage: hb_mapper [OPTIONS] COMMAND [ARGS]...

  hb_mapper is an offline model transform tool provided by horizon.

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  checker    check whether the model meet the requirements.
  infer      inference and dump output feature as float vector.
  makertbin  transform caffe model to quantization model, generate runtime...
1
2
3
4
5
6
7
8
9
10
11
12

后续进行模型转换时，可使用命令 source activate horizon_bpu 或 conda activate horizon_bpu 进入模型转换环境。

模型准备

进入模型转换环境后，执行以下命令，检查yolov5s浮点模型是否存在：

ls -l yolov5s_v2.0/01_common/model_zoo/mapper/detection/yolov5_onnx_optimized
1

出现：

ls: 无法访问 'yolov5s_v2.0/01_common/model_zoo/mapper/detection/yolov5_onnx_optimized': 没有那个文件或目录
1

怎么回事？是模型示例包没下载成功吗？还是上面环境安装的过程有问题？检查了一下，没有发现；既然终端中提示说是没有那个文件或目录，我们就到上面环境安装里面wget下载后解压的yolov5s_v2.0文件夹下看看，发现01_common文件夹下并没有model_zoo文件夹。

模型验证

若示例浮点模型已准备完成，根据以下步骤进行模型验证，确保其符合地平线X3处理器的支持约束。

• 进入浮点模型转换示例yolov5s模型目录

cd yolov5s_v2.0/04_detection/03_yolov5s/mapper
1

• 模型检查

#确认模型结构及算子是否支持，并提供每个算子执行硬件的分配情况（BPU/CPU）
bash 01_check.sh
1
2

终端出现提示bash: 01_check.sh: 没有那个文件或目录，进入wget下载后解压的yolov5s_v2.0文件夹下的04_detection下03_yolov5s下mapper中，发现有01_check_Ultra.sh和01_check_X3.sh，个人使用的板子为X3，模型检查命令替换为：

bash 01_check_X3.sh
1

命令执行完毕后，成功出现下面日志

2023-12-13 18:29:37,484 INFO [Wed Dec 13 18:29:37 2023] End to Horizon NN Model Convert.
2023-12-13 18:29:37,496 INFO ONNX model output num : 3
2023-12-13 18:29:37,513 INFO End model checking....
1
2
3

模型转换

模型检查通过后，根据以下步骤进行模型转换。

• 进行校准数据预处理

  bash 02_preprocess.sh
  1

  命令执行完毕后，若出现以下日志并无任何报错，说明数据预处理成功

  write:./calibration_data_rgb_f32/COCO_val2014_000000181677.rgb
  write:./calibration_data_rgb_f32/COCO_val2014_000000181714.rgb
  write:./calibration_data_rgb_f32/COCO_val2014_000000181739.rgb
  1
  2
  3

• 模型转换
  同样，命令和手册里面做下改变：

  bash 03_build_X3.sh
  1

  命令执行完毕后，若出现以下日志并无任何报错，说明模型转换成功

  2023-12-14 08:55:04,648 INFO Convert to runtime bin file successfully!
  2023-12-14 08:55:04,648 INFO End Model Convert
  1
  2

  模型转换完成后，会在 model_output 文件夹下保存模型文件和静态性能评估文件。

  • torch-jit-export_subgraph_0.html # 静态性能评估文件（可读性更好）
  • torch-jit-export_subgraph_0.json # 静态性能评估文件
  • yolov5s_672x672_nv12.bin # 用于在地平线处理器上加载运行的模型
  • yolov5s_672x672_nv12_optimized_float_model.onnx # 中间过程模型文件，可用于后续模型的精度校验
  • yolov5s_672x672_nv12_original_float_model.onnx # 中间过程模型文件，可用于后续模型的精度校验
  • yolov5s_672x672_nv12_quantized_model.onnx # 中间过程模型文件，可用于后续模型的精度校验

模型上板运行

注意事项：模型上板运行前，请确保已按照 安装系统 章节完成开发板端的环境部署。 将 yolov5s_672x672_nv12.bin 定点模型拷贝 替换 至开发板的 /app/ai_inference/models 目录下，调用以下命令运行：

cd /app/ai_inference/07_yolov5_sample/
sudo python3 ./test_yolov5.py
1
2

估计是板子有更新，模型存放的目录变动为/app/pydev_demo/models/，发现此目录下的models文件夹为一个文件链接，查看属性发现其链接目标为/app/model/basic，然后去此目录查看，basic链接目标为/opt/hobot/model/x3/basic，所以将 yolov5s_672x672_nv12.bin 定点模型拷贝替换至开发板此目录下，可以将目录中原有yolov5s_672x672_nv12.bin改下名称做一个备份，直接复制提示权限不够，在开发机model_output文件夹下打开终端，使用命令：

sudo cp -i yolov5s_672x672_nv12.bin /media/xxx/rootfs/opt/hobot/model/x3/basic
1

其中 /media/xxx/rootfs/opt/hobot/model/x3/basic根据开发板的存储卡使用读卡器挂载在你电脑上的位置名称确定，xxx替换根据自己电脑而定，可查看文件属性得到；而test_yolov5.py的目录变动为/app/pydev_demo/07_yolov5_sample，因此命令改为：

cd /app/pydev_demo/07_yolov5_sample/
sudo python3 ./test_yolov5.py
1
2

yolov5s_672x672_nv12.bin使用开发机model_output文件夹下的文件替换后，运行上述命令，运行成功后，会输出图像的分割结果，并且dump出分割效果图: result.jpg。运行成功，贴一下手册上的结果：

 ......
    detected item num:  15
    person is in the picture with confidence:0.8555
    person is in the picture with confidence:0.7774
    person is in the picture with confidence:0.6599
    person is in the picture with confidence:0.6310
    person is in the picture with confidence:0.6091
    person is in the picture with confidence:0.5242
    person is in the picture with confidence:0.5182
    person is in the picture with confidence:0.4737
    person is in the picture with confidence:0.4037
    person is in the picture with confidence:0.4023
    kite is in the picture with confidence:0.8651
    kite is in the picture with confidence:0.8428
    kite is in the picture with confidence:0.7063
    kite is in the picture with confidence:0.6806
    kite is in the picture with confidence:0.5446
    ......
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

常用API示例，请参考 yolov5目标检测算法 章节内容:
更多模型推理API使用说明，请参考 Python开发指南-AI 算法推理接口使用说明 和 C/C++开发指南-BPU（算法推理模块）API 章节内容。详见旭日X3派用户手册算法工具链开发指南入门指南。

公版模型性能精度指标

注意：

1. 表格中的数据均为X3M处理器（BPU 1GHz）在开发板端实测的结果（测试模型均来自于horizon_model_convert_sample模型示例包）；
2. 对于 BPU/CPU 混合异构模型，单帧串行下的耗时包括：输入量化CPU节点 + 模型BPU算子 + 模型CPU算子 + 输出反量化CPU节点 + CPU后处理
   a. 输入量化CPU节点：float32->int8，只有 featuremap 输入模型包含，图像输入模型不包含。因为需要遍历数据，所以耗时与 shape 大小成正比
   b. 模型CPU算子：
   ⅰ. 分类模型尾部的 Softmax 和 Reshape 为 CPU 算子，耗时约 0.046ms
   ⅱ. 检测模型均没有 CPU 算子
   ⅲ. 分割模型 DeepLabV3+ 尾部的 Argmax 为 CPU 算子
   c. 输出反量化CPU节点：int8->float32，耗时同样与 shape 大小成正比
   d. 地平线目前支持将 量化/反量化节点手动摘除，由用户自行融入前后处理代码中实现，以减少数据重复遍历的损耗，我们已在交付包中提供了 EfficientDet 参考示例，摘除了反量化节点合入后处理，整体性能提升明显（ 66FPS–>100FPS ）
   e. 目前地平线示例模型的后处理均未做针对性的性能优化，您可以根据实际需求采用如近似高效实现等优化手段进行代码级加速
3. 在实际应用中，BPU 和 CPU 可以并发运行，提高整体推理速度。