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

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模型可供选择。

二、适用环境

三、内容目标

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

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

四、操作步骤

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

首先克隆 Model Zoo 仓库：

gitclone https://github.com/D-Robotics/rdk_model_zoo.gitcdrdk_model_zoo/samples/vision/ultralytics_yolo

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

cdmodel# 仅下载默认模型（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 pipinstallnumpy opencv-python hbm-runtime scipy

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

步骤三：运行目标检测

python3 main.py\--taskdetect\--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\--taskseg\--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\--taskpose\--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\--taskcls\--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-nrdk_envpython=3.10-yconda activate rdk_env pipinstallrdkx5-yolo-mapper hb_mapper--version

方式二：Docker 安装

dockerpull openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8dockerrun-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：

cdconversion python3 export_monkey_patch.py--ptyolo11n.pt

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

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

这一步会自动：

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

5.4 编译 BIN 模型

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

5.5 验证编译结果

# 性能预估hb_perf config.yaml# 模型信息检查hrt_model_exec model_info--model_fileyolo11n_detect_bayese_640x640_nv12.bin# 板端性能测试hrt_model_exec perf--model_fileyolo11n_detect_bayese_640x640_nv12.bin--thread_num1

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参数切换任务类型。

七、模型列表概览

本 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）：

检测性能（部分）

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

建议：评估具体精度和完整性能数据时，请直接查看仓库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\--taskdetect\--model-path../../model/yolo11s_detect_bayese_640x640_nv12.bin\--test-img../../../../../datasets/coco/assets/bus.jpg

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

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

python3 main.py\--taskdetect\--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 结果。