选用 RDK X5（rdk_x5 分支） 作为实操案例；

全程区分两大使用模式：

✅ 模式 A：直接运行官方预编译模型（新手验证硬件，最快上手）

✅ 模式 B：基于模板转换自己训练的 ONNX 模型（工程落地）

前置重要前提

1. 仓库地址：https://github.com/D-Robotics/rdk_model_zoo
2. 分支绝对不能切错
   • RDK X3 → git checkout rdk_x3
   • RDK X5 → git checkout rdk_x5
3. 环境区分：
   • PC 电脑（Ubuntu/Docker OE 工具链）：用来把 ONNX → 量化编译生成 .bin
   • RDK X5 开发板：运行推理代码、加载.bin模型；板子上没有 hb_mapper 编译工具
4. 关键常识：X5 只能使用 bayes-e 架构的.bin，不支持 J5/S100 的.hbm

一、目录结构快速看懂（rdk_x5 分支）

plaintext

rdk_model_zoo/
└── samples/vision/ultralytics_yolo/   # YOLOv8/v10通用demo
    ├── conversion/        # PC端模型转换工程（yaml、导出脚本）
    ├── model/             # 存放预编译 *.bin
    ├── python/            # Python推理代码
    ├── cpp/               # C++推理代码
    ├── resource/          # 测试图片、类别文件
    └── download.sh        # 一键下载官方预编译模型

模式 A：开箱即用，运行官方预编译 YOLOv8（推荐新手第一步）

步骤 1：PC / 开发板拉取仓库，切换硬件分支

bash

运行

git clone https://github.com/D-Robotics/rdk_model_zoo.git
cd rdk_model_zoo
# RDK X5必须切换分支！
git checkout rdk_x5

步骤 2：进入 YOLO 工程目录，下载预编译模型

bash

运行

cd samples/vision/ultralytics_yolo

# 执行下载脚本，自动拉取适配X5的 nv12格式.bin模型
bash download.sh

执行完毕后，model/文件夹生成： yolov8s_640x640_nv12.bin

命名解读：640 输入分辨率、NV12 输入格式（摄像头原生格式）

步骤 3：RDK X5 开发板执行推理（Python）

bash

运行

# 进入python推理目录
cd python

# 运行图片推理demo
python3 infer.py \
--model_file ../model/yolov8s_640x640_nv12.bin \
--image ../resource/bus.jpg

运行成功后：

1. 控制台打印 FPS、推理耗时；
2. 输出画检测框的图片； ✅ 验证：BPU 环境正常、推理链路全部打通。

常见踩坑： 不要用 X3 的 bin 放到 X5；不要把 RGB 图片直接喂给nv12.bin模型。

模式 B：使用自己训练的模型（完整工程流程）

完整链路：Pytorch训练 → 导出ONNX → PC量化编译 → 拷贝.bin到X5部署 所有模板直接复用 Model Zoo conversion目录内文件。

步骤 1：导出兼容地平线的 ONNX（PC 端）

进入conversion/，参考仓库自带export_onnx.py。 重点约束：

• opset=11
• 固定输入尺寸 640×640
• YOLO 系列调整输出顺序为 NHWC，适配 BPU 输出得到 my_yolov8.onnx

步骤 2：修改量化编译 yaml（核心文件）

打开conversion/yolov8_ptq.yaml，关键参数：

yaml

model_parameters:
  onnx_model: './my_yolov8.onnx'
  march: "bayes-e"    # ⭐RDK X5固定，绝对不能写成bernoulli2
  output_model_file_prefix: "my_yolov8_640x640_nv12"

input_parameters:
  input_type_rt: 'nv12'        # 板端推理输入格式
  input_type_train: 'rgb'
  norm_type: 'data_scale'
  scale_value: 0.0039215686    # 1/255

calibration_parameters:
  cal_data_dir: './calibration' # 校准图片文件夹（30~200张真实场景图）

步骤 3：PC 端 OpenExplorer (OE) 工具链编译.bin

在 OE docker 环境执行：

bash

运行

hb_mapper makertbin --config yolov8_ptq.yaml

编译完成，输出目录得到：my_yolov8_640x640_nv12.bin

步骤 4：部署到 RDK X5

1. 将生成的.bin上传至开发板；
2. 复制python/infer.py推理代码；
3. 修改代码内类别数量、类别名称；
4. 执行推理，测试精度。

步骤 5（可选）：C++ 部署

复用cpp目录源码，修改模型路径、类别参数，cmake 编译运行。

二、两条使用路线对比

表格

使用路线	适用人群	操作内容
路线 A：下载预编译模型直接跑	新手、硬件验证	只执行 download.sh + python 推理，不需要 PC 工具链
路线 B：自行转换 ONNX 生成 bin	算法工程师、项目落地	需要 OE 工具链、校准数据集、修改 yaml 配置

三、高频工具命令（调试必备）

1. 校验模型是否为合法 X5 bin（最重要） 在 RDK X5 板端执行：

bash

运行

hrt_model_exec model_info --model_file yolov8s_640x640_nv12.bin

✅ 正常：打印输入输出张量信息 ❌ 报错：模型是 X3 的 bin 或者文件损坏，无法使用

1. 测速基准测试

bash

运行

hrt_model_exec infer --model_file xxx.bin --loop 100

四、典型踩坑清单（结合你之前.bin/hbm 知识）

1. 不切换 git 分支：下载 X3 代码，在 X5 运行，模型加载失败
2. march 参数写错：X5 yaml 写成bernoulli2，编译出 X3 模型，X5 无法加载
3. 格式不匹配：nv12 模型输入 RGB 图像，检测结果完全错乱
4. 概念陷阱：X5 python 包名叫hbm_runtime，不能加载.hbm 文件，仅支持.bin
5. 混淆产品线：Model Zoo（rdk_x5）≠ S100 rdk_model_zoo_s；二者模型不互通

五、通俗总结一句话

Model Zoo 提供一套标准化模板流水线： 想快速验证硬件 → 下载预编译 bin 直接运行； 想部署自己算法 → 复制仓库内 yaml、前后处理、推理代码模板，替换自己的 ONNX 重新编译。