YOLO板端部署目标检测¶

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_KP5ybcVc5oimuhxDBbuceMq9n5d.webp

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

../../_images/image_Vz4rbxL88oNpHLxw0eccJ7QAnJe.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 推理 → 合成带检测框的视频。

环境准备（宿主机）¶

# PC 端需要 ffmpeg 做抽帧与合成
sudo apt install ffmpeg

操作步骤¶

# 1. 推送视频到板子
adb push video.mp4 /tmp/input.mp4

# 2. 板端抽帧（用 MPP 硬解，速度极快）
adb shell "mkdir -p /tmp/frames && cd /tmp/frames && \
  gst-launch-1.0 filesrc location=/tmp/input.mp4 ! qtdemux ! h264parse ! \
  mppvideodec ! videoconvert ! video/x-raw,format=RGB ! \
  jpegenc ! multifilesink location=frame_%06d.jpg"

# 3. 板端逐帧 NPU 检测
#    对每帧执行 rknn_yolov5_demo，生成带框帧（可写脚本循环）

# 4. 拉回带框帧，宿主机合成视频（25fps）
cat frame_*.jpg | ffmpeg -f image2pipe -framerate 25 -i - -c:v libx264 \
  -pix_fmt yuv420p det_video.mp4

完整的一键脚本可参考 SDK 内 external/quectel-app/rknn-detect/ 目录（deploy.sh / batch_detect.sh）。

检测效果视频¶

板端实时检测演示视频（YOLOv5s NPU 检测 + 屏幕播放）：

微信视频2026-08-14_135944_578

常见问题¶

问题	原因	解决
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 模型（如自定义训练的模型）：

用 rknn-toolkit2 将模型转换为 RK3576 版 .rknn（见 [NPU使用指南] 模型转换章节）
替换模型文件与 labels 文件
重新运行检测命令

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