YOLO板端部署目标检测

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

YOLO 是什么

YOLO（You Only Look Once，只看一眼）是一种基于深度卷积神经网络（CNN）的 实时目标检测算法，2016 年由 Joseph Redmon 等人提出，开创了"单阶段（one-stage）"目标检测的先河。

传统目标检测算法（如 R-CNN 系列）分两步：先"找候选区域"，再"对每个区域分类"，速度慢。而 YOLO 的核心思想是：把整张图片一次性送入网络，在 一次前向推理 中同时输出：

  • 图像中每个目标的 类别（如 person、bus、car…）

  • 每个目标的 边框位置（bounding box）

  • 每个目标属于该类别的 置信度（confidence）

准备工作

硬件

  • Quectel PI M2 开发板（RK3576，板载 6 TOPS NPU）

  • USB 数据线连接 PC（ADB 调试）

板载资源（无需额外下载）

M2 板 Debian 系统已预置以下资源，开箱即用：

资源

路径

NPU 推理运行时

/usr/lib/librknnrt.so（v2.3.2）

YOLOv5 检测程序

/usr/bin/rknn_yolov5_demo

YOLOv5s 模型（COCO 80 类）

/usr/share/model/yolov5/RK3576/yolov5s-640-640.rknn

类别标签文件

/usr/share/model/yolov5/model/coco_80_labels_list.txt

测试图片

/usr/share/model/yolov5/model/bus.jpg

连接开发板

adb devices          # 确认设备已连接（显示 device 状态）

单张图片检测（一步一步来）

第 1 步：准备测试图片

板载已有一张 COCO 标准测试图 bus.jpg（公交车+行人场景）：

adb shell "ls /usr/share/model/yolov5/model/bus.jpg"

第 2 步：执行检测

# 进入模型目录（demo 需要在此目录找到 model/coco_80_labels_list.txt）
adb shell "cd /usr/share/model/yolov5 && rknn_yolov5_demo \
  /usr/share/model/yolov5/RK3576/yolov5s-640-640.rknn \
  model/bus.jpg resize /tmp/bus_detected.jpg"

参数说明：

参数

说明

第 1 个

RKNN 模型路径

第 2 个

输入图片路径

第 3 个

缩放方式：resize（拉伸）或 letterbox（等比留边）

第 4 个

输出图片路径

第 3 步：查看结果

adb shell "ls -la /tmp/bus_detected.jpg"        # 确认检测结果文件生成
adb pull /tmp/bus_detected.jpg ./               # 拉回 PC 查看

运行输出

post process config: box_conf_threshold = 0.25, nms_threshold = 0.45
sdk version: 2.3.2 (429f97ae6b@2025-04-09T09:09:27) driver version: 0.9.8
model input height=640, width=640, channel=3
Read model/bus.jpg ...
once run use 24.300000 ms
person @ (209 243 286 510) 0.879723
person @ (479 238 560 526) 0.870588
person @ (109 237 232 534) 0.828112
bus @ (93 129 553 464) 0.700761
person @ (79 353 122 517) 0.307297
save detect result to /tmp/bus_detected.jpg
loop count = 10 , average run  19.313700 ms

可以看到：识别出 4 个 person 和 1 个 bus，单帧推理约 19ms（约 50 FPS）。

检测效果

测试原图：

../../_images/image_Q2rIbrZeioetwpxvi6EcVmnTn3e.webp

NPU 检测结果（蓝框标注目标位置与类别）：

../../_images/image_UqlxbWM8uoHXdyxnGErcBmZonod.webp

检测自己的图片

# 1. 把图片推送到板子
adb push my_photo.jpg /tmp/

# 2. 执行检测（注意要在模型目录运行）
adb shell "cd /usr/share/model/yolov5 && rknn_yolov5_demo \
  /usr/share/model/yolov5/RK3576/yolov5s-640-640.rknn \
  /tmp/my_photo.jpg resize /tmp/my_photo_detected.jpg"

# 3. 拉回结果查看
adb pull /tmp/my_photo_detected.jpg ./

提示：若图片不是 640x640，demo 会自动缩放；resize 会拉伸变形，letterbox 保持宽高比（推荐）。

视频检测

视频检测流程：视频解码 → 每帧 NPU 推理 → 画框后实时送显。板端由 MPP 硬解 + NPU 逐帧推理，检测画面直接输出到屏幕，无需抽帧落盘。

前置条件

  • 板端 Debian 系统已进入 GNOME 桌面（Wayland 会话已登录）——检测画面显示在屏幕上

  • 主机已安装 adb，adb devices 可看到设备

  • 已获取本 SDK 源码（含 external/rknpu2 与 buildroot 输出，用于编译 demo 与取运行库）

第 1 步：交叉编译实时检测 demo（主机）

# SDK 指 SDK 根目录
export SDK=/path/to/RK3576_Linux6.1_SDK
cd $SDK/external/rknpu2/examples/rknn_yolov5_demo

# 1) 指定交叉工具链与 buildroot sysroot（提供 gstreamer 头文件）
export GCC_COMPILER=$SDK/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu
export PKG_CONFIG_PATH=$SDK/buildroot/output/rockchip_rk3576/host/aarch64-buildroot-linux-gnu/sysroot/usr/lib/pkgconfig
export PKG_CONFIG_SYSROOT_DIR=$SDK/buildroot/output/rockchip_rk3576/host/aarch64-buildroot-linux-gnu/sysroot

# 2) 编译并安装到 install/（带 --display 实时显示的 video demo）
bash build-linux.sh -t rk3576 -a aarch64

# 3) 产物目录 install/rknn_yolov5_demo_Linux/
#      rknn_yolov5_video_demo    实时检测 demo（本流程使用）
#      lib/                      板端运行库：librknnrt.so / librga.so / librockchip_mpp.so / libmk_api.so
#      model/RK3576/yolov5s-640-640.rknn + model/coco_80_labels_list.txt

第 2 步：部署到板端

cd $SDK/external/rknpu2/examples/rknn_yolov5_demo/install/rknn_yolov5_demo_Linux

adb shell "mkdir -p /data/local/tmp/yolo/lib /data/local/tmp/yolo/model /data/local/tmp/yolo/videos"
adb push rknn_yolov5_video_demo /data/local/tmp/yolo/
adb push lib/. /data/local/tmp/yolo/lib/
adb push model/coco_80_labels_list.txt model/RK3576/yolov5s-640-640.rknn /data/local/tmp/yolo/model/
adb shell "chmod +x /data/local/tmp/yolo/rknn_yolov5_video_demo"

第 3 步：准备视频（转 h264 裸流）

# demo 只吃 h264 裸流，先用板端 gstreamer 转码（此步不要设 LD_LIBRARY_PATH）
adb push my_video.mp4 /data/local/tmp/yolo/videos/
adb shell "cd /data/local/tmp/yolo/videos && gst-launch-1.0 filesrc location=my_video.mp4 ! qtdemux ! h264parse ! video/x-h264,stream-format=byte-stream ! filesink location=my_video.h264"

第 4 步：运行实时检测

# 自动探测当前图形会话的 Wayland socket（不写死用户名 / UID）
adb shell 'cd /data/local/tmp/yolo && \
  export LD_LIBRARY_PATH=$PWD/lib && \
  export XDG_RUNTIME_DIR=$(dirname $(ls /run/user/*/wayland-* | head -1)) \
         WAYLAND_DISPLAY=$(basename $(ls /run/user/*/wayland-* | head -1)) && \
  ./rknn_yolov5_video_demo model/yolov5s-640-640.rknn videos/my_video.h264 264 --display'

参数说明：第 1 个为 RKNN 模型路径，第 2 个为 h264 视频，264 表示 h264 编码，--display 实时送显（--noshow 关闭显示、--save 另存 out.h264）。检测画面即屏幕实际显示（红框 + 类别名）。需要循环播放时可把命令包在 while true; do ... ; done 中。若屏幕不出画面，追加 export GST_PLUGIN_PATH=/usr/lib/aarch64-linux-gnu/gstreamer-1.0 再试。

检测效果视频

板端实时检测演示视频（本视频录制自板端实际运行：YOLOv5s NPU 逐帧推理 + 屏幕实时显示，源视频 combined_qbox.mp4，1280x720）：

live_detect_demo

常见问题

问题

原因

解决

Segmentation fault

工作目录不对，找不到 ./model/coco_80_labels_list.txt

先 cd /usr/share/model/yolov5 再运行

检测不到目标

置信度阈值过高

修改 postprocess.h 中 BOX_THRESH（默认 0.25）

误检（如猴子识别成 bird）

COCO 数据集无 monkey 类

换自定义模型或调阈值

推理慢

NPU 未定频

设置 NPU 最高频率 950MHz（见 NPU 使用指南）

换模型

如需换其他 YOLO 模型（如自定义训练的模型）：

  1. 用 rknn-toolkit2 将模型转换为 RK3576 版 .rknn（见 [NPU使用指南] 模型转换章节）

  2. 替换模型文件与 labels 文件

  3. 重新运行检测命令

模型转换详细流程见「NPU使用指南」文档。