RDK Model Zoo 完整详解（地瓜机器人 D-Robotics）

一、基础定义与诞生背景

1. 概念全称

RDK Model Zoo：面向 RDK 系列边缘开发板的开源模型案例仓库，俗称模型动物园。 仓库地址：https://github.com/D-Robotics/rdk_model_zoo

2. 技术发展背景

地平线机器人产品线（RDK X3 / X5）与车载产品线（J5/J6）工具链、模型格式割裂：

1. 早期痛点
   • 开发者缺少完整链路参考：Pytorch 训练模型 → ONNX 导出 → PTQ 量化 → BPU 模型编译 → 板端推理、前后处理全套代码；
   • 量化参数、图像预处理归一化、NV12 输入格式、BPU 后处理极易踩坑；
   • X3、X5 BPU 指令集不同，.bin模型不能互通，缺少平台隔离的标准化 Demo。
2. 项目目标 官方统一提供端到端标准化参考工程，打通「训练导出→PC 量化编译→板端 BPU 部署」全链路，降低边缘 AI 落地门槛。
3. 关键区分（结合你之前关注的.bin/.hbm）
   • RDK X3、X5（机器人线）Model Zoo 全部使用 .bin；
   • 车载征程 5/6 使用.hbm，不在此仓库内；
   • RDK S100 独立分支仓库 rdk_model_zoo_s，使用.hbm，与 X5 仓库互相独立。

重要：RDK Model Zoo 不提供 hbm 模型；X5 分支所有预编译模型均为bayes-e架构专用.bin，无法在 X3 运行。

二、核心设计目标

1. 提供开箱即用预编译 BPU 模型 仓库内置下载脚本，一键拉取已经 PTQ 量化、编译完成的.bin模型，直接上板运行，无需本地编译。
2. 提供完整链路参考模板 每个模型目录包含：
   • Pytorch → ONNX 导出脚本
   • OpenExplorer (OE) 工具链量化 yaml 配置
   • Python / C++ 板端推理代码
   • 图像预处理、BPU 输出后处理（YOLO、分割、分类解析代码）
3. 统一规范输入标准 绝大多数模型采用 NV12 图像输入（RDK 摄像头原生输出格式，省去板端 RGB 转换，节省算力），模型命名规范：xxx_640x640_nv12.bin。
4. 屏蔽底层 API 差异 按硬件划分 Git 分支，隔离 X3 hobot_dnn、X5 hbm_runtime两套推理接口。
5. 性能基准参考 附带 Benchmark 测速脚本，用于评估 BPU 实际推理耗时、FPS。

三、分支与硬件平台映射（重中之重）

仓库通过Git 分支区分硬件，分支不可混用，模型不能跨分支迁移：

表格

开发板	Git 分支	推理 Python 接口	模型文件	BPU 架构
RDK X3 / X3Pi	rdk_x3	hobot_dnn.pyeasy_dnn	bernoulli2 .bin	Bayes 一代
RDK X5 / Ultra	rdk_x5	hbm_runtime	bayes-e .bin	Bayes2（Bayes-e）
RDK X5 历史旧 Demo	rdk_x5_legacy	pyeasy_dnn（淘汰）	bayes-e .bin	Bayes-e
RDK S100/S600	独立仓库 rdk_model_zoo_s	hbm_runtime	.hbm	Nash

⚠️ 高频踩坑：直接 clone 默认切到主分支，必须手动切换对应硬件分支，否则代码、模型全部不兼容。

四、仓库标准目录结构（rdk_x5 分支）

plaintext

rdk_model_zoo/
├── demos/                    # X3分支目录名
├── samples/                  # X5分支标准目录
│   └── vision/               # 视觉算法大类
│       ├── classification/  # 图像分类 ResNet/MobileNet
│       ├── detect/           # 目标检测 YOLOv5/v8/v10/FCOS
│       ├── instance_segmentation/ # 实例分割
│       ├── pose_estimation/  # 人体姿态
│       └── ocr/              # PaddleOCR
│           ├── download.sh  # 一键下载预编译.bin模型
│           ├── conversion/  # PC端模型量化、编译脚本+yaml
│           ├── python/       # Python推理demo
│           ├── cpp/          # C++推理demo
│           ├── README_cn.md  # 参数说明、运行命令
│           └── resource/     # 测试图片
├── resource/                 # 公共文档素材
└── requirements.txt

每个模型目录三大核心组件

1. download.sh：从官方云端下载预编译.bin；
2. conversion/：PC 工具链模型转换全套工程（ONNX→bin）；
3. python/cpp：板端部署代码。

五、标准使用流程（实操步骤）

步骤 1：拉取仓库并切换正确分支

bash

运行

git clone https://github.com/D-Robotics/rdk_model_zoo.git
cd rdk_model_zoo
# RDK X5 使用
git checkout rdk_x5
# RDK X3 使用
# git checkout rdk_x3

步骤 2：下载预编译模型（两种方案）

方案 A（推荐，开箱即用） 进入对应模型目录执行下载脚本：

bash

运行

cd samples/vision/ultralytics_yolo
bash download.sh

脚本自动下载*_nv12.bin模型到本地。

方案 B（自行重新编译模型）

1. PC 端安装 OpenExplorer OE Toolchain；
2. 进入conversion目录，修改 yaml；
3. 执行hb_mapper makertbin生成适配平台的.bin；

注意：yaml 内march参数必须和硬件匹配：

• X5：bayes-e
• X3：bernoulli2

步骤 3：拷贝代码 + 模型到开发板运行

示例（X5 Python 推理）

bash

运行

# 板端执行
python3 python/infer.py --model_file yolov8s_640x640_nv12.bin --image test.jpg

六、核心技术要点（结合你之前.bin/hbm 知识）

1. 模型命名规则解读 yolov8s_640x640_nv12.bin

• yolov8s：网络结构
• 640x640：固定输入分辨率
• nv12：模型期望输入图像格式（不是 RGB/BGR）

若输入图片格式不匹配，推理结果完全错乱。

1. 前后处理划分原则（Model Zoo 标准范式）

• 预处理：缩放、均值归一化、色域转换 → 放在板端 CPU；
• 量化、归一化偏移：嵌入模型内部（BPU 执行）；
• 后处理：置信度过滤、NMS、坐标解码 → CPU 执行；

部分高性能 Demo 使用 C++ 编写的libpostprocess.so加速后处理，避免 Python 速度瓶颈。

1. 接口名称陷阱（重点！） X5 分支 Python 包名为hbm_runtime，极易误认为支持.hbm 文件 ✅ 真相：hbm_runtime只是 API 名称，仅加载 bayes-e 架构.bin，无法加载 J5/S100 的.hbm。

七、工程价值与使用建议

✅ 适合场景

1. 新手快速验证 BPU 推理链路；
2. 自研算法部署时，复制量化 yaml、后处理代码作为模板；
3. 评估不同模型在 RDK 板卡上的 FPS、内存占用；
4. TROS.B 机器人项目算法基线参考。

⚠️ 局限性

1. 仅提供主流开源模型，定制网络需要自行基于 conversion 脚本改造；
2. 预编译模型为固定分辨率，动态 shape 需要修改量化配置重新编译；
3. 不支持多模型权重共享（X5 bin 单模型机制，无 hbm link 链接能力）；
4. 预训练权重不提供，仅提供导出 ONNX 与编译流程。

八、常见踩坑清单

1. 不切换 Git 分支，X3 代码在 X5 运行，模型加载失败；
2. 使用 X3 的 bin 放到 X5；
3. RGB 图像直接喂给nv12.bin模型，输出乱码；
4. 混淆 rdk_model_zoo（机器人 X3/X5）与 rdk_model_zoo_s（S100 车载）；
5. 误以为 hbm_runtime 可以加载.hbm 模型。