简介YOLOv5源代码压缩包面向目标检测方向的学习者与开发者提供从环境搭建、数据集配置到模型训练与推理的完整工程实现既可作为深度学习的入门实战素材也可作为项目二次开发的基线版本。资源包共包含215个文件其中51个Python脚本承载训练、验证、检测等核心逻辑64个YAML文件定义了模型结构、数据增强与超参数配置另有6个预训练权重文件、9个Shell脚本、多个Dockerfile及环境配置文件整体大小约226.67MB解压后结构清晰、模块划分完整。Python脚本可直接调用入口帮助用户快速启动训练或测试YAML配置便于灵活调整网络层数与数据集路径预训练权重能够直接迁移使用省去从头训练的大量时间。压缩包内还附带示例图片、测试结果CSV、可视化Notebook等辅助材料便于验证效果与进行结果分析。目前已有780人下载学习适合用于课程作业、算法复现以及实际项目的快速落地。1. 拿到YOLOv5源代码压缩包之后先搞清楚它能不能跑如果你是第一次接触目标检测手里刚拿到一个YOLOv5源代码压缩包第一反应多半是解压、打开 README、然后被里面几十个文件砸晕。这个压缩包本身不是一个软件而是一整套可训练、可推理、可导出的工程骨架你的数据集、你的算力、你的调参水平才是让这套骨头长出肉的东西。我见过太多人卡在同一个地方压缩包解压了环境装完跑detect.py却报错或者跑通了但检测框乱飞最后归咎于代码有问题——其实八成是自己的路径、权重和参数没配对。这篇文章就顺着从压缩包到能跑通、能训练、能落地这条线把每一步怎么操作、参数怎么调、踩过的坑在哪一次性讲清楚。2. 压缩包里装了什么目录结构与代码路径2.1 核心入口文件detect.py、train.py、val.py 各自负责什么YOLOv5 源码压缩包解压之后第一眼就要认准三个入口文件detect.py、train.py、val.py。这三个文件决定了你绝大多数时间的操作方向先分清它们后面才不会被参数列表搞混。detect.py负责推理也就是拿着训练好的权重对图片或视频做检测输出带框的结果图。它既能用官方预训练权重也能用你自己训练出来的权重。train.py负责训练是整个工程里参数最多的入口从模型规模、数据配置到训练轮数全在这里控制。val.py负责评估在验证集上计算 mAP、Precision、Recall 等指标是判断模型练得好不好的唯一标准。# 推理入口 python detect.py --weights yolov5s.pt --source data/images # 训练入口 python train.py --data coco128.yaml --weights yolov5s.pt --epochs 50 # 验证入口 python val.py --weights runs/train/exp/weights/best.pt --data coco128.yaml三个入口的底层逻辑是共通的train.py训练完会在runs/train下生成实验目录val.py读取其中的best.pt做评估detect.py读取权重做推理。很多新手拿到压缩包先改模型结构这是最大的误区——应该先跑通这三个入口再动结构。2.2 模型定义与配置文件models 目录下的 yaml 到底在配什么解压后进到models目录会看到一堆.yaml文件像yolov5s.yaml、yolov5m.yaml、yolov5l.yaml等。这些不是训练超参数而是模型结构定义文件。它们描述的是网络的深度、宽度、以及每一层怎么堆叠。这里有一个非常重要的概念YOLOv5 的模型结构是搭出来的不是写死的。同一个核心代码通过不同的 yaml 配置可以生成 s、m、l、x 不同规模的模型。yolov5s的 depth_multiple 是 0.33width_multiple 是 0.50意思是基础通道数和层深度按比例缩小。所以当你只有一张消费级显卡时先跑yolov5s显存够大再上yolov5l。# models/yolov5s.yaml 核心片段 nc: 80 # 类别数量改成你自己的数据集类别数 depth_multiple: 0.33 # 深度倍率 width_multiple: 0.50 # 宽度倍率 anchors: - [10, 13, 16, 30, 33, 23] - [30, 61, 62, 45, 59, 119]修改nc为你自己的类别数是训练自定义数据集时最基础的配置改动。注意 anchors 一般是自动计算的如果不是特殊情况不要手动改 anchors否则训练前期 loss 会异常波动。2.3 数据与权重目录weights 和 data 目录的常见组织方式压缩包里的data目录存放数据配置比如coco128.yaml就是一个只有一张图片 128 张的迷你数据集配置用来测试流程是否跑通。weights目录通常用来放预训练权重文件不过官方压缩包里不一定带权重需要自己下载后放进去。runs目录在初始状态下不存在只有跑过train.py或detect.py之后才会生成。我拿到一个压缩包后的标准动作是# 创建数据与输出目录的统一规划 mkdir -p datasets/mydata/images datasets/mydata/labels mkdir -p weights # 解压源代码 unzip yolov5-source.zip -d yolov5 cd yolov5目录规划是最容易被忽视的坑。很多人直接把图片和标签散落在各个位置然后用绝对路径到处引用最后训练时找不到标签文件。我的习惯是在压缩包解压目录下单独建datasets目录把所有数据集放进去代码内部统一用../datasets/xxx.yaml这种相对路径引用。3. 本地跑通推理最小命令与三个必调参数3.1 环境安装从压缩包到可运行的依赖清单压缩包解压后第一件事是安装依赖。YOLOv5 的依赖清单在requirements.txt里这里面包括 PyTorch、OpenCV、numpy、matplotlib、seaborn 等。最稳妥的安装方式是用虚拟环境避免和系统其他 Python 包冲突。# 创建虚拟环境并安装依赖 python -m venv yolov5-env source yolov5-env/bin/activate # Windows 下执行 yolov5-env\Scripts\activate pip install -r requirements.txt依赖安装是第一个分水岭。如果你用的是 PyTorch CPU 版本也能跑通推理但训练速度会慢到怀疑人生。我的建议是:先把 PyTorch 装成 CUDA 版本再装其他依赖。检查 CUDA 是否可用用下面这段代码。import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else CPU only)如果输出False说明你安装的是 CPU 版 PyTorch需要重新安装。这个检查步骤 30 秒能帮你省下一整天的排错时间。3.2 第一次推理detect.py 的最小命令与输出位置依赖装完权重准备好就可以跑推理了。最小推理命令只需要两个参数--weights指定权重文件--source指定输入来源。# 用预训练权重对单张图片做推理 python detect.py --weights yolov5s.pt --source data/images/bus.jpg # 用摄像头实时检测 python detect.py --weights yolov5s.pt --source 0 # 用视频文件检测 python detect.py --weights yolov5s.pt --source test.mp4推理结果默认保存在runs/detect/exp第一次运行、runs/detect/exp2第二次运行等目录下。每次运行都会生成一个新目录这是 YOLOv5 的默认机制目的是不覆盖之前的输出结果。当你看到屏幕打印出检测框坐标并且在输出目录里看到带框的图片时说明整个工程跑通了。这里有个小技巧:第一次推理不要用摄像头因为摄像头帧率不稳定出问题不好定位。先用一张内容丰富的图片比如人群、车辆较多的场景确认检测框正常再上视频或摄像头。3.3 三个必调参数conf-thres、iou-thres、imgsz推理时最常调的三个参数是--conf-thres置信度阈值、--iou-thresNMS 交并比阈值、--imgsz输入分辨率。这三个参数直接影响检测结果的质量和数量。--conf-thres控制保留哪些框。置信度低于这个值的检测框会被过滤掉默认 0.25。如果你觉得误检太多就调高到 0.5如果你觉得漏检太多就调低到 0.1。--iou-thres控制 NMS 阶段对重叠框的抑制程度默认 0.45。两个框重叠程度超过这个值置信度低的会被删除。--imgsz控制输入图片的尺寸默认 640。增大到 1280 可能提升小目标检测效果但推理速度会下降。# 高精度推理配置 python detect.py --weights yolov5s.pt --source data/images/bus.jpg \ --conf-thres 0.5 --iou-thres 0.5 --imgsz 1280这三个参数是经验值不是越大越好。conf-thres调太高检测框数量会剧减召回率下降imgsz调太大显存占用飙升。我的调参习惯是先用默认值跑一遍看结果再决定往哪个方向调。这一步不是玄学但确实需要看具体场景。比如夜间监控场景conf-thres建议降到 0.15 以下工厂质检场景conf-thres则建议调到 0.7 以上减少误检。4. 拿自己的数据训练数据准备与训练命令4.1 数据集目录组织images 和 labels 怎么摆放用自己的数据训练是 YOLOv5 源码压缩包最核心的用途。第一步是把数据集按照 YOLO 格式组织好。YOLOv5 要求数据分为训练集和验证集图片放在images目录标注文件放在labels目录。标准目录结构如下datasets/ ├── train/ │ ├── images/ │ │ ├── img001.jpg │ │ └── img002.jpg │ └── labels/ │ ├── img001.txt │ └── img002.txt └── val/ ├── images/ └── labels/标注文件是纯文本格式每行代表一个目标格式为class x_center y_center width height坐标值都是归一化到 0~1 之间的小数。比如一行0 0.5 0.5 0.2 0.3表示类别 0目标中心点在图片的相对位置 (0.5, 0.5)宽是图片宽度的 20%高是图片高度的 30%。# 创建标准目录结构 mkdir -p datasets/mydata/train/images datasets/mydata/train/labels mkdir -p datasets/mydata/val/images datasets/mydata/val/labels目录结构不对训练时最常见的报错是AssertionError: train: No labels found in ...原因就是labels目录里没有标注文件或者图片和标注文件的文件名不一致。YOLOv5 要求图片img001.jpg对应的标注文件必须是img001.txt严格同名。4.2 修改 data yaml 和数据增强参数数据目录准备好之后需要写一个数据配置文件告诉 YOLOv5 去哪里找训练图片、验证图片以及有多少个类别。# datasets/mydata.yaml train: ../datasets/mydata/train/images val: ../datasets/mydata/val/images nc: 2 # 你的类别数 names: [cat, dog] # 类别名称列表这个 yaml 文件放在哪都可以只要路径写对。我一般放在datasets目录下和数据集放一起这样压缩包代码目录保持干净。训练时通过--data参数指定这个文件。数据增强参数主要在train.py里通过命令行控制。常用的有--hsvHSV 色彩增强、--flipud垂直翻转、--fliplr水平翻转、--mosaic马赛克增强等。默认情况下--mosaic是开启的它对小目标检测效果提升明显但也会引入一些噪声。实际使用中我认为--mosaic在训练后期应该关闭或降低概率防止模型过拟合到马赛克拼接出的假样本。4.3 训练命令与常见参数释义训练命令是 YOLOv5 中参数最多的入口但核心参数其实就那么几个--data指定数据配置--weights指定预训练权重--epochs指定训练轮数--batch-size指定批次大小--img指定输入分辨率。# 从头训练一个两类别检测器 python train.py --data datasets/mydata.yaml \ --weights yolov5s.pt \ --epochs 100 \ --batch-size 16 \ --img 640--weights yolov5s.pt这里有一个多数新手不知道的机制它加载的是 COCO 预训练权重但会自动把最后的输出层替换成适应你自己类别数的结构。也就是说你不需要手动修改模型文件的nctrain.py会在加载权重时自动适配。前提是权重文件和代码版本匹配如果版本对不上会报结构不一致的错误。常见的 batch-size 选择策略显存 8GB 用 1616GB 用 3224GB 以上可以尝试 64。但 batch-size 不是越大越好过大的 batch 会导致模型收敛变慢甚至出现 loss 震荡。训练过程中每隔一段时间保存的权重存在runs/train/exp/weights/下last.pt是最后一轮的权重best.pt是验证集 mAP 最优的权重。部署时一定要用best.pt不要用last.pt。5. YOLOv5 源码使用避坑指南5 条血泪经验5.1 现象显存足够却报 OutOfMemory明明显卡显存显示还有剩余运行train.py却直接报CUDA out of memory。这个问题的根源往往不是单张图片的显存占用而是 batch-size 与图片分辨率的乘积超出了显存上限。YOLOv5 在训练时会根据--batch-size和--img动态计算显存占用如果你的图片本身是 4K 超高清即使 batch-size 只有 8也可能撑爆显存。解决思路是把--batch-size调小或者把--img调小。我常用的做法是先用--batch-size 8 --img 640跑一个 epoch用nvidia-smi观察显存占用再逐步放大。另外注意关闭其他占用显存的程序比如浏览器里的硬件加速。# 小显存安全训练配置 python train.py --data datasets/mydata.yaml --weights yolov5s.pt \ --batch-size 4 --img 640 --workers 25.2 现象训练 mAP 一直在低位震荡训练了 50 个 epochmAP 一直在 0.2 附近震荡上不去。最常见的原因是学习率设置不当或者预训练权重没有正确加载。YOLOv5 默认使用--cos-lr余弦退火学习率初始学习率默认是 0.01。如果数据集很小或者类别差异很大0.01 的初始学习率容易导致震荡。我遇到这种情况时会先降低初始学习率或者关闭余弦退火改用固定学习率。另一个原因是数据标注问题比如标注框和类别对不上、标注文件坐标未归一化等。建议先用val.py可视化验证一下标注是否正确。# 降低学习率重新训练 python train.py --data datasets/mydata.yaml --weights yolov5s.pt \ --epochs 100 --batch-size 16 --lr0 0.0015.3 现象detect.py 推理结果全黑或全空白模型训练完detect.py跑出来的图片全是黑底或者输出目录里是空的。这个问题的原因有很多最常见的是输入图片本身的问题。如果你的图片是 PNG 格式且带有 alpha 通道OpenCV 读取时可能产生黑底如果图片是单通道灰度图也可能出现通道不匹配。另一个可能原因是模型权重损坏或与代码版本不兼容。如果你从非官方渠道下载了权重而权重文件的网络结构定义和当前代码不一致推理时可能输出全零结果。解决方法是重新下载权重或者检查代码版本与权重的匹配关系。排查顺序建议先跑官方示例图片再跑自己的图片先确认官方权重能出结果再换自己的权重。5.4 现象修改 models 下的 yaml 后加载报错很多人在models/yolov5s.yaml里添加或者修改了层定义然后训练时报KeyError或者维度不匹配错误。这是因为 YOLOv5 的模型解析机制非常严格yaml 文件里的每个字段都对应代码里具体的解析逻辑不是随意增删就能生效的。我的建议是不要随意修改结构定义文件。如果你想调整模型深度和宽度只需要修改depth_multiple和width_multiple这两个倍率如果你想改变检测头的输出那需要同时修改 yaml 和对应代码风险较高。在还没有完全理解网络结构之前优先靠数据增强和训练参数来提升效果而不是改结构。5.5 现象采用 AMP 训练后 loss 不下降开启--amp自动混合精度后loss 在初始阶段不下降甚至出现 NaN。这是混合精度训练的常见问题原因是梯度溢出或学习率对精度变化敏感。YOLOv5 的 AMP 实现已经做了很多稳定性处理但仍可能在某些数据集上出问题。遇到这个情况先关闭 AMP 跑一轮确认 loss 能下降如果没问题再开 AMP并把学习率降低 10 倍。另一个要注意的是AMP 训练出的模型在导出时也要保持精度对齐否则推理时精度会有明显掉点。对于新手我建议第一轮训练直接不开--amp稳定了再优化提速。6. 从压缩包到自有模型验证与进阶6.1 用 val.py 验证 mAP 与混淆矩阵训练完成后验证是必经的一步。val.py会计算模型的 Precision、Recall、mAP0.5、mAP0.5:0.95并生成混淆矩阵图片。这组指标告诉你模型到底学到了什么而不是凭感觉判断。# 验证 best 权重 python val.py --weights runs/train/exp/weights/best.pt \ --data datasets/mydata.yaml \ --img 640输出的混淆矩阵图存放在runs/val/exp/目录下。每行代表真实类别每列代表预测类别对角线上的值越高越好。如果看到某两个类别之间频繁互相误判说明这两个类别的特征区分度不够要么增加这两类样本量要么考虑用更高分辨率的输入重新训练。另一个验证维度是置信度曲线。当曲线整体偏低时说明模型对目标不够确信可以尝试降低conf-thres提高召回率当曲线在低置信度区间异常陡峭时说明模型可能存在过拟合。6.2 进阶剪枝与蒸馏让模型更小如果你训练完的模型太大部署到嵌入式设备上跑不动剪枝和蒸馏是两个实际可用的方案。剪枝的常见做法是对 BN 层的缩放因子做稀疏化训练然后移除贡献小的通道。这个过程不需要改 YOLOv5 的核心结构只需要在训练阶段增加一个稀疏化损失。蒸馏的思路更直接训练一个大模型作为教师模型让学生模型模仿教师模型的输出。因为 YOLOv5 本身有 s/m/l/x 多个规模你可以直接用 l 模型蒸馏到 s 模型做法是同时加载两个模型让学生模型的输出逼近教师模型。# 启动稀疏化训练剪枝前准备 python train.py --data datasets/mydata.yaml --weights yolov5s.pt \ --epochs 50 --sparse-rate 0.0001注意剪枝和蒸馏是进阶操作需要你对训练流程有比较完整的理解。我不建议刚跑通训练就去剪枝先把基础训练流程摸透再考虑压缩模型。6.3 部署导出 onnx 与 tensorrt 的注意事项验证完模型效果最后一步是部署。YOLOv5 官方代码支持导出 ONNX 和 TensorRT 格式。导出 ONNX 是最通用的做法TensorRT 则针对 NVIDIA GPU 做了深度优化推理速度能提升数倍。# 导出 ONNX python export.py --weights runs/train/exp/weights/best.pt \ --include onnx \ --img 640 # 导出 TensorRT FP16 python export.py --weights runs/train/exp/weights/best.pt \ --include engine \ --img 640 --half导出过程中最容易踩的坑是 ONNX 的 opset 版本与推理框架不兼容。如果导出后在其他推理平台上加载失败先在本地用 ONNXRuntime 验证一下输出是否和 PyTorch 一致。我的一个习惯是导出前先记录 PyTorch 模型的输出形状和典型检测结果导出后再跑同一张图对比确认完全一致再交付。这个习惯让我避免了很多部署事故。毕竟从压缩包到模型每一步都可能出错每一步的错误都可能是时间黑洞。希望这篇笔记能帮你少踩几个坑把时间花在真正提升模型效果上。本文还有配套的精品资源点击获取