3、部署环境准备：搭建旭日开发环境，安装交叉编译工具链、模型转换工具（如Horizon OpenExplorer）及依赖库

旭日系列芯片（如旭日3、旭日5）的模型部署并非在开发PC上直接运行，而是需要经过“模型转换—交叉编译—板端集成”的完整链路。环境准备是整条链路的地基，其核心目标是在x86主机上构建一套能够产出ARM架构可执行文件与芯片专用模型bin的完整工具链。本章将围绕开发机系统配置、交叉编译工具链安装、Horizon OpenExplorer模型转换工具部署、依赖库管理四个维度展开，并给出可复现的验证方法。

主机开发环境 (x86_64) 模型转换工具链 板端运行环境 (ARM) Ubuntu 20.04 Python 3.8/3.10 交叉编译链 依赖库(.so) OpenExplorer hb_mapper 量化校准器 模型编译器 旭日Linux BPU驱动 hbrt库 应用可执行 ONNX/PyTorch .bin 部署环境核心链路 模型训练 → ONNX导出 → OpenExplorer量化转换 → 交叉编译 → 板端集成 → 推理运行 关键验证点： ① 交叉编译链版本与板端glibc兼容性 ② OpenExplorer与Python版本匹配 ③ 模型bin文件与板端runtime库版本一致性 ④ 依赖库的ABI兼容性（避免GCC版本不匹配）

3.1 开发机系统与基础依赖配置

旭日工具链官方支持的操作系统为Ubuntu 20.04 LTS（64位），部分新版本工具链已兼容Ubuntu 22.04。开发机建议配置不低于16GB内存、100GB可用磁盘空间，CPU核心数建议8核以上，因为模型量化校准过程会消耗较多计算资源。系统安装完成后，需要先完成以下基础依赖的安装：

# 更新软件源
sudo apt update && sudo apt upgrade -y

# 安装基础编译工具
sudo apt install -y build-essential cmake git wget unzip

# 安装Python环境（OpenExplorer依赖Python 3.8/3.10）
sudo apt install -y python3.8 python3.8-dev python3.8-venv
sudo apt install -y python3-pip

# 安装OpenExplorer所需的Python依赖
pip3 install numpy==1.24.4 onnx==1.14.1 protobuf==3.20.3
pip3 install pyyaml scipy opencv-python-headless

这里需要特别注意Python版本的选择。Horizon OpenExplorer不同版本对Python版本有严格限制，例如OE 2.0.x系列要求Python 3.8，而OE 2.3.x及以上版本支持Python 3.10。建议使用虚拟环境隔离不同项目的依赖，避免系统级Python环境被污染。

版本兼容性风险：不要随意升级numpy或onnx到最新版本。OpenExplorer内部对onnx的算子解析依赖特定版本，例如onnx 1.14.1与protobuf 3.20.3是经过官方验证的稳定组合。升级到onnx 1.15+可能导致模型解析失败或算子映射异常。

3.2 交叉编译工具链安装与验证

交叉编译工具链用于在x86主机上编译出ARM架构的可执行文件。旭日官方推荐使用gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu交叉编译器，该工具链基于GCC 9.2，与旭日Linux系统的glibc版本兼容性最佳。安装步骤如下：

# 下载交叉编译工具链（以aarch64为例）
wget https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz

# 解压到指定目录
sudo mkdir -p /opt/arm-gcc
sudo tar -xf gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz -C /opt/arm-gcc

# 配置环境变量
echo 'export PATH=/opt/arm-gcc/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin:$PATH' >> ~/.bashrc
echo 'export CROSS_COMPILE=aarch64-none-linux-gnu-' >> ~/.bashrc
source ~/.bashrc

# 验证安装
aarch64-none-linux-gnu-gcc --version

验证交叉编译工具链是否正常工作，可以编写一个简单的Hello World程序进行交叉编译，然后在板端运行。但更实用的验证方式是编译一个带依赖库的测试程序，确认动态链接库的搜索路径配置正确。

交叉编译核心原理：交叉编译器生成的二进制文件依赖目标平台的动态链接器（ld-linux-aarch64.so.1）和系统库（libc.so.6）。在编译时通过 -sysroot 参数指定目标平台的根文件系统路径，编译器会从该路径下查找头文件和库文件。如果板端系统库版本与编译时使用的sysroot版本不一致，会出现“GLIBC_2.XX not found”的运行时错误。

3.3 Horizon OpenExplorer模型转换工具部署

Horizon OpenExplorer（简称OE）是旭日芯片的模型转换与量化工具包，它负责将ONNX、Caffe等格式的模型转换为旭日BPU（Brain Processing Unit）可执行的二进制模型文件（.bin）。OE的安装包以压缩包形式提供，解压后需要配置环境变量并安装Python依赖。

# 解压OpenExplorer工具包
tar -xzf horizon_open_explorer_2.3.3_x86_64.tar.gz
cd horizon_open_explorer_2.3.3_x86_64

# 安装Python依赖
pip3 install -r requirements.txt

# 配置环境变量
echo 'export OE_ROOT=/opt/horizon/open_explorer' >> ~/.bashrc
echo 'export PATH=$OE_ROOT/bin:$PATH' >> ~/.bashrc
echo 'export PYTHONPATH=$OE_ROOT/python:$PYTHONPATH' >> ~/.bashrc
source ~/.bashrc

# 验证安装
hb_mapper --help

OE工具链的核心组件包括：hb_mapper（模型转换主工具）、hb_compile（模型编译工具）、hb_quantizer（量化校准工具）以及模型检查器。其中hb_mapper是使用频率最高的入口，它支持一键完成模型格式检查、算子映射、量化、编译的全流程。

工具组件 功能说明 典型使用场景
hb_mapper 模型转换主入口，支持ONNX/Caffe模型导入 将训练好的模型转换为旭日bin格式
hb_compile 模型编译优化，生成BPU指令 对量化后的模型进行编译优化
hb_quantizer 校准数据加载与量化参数计算 使用校准集计算激活值的量化scale
hb_model_checker 模型算子兼容性检查 转换前检查模型是否支持BPU加速

3.4 板端依赖库与运行时环境准备

模型转换完成后，需要在板端集成运行时库（hbrt，Horizon BPU Runtime Library）和对应的依赖库。旭日官方提供两种部署方式：一是使用预编译的运行时库，二是从源码编译。对于大多数场景，推荐使用预编译库，因为源码编译需要额外配置交叉编译环境且容易出错。

# 从OE工具包中获取板端运行时库
cp -r $OE_ROOT/runtime/ /opt/horizon/runtime

# 将运行时库拷贝到板端（通过NFS或scp）
scp -r /opt/horizon/runtime root@<板端IP>:/opt/horizon/

# 在板端配置动态链接库路径
echo 'export LD_LIBRARY_PATH=/opt/horizon/runtime/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证运行时库
ldconfig -p | grep hbrt

板端依赖库的版本必须与主机端OE工具链版本严格对应。例如，使用OE 2.3.3版本转换的模型，必须搭配OE 2.3.3对应的hbrt运行时库。版本不匹配会导致模型加载失败或推理结果异常。

经验建议：在项目初始化阶段，建议将OE工具链版本、交叉编译链版本、板端系统镜像版本、hbrt运行时库版本记录在项目的README或版本管理文件中。旭日芯片的软件栈更新较快，版本组合的兼容性矩阵需要以官方发布说明为准。

3.5 环境验证与常见问题排查

环境搭建完成后，必须进行端到端的验证，确保所有工具链组件能够协同工作。验证流程分为三个层次：工具链自检、模型转换验证、板端推理验证。

  1. 工具链自检：运行 hb_mapper --version 确认版本信息，运行 aarch64-none-linux-gnu-gcc --version 确认交叉编译器可用。
  2. 模型转换验证：使用官方提供的示例模型（如YOLOv3 tiny）执行一次完整的模型转换流程，确认能够生成.bin文件。
  3. 板端推理验证：将转换后的模型和编译好的测试程序拷贝到板端，运行推理程序，确认输出结果与预期一致。
# 模型转换验证命令示例
hb_mapper makertbin --model-type onnx \
  --model config/yolov3_tiny.onnx \
  --output-dir output/ \
  --config config/yolov3_tiny_config.yaml

常见问题主要集中在以下几个方面：

问题现象 可能原因 解决方案
hb_mapper命令找不到 环境变量未配置或配置错误 检查OE_ROOT和PATH变量，重新source ~/.bashrc
模型转换时报“Unsupported OP” 模型包含BPU不支持的算子 使用hb_model_checker检查算子兼容性，将不支持的算子替换或拆分为CPU算子
板端运行时报“libhbrt.so not found” 运行时库路径未配置 确认LD_LIBRARY_PATH包含hbrt库路径，使用ldd检查依赖
推理结果全为0或NaN 量化参数设置错误或校准数据不充分 检查校准数据集的数量和多样性，重新执行量化
重要提醒：不要使用系统自带的gcc（x86版本）编译板端程序。即使编译通过，生成的二进制文件也无法在ARM架构上运行。务必使用交叉编译工具链，并在编译脚本中显式指定 CC=aarch64-none-linux-gnu-gcc。

3.6 实战案例：从零搭建YOLOv5s部署环境

下面通过一个完整的案例，演示如何从零搭建一个可用于YOLOv5s模型部署的开发环境。该案例以旭日3芯片（XJ3）为目标平台，操作系统为Ubuntu 20.04。

项目背景与约束：某安防项目需要在旭日3开发板上部署YOLOv5s模型，实现实时行人检测。开发团队需要在3天内完成环境搭建和模型转换验证。板端系统为旭日官方提供的Linux 4.14.87镜像，内存2GB，存储16GB。

初始环境状态：开发机为全新安装的Ubuntu 20.04，未安装任何开发工具。板端已烧录系统镜像，可通过SSH访问。

操作步骤：

  1. 基础环境安装（第1天上午）：按照3.1节步骤安装基础依赖，耗时约1小时。安装过程中遇到pip下载慢的问题，通过配置清华镜像源解决。
  2. 交叉编译链安装（第1天下午）：下载gcc-arm-9.2工具链，安装到/opt/arm-gcc目录。验证编译一个简单的hello程序，在板端运行成功。
  3. OpenExplorer安装（第2天上午）：从地平线官网下载OE 2.3.3版本，解压后安装Python依赖。运行hb_mapper --help验证安装成功。
  4. 模型转换验证（第2天下午）：使用官方提供的yolov3_tiny示例模型进行转换测试，成功生成.bin文件。转换过程中发现校准数据需要至少100张图片，使用公开数据集COCO2017的子集作为校准集。
  5. 板端集成测试（第3天）：将运行时库和测试程序部署到板端，运行推理程序。首次运行时出现libopencv_world.so.4.5缺失的问题，通过拷贝主机端交叉编译的OpenCV库解决。

结果与复盘：整个环境搭建耗时2.5天，比预期提前半天完成。关键经验包括：

  • 版本组合确认非常重要，OE 2.3.3与Python 3.8的组合是经过验证的稳定方案。
  • 校准数据集的质量直接影响量化后模型的精度，建议使用与目标场景分布接近的图片。
  • 板端依赖库的排查需要借助 ldd 命令逐项检查，不要盲目安装库文件。

环境搭建是模型部署的第一步，也是后续所有工作的基础。一个干净、版本可控、验证充分的环境能够大幅减少后续模型转换和集成调试的时间。建议在项目启动初期就建立环境版本清单，并记录所有安装步骤，便于团队成员协作和问题回溯。

← 上一章 📖 返回目录 下一章 →