树莓派5部署YOLOv5实战：六大关键问题与避坑指南

上个月把树莓派5搬进车间目标很明确在传送带边上做一个轻量的视觉检测节点跑我自己训练的YOLOv5模型识别工件缺料、方向错位这些常见问题。本来以为“训练好模型、导出来、部署上去”三步就能收工结果从系统安装到稳定运行前后折腾了两周实打实卡在六件事上。这篇文章把这六个卡点从头到尾捋一遍系统选型与启动、YOLOv5模型导出与量化、推理框架选型、供电散热、图像链路、无人值守与自恢复。适合正准备拿树莓派5做边缘AI或者想把自己训练的YOLOv5模型部署到ARM板子上的朋友参考。里面没有一步是弯路都是我踩过之后重新走出来的照着做能省掉不少麻烦。1. 第一件事系统装Ubuntu别一上来就插电拿到树莓派5之后最想干的事情肯定是赶紧通电看看但车间这种工况我更建议先把系统层面想清楚。我一开始直接用了树莓派官方系统跑了半天发现很多习惯不对然后又换成了Ubuntu Server这一步就耽误了大半天。1.1 为什么选Ubuntu Server而不是树莓派官方系统树莓派官方系统Raspberry Pi OS当然不差外设支持最全自带一堆教学工具桌面环境开箱即用。但车间里跑AI推理节点本质上是无头服务器我更习惯Ubuntu的生态。选Ubuntu Server 24.04 LTS有几点现实考虑第一apt源里的Python版本、OpenCV、各种AI依赖都更跟得上不用折腾PPA和源码编译第二Ubuntu对树莓派5有官方适配内核和驱动维护得比较勤LTS还有五年支持周期车间设备不会频繁换系统第三SSH和netplan的配置方式我很熟远程改网络、排查问题都顺手。需要提醒一句Ubuntu Server默认不带桌面环境VideoCore GPU的加速也不做重点优化但这恰恰是这个场景需要的。推理程序用CPU跑GPU那块不用管省下的显存其实就是内存。1.2 烧录与首次启动注意cloud-init这个隐形步骤烧录这块我推荐直接用Raspberry Pi Imager不要手动dd镜像。Imager里选择“Ubuntu 24.04 LTS (Server)”之后还有一组Advanced Options可以预写hostname、用户名、密码、SSH公钥和WiFi配置。这个步骤看起来不起眼其实是最大的坑。Ubuntu Server的树莓派镜像默认启用cloud-init第一次开机会做云端初始化。如果你直接拿镜像工具dd到SD卡不预先配置cloud-init开机后会卡在“等待网络”或者让你重新交互式设置用户结果就是SSH根本连不上你只能接显示器键盘重新弄一遍。所以我的建议是Imager烧录时把SSH和用户信息全部预写好开机后直接就能ssh进去省掉大量现场操作的麻烦。车间环境里没有多余的显示器这一步真的很关键。1.3 把系统迁到NVMe SSD别让SD卡拖后腿树莓派5最大的硬件升级是带了PCIe接口这意味着可以接NVMe SSD。我在车间部署时第一时间上了M.2 HAT加一块NVMe盘系统直接跑在SSD上。SD卡在车间里其实挺脆弱的振动、频繁断电、小文件随机读写这几个因素叠加起来SD卡很容易出坏块甚至直接挂掉。而且YOLOv5模型加Python虚拟环境里面成千上万个小文件SD卡的随机读写性能完全跟不上加载模型和环境都要等。NVMe HAT的建议型号不多说市面上主流的都能用。装上后系统启动从一分钟级别缩到十几秒模型加载时间也减半。迁移方法我试过两种直接dd整盘迁移最省事但容易把原来的分区UUID和cloud-init配置一起带过去新系统起来后网络设置可能全乱我踩过一次这个坑。后来改成在NVMe盘上重新装一版系统再用rsync把项目和配置同步过去干净又可控。2. 第二件事自己训练的YOLOv5先过导出和量化这两关模型训练阶段在电脑上做得挺顺利但到了往树莓派5上部署的时候麻烦才开始出现。YOLOv5训练出来的PyTorch权重不能直接在板子上跑必须先导出再量化这一步决定了最终推理速度的上限。2.1 训练阶段就要为部署留好后路我训练用的是YOLOv5官方代码库标注数据用常见的LabelImg工具输出YOLO格式的txt文件再按7:2:1划分训练集、验证集、测试集。模型主体选的YOLOv5s因为树莓派5的CPU算力有限YOLOv5s已经是偏重的选择复杂场景甚至我直接改用YOLOv5n。这里有个重要提醒如果你准备把模型部署到边缘设备训练时就要考虑目标尺寸和锚框的适配。YOLOv5训练时默认会自动重新计算anchors所以训练本身没问题但导出到NCNN后解码层要手动配置合适的anchor和stride。我最初没注意部署后检测框位置老是偏排查了很久才发现是解码层的anchor和训练配置对不上。训练完不要只看mAP要多看PR曲线。车间场景里漏检比误检严重得多部署时的confidence阈值和NMS阈值要根据PR曲线调整不能用训练默认的0.25。我最后把confidence调到了0.35左右误检降下来了漏检也没有明显增加。2.2 ONNX导出这几个参数别乱调YOLOv5导出ONNX的命令很简单在官方代码库目录下执行python export.py --weights best.pt --include onnx --opset 12opset选12是比较稳妥的取值版本太低会缺算子版本太高NCNN转换可能要踩兼容性问题。导出后我习惯用onnx-simplifier跑一遍再转能去掉一些部署用不到的多余算子减小模型体积。输入尺寸也是导出时必须定死的一个参数。如果训练用的是640x640导出时也会默认640x640但到了推理阶段如果发现太慢想改成512x512那建议重新导出一次再量化而不是在代码里直接改输入resize的尺寸。因为量化校准和推理代码里的预处理尺寸不一致时结果会偏差很大。2.3 INT8量化模型缩到1/4速度翻倍树莓派5目前GPU的成熟度一般指望它跑FP16加速不太现实CPU上INT8才是实打实的提速手段。我用NCNN的量化工具链做INT8量化需要准备几百张有代表性的校准图片。校准图的选择非常影响量化精度。我一开始从训练集里随机抽了200张结果效果不理想小目标漏检特别多。后来改成从验证集里挑并且刻意均衡类别分布多放一些包含待检测工件的现场照片不能全是干净背景图。校准集调整后量化模型的精度损失小了很多。量化的收益很直接YOLOv5s的FP32模型大概是14MBINT8量化后缩到4MB左右推理速度大约提升30%到60%。代价是精度会掉一点特别是小目标。所以量化前后一定要在验证集上跑一遍对比确认掉点程度可以接受再决定用不用量化模型。3. 第三件事推理框架选型NCNN / ONNX Runtime / TFLite怎么取舍模型准备好之后下一步就是选推理框架。我先后在树莓派5上试了ONNX Runtime、TFLite、NCNN三个框架每个都有各自的问题和优势这里把我的实际对比结果写出来。3.1 三个框架在树莓派5上的表现差异先说ONNX Runtime。部署最简单pip install onnxruntime就能用CPU的线程优化也不错。适合快速验证模型能不能跑通但依赖体积比较大整个环境装下来占用不少空间而且INT8量化的工具链要额外配置CPU上的INT8效率没有想象中高。TFLite的转换链路和ONNX Runtime不太一样要走TFLite的转换脚本还需要做动态范围校准。如果TensorFlow生态你本来就很熟TFLite是个选择但YOLOv5转TFLite时NMS处理经常要额外写代码总体转换成本偏高。NCNN是腾讯开源的移动端推理框架对ARM CPU的NEON指令集优化做得比较彻底配合INT8量化在树莓派5上性能最稳。缺点是转换链路上多一步onnx2ncnnYOLOv5的某些结构需要手动处理。我最终选NCNN做主力ONNX Runtime做调试对照。大概的性能参考YOLOv5s原FP32模型640x640输入ONNX Runtime在树莓派5上大概是3到5FPS同样模型走NCNN INT8量化后能到7到10FPS。如果换YOLOv5n加INT8再加输入降到41615FPS是可以摸到的这个速度对很多车间检测需求已经够用。3.2 我用NCNN的部署代码长什么样NCNN在树莓派上可以用Python绑定核心流程是加载模型参数和权重设置线程数预处理输入前向推理最后做后处理。import ncnn import numpy as np net ncnn.Net() net.opt.use_vulkan_compute False net.opt.num_threads 4 net.load_param(yolov5s_int8.param) net.load_model(yolov5s_int8.bin) input_mat ncnn.Mat.from_pixels_resize( img_bgr, ncnn.Mat.PixelType.PIXEL_BGR2RGB, w, h, target_w, target_h ) input_mat.substract_mean_normalize([], [1 / 255.0, 1 / 255.0, 1 / 255.0]) ex net.create_extractor() ex.input(images, input_mat) outputs [] for out_name in [output_0, output_1, output_2]: ret, mat ex.extract(out_name) outputs.append(mat)这里有个老坑YOLOv5在PyTorch里导出的ONNX输出层是三个特征图但经过onnx2ncnn转换和优化后输出层的顺序和shape可能变化。我第一次部署时想当然按网上的解码代码写结果输出shape对不上程序直接报错。后来在param文件里查实际输出层名和维度再调整解码逻辑才正常跑起来。线程数我也调过好几轮。树莓派5是四核Cortex-A76NCNN默认开4个线程是合理的但有时候手动设成6个反而更慢。原因是树莓派5的内存带宽有限INT8推理已经接近带宽瓶颈线程太多会互相抢带宽。3.3 性能权衡分辨率、线程数、量化模型部署到具体场景后不要一上来就追求640x640高分辨率。车间检测通常机位固定工件大小在画面里的比例基本不变我用512x512输入代替640x640推理速度明显提升检测精度受影响很小。最终我用的组合是YOLOv5s加INT8量化512x512输入NCNN 4线程推理实测稳定在8FPS左右。如果工件特别小或者精度要求高再用YOLOv5n把输入升回640速度反而可能更快。反正就是根据现场情况做权衡别硬套一个模板。后处理的NMS阈值也值得单独调整。车间工位工件间距可能很小重叠框特别多我最后把NMS阈值从0.45调到了0.55左右检测稳定性好了很多。这属于部署现场必须做的细节调优用默认参数很容易出问题。4. 第四件事供电和散热AI没跑起来先被温度干掉了树莓派5的算力比前代强很多但代价是功耗和发热也上来了。车间环境温度和洁净度都不友好供电和散热这两件事不解决好模型跑得再快也会频繁掉线。4.1 树莓派5的供电要求比想象中苛刻树莓派5官方电源是USB-C接口规格5V/5A也就是最大25W。这个功率不是随便标的四核A76满载功耗能到10W以上加上USB摄像头、NVMe SSD、风扇这些外设整机瞬时功耗完全可以超过12W。我一开始偷懒用了一个普通5V/3A手机充电器结果插上USB摄像头后系统跑几分钟就重启一次。后来排查发现电压在负载上来时跌到4.6V以下树莓派触发了低压保护。这个教训很直接供电不能将就。正确的做法是直接用官方27W USB-C电源或者上工业导轨电源比如24V转5V/5A的DC-DC模块比家用充电器可靠得多。另外数据线也要注意普通USB-C线可能不支持5A电流要用带E-mark芯片的线才能过5A。树莓派5的供电接口本身带PD协商线材不合格就触发不了高电流模式。4.2 主动散热和防尘车间工况不能将就树莓派5的发热量真的不小。我裸板跑压力测试CPU温度很快就到85°C然后触到温度墙开始降频推理速度肉眼可见变慢从8FPS掉到4FPS直接卡顿。后来装了官方Active Cooler铝散热片加4线PWM风扇满载压在60°C左右性能稳定多了。如果想更稳一点可以换带风扇的铝制外壳或者自己设计一个简单风道。但要注意车间粉尘多风扇用久了会积灰风量下降后温度会悄悄回升可能某天突然发现设备变慢甚至死机。我在外壳进气口加了可拆卸防尘网每两周吹一次灰换一次防尘网效果很好。温度监控也是有必要的。我写了个小脚本每30秒读一次/sys/class/thermal/thermal_zone0/temp记录到日志文件通过远程看日志判断散热状态。有一次就是通过日志发现风扇线松了没转CPU温度飙到80°C及时处理才没烧设备。4.3 实测温度曲线装风扇和裸奔的差距记录的实测数据大概是这样的车间室温30°C左右满载推理时裸奔状态下一分钟内冲到75°C然后持续爬升到85°C被降频装了官方散热器加风扇之后稳定在55到65°C全程没有降频。可见散热不是可选项而是必需品。特别是夏天车间温度比办公室高不少一台没有主动散热的树莓派5基本等于不定期自动降速。温度数据可以通过InfluxDB加Grafana做可视化不过车间里没必要搞那么复杂一个文本日志文件够用了。5. 第五件事摄像头和图像链路卡在最不起眼的地方模型和推理环境都搞定了我以为万事大吉结果在摄像头和图像采集链路上又卡了两天。这部分问题都不难但特别容易被忽略而且一旦出现问题检测系统就是“能用但不可用”的状态。5.1 CSI还是USB摄像头车间场景我这样选树莓派5原生支持CSI摄像头官方Camera Module 3画质好、体积小、延迟低理论上更适合嵌入式场景。但我实际装在车间里发现一个问题CSI排线长度有限机架稍微调整个角度就要重新布线维护很不方便。后来我换成了USB摄像头虽然多占一个USB口供电也多几瓦但安装灵活很多直接固定在工作台支架上想换角度拧个螺丝就行。如果工位位置固定不变CSI摄像头会更好但如果设备经常要挪动位置USB摄像头省心太多。这里提醒一个硬件坑树莓派5的CSI接口换成了22pin老款的15pin排线摄像头不能直接插需要转接线或者换新线材。很多人买摄像头时没注意到手才发现插不上白白等快递。5.2 固定曝光和分辨率画面不稳检测全乱车间光线的变化比想象中大得多。有自然光窗口的工位上午到下午亮度都不一样顶灯管老化会导致频闪旁边机器指示灯、焊接弧光都会影响画面。起初我用自动曝光画面亮度忽高忽低YOLOv5的检测结果也跟着飘同一角度同一工件置信度一会儿0.7一会儿0.3。后来用v4l2-ctl手动固定曝光、白平衡和增益画面亮度稳定下来检测置信度也稳了。具体做法是查看摄像头支持的参数项然后手动设置一个适合现场光线的固定值。每个摄像头的参数名可能不一样但思路都一样先把画面亮度调到合适再固定参数不要依赖自动调节。5.3 图像采集代码里最容易忽略的两个点第一点是采集分辨率。OpenCV的VideoCapture读取USB摄像头时我先把输出设成1920x1080然后在推理前再resize到模型的512x512输入。不要图省事直接让摄像头输出512分辨率的画面分辨率太低会损失细节检测精度明显下降。第二点是初始化时的黑帧和延迟。USB摄像头从打开到画面稳定通常需要一小段时间初始几帧可能是黑屏或者残影。我在初始化后预读10帧直接丢弃再进入正式循环画面稳定很多。第三点不算忽略但很重要推理慢的时候不要同步丢帧。我的做法是图像采集线程和推理线程分开采集线程持续把最新帧写入一个受锁保护的变量推理线程每帧处理完后再从变量里取最新帧。这样即使推理只有5FPS画面延迟也是最低的不会检测到陈旧帧导致判断滞后。6. 第六件事掉线重启与无人值守车间不讲人情车间设备不可能像办公室那样天天有人盯着掉线、卡死、断电都得能自己恢复。树莓派5当成开发板用很简单但作为无人值守的检测节点这最后一步最考验工程的细致程度。6.1 systemd守护进程开机自启加崩溃自动拉起我用systemd管理推理主程序service文件里配置了Restartalways和RestartSec5进程只要异常退出systemd会在5秒后自动拉起。这个方案比在代码里写while循环复杂但可靠得多。service文件有一点需要注意WorkingDirectory、User、ExecStart这些字段要写完整不要用相对路径。项目路径变了service文件也要同步更新不然就是找不到文件的经典报错。还有初始化依赖问题。服务启动的时候摄像头设备节点和网络可能还没就绪程序直接退出会被systemd反复拉起形成重启风暴。我在程序初始化逻辑里加了重试机制摄像头打不开就等3秒重试最多试10次网络不通就断言等待。这里折腾了两个小时但处理完就再也没出过类似问题。6.2 看门狗和心跳把“死给你看”变成“自己醒过来”进程崩溃可以由systemd处理但系统死锁、内核卡死这种情况systemd也无能为力这时候需要硬件看门狗。树莓派SoC内部其实有硬件看门狗对应内核模块是bcm2835_wdt。我直接在systemd配置文件里设置了RuntimeWatchdogSec10系统就会自动用硬件看门狗定时喂狗一旦整个系统死锁超过10秒硬件强制复位。这个配置比在Python里手动喂狗更稳。具体配置很简洁在/etc/systemd/system.conf里设置RuntimeWatchdogSec10重启后生效。我自己验证过把主程序kill掉systemd会拉起把系统搞到卡死状态大约10秒后会自动重启。车间停电也是无法避免的。树莓派5只要电源恢复就会自动上电启动所以我在前端加了一个小UPS断电后给树莓派留出正常关机的时间避免文件系统损坏。如果预算有限至少要在断电关机脚本里做数据落盘否则SD卡或SSD有概率出现文件系统错误。6.3 局域网部署的固定IP、日志与备份心得车间局域网一般比较单纯我用netplan配置了固定IP地址。DHCP虽然方便但设备重启后IP可能变服务器对接、传感器上报、PLC联动都会断掉。固定IP配置在Ubuntu下很简单/etc/netplan/下的yaml文件改一下netplan apply生效。日志管理也别忽略。Python logging写的日志如果不切割几个月下来能到几个GB。我配置了logrotate按天切割最多保留30天这个习惯能避免很多存储空间告警。备份方面我的做法是项目代码全部走git仓库系统盘用dd做过一个完整的镜文件放到局域网NAS里。一旦现场SSD彻底损坏拿新盘把镜像写回去半小时恢复不用重新装环境。这个流程建议提前测试一遍真到故障时再尝试就来不及了。这六件事全部处理完之后树莓派5在车间已经连续跑了三周没掉链子。我个人最大的体会是边缘部署这件事真正的难点不在模型训练和推理框架而在系统集成。散热不好算力打折供电不稳疯狂重启模型不量化就跑不动摄像头参数不固定检测结果就飘。每一个环节单独看都不难但串在一起就变成了一座座“看不见的墙”。如果你此时也在折腾树莓派5上部署自己训练的YOLOv5模型或者准备把树莓派5装到车间这种环境里不妨先照着这六件事排查一遍剩余的坑会比我想象中少很多。