# 环境安装

本章节主要介绍X5算法工具链完整开发环境部署方法。

## <span id="ai_toolchain_package"/>交付物使用说明


在进行算法工具链使用环境部署前，请根据 **``X5 SDK交付包中的 ai_toolchain_package``** 目录下的版本信息去下载对应版本的 **嵌入式应用开发Sample交付包** 到Linux开发机环境中。

下载嵌入式应用开发Sample交付包：

```bash
// 示例版本为 V1.2.8，请根据X5 SDK交付包中 ai_toolchain_package 目录下的 release_note.txt 下载对应版本SDK

wget -c ftp://oeftp@sdk.d-robotics.cc/runtime_package/Ai_Toolchain_Package-release-v1.23.9-OE-v1.2.8.tar.xz --ftp-password=Oeftp~123$%
```


### 示例包源码目录结构说明

解压算法工具链SDK源码包：

```bash
// 示例版本为 V1.2.8，请根据X5 SDK交付包中 ai_toolchain_package 目录下的 release_note.txt 下载对应版本SDK

tar -xvf Ai_Toolchain_Package-release-v1.23.9-OE-v1.2.8.tar.xz
```

解压后的目录结构如下：

-   **ai_benchmark**: 目录下提供了常见的分类、检测和分割模型的评测示例，包括性能评测和精度评测两部分。

-   **horizon_runtime_sample**: 目录下提供了定点模型的上板示例。

-   **package**: 目录下包含了发布物运行的一些基础库和组件

    1. ``board`` 文件夹下为板端可执行程序。

    2. ``host`` 文件夹下为x86开发环境下的环境依赖、工具依赖以及模型推理相关的libdnn库和头文件。


## 开发机部署

对于开发机的环境部署，X5算法工具链支持使用Docker部署方式。

### 开发机准备


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

  | 硬件/操作系统 | 要求                                 |
  |---------------|------|
  | CPU           | CPU I3以上或者同级别E3/E5的处理器    |
  | 内存          | 16G或以上级别                        |
  | GPU(可选)     | CUDA11.6、驱动版本Linux:>= 510.39.01*<br/>适配显卡包括但不限于：<br/>1)GeForce RTX 3090<br/>2)GeForce RTX 2080 Ti<br/>3)NVIDIA TITAN V<br/>4)Tesla V100S-PCIE-32GB <br/>5)A100
  | 系统          | Ubuntu 20.04         |

更多关于CUDA与显卡的兼容性问题请参考[**NVIDIA官网信息**](https://docs.nvidia.com/deploy/cuda-compatibility/) 。

### 使用Docker环境

为了帮助您快速使用算法工具链，X5算法工具链提供了包含完整开发环境的Docker镜像，大大简化了环境的部署过程。

在阅读此部分内容前，我们希望您的开发机中已经预装好了Docker的基础环境。
X5算法工具链要求的Docker基础环境信息如下：

- Docker（19.03或更高版本，建议安装19.03版本）, [**Docker安装手册**](https://docs.docker.com/get-started/get-docker/) 。
- NVIDIA Container Toolkit（1.13.1-1.13.5，建议安装1.13.5），详见[**NVIDIA Container Toolkit 安装手册**](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)。

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

```bash
sudo groupadd docker
sudo gpasswd -a ${USER} docker
sudo service docker restart
```

获取本节需要使用的Docker镜像的地址如下：

- [**X5算法工具链 Docker Hub CPU Docker**](https://hub.docker.com/r/openexplorer/ai_toolchain_ubuntu_20_x5_cpu)
- [**X5算法工具链 Docker Hub GPU Docker**](https://hub.docker.com/r/openexplorer/ai_toolchain_ubuntu_20_x5_gpu)

镜像文件命名形式为：

- CPU版本docker： ``openexplorer/ai_toolchain_ubuntu_20_x5_cpu:{version}``
- GPU版本docker： ``openexplorer/ai_toolchain_ubuntu_20_x5_gpu:{version}``


**小技巧：**
>1. 执行命令时将 ``{version}`` 替换为您根据 **``X5 SDK交付包中的 ai_toolchain_package``** 目录下获取到的 **版本信息**
>2. 本地Docker镜像包版本，可以联系技术支持团队获取。
>3. 开发机并不是必须含有GPU卡，一般使用CPU开发机加载Docker镜像即可做模型转换！

每个镜像文件在第一次使用前，需要拉取镜像。

- 镜像拉取命令为：

  ```bash
  docker pull openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8
  ```
然后执行以下命令运行Docker容器。

- CPU开发机Docker容器执行以下命令：

  ```bash
  // 运行 docker 镜像的命令

  export version=v1.2.8

  export ai_toolchain_package_path=/home/users/xxx/ai_toolchain_package

  export dataset_path=/home/users/xxx/data/

  docker run -it --rm \
    -v "$ai_toolchain_package_path":/open_explorer \
    -v "$dataset_path":/data \
    openexplorer/ai_toolchain_ubuntu_20_x5_cpu:"${version}"
  ```
- GPU开发机 Docker容器执行以下命令：

  ```bash
  // 运行 docker 镜像的命令

  export version=v1.2.8

  export ai_toolchain_package_path=/home/users/xxx/ai_toolchain_package

  export dataset_path=/home/users/xxx/data/
  
  # 手动启动 GPU Docker 镜像
  docker run -it --rm 
    --gpus all \ # 在启动容器时，添加标记以启用GPU资源的访问
    --shm-size=15g \  # 修改共享内存大小
    -v "$ai_toolchain_package_path":/open_explorer \
    -v "$dataset_path":/data \
    openexplorer/ai_toolchain_ubuntu_20_x5_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` 命令再次进入容器。

**小提示：**

- ``dataset_path`` 为数据集文件目录，如果该目录不存在会导致加载问题，需要创建好后再运行命令。

- 公共数据集可参考以下链接下载：

  [**VOC（使用VOC2012版本）：**](http://host.robots.ox.ac.uk/pascal/VOC/)

  [**COCO：**](https://cocodataset.org/#download)

  [**ImageNet：**](https://www.image-net.org/download.php)

  [**Cityscapes：**](https://github.com/mcordts/cityscapesScripts)
        
  [**CIFAR-10:**](http://www.cs.toronto.edu/~kriz/cifar.html)
        
  [**FlyingChairs:**](https://lmb.informatik.uni-freiburg.de/resources/datasets/FlyingChairs.en.html)
        
  [**KITTI3D:**](https://www.cvlibs.net/datasets/kitti/eval_object.php?obj_benchmark=3d)
        
  [**CULane:**](https://xingangpan.github.io/projects/CULane.html)

  [**nuScenes:**](https://www.nuscenes.org/nuscenes)


至此，您已经成功通过Docker镜像进入完整的算法工具链开发环境。
您可以键入 ``hb_mapper --help`` 命令验证是否可以正常得到帮助信息：

```bash
[root@d67382e74eea open_explorer]# 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.
  --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...
```
若hb_mapper工具已正常输出日志， 说明环境已安装部署完成，请到 [**开发板部署**](./environment_config.html#span-id-board-env-install) 章节，进行开发板的环境安装。


## <span id="board_env_install"/>开发板部署

开发板部署需要您按照刷机说明，将开发版镜像更新到最新版本，升级方法请参考[**安装系统**](../../quick_start/update_system_firmware.html#span-id-system-update) 章节内容， 升级完成后，再将相关补充文件拷贝到开发板中即可。

算法工具链的部分补充工具未包含在系统镜像中，这些工具已经放置在 ``Ai_Toolchain_Package-release-vX.X.X-OE-vX.X.X/package/`` 安装包中，
进入到 ``Ai_Toolchain_Package-release-vX.X.X-OE-vX.X.X/package/board`` 执行install脚本。
执行命令如下：

```bash
bash install.sh ${board_ip}
```
**注意：**
-  ``${board_ip}`` 是您为开发板设置的IP地址，请确保在开发机上可以访问该IP。
-  成功安装后，重新启动开发板，在开发板上执行 ``hrt_model_exec`` 可以验证安装是否成功。

## 版本管理工具使用说明

本章节主要介绍ddk_vcs版本管理工具的使用说明，便于开发者了解当前开发机环境中算法工具链依赖包的版本情况。

**注意：** **``版本管理工具主要用于在使用Docker环境进行模型PTQ转换出现错误时做DEBUG使用，若模型转换功能正常，可跳过此章节阅读。``**

版本管理工具包括以下功能：

- ddk_vcs list;
- ddk_vcs install;
- ddk_vcs uninstall;
- ddk_vcs patch;
- ddk_vcs show;


### ddk_vcs list

ddk_vcs list 用于列出已安装的软件包。

不加参数执行此命令时，结果会展示当前已安装的各个模块的信息。使用示例如下：

```bash

[horizon@gpu-dev067 ai_toolchain]$ ddk_vcs list
Host package version: x5 1.2.8
The following packages versions
Platform         Package        Version MD5
---------------- -------------- ------- --------------
aarch_64         dnn            1.24.5  a4c77552d3
x86_64_gcc11.4.0 dnn_x86        1.24.5  39527daad7
x86_64_gcc11.4.0 horizon-nn     1.1.0   origin:1.1.0
x86_64_gcc11.4.0 horizon-nn-gpu N/A     origin:N/A
x86_64_gcc11.4.0 horizon_tc_ui  1.24.3  origin:1.24.3
x86_64_gcc11.4.0 hbdk           3.49.15 origin:3.49.15
```

**备注：**
```bash
最后几行的origin信息会在每次使用工具链SDK包内的install脚本进行安装后更新为当前环境下的版本，
后续在使用ddk_vcs进行安装时则不会改变，只会改变Version的值。
```

使用 ``-p`` 参数以后会显示当前可以安装的模块版本情况，可以通过 ``ddk_vcs install`` 进行安装，使用示例如下：

```bash

[horizon@gpu-dev004]$ ddk_vcs list -l
Host package version: 1.2.8
The following packages versions
Platform         Local Package         Version MD5
---------------- --------------------- ------- ----------
aarch_64         dnn_1.24.5.tar.gz     1.24.5  a4c77552d3
x86_64_gcc11.4.0 dnn_x86_1.24.5.tar.gz 1.24.5  39527daad7
```

### ddk_vcs install

ddk_vcs install 用于对安装包进行安装。
用户可以直接通过 ``ddk_vcs install`` 将对应的模块tar包进行安装。安装时需要指定对应的platform。使用示例如下：

```bash

[horizon@gpu-dev004]$ ddk_vcs install dnn_1.17.3d.tar.gz -p aarch_64
dnn installed successfully, version: 1.17.3d, platform: aarch_64
[horizon@gpu-dev004]$ ddk_vcs install hbdk-3.44.7-cp38-cp38-linux_x86_64.whl  horizon_nn-0.17.1-cp38-cp38-linux_x86_64.whl
hbdk-3.44.7-cp38-cp38-linux_x86_64.whl installed successfully
horizon_nn-0.17.1-cp38-cp38-linux_x86_64.whl installed successfully
```
在使用 ``ddk_vcs list -l`` 后用户可以得到自己当前host package中各个模块包的版本信息，
然后使用 ``ddk_vcs install`` 可以很方便地切换各个版本，使用示例如下：

```bash

[horizon@gpu-dev004]$ ddk_vcs install dnn==1.15.2  --platform aarch_64
dnn installed successfully, version: 1.15.2, platform: aarch_64
```
如果本地没有对应版本可以指定安装包位置进行安装。

### ddk_vcs uninstall

ddk_vcs uninstall 用于卸载指定模块。使用示例如下：

```bash

[horizon@gpu-dev004]$ ddk_vcs uninstall dnn --platform aarch_64
Start to uninstall modules, platform: aarch_64
dnn uninstalled successfully, version: 1.17.3d, platform: aarch_64
```

### ddk_vcs patch

使用 ``ddk_vcs patch ddk_patch.tar.gz`` 可以安装预先制作好的patch包。使用示例如下：

```bash

[horizon@gpu-dev004]$ ddk_vcs patch ddk_patch.tar.gz
dnn installed successfully, version: 1.15.2_patch0, platform: aarch64
```

### ddk_vcs show

ddk_vcs show 用于显示有关已安装软件包的信息。使用 ``ddk_vcs show [模块名]`` ，可以展示对应模块的信息。使用示例如下：

```bash

[horizon@gpu-dev004]$ ddk_vcs show dnn
Host package version: x5 1.2.8
The following packages versions
Platform Package Version MD5
-------- ------- ------- ----------
aarch_64 dnn     1.24.5  a4c77552d3
```
