RDK X5 部署 Ultralytics YOLO 目标检测/分割/姿态/分类实战教程

一、背景介绍

在端侧设备上运行视觉 AI 模型，是实现低成本、低延迟、高隐私实时推理的关键。RDK X5 是 D-Robotics 推出的嵌入式 AI 开发板，内置 BPU（Brain Processing Unit），专为卷积神经网络推理优化，能够在低功耗条件下提供可观的吞吐能力。

Ultralytics YOLO 是目前工业界使用最广泛的实时目标检测框架之一，涵盖检测（Detect）、实例分割（Segment）、姿态估计（Pose）和图像分类（Classify）四大任务。本教程将指导你在 RDK X5 上完成从模型下载到多任务推理的全流程。

特别说明：本教程覆盖 YOLOv5u / v8 / v9 / v10 / v11 / v12 / v13 共 7 个系列的检测模型，以及对应的分割、姿态、分类模型，总计 50+ 个预编译 .bin 模型可供选择。

二、适用环境

项目	要求
硬件平台	RDK X5
操作系统	RDK OS ≥ 3.5.0 (Ubuntu 22.04)
推理后端	hbm_runtime
模型格式	.bin（BPU 量化模型）
输入格式	packed NV12（YUV420SP）
Python 版本	Python 3

三、内容目标

完成本教程后，你将能够：

• 下载任意 YOLO 系列的预编译 .bin 模型
• 在 RDK X5 上运行目标检测推理
• 切换任务类型，运行实例分割、姿态估计、图像分类
• 理解关键参数的作用并灵活调整

---

四、操作步骤

步骤一：克隆仓库并下载模型

首先克隆 Model Zoo 仓库：

git clone https://github.com/D-Robotics/rdk_model_zoo.git
cd rdk_model_zoo/samples/vision/ultralytics_yolo

进入模型目录，按需下载：

cd model

# 仅下载默认模型（yolo11n 检测）
chmod +x download_model.sh
./download_model.sh

# 或下载全部 50+ 模型
chmod +x fulldownload.sh
./fulldownload.sh

所有模型的下载地址为：

https://archive.d-robotics.cc/downloads/rdk_model_zoo/rdk_x5/ultralytics_YOLO/

步骤二：安装 Python 依赖

进入 Python 运行时目录，安装必需的依赖：

cd ../runtime/python
pip install numpy opencv-python hbm-runtime scipy

注意：hbm-runtime 为 RDK X5 板端专用包，仅在板端环境可安装。如果你在 PC 端配置，可先跳过此包，待推送到板端后再安装。

步骤三：运行目标检测

python3 main.py \
    --task detect \
    --model-path ../../model/yolo11n_detect_bayese_640x640_nv12.bin \
    --test-img ../../../../../datasets/coco/assets/bus.jpg \
    --img-save-path ../../test_data/result_detect.jpg

检测结果图将保存到 ../../test_data/result_detect.jpg。

一键运行（默认检测任务）：

chmod +x run.sh
./run.sh

run.sh 默认会在模型不存在时自动下载 yolo11n_detect_bayese_640x640_nv12.bin。

步骤四：运行实例分割

python3 main.py \
    --task seg \
    --model-path ../../model/yolo11n_seg_bayese_640x640_nv12.bin \
    --test-img ../../../../../datasets/coco/assets/bus.jpg \
    --img-save-path ../../test_data/result_seg.jpg

步骤五：运行姿态估计

python3 main.py \
    --task pose \
    --model-path ../../model/yolo11n_pose_bayese_640x640_nv12.bin \
    --test-img ../../../../../datasets/coco/assets/bus.jpg \
    --img-save-path ../../test_data/result_pose.jpg

步骤六：运行图像分类

python3 main.py \
    --task cls \
    --model-path ../../model/yolo11n_cls_detect_bayese_640x640_nv12.bin \
    --test-img ../../test_data/zebra_cls.jpg \
    --label-file ../../../../../datasets/imagenet/imagenet_classes.names

---

五、模型转换（自定义模型）

如果你使用的是 Model Zoo 提供的预编译 .bin 模型，可以直接跳过本章节。

如果你需要部署自己训练的 YOLO 模型，或者想使用 Model Zoo 未覆盖的模型变体（如不同的输入尺寸、不同的类别数），则需要将 PyTorch 模型转换为 BPU 可执行的 .bin 格式。整个转换流程分为四步：

5.1 准备转换环境

模型转换需要在 x86 Linux 机器（非板端）上进行。推荐两种方式：

方式一：Pip 安装

conda create -n rdk_env python=3.10 -y
conda activate rdk_env
pip install rdkx5-yolo-mapper
hb_mapper --version

方式二：Docker 安装

docker pull openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8
docker run -it --rm \
    -v /path/to/rdk_model_zoo:/data \
    openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8 /bin/bash

离线版本的 Docker 镜像可从地瓜开发者社区获取：https://forum.d-robotics.cc/t/topic/28035

5.2 导出 ONNX

使用 conversion/ 目录下的 export_monkey_patch.py 将 .pt 模型导出为 ONNX：

cd conversion
python3 export_monkey_patch.py --pt yolo11n.pt

5.3 准备校准数据并生成配置

python3 mapper.py --onnx yolo11n.onnx --cal-images /path/to/calibration_images

这一步会自动：

• 从校准图片中提取量化校准数据
• 生成 hb_mapper 所需的 config.yaml 配置文件

5.4 编译 BIN 模型

hb_mapper checker --model-type onnx --config config.yaml
hb_mapper makertbin --config config.yaml

5.5 验证编译结果

# 性能预估
hb_perf config.yaml

# 模型信息检查
hrt_model_exec model_info --model_file yolo11n_detect_bayese_640x640_nv12.bin

# 板端性能测试
hrt_model_exec perf --model_file yolo11n_detect_bayese_640x640_nv12.bin --thread_num 1

5.6 输出 Tensor 协议（关键）

转换时需要保持与 Runtime 一致的输出协议，否则推理结果无法正确解析：

Detection（检测） — YOLOv5u/v8/v9/v10/v11/v12/v13：

• output[0]+[1]：stride 8 的 cls + box
• output[2]+[3]：stride 16 的 cls + box
• output[4]+[5]：stride 32 的 cls + box

Segmentation（分割） — YOLOv8/v9/v11：

• [cls, box, mask_coeff] × 3 + proto 输出

Pose（姿态） — YOLOv8/v11：

• [cls, box, keypoints] × 3

Classification（分类） — YOLOv8/v11：

• output[0]：shape (1, 1000, 1, 1)

转换参考日志保存在 conversion/ 目录中，包含各模型族的 hb_mapper 和 hrt_model_exec 输出。

---

六、参数说明

所有任务均通过统一的 main.py 入口运行，通过 --task 参数切换任务类型。

参数	说明	默认值
--task	任务类型：detect / seg / pose / cls	detect
--model-path	.bin 模型路径	../../model/yolo11n_detect_bayese_640x640_nv12.bin
--test-img	输入图片路径	../../../../../datasets/coco/assets/bus.jpg
--label-file	标签文件路径（分类任务需指定）	""
--img-save-path	结果图保存路径	../../test_data/result_detect.jpg
--priority	模型调度优先级	0
--bpu-cores	BPU core 列表	[0]
--classes-num	检测类别数	80
--score-thres	置信度阈值	0.25
--nms-thres	NMS IoU 阈值	0.70
--strides	解码 stride	8,16,32
--reg	DFL 回归通道数	16
--mc	分割 mask coefficient 通道数	32
--nkpt	姿态关键点数量	17
--kpt-conf-thres	姿态关键点显示阈值	0.50
--topk	分类 Top-K 输出数量	5
--resize-type	缩放策略：0=直接 resize，1= letterbox	1

---

七、模型列表概览

本 sample 在 RDK X5 上支持以下模型家族，全部以预编译 .bin 格式提供：

Detection（检测）

• YOLOv5u: n / s / m / l / x
• YOLOv8: n / s / m / l / x
• YOLOv9: t / s / m / c / e
• YOLOv10: n / s / m / b / l / x
• YOLO11: n / s / m / l / x
• YOLO12: n / s / m / l / x
• YOLOv13: n / s / l / x

Instance Segmentation（实例分割）

• YOLOv8-Seg: n / s / m / l / x
• YOLOv9-Seg: c / e
• YOLO11-Seg: n / s / m / l / x

Pose Estimation（姿态估计）

• YOLOv8-Pose: n / s / m / l / x
• YOLO11-Pose: n / s / m / l / x

Classification（图像分类）

• YOLOv8-CLS: n / s / m / l / x
• YOLO11-CLS: n / s / m / l / x

---

八、性能数据解读

完整的 Benchmark 数据维护在 evaluator/README_cn.md 中，以下为部分代表性数据（RDK X5 板端实测，输入 640×640，packed NV12）：

检测性能（部分）

模型	单线程延迟	单线程 FPS	双线程 FPS
YOLOv5nu	6.3 ms	157.4	291.8
YOLOv8n	7.0 ms	141.9	247.2
YOLOv9t	6.9 ms	144.0	250.6
YOLOv10n	8.7 ms	114.2	171.9
YOLO11n	8.2 ms	121.6	188.9
YOLOv8x	92.4 ms	10.8	11.2

分类性能（部分，输入 224×224）

模型	单线程延迟	单线程 FPS	双线程 FPS
YOLOv8n-CLS	0.7 ms	1374.6	2023.2
YOLO11n-CLS	1.0 ms	949.5	1238.4

建议：评估具体精度和完整性能数据时，请直接查看仓库 evaluator/README_cn.md，其中包含每个模型的 COCO mAP / ImageNet Top-1 精度对照表。

---

九、常见问题

Q1：模型下载失败？

确保网络可访问 archive.d-robotics.cc。如果在板端直接下载较慢，可在 PC 上下载后通过 scp 传输至板端。

Q2：提示 ModuleNotFoundError: No module named 'hbm_runtime'？

hbm_runtime 是 RDK X5 板端专用 Python 包，依赖 BPU 硬件。请确认：

1. 当前操作在 RDK X5 板端执行，而非 PC
2. RDK OS 版本 ≥ 3.5.0
3. 已通过 pip install hbm-runtime 安装（通常板端镜像已预装）

Q3：为什么输入必须是 NV12 格式？

BPU 硬件针对 YUV420SP（NV12）格式做了深度优化，使用该格式可以直接在 BPU 内部完成颜色空间转换，节省 CPU 开销并降低延迟。main.py 内部已自动处理 NV12 的打包，用户只需传入常规 .jpg 图片即可。

Q4：如何切换不同大小的模型？

修改 --model-path 参数即可。例如从 yolo11n 切换到 yolo11s：

python3 main.py \
    --task detect \
    --model-path ../../model/yolo11s_detect_bayese_640x640_nv12.bin \
    --test-img ../../../../../datasets/coco/assets/bus.jpg

Q5：跑自己的图片怎么做？

将 --test-img 参数指向你的图片路径：

python3 main.py \
    --task detect \
    --model-path ../../model/yolo11n_detect_bayese_640x640_nv12.bin \
    --test-img /path/to/your/image.jpg

---

十、参考资料

• RDK Model Zoo 仓库
• Ultralytics 官方实现
• ultralytics_yolo Runtime 说明
• ultralytics_yolo 模型列表
• ultralytics_yolo Benchmark

---

十一、来源声明

本文内容基于 D-Robotics RDK Model Zoo 官方文档整理，原始文档路径：

• https://github.com/D-Robotics/rdk_model_zoo/tree/rdk_x5/samples/vision/ultralytics_yolo

所有参数、路径、版本号均与官方文档保持一致。性能数据来源于 evaluator/README_cn.md 中公开的 Benchmark 结果。