4. 开发环境搭建

旭日（Sunrise）系列开发板通常搭载地平线（Horizon）X3、X5 等 AI 芯片，其目标检测部署链路是“PC 端训练与量化 → 交叉编译 → 板端推理”。因此开发环境不是单一主机环境，而是由宿主机（Ubuntu x86_64）、交叉编译工具链、板端运行环境三部分组成的协同体系。本节围绕这三层展开，给出可复现的配置流程与验证方法。

一、核心原理：为什么需要交叉编译环境

旭日开发板的 CPU 架构为 ARM（X3 为 ARM Cortex-A53，X5 为多核 ARM），而模型转换、量化、编译工具（如 horizon_joint_march、hb_mapper、hb_model_verifier）大多运行在 x86_64 的 Ubuntu 主机上。宿主机负责把 ONNX 模型编译成板端可执行的 .hbm 或 .bin 模型，板端只负责加载与推理。二者通过交叉编译工具链和共享的依赖库版本对齐，才能保证“编译通过、板端可跑”。

环境搭建的本质是版本对齐：Docker 镜像版本、工具链版本、板端系统镜像版本、Python 依赖版本必须属于同一发布批次，否则会出现算子不支持、ABI 不匹配、动态库缺失等典型问题。

二、方法流程：从零到可运行的四步配置

1. 准备宿主机基础环境：安装 Ubuntu 20.04，配置 Docker，拉取官方 open_explorer 镜像。镜像内已集成 hb_mapper、交叉编译工具链与 Python 依赖，避免手工安装版本冲突。
2. 安装交叉编译工具链：若需自行编译板端 C++ 推理程序，安装 gcc-arm-linux-gnueabihf 并验证目标架构。
3. 安装依赖库：宿主机侧安装 onnx、numpy、opencv-python 等；板端侧确认 libbpu、hb_dnn、opencv 等运行库存在。
4. 验证环境：用 hb_mapper 转换一个最小模型，用 hb_model_verifier 校验精度，再在板端加载 .hbm 模型跑通一次推理。

# 1. 拉取并启动官方 Docker 镜像
docker pull openexplorer/ai_toolchain_ubuntu_20_xj3_cpu:v1.2.0
docker run -it --rm -v $(pwd):/workspace openexplorer/ai_toolchain_ubuntu_20_xj3_cpu:v1.2.0 /bin/bash

# 2. 安装 ARM 交叉编译工具链
sudo apt update
sudo apt install -y gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
arm-linux-gnueabihf-gcc -v

# 3. 安装 Python 依赖
pip install numpy==1.19.5 onnx==1.10.0 opencv-python==4.5.5.64

# 4. 验证 hb_mapper 是否可用
hb_mapper --version
hb_model_verifier --help

三、依赖库安装与版本对齐清单

下表列出宿主机与板端的关键依赖及其版本对齐要求，是排障时最常查阅的对照表。

四、案例场景：一次典型的“板端跑不起来”复盘

某次部署中，宿主机用 hb_mapper 成功生成了 yolov5s.hbm，但板端执行时报 libhbdnn.so: cannot open shared object file。排查发现：宿主机 Docker 镜像版本为 v1.1.0，而板端系统镜像为 v1.2.0，两者 BPU 运行时 ABI 不一致。解决方式是统一使用 v1.2.0 镜像重新转换模型，并在板端执行 ldconfig 刷新动态库缓存。