[具身智能-659]：RDK Model Zoo 使用完整教程（实例：RDK X5 + YOLOv8 目标检测）
选用RDK X5（rdk_x5 分支）作为实操案例；
全程区分两大使用模式：
✅ 模式 A：直接运行官方预编译模型（新手验证硬件，最快上手）
✅ 模式 B：基于模板转换自己训练的 ONNX 模型（工程落地）
前置重要前提
- 仓库地址：
https://github.com/D-Robotics/rdk_model_zoo - 分支绝对不能切错
- RDK X3 →
git checkout rdk_x3 - RDK X5 →
git checkout rdk_x5
- RDK X3 →
- 环境区分：
- PC 电脑（Ubuntu/Docker OE 工具链）：用来把 ONNX → 量化编译生成
.bin - RDK X5 开发板：运行推理代码、加载
.bin模型；板子上没有 hb_mapper 编译工具
- PC 电脑（Ubuntu/Docker OE 工具链）：用来把 ONNX → 量化编译生成
- 关键常识：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运行成功后：
- 控制台打印 FPS、推理耗时；
- 输出画检测框的图片； ✅ 验证：BPU 环境正常、推理链路全部打通。
常见踩坑： 不要用 X3 的 bin 放到 X5；不要把 RGB 图片直接喂给
nv12.bin模型。
模式 B：使用自己训练的模型（完整工程流程）
完整链路：Pytorch训练 → 导出ONNX → PC量化编译 → 拷贝.bin到X5部署所有模板直接复用 Model Zooconversion目录内文件。
步骤 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
- 将生成的
.bin上传至开发板； - 复制
python/infer.py推理代码； - 修改代码内类别数量、类别名称；
- 执行推理，测试精度。
步骤 5（可选）：C++ 部署
复用cpp目录源码，修改模型路径、类别参数，cmake 编译运行。
二、两条使用路线对比
表格
| 使用路线 | 适用人群 | 操作内容 |
|---|---|---|
| 路线 A：下载预编译模型直接跑 | 新手、硬件验证 | 只执行 download.sh + python 推理，不需要 PC 工具链 |
| 路线 B：自行转换 ONNX 生成 bin | 算法工程师、项目落地 | 需要 OE 工具链、校准数据集、修改 yaml 配置 |
三、高频工具命令（调试必备）
- 校验模型是否为合法 X5 bin（最重要）在 RDK X5 板端执行：
bash
运行
hrt_model_exec model_info --model_file yolov8s_640x640_nv12.bin✅ 正常：打印输入输出张量信息 ❌ 报错：模型是 X3 的 bin 或者文件损坏，无法使用
- 测速基准测试
bash
运行
hrt_model_exec infer --model_file xxx.bin --loop 100四、典型踩坑清单（结合你之前.bin/hbm 知识）
- 不切换 git 分支：下载 X3 代码，在 X5 运行，模型加载失败
- march 参数写错：X5 yaml 写成
bernoulli2，编译出 X3 模型，X5 无法加载 - 格式不匹配：nv12 模型输入 RGB 图像，检测结果完全错乱
- 概念陷阱：X5 python 包名叫
hbm_runtime，不能加载.hbm 文件，仅支持.bin - 混淆产品线：Model Zoo（rdk_x5）≠ S100 rdk_model_zoo_s；二者模型不互通
五、通俗总结一句话
Model Zoo 提供一套标准化模板流水线： 想快速验证硬件 → 下载预编译 bin 直接运行； 想部署自己算法 → 复制仓库内 yaml、前后处理、推理代码模板，替换自己的 ONNX 重新编译。