[具身智能-659]：RDK Model Zoo 使用完整教程（实例：RDK X5 + YOLOv8 目标检测）

选用RDK X5rdk_x5 分支作为实操案例全程区分两大使用模式✅ 模式 A直接运行官方预编译模型新手验证硬件最快上手✅ 模式 B基于模板转换自己训练的 ONNX 模型工程落地前置重要前提仓库地址https://github.com/D-Robotics/rdk_model_zoo分支绝对不能切错RDK X3 →git checkout rdk_x3RDK X5 →git checkout rdk_x5环境区分PC 电脑Ubuntu/Docker OE 工具链用来把 ONNX → 量化编译生成.binRDK X5 开发板运行推理代码、加载.bin模型板子上没有 hb_mapper 编译工具关键常识X5 只能使用bayes-e架构的.bin不支持 J5/S100 的.hbm一、目录结构快速看懂rdk_x5 分支plaintextrdk_model_zoo/ └── samples/vision/ultralytics_yolo/ # YOLOv8/v10通用demo ├── conversion/ # PC端模型转换工程yaml、导出脚本 ├── model/ # 存放预编译 *.bin ├── python/ # Python推理代码 ├── cpp/ # C推理代码 ├── resource/ # 测试图片、类别文件 └── download.sh # 一键下载官方预编译模型模式 A开箱即用运行官方预编译 YOLOv8推荐新手第一步步骤 1PC / 开发板拉取仓库切换硬件分支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 输入格式摄像头原生格式步骤 3RDK X5 开发板执行推理Pythonbash运行# 进入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导出兼容地平线的 ONNXPC 端进入conversion/参考仓库自带export_onnx.py。 重点约束opset11固定输入尺寸 640×640YOLO 系列调整输出顺序为 NHWC适配 BPU 输出得到my_yolov8.onnx步骤 2修改量化编译 yaml核心文件打开conversion/yolov8_ptq.yaml关键参数yamlmodel_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张真实场景图步骤 3PC 端 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 Zoordk_x5≠ S100 rdk_model_zoo_s二者模型不互通五、通俗总结一句话Model Zoo 提供一套标准化模板流水线 想快速验证硬件 → 下载预编译 bin 直接运行 想部署自己算法 → 复制仓库内 yaml、前后处理、推理代码模板替换自己的 ONNX 重新编译。