2.1. 环境部署

2.1.1. 前言

地瓜机器人 OpenExplorer 目前同时提供了 2 套模型量化方案：

  • PTQ：Post-training Quantization，训练后量化。

  • QAT：Quantization aware training，量化感知训练（暂时只支持 Pytorch 框架）。

其中：

  • 两套方案均不干预浮点模型的训练阶段，您需要自行负责。地瓜机器人也在以下路径开源了一些分类/检测/分割等场景 高效模型的公版 Pytorch 实现以供参考，并支持在宿主机上进行训练和复现。

ddk/samples/ai_toolchain/horizon_model_train_sample

  • 对于 PTQ 方案，您需要在宿主机的开发环境完成模型的量化转换，再将编译生成的 .bin 模型拷贝至开发板环境 完成后续的部署工作。

  • 对于 QAT 方案，您则需要在宿主机的开发环境先完成模型的 QAT 训练，再进行量化转换，再将编译生成的 .hbm 模型 拷贝至开发板环境完成后续的部署工作。

两种量化方案以及高效模型的开发环境，地瓜机器人都提供了本地手动安装和 Docker 容器两种方式。 我们强烈建议您使用不污染本地环境，且使用方便的 Docker 容器，以下也将分别进行介绍。

2.1.2. 开发环境部署

2.1.2.1. 下载 OE 发布包

请先 下载 OE 发布包 并正确解压到开发机。示例所用模型已包含在 OE 发布包的 model_zoo 中。

2.1.2.2. 开发机准备

为了顺利地使用工具链，地瓜机器人建议您选择的开发机应满足以下要求：

更多关于 CUDA 与显卡的兼容性问题请参考 NVIDIA 官网信息 。

此外，嵌入式开发需要安装交叉编译工具，请从 ddk/package/host 目录下通过执行 resolve.sh 进行获取，并将其解压 到开发机的 /opt 目录下（ 使用 Docker 可跳过此步骤 ）。

解压命令如下：

tar xvf gcc-ubuntu-9.3.0-2020.03-x86_64-aarch64-linux-gnu.tar.xz

tar xvf gcc_linaro_6.5.0_2018.12_x86_64_aarch64_linux_gnu.tar.xz

另外您需要在环境中新增一个变量 LINARO_GCC_ROOT，值为交叉编译器的完整路径，参考命令如下：

export LINARO_GCC_ROOT=/opt/gcc-ubuntu-9.3.0-2020.03-x86_64-aarch64-linux-gnu

export LINARO_GCC_ROOT=/opt/gcc-linaro-6.5.0-2018.12-x86_64_aarch64-linux-gnu

注解

环境变量 LINARO_GCC_ROOT 的设置路径需要与交叉编译工具解压的目录相同，否则会导致失败。

对于 host 端（x86）依赖的库，比如 isl,gmp,mpc,mpfr 等，在 lib/x86_64-linux-gnu 下，如果编译报错， 请在编译工程中通过 LD_LIBRARY_PATH 来指定。

如果编译过程中出现 glibc 库版本冲突的问题，例如：xxx@GLIBC_xxx 的未定义符号的错误， 请在编译工程中通过-rpath-link 来指定到工具链的 aarch64-linux-gnu/lib 路径下, 同时在编译工程中加上-lxxx, 例如：-lpthread。

另外需要特别注意的是下图框起来的记录源文件的变量 SRCS，最好放在${LIBS}链接库的前面，不然也会报未定义的符号。

../../../_images/gcc_SRCS.png

2.1.2.3. Docker 容器部署

2.1.2.3.1. Docker 基础环境

地瓜机器人要求的 Docker 基础环境如下，请提前在您的宿主机上完成安装：

完成 Docker 基础环境安装后，还需要将无 root 权限的用户添加到 Docker 用户组中。参考命令如下：

sudo groupadd docker
sudo gpasswd -a ${USER} docker
sudo systemctl restart docker  # Ubuntu
# re-login

使用以下命令获取本节需要使用的 Docker 镜像：

镜像文件命名形式为：

  • GPU 版本 docker： docker_open_explorer_ubuntu_20_xj3_gpu_{version}.tar.gz

  • CPU 版本 docker： docker_open_explorer_ubuntu_20_xj3_cpu_{version}.tar.gz

小技巧

{version}需替换为您获取到的版本号。

2.1.2.3.2. Docker 镜像使用

为了帮助用户快速使用工具链，地瓜机器人提供了包含完整开发环境的 Docker 镜像，大大简化了开发环境的部署过程。

注解

若您已下载离线镜像，需先使用下方命令将镜像加载到本地。

docker load -i docker_openexplorer_xxx.tar.gz

您可以在 OE 包的一级目录下直接运行以下脚本启动当前 OE 版本所对应的 Docker 容器（如果本地没有对应镜像，则脚本会自动从官方 Docker hub 拉取镜像）：

sh run_docker.sh data

若您想要使用 CPU 版本 Docker 镜像则需要增加 cpu 参数：

sh run_docker.sh data/ cpu

OE 包示例所依赖的相关公开评测数据集的下载链接为：

如果您在数据准备过程中有遇到问题，可以前往 地瓜机器人开发者社区 发帖进行求助。

如果您希望手动启动 Docker 容器，可以参考下方命令，其中{version}为您当前所用的 OE 版本号。

注解

为方便使用，我们为您提供了两种 CPU Docker 以及 GPU Docker，可按需选择。

CPU Docker：

# CPU Docker
docker pull openexplorer/ai_toolchain_ubuntu_20_xj3_cpu:{version}
# 手动启动 CPU Docker 镜像
docker run -it --rm
  -v {OE 包路径}:/open_explorer \ # 挂载 OE 包
  -v ./dataset:/data/horizon_xj3/data \ # 挂载数据集
  openexplorer/ai_toolchain_ubuntu_20_xj3_cpu:{version}

GPU Docker：

# GPU Docker
docker pull openexplorer/ai_toolchain_ubuntu_20_xj3_gpu:{version}
# 手动启动 GPU Docker 镜像
docker run -it --rm
  --gpus all \ # 在启动容器时，添加标记以启用GPU资源的访问
  --shm-size=15g \ # 修改共享内存大小
  -v {OE 包路径}:/open_explorer \ # 挂载 OE 包
  -v {数据集路径}:/data/horizon_xj3/data \ # 挂载数据集
  openexplorer/ai_toolchain_ubuntu_20_xj3_gpu:{version}

注意

  1. 由于 OE Docker 镜像构建过程中配置了 PATH 和 LD_LIBRARY_PATH 等环境变量的值，未使用推荐方式（如 docker attach）进入容器可能会导致环境变量加载不正常从而导致 Cmake、GCC、CUDA 等工具使用异常。

  2. 若希望 Docker 容器退出后不销毁，请使用命令行 docker run -it 手动启动，不要带上 --rm 选项。

  3. 若希望 Docker 容器启动后可在后台执行，请在命令行 docker run -it 后增加 -d 选项，容器启动后会返回容器 ID，此时可通过 docker exec -it {容器ID} /bin/bash 命令再次进入容器。

成功进入 Docker 容器后， 您可以键入 hb_mapper 命令验证是否能正常得到其帮助信息，该工具是工具链的重要工具， 将在后文的 hb_mapper 工具 章节对其进行详细介绍。

2.1.2.4. 本地手工安装

本节将为您介绍本地手动安装环境方法，并分别介绍两种量化方案和地瓜机器人开源的高效模型训练的环境相关依赖及说明。我们推荐您在浮点模型训练完成后优先 选择简单易用的 PTQ 量化方案，只在精度问题确实无法解决时再切换到 QAT 量化方案。

2.1.2.4.1. 本地手动安装环境方法

本地手动安装环境，仅需运行下方脚本，即可一键式完成环境安装。

cd ddk/package/host
bash install.sh

安装脚本会自动检查相应的环境，缺少相应依赖或配置会中断安装过程，并给出修正建议如下图。

../../../_images/tool_installation.png

根据建议补充依赖后，重新执行 install 脚本即可。

注解

  • 如果修正建议指出是 gcc/g++版本不符合要求，在安装完指定版本之后，您需要重新建立 gcc 和 g++软链接为 gcc-5.4.0 和 g++-5.4.0。

  • 安装脚本会自动检查相应的环境，缺少相应依赖或配置会中断安装过程，可以根据提示补充依赖，并重新执行 install 脚本。

  • 脚本执行成功后，会在 ~/.bashrc 系统环境变量中添加 Path 等信息（环境变量 LD_LIBRARY_PATH 经常被使用，建议您检查环境变量是否符合预期），请执行 source ~/.bashrc 来使当前 terminal 的配置生效。

  • torch 版本应满足 1.13.0，torchvision 版本应满足 0.14.0。

在顺利完成 install 脚本后，您可以键入 ddk_vcs list 命令验证下您所需的工具和依赖是否被正确安装。

2.1.2.4.2. PTQ 量化环境依赖

PTQ 量化方案对于开发机操作环境的基础软件依赖如下：

  • 操作系统：Ubuntu20.04

  • Python3.8

  • libpython3.8

  • python3-devel

  • python3-pip

  • gcc&g++: 5.4.0

  • graphviz

2.1.2.4.3. QAT 量化环境依赖

QAT 量化环境在本地环境进行安装，需要先确保已满足以下基础环境条件。 量化训练工具能够训练起来所必需的环境依赖如下表：

硬件/操作系统

GPU

CPU

os

Ubuntu20.04

Ubuntu20.04

cuda

11.6

N/A

python

3.8

3.8

torch

1.13.0+cuda-11.6

1.13.0+cpu

torchvision

0.14.0+cuda-11.6

0.14.0+cpu

推荐显卡

titan v/2080ti/ v100/3090

N/A

在完成 QAT 模型的训练后，我们可以选择以下两种路径完成后续的模型转换工作：

路径 1：先导出 onnx 模型，再基于 PTQ（Post Training Quantization，训练后量化）路线通过 yaml 文件完成模型转换（此路径我们建议您直接使用地瓜机器人提供的 docker）。

路径 2：在当前训练环境安装相关工具包，并直接通过接口调用的方式完成模型转换。

2.1.2.4.4. 高效模型浮点训练环境说明

地瓜机器人在 ddk/samples/ai_toolchain/horizon_model_train_sample 路径下开源了一些高效模型源码，其浮点及 QAT 训练基础环境 请参考 QAT 量化环境部署 。

2.1.3. 运行环境部署

当模型完成量化转换后，即可将编译好的模型部署在开发板环境推理运行。运行环境的部署需要您先准备好一块烧写好系统镜像的 开发板，再将相关补充文件拷贝到开发板中即可。

2.1.3.1. 开发板准备

此阶段需要验证下开发板的可用性，将可用系统镜像烧写到开发板中。具体过程请参考 开发板套件及系统镜像说明 章节内容。

2.1.3.2. 板端工具安装

工具链的部分补充工具未包含在系统镜像中，但可以在宿主机环境下执行 OE 包中的安装脚本 将其拷贝至开发板，其参考命令如下：

cd ddk/package/board
bash install.sh ${board_ip}

注解

其中，${board_ip} 是您为开发板设置的 IP 地址，请确保在开发机上可以成功访问该 IP。 补充文件成功安装后，请重新启动开发板，在开发板上执行 hrt_model_exec --help 即可验证安装是否成功。