移远 Quectel Pi M2 上手 yolo 实战

移远 Quectel Pi M2 上手YOLO 目标检测/分割模型板端部署实战系列说明本文是《移远 Quectel Pi M2 从入门到实战》系列。资料来源本文所有步骤、参数均来自移远官方文档中心docs.quectel.com资料截至2026-10-10。标注【本机实测 2026-10-15】的内容为作者在自购板卡上的实测记录Debian 13USB 摄像头 1280×720与官方数据分开引用不混口径。一、YOLO 与本篇的两条部署路线1. YOLO 是什么YOLOYou Only Look Once只看一眼是一种基于深度卷积神经网络CNN的实时目标检测算法2016 年由 Joseph Redmon 等人提出开创了单阶段one-stage目标检测的先河。传统目标检测算法如 R-CNN 系列分两步先找候选区域再对每个区域分类速度慢。而 YOLO 的核心思想是把整张图片一次性送入网络在一次前向推理中同时输出图像中每个目标的类别如 person、bus、car…每个目标的边框位置bounding box每个目标属于该类别的置信度confidence2. 检测 vs 分割输出差在哪任务输出精度目标检测YOLOv8类别 矩形框边界是矩形框实例分割YOLOv8-seg类别 矩形框 像素掩膜边界贴合目标轮廓检测给框分割给抠图——分割输出的每个目标都带一张像素级掩膜轮廓精准贴合目标边缘。3. 两条部署路线怎么选路线模型推理硬件框架实测速度适用A目标检测YOLOv5sCOCO 80 类NPU6 TOPSRKNN 运行时 v2.3.2单帧约 19 ms约 50 FPS实时检测、项目落地B实例分割yolo11n-segCOCO 80 类约 11.7 MBCPU模拟推理ONNX Runtime OpenCV单张约 0.5 s功能验证、算法调试什么是模拟推理Simulated Inference不依赖 NPU/VPU 等专用硬件加速器直接在CPU上用通用推理框架如 ONNX Runtime完成神经网络的前向计算。优点是通用性强、无需特定硬件 SDK、部署简单缺点是算力利用率不如 NPU速度较慢。官方定位很明确在真实硬件加速NPU方案确定之前先验证算法与效果。二、路线 A单张图片检测开箱即用1. 板载资源什么都不用下载M2 板 Debian 系统已预置以下资源开箱即用资源路径NPU 推理运行时/usr/lib/librknnrt.sov2.3.2YOLOv5 检测程序/usr/bin/rknn_yolov5_demoYOLOv5s 模型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硬件要求只有两条Quectel Pi M2 开发板RK3576板载 6 TOPS NPU以及 USB 数据线连接 PCADB 调试。先确认连接adb devices# 确认设备已连接显示 device 状态【本机实测 2026-10-15】除了 ADBSSH 也能执行本节全部命令ssh chen192.168.1.108登录后直接跑效果与 ADB 完全一致。2. 三步跑通第 1 步准备测试图片。板载已有一张 COCO 标准测试图bus.jpg公交车 行人场景adb shellls /usr/share/model/yolov5/model/bus.jpg第 2 步执行检测。注意必须先进入模型目录——demo 需要在此目录下找到model/coco_80_labels_list.txtadb shellcd /usr/share/model/yolov5 rknn_yolov5_demo \ /usr/share/model/yolov5/RK3576/yolov5s-640-640.rknn \ model/bus.jpg resize /tmp/bus_detected.jpgrknn_yolov5_demo的四个位置参数参数说明第 1 个RKNN 模型路径第 2 个输入图片路径第 3 个缩放方式resize拉伸或letterbox等比留边第 4 个输出图片路径第 3 步查看结果。adb shellls -la /tmp/bus_detected.jpg# 确认检测结果文件生成adb pull /tmp/bus_detected.jpg ./# 拉回 PC 查看3. 运行输出解读官方文档给出的完整输出原样引用post process config: box_conf_threshold 0.25, nms_threshold 0.45 sdk version: 2.3.2 (429f97ae6b2025-04-09T09:09:27) driver version: 0.9.8 model input height640, width640, channel3 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单帧推理约19 ms约 50 FPS——这是官方文档的结论once run use 24.300000 ms是首帧耗时后面loop count 10 , average run 19.313700 ms是连续 10 次取平均更能代表稳态性能第一行是后处理配置置信度阈值box_conf_threshold 0.25、NMS 阈值nms_threshold 0.45sdk version: 2.3.2对应板载 librknnrt.so 的版本driver version: 0.9.8对应 NPU 驱动版本与官方资源表一致。两组性能数据别混淆《YOLO板端部署目标检测》实测 demo 单帧约19 ms约 50 FPS包含读图与后处理《NPU使用指南》中rknn_benchmark实测 yolov5s640×640平均17.37 ms / 57.6 FPS是纯推理基准。两处均为官方数据只是口径不同。✅【本机实测 2026-10-15】在 M2 板上原样复跑上述命令NPU 定频 950MHz输出与官方文档完全一致person (209 243 286 510) 0.879723等五个目标逐一复现loop count 10 , average run 19.433000 ms与官方 19.31 ms 基本持平。4. 检测自己的图片# 1. 把图片推送到板子adb push my_photo.jpg /tmp/# 2. 执行检测注意要在模型目录运行adb shellcd /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 ./ 官方提示若图片不是 640×640demo 会自动缩放resize会拉伸变形letterbox保持宽高比推荐。三、路线 A 进阶摄像头/视频实时检测视频检测流程视频解码 → 每帧 NPU 推理 → 画框后实时送显。板端由 MPP 硬解 NPU 逐帧推理检测画面直接输出到屏幕无需抽帧落盘。这一节给两条实现路线官方交叉编译 demo视频文件 屏幕送显与Python RKNNLite 免编译方案USB 摄像头直连 屏幕窗口/网页流本机实测。路线 A-1官方交叉编译 demo视频文件 送显前置条件官方列出三条缺一不可板端 Debian 系统已进入 GNOME 桌面Wayland 会话已登录——检测画面要显示在屏幕上主机已安装 adbadb devices可看到设备已获取本 SDK 源码含external/rknpu2与 buildroot 输出用于编译 demo 与取运行库。与单图检测不同视频 demo 板端没有预置需要在主机上交叉编译。第 1 步主机交叉编译实时检测 demo# SDK 根目录exportSDK/path/to/RK3576_Linux6.1_SDKcd$SDK/external/rknpu2/examples/rknn_yolov5_demo# 1) 指定交叉工具链与 buildroot sysroot提供 gstreamer 头文件exportGCC_COMPILER$SDK/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnuexportPKG_CONFIG_PATH$SDK/buildroot/output/rockchip_rk3576/host/aarch64-buildroot-linux-gnu/sysroot/usr/lib/pkgconfigexportPKG_CONFIG_SYSROOT_DIR$SDK/buildroot/output/rockchip_rk3576/host/aarch64-buildroot-linux-gnu/sysroot# 2) 编译并安装到 install/带 --display 实时显示的 video demobashbuild-linux.sh-trk3576-aaarch64# 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 shellmkdir -p /data/local/tmp/yolo/lib /data/local/tmp/yolo/model /data/local/tmp/yolo/videosadb 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 shellchmod x /data/local/tmp/yolo/rknn_yolov5_video_demo第 3 步准备视频转 h264 裸流demo 只吃 h264 裸流先用板端 gstreamer 转码注意此步不要设 LD_LIBRARY_PATHadb push my_video.mp4 /data/local/tmp/yolo/videos/ adb shellcd /data/local/tmp/yolo/videos gst-launch-1.0 filesrc locationmy_video.mp4 ! qtdemux ! h264parse ! video/x-h264,stream-formatbyte-stream ! filesink locationmy_video.h264第 4 步运行实时检测# 自动探测当前图形会话的 Wayland socket不写死用户名/UIDadb shellcd /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.mp41280×720可到文档中心查看。路线 A-2Python RKNNLite 直连摄像头免交叉编译【本机实测 2026-10-15】交叉编译路线效果好但 SDK 体积大、工具链门槛高。如果只是想让 USB 摄像头的实时画面跑上 NPU用 Python 就够了——本节是作者在板上的完整实测记录从零到出画面约 20 分钟。1. 板端环境绕开 Python 版本坑板载 Debian 13 自带Python 3.13而 RKNN 的板端推理包rknn-toolkit-lite2目前2026-10PyPI 只发布到cp312——直接pip install会报找不到匹配版本。解决办法是用 Miniconda 装一个 Python 3.12 环境与系统 Python 共存# 1) Miniconda国内建议清华镜像GitHub 直连在板子上不通curl-fsSL-o/tmp/miniconda.sh https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-aarch64.shbash/tmp/miniconda.sh-b-p$HOME/miniconda3# 2) 建 py3.12 环境conda 建环境时加 --override-channels 避开需要接受 ToS 的官方源$HOME/miniconda3/bin/conda create-y-nyolo --override-channels\-chttps://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/python3.12# 3) 装包注意版本与板载运行时对齐librknnrt.so 是 v2.3.2$HOME/miniconda3/envs/yolo/bin/pipinstall-ihttps://pypi.tuna.tsinghua.edu.cn/simple\rknn-toolkit-lite22.3.2 opencv-python numpyrknn-toolkit-lite2版本要与板载librknnrt.so对齐都是 2.3.2避免运行时模型版本错配。确认运行时版本strings /usr/lib/librknnrt.so | grep -m1 librknnrt version或跑一次推理看日志。2. 实时检测脚本要点核心流程四十来行就够了关键步骤fromrknnlite.apiimportRKNNLiteimportcv2,numpyasnp rknnRKNNLite()rknn.load_rknn(/usr/share/model/yolov5/RK3576/yolov5s-640-640.rknn)rknn.init_runtime()# NPU 初始化capcv2.VideoCapture(/dev/video73,cv2.CAP_V4L2)# USB 摄像头UVCcap.set(cv2.CAP_PROP_FOURCC,cv2.VideoWriter_fourcc(*MJPG))cap.set(cv2.CAP_PROP_FRAME_WIDTH,1280)cap.set(cv2.CAP_PROP_FRAME_HEIGHT,720)whileTrue:ok,framecap.read()smallletterbox(frame,640)# 等比缩放补边到 640×640rgbcv2.cvtColor(small,cv2.COLOR_BGR2RGB)outsrknn.inference(inputs[np.expand_dims(rgb,0)])# uint8 NHWC 直接喂detspost_process(outs)# 解码 NMS画框送显/推流最容易踩的坑输出解码。这颗 yolov5s RKNN 模型的输出是 3 个(1, 255, 80/40/20, 80/40/20)的 float32 张量正确姿势是先reshape(3, 85, h, w)再转(3, h, w, 85)NCHW → 按锚框分组模型图内已经做了 Sigmoid输出值域就是 [0,1]后处理直接x*2-0.5grid解码即可千万别再套一层 Sigmoid——否则置信度全部压到 0.5 左右、框明显偏移这是最隐蔽的坑校验方法拿板载bus.jpg跑一遍输出应与官方 demo 完全一致4 person 1 busperson (209 243 286 510) 0.880。本机按此校准后逐框对齐官方结果。3. 两种实时输出屏幕窗口 网页流屏幕窗口cv2.imshow()。板子桌面是 WaylandGNOME从 SSH 启动的程序要补三个环境变量走 XWayland否则窗口弹不出来exportDISPLAY:0exportXAUTHORITY$(ls/run/user/$(id -u)/.mutter-Xwaylandauth*|head-1)exportQT_QPA_PLATFORMxcb网页流检测帧用cv2.imencode(.jpg, ...)编码后以multipart/x-mixed-replace推流PC 浏览器直接打开http://板子IP:8000就能看适合演示和录屏。4. 实测数据项目数值说明NPU 单帧推理~27 msPython RKNNLite含前后处理纯推理口径见下行对照端到端帧率12~15 FPS720p USB 摄像头抓帧 推理 画框 编码推流全链路官方 C demo 对照19.4 ms / ~50 FPS纯推理含读图后处理Python 版差距主要在前后处理内存占用常驻 ~500 MB板载 4GBGNOME 桌面同时在线无压力 摄像头选择UVC USB 摄像头/dev/video*OpenCV V4L2 后端直读最省事MIPI 摄像头走 RKISP需要 GStreamer 管道v4l2src ! video/x-raw,formatNV12 ! videoconvert ! appsink且 OpenCV 需带 GStreamer 支持。本机实测时 MIPI 座子未插摄像头dmesg提示imx219 ... failed to read chip id故用 USB 摄像头完成全部实测。四、路线 B分割模型 CPU 模拟推理1. 分割模型原理一分钟YOLO 分割模型YOLOv8-seg / YOLO11-seg有两个输出头输出1检测头 [1, 116, 8400] ├─ 前 4 行框中心 (cx,cy) 与宽高 (w,h) ├─ 中间 80 行80 个类别的置信度 └─ 后 32 行每个候选的掩膜系数mask coefficients 输出2原型掩膜[1, 32, 160, 160] 32 张 160×160 的原型掩膜prototype masks掩膜重建公式mask Sigmoid( 掩膜系数(32) × 原型掩膜(32×160×160) ) → 160×160即用每个目标的 32 个掩膜系数对 32 张原型掩膜做线性组合再经 Sigmoid 激活与阈值化得到该目标的二值掩膜最后缩放到检测框尺寸。出处提醒官方文档分割效果演示一节展示的输入图/掩膜效果图来自RK3576Buildroot 系统板端的 NPU 人像分割 Demo输入 513×513 原图 → 输出像素级掩膜用来说明分割输出的形态而下面部署的/opt/yolodemo 是CPU 模拟推理版本。两处出处不同看图理解效果即可别当成同一个 demo。2. 环境准备M2 板端# 设备自带 Python 3安装 OpenCV 与 numpysudoaptupdatesudoaptinstall-ypython3-opencv python3-numpy# 安装 onnxruntimeaarch64pip3installonnxruntime若 pip 安装 onnxruntime 失败可在宿主机x86_64下载 aarch64 wheel 后推送adb push onnxruntime.whl /opt/yolo/ adb shell cd /opt/yolo python3 -m zipfile -e onnxruntime.whl /opt/yolo/ort3. 模型下载与目录结构设备端目录结构/opt/yolo/ ├── yolov8n-seg.onnx # 分割模型yolo11n-seg约 11.7 MB ├── yolo_seg.py # 分割 Demo 脚本 ├── ort/ # 兼容版 onnxruntimeCPU 模拟推理用 └── test.jpg # 测试图片在可联网宿主机下载后推送curl-sL-oyolov8n-seg.onnx\https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo11n-seg.onnx adb push yolov8n-seg.onnx /opt/yolo/ 一个容易困惑的命名细节文件名叫yolov8n-seg.onnx实际下载的是yolo11n-segYOLO11 的 nano 分割模型COCO 80 类约 11.7 MB。官方目录注释里写明了这层对应关系脚本按文件名引用照抄即可。4. 运行与性能adb shellcd /opt/yolo python3 yolo_seg.py test.jpg输出result.jpg原图 分割掩膜叠加效果效果即分割模型原理一节所说的像素级抠图。实测性能官方数据项目数值推理方式CPUONNX Runtime单张耗时~0.5 s模型yolo11n-segCOCO 80 类如需加速官方指路可将分割模型转换为 RKNN 格式跑 NPU 推理参考《NPU使用指南》。五、推理变慢先给 NPU 定频《YOLO板端部署目标检测》和《NPU使用指南》两章的常见问题表里推理慢都指向同一个原因NPU 未定频。官方给出的解决命令root 权限跑模型前推荐执行# root 权限NPU 固定最高频率echouserspace/sys/class/devfreq/27700000.npu/governorecho950000000/sys/class/devfreq/27700000.npu/userspace/set_freq【本机实测 2026-10-15】以 SSH 执行时用echo 你的密码 | sudo -S sh -c ...一条 shell 包住两行定频在重启后失效长跑前重设一次即可。定频后cat /sys/class/devfreq/27700000.npu/cur_freq应显示950000000。作为参照官方《NPU使用指南》给出了 RK3576 NPU 的rknn_benchmark实测成绩模型输入尺寸平均耗时FPS类型resnet18224x2243.50ms285图像分类resnet152224x22419.35ms51.7图像分类yolov5s640x64017.37ms57.6目标检测yolo11s640x64033.24ms30.1目标检测官方结论yolov5s 的 57.6 FPS 30 FPS视频帧率说明 RK3576 可以实时做视频目标检测。六、常见问题与换模型路线 ANPU 目标检测常见问题问题原因解决Segmentation fault工作目录不对找不到 ./model/coco_80_labels_list.txt先cd /usr/share/model/yolov5再运行检测不到目标置信度阈值过高修改 postprocess.h 中 BOX_THRESH默认 0.25误检如猴子识别成 birdCOCO 数据集无 monkey 类换自定义模型或调阈值推理慢NPU 未定频设置 NPU 最高频率 950MHz见《NPU使用指南》路线 A-2Python 实时检测踩坑实录【本机实测】问题原因解决pip install rknn-toolkit-lite2找不到版本板载 Python 3.13官方轮子只到 cp312Miniconda 建 Python 3.12 环境见第三节GitHub 下载不通Miniconda/micromamba 等板端访问 GitHub 不稳定全部改走清华 TUNA 镜像conda 源 pip 源检测框错乱、置信度全在 0.5 左右后处理对模型输出重复做 Sigmoid模型图内已做输出 reshape 成 (3,h,w,85) 后直接解码校准到 bus.jpg 官方结果SSH 启动后屏幕不弹窗口Wayland 会话下无 DISPLAYDISPLAY:0XAUTHORITYmutter-XwaylandauthQT_QPA_PLATFORMxcbNPU 定频命令权限不够普通用户写不了 devfreqsudo执行重启后失效需重设板子运行中突然重启NPU 满载时供电不足官方要求5V/5A 以上适配器换官方电源与 5A 线路线 B分割模拟推理常见问题问题解决onnxruntime 安装失败用宿主机下载 aarch64 wheel 推送见第四节ImportError: no module named cv2sudo apt install python3-opencv推理慢CPU 模拟推理正常现象需要速度请转 RKNN 走 NPU换自己的模型如需换其他 YOLO 模型如自定义训练的模型官方给出三步用 rknn-toolkit2 将模型转换为 RK3576 版.rknn模型转换详细流程见《NPU使用指南》替换模型文件与 labels 文件重新运行检测命令。写在最后本篇在 M2 上跑通了三类视觉任务NPU 目标检测单图YOLOv5s一条命令官方与实测一致约 19 ms / 约 50 FPS、摄像头实时检测官方交叉编译 demo 走 MPP 硬解 屏幕送显以及本机实测的 Python RKNNLite 免编译方案NPU 单帧 ~27 ms端到端 12~15 FPS屏幕窗口和网页流双输出和CPU 模拟推理分割yolo11n-seg单张约 0.5 s适合先验证效果再转 NPU。三条关键经验检测命令必须在模型目录下运行缩放方式优先letterbox推理慢先给 NPU 定频到 950 MHz。视觉只是开始。下一篇我们把话题从看切换到想——《九把大模型装进开发板DeepSeek / ChatGPT 板端部署》一条路线用 RKLLM 工具链把 DeepSeek-R1 蒸馏小模型真正跑上 NPU离线可用另一条路线在板上搭一个 OpenAI API 网关联网即用两条路线的部署流程、实测性能与选型建议一次讲清。#移远产品体验官 #QuectelPi #QuectelPiM2参考资料与延伸阅读官方产品页https://www.quectel.com.cn/product/quectel-pi-m2官方文档中心M2https://www.quectel.com.cn/docs/quectel-pi/m2yolo11n-seg.onnx 下载地址官方《YOLO模拟推理分割模型》文档内给出https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo11n-seg.onnx本地文档镜像01_官方资料/文档中心/md/重点章节《边缘计算_YOLO板端部署目标检测_YOLO板端部署目标检测.md》《边缘计算_YOLO模拟推理分割模型_YOLO模拟推理分割模型.md》《边缘计算_NPU使用指南_NPU使用指南.md》模型转换与 NPU 定频参考