YOLOv5从解压到部署：目标检测模型训练与工程实践指南

简介面向YOLOv5目标检测入门与进阶学习者这份代码仓库配套B站同名实战课程从环境安装、模型推理、数据集构建与训练延伸到桌面界面、网页部署、结构改进、注意力机制与加速等内容覆盖入门、拓展、进阶、部署四大篇章帮助读者从调包走向改模型与工程化落地。压缩包共340个文件以Python脚本、YAML配置、JPG图片为主要类型另含训练得到的PT权重、engine推理引擎、TorchScript模型与多种Dockerfile等部署文件总计275.62MB目录结构清晰可按学习模块快速定位。资源内还提供了C2f结构修改、SE注意力引入、MobileNet主干替换等参考实现以及云端训练、远程连接和基于Flask的部署示例便于完整走通数据、训练、优化到上线的全流程。目前已有137人学习适合需要配合视频逐行动手操作、希望掌握YOLOv5完整项目链路的学习者拿到手即可对照训练日志与测试图片验证效果也可直接作为二次开发基线。1. 拿到 YOLOv5.zip先搞清楚这个包是干嘛的再决定怎么解压如果你在搜索引擎里敲下“YOLOv5.zip”大概率是刚接触目标检测或者已经踩了一遍环境配置的坑想找个现成的压缩包直接开箱。YOLOv5 是目前工业界和学术圈落地最顺滑的检测模型之一它的官方仓库以 zip 形式分发解压、装依赖、下权重、跑推理四步就能看到第一组检测框。相比 R-CNN 系和更早期的 YOLO 版本YOLOv5 把“训练到部署”的链路压得极短这也是它被大量工程选型的原因。这篇笔记就是按我自己从零跑通的经验写的环境怎么搭、推理怎么跑、数据集怎么训练、坑在哪里以及最后怎么部署到树莓派 5 这种边缘设备上。适合刚入门的从业者照着做也适合熟手查参数边界。2. 环境准备与代码获取conda 环境、zip 解压与 git clone 的差别2.1 用 conda 建干净环境避开 Python 版本玄学我见过太多人在 YOLOv5 上翻车第一原因不是模型难而是环境脏。系统 Python 里装了一堆包版本互相打架torch 装完 import 报错cuda 版本对不上最后连pip install -r requirements.txt都跑不完。所以从头到尾我强烈建议用 conda 创建一个独立环境别碰系统 Python。conda create -n yolov5 python3.9 -y conda activate yolov5创建环境的逻辑很简单-n指定环境名python3.9锁版本。选 3.9 不是因为官方强制而是 PyTorch 在 3.9 上的 wheel 包最全兼容性最好。3.7 到 3.10 都有人用但如果你不想在 torchvision 版本上折腾3.8 或 3.9 是最稳的区间。环境激活后顺手确认一下 Python 版本然后装 PyTorch。这里有个关键点先装 PyTorch再装 requirements.txt顺序反了你可能踩到依赖冲突。CPU 版和 GPU 版的安装指令不一样GPU 版用官方给的 CUDA 版本对应命令CPU 版用cpu标记的源。我自己一般先装 GPU 版如果机器没有 N 卡再退回到 CPU 版不会浪费时间测算力。2.2 从 zip 包解压到 git clone两条路线的差异和选择拿到 YOLOv5.zip 之后第一步自然是解压。Windows 下右键解压就行但如果你在 Linux 服务器上解压命令要记牢unzip YOLOv5.zip -d /opt/projects/ cd /opt/projects/YOLOv5-d参数指定解压目标目录不写的话默认解压到当前目录。有的压缩包是yolov5-master.zip这种命名解压出来目录名带-master后续写脚本时路径容易出问题建议解压后马上改名mv yolov5-master yolov5不过从 zip 解压只是获取代码的一种方式。我更推荐的做法是直接git clone因为 YOLOv5 仓库迭代非常快clone 之后可以随时git pull拉取最新代码还能用git checkout切换版本标签。zip 包的问题是拿到的是某个时间点的快照如果你想复现某个 release 的效果还得重新下载对应版本。git clone https://github.com/ultralytics/yolov5.git cd yolov5 git tag -l # 查看可用版本标签两条路线的差别在于zip 适合“一次性拿到”git clone 适合“长期跟版本”。实际工程里我通常 clone 之后切到某个稳定版本标签比如代码里默认的 master 分支可能引入未完全验证的新特性选一个大家都验证过的 release 更靠谱。之前有段时间 master 分支的推理代码改过接口很多人用旧权重配新代码直接报错切回稳定版本就没事了。2.3 requirements.txt 安装依赖版本锁死比最新版更省事代码到位后安装依赖这一步看起来是pip install -r requirements.txt一行命令但执行时经常出幺蛾子。YOLOv5 的 requirements.txt 里已经锁定了主要依赖的版本范围比如 torch、torchvision、opencv-python、numpy 等但pip在解析依赖时可能因为环境里已有其他包的版本产生冲突。pip install -r requirements.txt装完后必须验证 torch 和 CUDA 是否正常这一步能省掉后面大量无意义的报错排查python -c import torch; print(torch.__version__, torch.cuda.is_available())输出里torch.cuda.is_available()为 True说明 GPU 版本可用为 False 的话即使装了 NVIDIA 驱动也可能是 PyTorch 版本和 CUDA 版本不匹配或者装成了 CPU 版。这个验证脚本我每次新环境都会跑一遍比看任何安装日志都直观。一个常用参数是--index-url如果你在的网络环境访问 PyPI 慢可以换到国内镜像源。但注意torch 这种大包最好从 PyTorch 官方源装不要走镜像否则容易装到不兼容的本地编译版本。常见做法是官方源装 torchrequirements.txt 里其他小包装镜像源。3. 用官方权重跑通检测detect.py 的最小命令与必调参数3.1 下载官方预训练权重yolov5s.pt 是最合适的起步档YOLOv5 官方提供了 n、s、m、l、x 五个尺寸的预训练权重对应从轻到重。第一次跑通流程选yolov5s.pt它是速度和精度的平衡点COCO 数据集上 mAP 50 在 56% 左右推理速度比yolov5m快接近一倍足够你验证整条链路。如果你直接上yolov5x.pt光下载就要等很久推理速度还慢没必要。权重文件在首次运行detect.py时会自动下载到一个名为weights或当前目录下的缓存位置。但国内网络环境下从 GitHub 下载权重经常断流常见做法是手动下载后放到指定目录再在命令里用--weights指定路径这样不会因为网络问题卡住。wget https://github.com/ultralytics/yolov5/releases/download/v6.0/yolov5s.pt -O yolov5s.pt-O参数指定保存文件名。如果你在自己电脑上下好了再传到服务器也行只要路径写对就行。权重文件的版本要和代码版本对应比如 v6.0 的权重配合 v6.0 的代码否则加载时会有提示影响不大但最好一致。3.2 跑第一张图detect.py 的参数表和输出位置权重就位后用官方的样例图片跑一次推理这是检验环境是否完整的硬标准。官方仓库默认带了一张data/images/bus.jpg里面有行人和公交车跑通了能看到检测框和标签。python detect.py --weights yolov5s.pt --source data/images/bus.jpg --conf-thres 0.25参数说明--weights指定权重文件路径支持 .pt 和 .onnx 格式。--source输入来源可以是单张图片、文件夹、视频文件、摄像头设备号甚至是 rtsp 流地址。第一次跑建议用单张图片。--conf-thres置信度阈值默认 0.25。低于这个值的检测结果会被过滤掉调低会显示更多框但误检也变多。运行结束后结果图会保存到runs/detect/exp目录下名字是exp第二次运行变成exp2以此类推。这是 YOLOv5 的默认行为不会覆盖之前的输出。如果你想指定输出目录加--project和--name参数。python detect.py --source data/images/bus.jpg --weights yolov5s.pt --project my_runs --name test01我实际用下来--project参数在批量测试多组权重时特别好用每组权重一个独立目录最后对比结果非常清晰。3.3 从图片到视频和摄像头source 参数的变化单张图片跑通后接视频和摄像头只是--source参数的不同。视频文件传路径摄像头传设备号0或1本地服务传 rtsp:// 地址。我之前在一个园区项目里需要实时分析几个监控点的画面就是直接用的 detect.py 接 rtsp 流。python detect.py --weights yolov5s.pt --source 0 --conf-thres 0.4 python detect.py --weights yolov5s.pt --source test.mp4 --conf-thres 0.3第一个命令打开本机摄像头第二个命令处理视频文件。这里有个细节摄像头推理时--conf-thres要适当调高比如 0.4因为视频流里误检的影响会被放大而图片测试可以调低一点多看看模型检测能力的天花板。摄像头跑的时候按q退出视频文件处理完自动结束结果视频存在runs/detect/exp下。实测中视频推理速度取决于 GPU 性能N 卡上yolov5s一般能跑 60-100 FPSCPU 上可能只有个位数 FPS这也是后面要讲部署优化的原因。4. 训练自己的数据集从标注到 train.py关键一步是 YAML4.1 数据准备标注格式、目录结构现成数据集怎么接官方权重能检测 COCO 的 80 个类别但实际项目里你要检测的物体大概率不在里面——生产环境的安全帽、工地上的反光衣、仓库里的货架都要用自己的数据训练。常见做法是标注工具用 LabelImg 或 Labelme其中目标检测推荐 LabelImg因为它直接导出 YOLO 格式的 txt 标注文件。YOLO 格式的标注是每个图片对应一个同名 txt每行代表一个目标格式为类别ID 中心点x归一化 中心点y归一化 宽度w归一化 高度h归一化目录结构必须按官方要求组织dataset/ images/ train/ val/ labels/ train/ val/images和labels必须分开放train和val子目录对应训练集和验证集。有人会把训练集图片和标注放在同一个目录下训练时 Annotation not found 报错就是路径结构不对。如果你从网上下载的是 COCO 格式的标注比如安全帽数据集需要转成 YOLO 格式转换脚本网上很多但要注意类别 ID 的映射关系不能直接拿 COCO 的类别号当 YOLO 的类别号。4.2 写 data.yaml路径和类别这两处最容易写错数据准备好后需要一个 YAML 文件告诉 YOLOv5 数据在哪、有多少类别。官方示例是data/coco.yaml我们照葫芦画瓢写自己的train: /home/user/dataset/images/train val: /home/user/dataset/images/val nc: 2 names: [helmet, person]参数说明train和val写的是图片目录的绝对路径不是 labels 目录。YOLOv5 会自动把路径里的images替换成labels来找标注文件。nc是类别数量写成整数。names是类别名称列表顺序必须和标注文件里的类别 ID 一致。这里如果写错训练出来的模型检测结果会张冠李戴。我第一次训练安全帽检测模型时就把nc写成了 3names 写了两项训练不报错但 loss 一直偏高后来发现是类别数对不上。另外路径写成相对路径容易在换机器后失效直接用绝对路径省心。4.3 train.py 训练参数batch、epochs、imgsz 怎么定训练命令是这一节的核心参数看着多但经常调的就这么几个python train.py --data safety_helmet.yaml --weights yolov5s.pt --batch-size 16 --epochs 100 --imgsz 640参数说明--data数据集的 YAML 文件路径。--weights预训练权重路径。从yolov5s.pt开始训练是迁移学习收敛快、精度高如果你从零开始训练写--weights 但数据量不够多时效果很差不建议。--batch-size批次大小。显存充足就设大点训练更稳定显存不足就调小但千万别小于 8否则 BN 层统计不稳定loss 会抖动。--epochs训练轮数。起步可以从 100 试看训练集 loss 和验证集 mAP 的趋势不够再加。--imgsz输入图片尺寸。默认 640显存允许时可以设 1280 提高小目标检测精度但推理速度会变慢。训练过程中会打印每个 epoch 的 loss 和 mAP 指标同时runs/train/exp目录下会生成results.png这个图是判断训练效果最直观的依据。如果训练集 loss 下降但验证集 mAP 不涨说明过拟合了可以加数据增强或提前停止。4.4 超参数与网络结构hyp.scratch.yaml 和 yolov5s.yaml 里值得动的几个值YOLOv5 的超参数在data/hyps/hyp.scratch-low.yaml这类文件里训练时用--hyp指定。新手先别动太多但有几个直接影响训练效果的值值得了解参数名作用我常用的调法lr0初始学习率默认 0.01loss 爆炸时降到 0.001momentum动量默认 0.937一般不动weight_decay权重衰减默认 0.0005数据量小时降到 0.0001 防过拟合hsv_h / hsv_s / hsv_v颜色增强幅度数据量少时适当调大提高泛化性fliplr水平翻转概率默认 0.5检测左右不对称物体时改成 0网络结构文件在models/yolov5s.yaml打开后能看到 depth_multiple 和 width_multiple 两个关键系数。它们决定了网络的深度和宽度yolov5s的系数是 0.33 和 0.50yolov5m是 0.67 和 0.75。如果你想调整网络规模改这个文件再另存一份配合--cfg参数加载。不过实际项目里直接用 s、m、l 三个档位切换比手动改系数更可靠手动改容易出网络结构不匹配的玄学错误。5. 避坑指南YOLOv5 实战里最常见的 6 个问题5.1 标注文件是空的LabelImg 导出格式与路径编码现象训练时提示找不到标签或者 loss 完全不下降打开labels/train目录发现 txt 文件都是 0 字节。原因三个可能——LabelImg 保存格式选错了默认是 PASCAL VOC 格式不是 YOLO 格式标注文件路径里带中文图片和 txt 文件名不对应。解决LabelImg 左侧边栏有个格式切换按钮切到 YOLO 再保存把所有路径改成纯英文用脚本检查一下文件名是否严格同名。for img in dataset/images/train/*.jpg; do name$(basename $img .jpg) if [ ! -f dataset/labels/train/$name.txt ]; then echo missing label for $name fi done5.2 zip 包解压报密码错误或文件损坏伪加密与压缩方式现象解压从网上下载的数据集或代码包时提示输入密码或者解压到一半报 CRC 校验错误。原因zip 格式有一个头部的“加密标志位”有些打包工具如 7-Zip或分享者会在不加密的情况下错误地置位这个标志造成“伪加密”假象其实内容并没有加密。另一个常见原因是网上下载的压缩包在传输中损坏特别是用某些下载工具断点续传后文件不完整。解决先用zipinfo或 7-Zip 检查压缩包的加密标志确认是伪加密后用 Python 的 zipfile 模块强行忽略加密标志解压import zipfile zf zipfile.ZipFile(yolov5.zip) zf.open(zf.infolist()[0], r) # 伪加密可正常读取如果确认是损坏重新下载换浏览器或下载工具大概率是传输问题。5.3 CUDA out of memory不是显卡不行是 batch 和 imgsz 没算明白现象训练刚开始就报CUDA out of memory很多人第一反应是换显卡。原因显存占用 batch_size × imgsz² × 模型占用。很多时候不是卡不行而是 batch_size 和 imgsz 设得太大。8GB 显存跑yolov5sbatch 32 imgsz 640 一定会爆。解决显存不足先把 batch-size 减半再不行把 imgsz 降到 480。训练精度损失不大但能跑起来。用下面这个命令快速测可用显存python -c import torch; print(torch.cuda.get_device_properties(0).total_memory / 1024**3, GB)实在不行启用梯度累积--nbs 64参数模拟更大批次显存占用不变。5.4 训练 loss 不降学习率、标签错位、类别不平衡现象训练跑了 20 个 epochloss 曲线是一条横线或者说下降很慢。原因最常见两种情况——标签类别 ID 从 1 开始而不是从 0 开始导致模型学习一个错位的映射或者数据集中 90% 是一个类别另一个类别只有几十张图模型偏向大头类别。解决用下面这段代码检查标注类别分布的合理性import numpy as np label_dir dataset/labels/train/ from collections import Counter cnt Counter() for f in os.listdir(label_dir): for line in open(os.path.join(label_dir, f)): cnt[int(line.split()[0])] 1 print(cnt)如果类别严重不均先想办法扩充少数类数据再考虑用--cls损失权重参数平衡但数据量不够时这个参数只能微调救不了根本问题。5.5 检测框全偏anchors 与输入尺寸的关系现象训练出来的模型检测框位置是对的但尺寸偏差很大小目标全部漏掉。原因YOLOv5 默认 anchors 是按 COCO 数据集聚类出来的你的数据集目标尺寸分布跟 COCO 差异大时anchors 不匹配。另外 imgsz 设太小小目标被缩放到几个像素特征图下采样后直接丢失。解决训练时加--noautoanchor参数重新聚类 anchors让小目标数据也能匹配。YOLOv5 训练时会自动聚类 anchors 并打印结果看到 Best Precision 和 Recall 不理想就要注意了。imgsz 适当加大到 960 或 1280小目标召回率会明显提升但显存和推理时间是代价。5.6 权重文件下载卡住配置代理 vs 手动下载现象detect.py首次运行时自动下载yolov5s.pt进度条长时间不动最后超时。原因GitHub 的 release 下载地址在国内网络环境很不稳定大文件经常断流。解决不要在命令行里死等。直接找能访问 GitHub 的机器下载或者用能下大文件的下载工具手动下载然后放到项目根目录。由于 YOLOv5 下载权重时会先检查本地是否已有同名文件只要本地有就不会再触发下载路径和文件名对上就行不需要额外配置。6. 部署到树莓派 5 并验证效果导出 ONNX、提速与精度取舍6.1 导出 ONNXexport.py 的参数与注意事项训练完成、模型在电脑上验证没问题后下一步是部署到边缘设备比如树莓派 5。第一步是把 PyTorch 权重导出为 ONNX 格式这是跨平台推理的通用接口。YOLOv5 官方提供了export.pypython export.py --weights runs/train/exp/weights/best.pt --include onnx --opset 12参数说明--include导出格式可以同时导出onnx、torchscript、engineTensorRT。树莓派上先用 ONNX后续要提速再考虑 TensorRT。--opsetONNX 算子集版本。opset 12 兼容性最好树莓派上的 onnxruntime 支持良好。--imgsz导出时指定的输入尺寸必须和训练时一致否则推理结果会异常。导出完成后会在同目录生成.onnx文件。注意ONNX 文件只包含模型结构和权重不包含训练时的预处理逻辑推理时需要自己实现归一化和尺寸缩放。6.2 在树莓派 5 上跑推理CPU 上的速度优化树莓派 5 没有 NVIDIA GPU推理只能靠 CPUonnxruntime 是最常用的推理引擎。安装和推理验证pip install onnxruntime python -c import onnxruntime as ort; print(ort.get_available_providers())树莓派上的 CPU 推理速度yolov5s大约在 1-3 FPS 左右取决于输入尺寸和线程数。核心调优点是线程数import onnxruntime as ort import numpy as np import cv2 sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) sess.set_providers([CPUExecutionProvider], [{intra_op_num_threads: 4}]) input_name sess.get_inputs()[0].name img cv2.imread(test.jpg) img cv2.resize(img, (640, 640)) img img[:, :, ::-1].transpose(2, 0, 1) # BGR 转 RGB 并调整为 CHW img np.ascontiguousarray(img, dtypenp.float32) / 255.0 img np.expand_dims(img, axis0) outputs sess.run(None, {input_name: img})intra_op_num_threads不是越大越好树莓派 5 是 4 核 CPU设为 4 通常最优超过 4 反而因为线程切换开销变慢。另一个实用技巧是减少预处理中的复制操作用np.ascontiguousarray避免内存不连续带来的性能损耗。6.3 验证模型效果mAP、FPS 和你自己的测试集最后一步是回到根本问题部署出来的模型到底行不行。两个指标必须测——精度mAP和速度FPS。精度用val.py验证python val.py --data safety_helmet.yaml --weights runs/train/exp/weights/best.pt --img 640输出会给出 mAP50、mAP50-95 和每类的精度召回率。这里要提醒你mAP 是模型能力的综合指标但实际项目里更看重的是你自己业务场景上的表现——把测试集分成模型见过的和没见过的场景单独看后者的准确率才有工程意义。FPS 测的是部署环境的实际性能在树莓派上对测试视频跑完整的推理循环用time记录总耗时除以帧数。优化空间一般有三个方向换更小的模型yolov5n或自定义瘦身、降低输入分辨率、打开 onnxruntime 的图优化。树莓派 5 上好一点的成绩是yolov5n跑到 8-10 FPS够用但不富余再想提速就得考虑 NPU 或外接加速卡了。最后说一句我的实践体会YOLOv5 的整套链路从 zip 解压到边缘部署最花时间的往往不是模型本身而是数据和环境的工程问题。项目进度紧的时候验证集效果先别追求极限先跑通再聚焦优化这个顺序能帮你避免很多白费的等待。希望帮到你。本文还有配套的精品资源点击获取