RDK X5 部署 Ultralytics YOLO 目标检测/分割/姿态/分类实战教程文章目录RDK X5 部署 Ultralytics YOLO 目标检测/分割/姿态/分类实战教程一、背景介绍二、适用环境三、内容目标四、操作步骤步骤一克隆仓库并下载模型步骤二安装 Python 依赖步骤三运行目标检测步骤四运行实例分割步骤五运行姿态估计步骤六运行图像分类五、模型转换自定义模型5.1 准备转换环境5.2 导出 ONNX5.3 准备校准数据并生成配置5.4 编译 BIN 模型5.5 验证编译结果5.6 输出 Tensor 协议关键六、参数说明七、模型列表概览Detection检测Instance Segmentation实例分割Pose Estimation姿态估计Classification图像分类八、性能数据解读检测性能部分分类性能部分输入 224×224九、常见问题Q1模型下载失败Q2提示 ModuleNotFoundError: No module named hbm_runtimeQ3为什么输入必须是 NV12 格式Q4如何切换不同大小的模型Q5跑自己的图片怎么做十、参考资料十一、来源声明一、背景介绍在端侧设备上运行视觉 AI 模型是实现低成本、低延迟、高隐私实时推理的关键。RDK X5 是 D-Robotics 推出的嵌入式 AI 开发板内置 BPUBrain 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模型格式.binBPU 量化模型输入格式packed NV12YUV420SPPython 版本Python 3三、内容目标完成本教程后你将能够下载任意 YOLO 系列的预编译.bin模型在 RDK X5 上运行目标检测推理切换任务类型运行实例分割、姿态估计、图像分类理解关键参数的作用并灵活调整四、操作步骤步骤一克隆仓库并下载模型首先克隆 Model Zoo 仓库gitclone https://github.com/D-Robotics/rdk_model_zoo.gitcdrdk_model_zoo/samples/vision/ultralytics_yolo进入模型目录按需下载cdmodel# 仅下载默认模型yolo11n 检测chmodx download_model.sh ./download_model.sh# 或下载全部 50 模型chmodx 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。一键运行默认检测任务chmodx run.sh ./run.shrun.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_envpython3.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/280355.2 导出 ONNX使用conversion/目录下的export_monkey_patch.py将.pt模型导出为 ONNXcdconversion python3 export_monkey_patch.py--ptyolo11n.pt5.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.yaml5.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_num15.6 输出 Tensor 协议关键转换时需要保持与 Runtime 一致的输出协议否则推理结果无法正确解析Detection检测— YOLOv5u/v8/v9/v10/v11/v12/v13output[0][1]stride 8 的 cls boxoutput[2][3]stride 16 的 cls boxoutput[4][5]stride 32 的 cls boxSegmentation分割— YOLOv8/v9/v11[cls, box, mask_coeff] × 3 proto 输出Pose姿态— YOLOv8/v11[cls, box, keypoints] × 3Classification分类— YOLOv8/v11output[0]shape (1, 1000, 1, 1)转换参考日志保存在conversion/目录中包含各模型族的hb_mapper和hrt_model_exec输出。六、参数说明所有任务均通过统一的main.py入口运行通过--task参数切换任务类型。参数说明默认值--task任务类型detect/seg/pose/clsdetect--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-coresBPU core 列表[0]--classes-num检测类别数80--score-thres置信度阈值0.25--nms-thresNMS IoU 阈值0.70--strides解码 stride8,16,32--regDFL 回归通道数16--mc分割 mask coefficient 通道数32--nkpt姿态关键点数量17--kpt-conf-thres姿态关键点显示阈值0.50--topk分类 Top-K 输出数量5--resize-type缩放策略0直接 resize1 letterbox1七、模型列表概览本 sample 在 RDK X5 上支持以下模型家族全部以预编译.bin格式提供Detection检测YOLOv5u: n / s / m / l / xYOLOv8: n / s / m / l / xYOLOv9: t / s / m / c / eYOLOv10: n / s / m / b / l / xYOLO11: n / s / m / l / xYOLO12: n / s / m / l / xYOLOv13: n / s / l / xInstance Segmentation实例分割YOLOv8-Seg: n / s / m / l / xYOLOv9-Seg: c / eYOLO11-Seg: n / s / m / l / xPose Estimation姿态估计YOLOv8-Pose: n / s / m / l / xYOLO11-Pose: n / s / m / l / xClassification图像分类YOLOv8-CLS: n / s / m / l / xYOLO11-CLS: n / s / m / l / x八、性能数据解读完整的 Benchmark 数据维护在evaluator/README_cn.md中以下为部分代表性数据RDK X5 板端实测输入 640×640packed NV12检测性能部分模型单线程延迟单线程 FPS双线程 FPSYOLOv5nu6.3 ms157.4291.8YOLOv8n7.0 ms141.9247.2YOLOv9t6.9 ms144.0250.6YOLOv10n8.7 ms114.2171.9YOLO11n8.2 ms121.6188.9YOLOv8x92.4 ms10.811.2分类性能部分输入 224×224模型单线程延迟单线程 FPS双线程 FPSYOLOv8n-CLS0.7 ms1374.62023.2YOLO11n-CLS1.0 ms949.51238.4建议评估具体精度和完整性能数据时请直接查看仓库evaluator/README_cn.md其中包含每个模型的 COCO mAP / ImageNet Top-1 精度对照表。九、常见问题Q1模型下载失败确保网络可访问archive.d-robotics.cc。如果在板端直接下载较慢可在 PC 上下载后通过scp传输至板端。Q2提示ModuleNotFoundError: No module named hbm_runtimehbm_runtime是 RDK X5 板端专用 Python 包依赖 BPU 硬件。请确认当前操作在 RDK X5 板端执行而非 PCRDK OS 版本 ≥ 3.5.0已通过pip install hbm-runtime安装通常板端镜像已预装Q3为什么输入必须是 NV12 格式BPU 硬件针对 YUV420SPNV12格式做了深度优化使用该格式可以直接在 BPU 内部完成颜色空间转换节省 CPU 开销并降低延迟。main.py内部已自动处理 NV12 的打包用户只需传入常规.jpg图片即可。Q4如何切换不同大小的模型修改--model-path参数即可。例如从yolo11n切换到yolo11spython3 main.py\--taskdetect\--model-path../../model/yolo11s_detect_bayese_640x640_nv12.bin\--test-img../../../../../datasets/coco/assets/bus.jpgQ5跑自己的图片怎么做将--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 结果。