RDK X5 部署 YOLO26 实战：模型下载、Python 推理与转换流程

@[TOC]

摘要

本文基于 D-Robotics RDK Model Zoo rdk_x5 分支中的 YOLO26 示例整理，面向希望在 RDK X5 上快速体验 YOLO26 的开发者。文章覆盖三部分：直接下载 RDK X5 预编译 .bin 模型、使用 hbm_runtime 运行 Python 推理样例，以及在 x86 Linux 开发机上通过 RDK X5 OpenExplore 1.2.8 工具链完成模型转换。示例模型输入格式为 NV12，推理后端为 hbm_runtime，可覆盖目标检测、实例分割、姿态估计、旋转框检测和图像分类任务。

前言

YOLO26 是 Ultralytics 提供的一套实时视觉模型系列。RDK Model Zoo 中的 ultralytics_yolo26 示例已经为 RDK X5 提供了完整样例，包括模型文件管理、Python 推理、模型转换和评测说明。

如果只是快速体验，最短路径是进入 runtime/python 目录运行一键脚本；如果需要适配自己的 ONNX 模型，则需要在 x86 Linux 开发机上准备 RDK X5 OpenExplore 工具链，并通过 mapper.py 生成 RDK X5 可运行的 .bin 模型。

适用环境

项目	内容
板卡	RDK X5
推荐系统	RDK OS >= 3.5.0，系统基于 Ubuntu 22.04 aarch64 和 TROS-Humble
推理后端	hbm_runtime
模型格式	.bin
输入格式	NV12
板端依赖	numpy、opencv-python、hbm-runtime、scipy
转换开发机	x86 Linux，推荐 Ubuntu 22.04
转换 Python	Python 3.10
转换工具链	RDK X5 OpenExplore 1.2.8
Docker 镜像	openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8
hb_mapper	1.24.3 或更新版本

需要注意的是，转换工具链的 Pip 安装方式是在 x86 开发机上使用，原始文档明确提示不要在 RDK 板端安装。

目录结构怎么看

YOLO26 示例目录大致分为几个部分：

.
├── conversion/                     # 模型转换流程
├── evaluator/                      # 精度评测和结果导出脚本
├── model/                          # 模型文件和下载脚本
│   ├── download_model.sh           # 下载 nano 模型
│   ├── fulldownload.sh             # 下载全部模型
│   └── README.md                   # 模型文件说明
├── runtime/                        # 运行时样例
│   └── python/                     # Python 推理样例
│       ├── main.py                 # Python 入口脚本
│       ├── yolo26_det.py           # 检测封装
│       ├── yolo26_seg.py           # 分割封装
│       ├── yolo26_pose.py          # 姿态封装
│       ├── yolo26_obb.py           # 旋转框封装
│       ├── yolo26_cls.py           # 分类封装
│       ├── run.sh                  # 一键运行脚本
│       └── README.md               # 运行时说明
├── test_data/                      # 推理结果目录
└── README.md                       # 当前总览文档

其中，runtime/python 适合快速上手，model 用于下载预编译模型，conversion 用于自定义模型转换，evaluator 用于精度和性能评测。

第一步：安装板端 Python 依赖

在 RDK X5 板端，先确认 Python 环境可用，然后安装运行样例需要的依赖：

pip install numpy opencv-python hbm-runtime scipy

这一步只针对运行时推理样例。模型转换工具链不要安装在 RDK 板端。

第二步：一键运行 YOLO26 Python 样例

进入 Python 推理目录：

cd runtime/python
chmod +x run.sh
./run.sh

脚本会在模型不存在时自动下载默认的 yolo26n 检测模型，并将结果图保存到 test_data/。

如果希望手动运行检测任务，可以使用：

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

这里几个关键参数含义如下：

参数	说明	默认值
--task	任务类型：detect、seg、pose、cls、obb	detect
--model-path	RDK X5 .bin 模型路径	../../model/yolo26n_detect_bayese_640x640_nv12.bin
--test-img	测试图片路径	../../../../../datasets/coco/assets/bus.jpg
--img-save-path	结果图保存路径	../../test_data/result_detect.jpg
--bpu-cores	推理使用的 BPU Core 索引	0
--score-thres	置信度阈值	0.25
--nms-thres	NMS 阈值	0.70

第三步：运行其他 YOLO26 任务

YOLO26 示例不仅包含检测，也包含分割、姿态估计、旋转框检测和分类。

实例分割

python3 main.py \
    --task seg \
    --model-path ../../model/yolo26n_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/yolo26n_pose_bayese_640x640_nv12.bin \
    --test-img ../../../../../datasets/coco/assets/bus.jpg \
    --img-save-path ../../test_data/result_pose.jpg

旋转框检测

python3 main.py \
    --task obb \
    --model-path ../../model/yolo26n_obb_bayese_640x640_nv12.bin \
    --test-img ../../../../../datasets/dotav1/asset/P0009.png \
    --label-file ../../../../../datasets/dotav1/dota_classes.names \
    --img-save-path ../../test_data/result_obb.jpg

图像分类

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

第四步：下载预编译模型

如果只关注推理，可以直接使用 Model Zoo 提供的 RDK X5 预编译 YOLO26 模型。

下载 nano 模型：

chmod +x download_model.sh
./download_model.sh

下载全部 n / s / m / l / x 模型：

chmod +x fulldownload.sh
./fulldownload.sh

模型说明中给出的下载目录为：

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

模型命名规则包括：

任务	模型文件
目标检测	yolo26{n/s/m/l/x}_detect_bayese_640x640_nv12.bin
实例分割	yolo26{n/s/m/l/x}_seg_bayese_640x640_nv12.bin
姿态估计	yolo26{n/s/m/l/x}_pose_bayese_640x640_nv12.bin
旋转框检测	yolo26{n/s/m/l/x}_obb_bayese_640x640_nv12.bin
图像分类	yolo26{n/s/m/l/x}_cls_bayese_224x224_nv12.bin

第五步：准备模型转换环境

如果需要把自己的 YOLO26 ONNX 模型转换为 RDK X5 可运行的 .bin，需要在 x86 Linux 开发机上准备转换环境。

推荐使用 Miniconda 创建 Python 3.10 环境：

conda create -n rdk_env python=3.10 -y
conda activate rdk_env

安装工具链：

pip install rdkx5-yolo-mapper

如果下载速度较慢，可以使用镜像源：

pip install rdkx5-yolo-mapper -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

验证安装：

hb_mapper --version
# 预期输出: hb_mapper, version 1.24.3 (或更新版本)

如果希望环境隔离，也可以使用官方 Docker 镜像：

docker pull openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8

启动容器时挂载 Model Zoo 目录：

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

第六步：执行模型转换

YOLO26 示例提供了 mapper.py 脚本，可以自动完成校准数据准备、配置文件生成以及调用 hb_mapper 进行编译。

准备工作：

• 已经导出为 BPU 适配的 ONNX 模型。

• 准备一个文件夹，包含 20~50 张用于量化校准的图片，格式为 .jpg 或 .png。

运行转换：

python3 mapper.py --onnx [model.onnx] --cal-images [校准图片目录]

转换成功后，生成的 .bin 模型文件将位于 ONNX 模型的同级目录下。

常用参数包括：

参数	说明
--onnx	原始浮点 ONNX 模型的路径
--cal-images	包含校准图片的目录路径，建议 20~50 张
--quantized	量化精度：int8（默认，推荐）或 int16
--jobs	模型编译时的并发任务数
--optimize-level	编译器优化等级：O0、O1、O2（默认）、O3
--cal-sample	是否从目录中采样图片，默认 True
--save-cache	是否保留 BPU 编译过程中的临时文件，默认 False

性能数据参考

以下数据来自 YOLO26 示例的评测说明，测试对象为 RDK X5，输入格式为 NV12。

Device	Model	Size	Classes	BPU Task Latency / BPU Throughput
X5	YOLO26n Detect	640x640	80	11.6 ms / 86.3 FPS (1 thread); 19.1 ms / 104.3 FPS (2 threads)
X5	YOLO26s Detect	640x640	80	20.9 ms / 47.7 FPS (1 thread); 37.8 ms / 52.8 FPS (2 threads)
X5	YOLO26m Detect	640x640	80	40.1 ms / 24.8 FPS (1 thread); 76.1 ms / 26.1 FPS (2 threads)
X5	YOLO26l Detect	640x640	80	51.1 ms / 19.5 FPS (1 thread); 98.0 ms / 20.3 FPS (2 threads)
X5	YOLO26x Detect	640x640	80	103.3 ms / 9.6 FPS (1 thread); 202.0 ms / 9.8 FPS (2 threads)
X5	YOLO26n Seg	640x640	80	15.5 ms / 64.3 FPS (1 thread); 22.8 ms / 87.6 FPS (2 threads)
X5	YOLO26n Pose	640x640	80	12.5 ms / 79.6 FPS (1 thread); 20.1 ms / 98.7 FPS (2 threads)
X5	YOLO26n Cls	224x224	1000	1.1 ms / 906.0 FPS (1 thread); 1.7 ms / 1156.8 FPS (2 threads)

从表中可以看到，同一套 YOLO26 示例在不同任务和不同模型规模下吞吐差异明显。快速体验建议先从 YOLO26n Detect 开始；如果对检测精度或任务类型有更高要求，再切换到 s/m/l/x 或分割、姿态、OBB、分类模型。

常见问题

1. 转换工具链能不能直接装在 RDK X5 板端？

不建议。原始转换文档明确说明，Pip 安装方式仅在 x86 开发机上进行，推荐 Ubuntu 22.04，切勿在 RDK 板端安装。

2. 只想跑一下 YOLO26，是否必须先转换模型？

不必须。样例已经提供了 RDK X5 适配的 .bin 模型，可以通过 model 目录下的下载脚本获取。

3. 安装 rdkx5-yolo-mapper 下载失败怎么办？

原始文档说明通常是网络连接不稳定导致，重新运行安装命令即可，Pip 会自动跳过已下载的包。也可以使用阿里云镜像命令。

4. mAP 精度相比官方结果偏低是否正常？

Model Zoo 说明中提到，pycocotools 计算的精度通常比 ultralytics 官方工具略低，原因包括 AP 曲线面积计算方式不同等。评估时更建议关注同一套计算方式下定点模型与浮点模型的对比。

总结

在 RDK X5 上体验 YOLO26，可以先走“下载预编译 .bin 模型 + 运行 runtime/python/run.sh”这条路径；如果需要自定义模型，再在 x86 Linux 开发机上使用 rdkx5-yolo-mapper 或 OpenExplore 1.2.8 Docker 镜像完成转换。整个示例围绕 .bin、NV12 和 hbm_runtime 组织，适合用作 RDK X5 视觉模型部署的入门模板。

来源说明

本文内容基于 D-Robotics RDK Model Zoo rdk_x5 分支中 YOLO26 示例文档整理，原始素材遵循 Model Zoo 顶层 Apache License 2.0。

参考文件：

• rdk_model_zoo_rdk_x5/samples/vision/ultralytics_yolo26/README_cn.md

• rdk_model_zoo_rdk_x5/samples/vision/ultralytics_yolo26/conversion/README_cn.md

• rdk_model_zoo_rdk_x5/samples/vision/ultralytics_yolo26/runtime/python/README_cn.md

• rdk_model_zoo_rdk_x5/samples/vision/ultralytics_yolo26/model/README_cn.md

• rdk_model_zoo_rdk_x5/samples/vision/ultralytics_yolo26/evaluator/README_cn.md

• rdk_model_zoo_rdk_x5/README_cn.md