Yolov5这个在目标检测领域几乎无人不知的项目我最早接触它的时候还是2.0版本那时候就被它“一条命令训练、一条命令推理”的爽感吸引了。但真正把它用在实战项目里踩过的坑比想象中多得多。这篇笔记不打算写成官方文档的复读机更多地是想记录我从零开始跑通Yolov5基本流程、再到成功训练自己数据集的全过程。标题里“从入门到入狱”是句玩笑话但背后有个真实的提醒Yolov5确实功能强大集成了大量训练技巧和推理优化稍有不慎就会在配置、数据、超参数上翻车。所以这篇内容既写给刚接触目标检测的朋友也写给已经跑通过demo、正准备训练自己数据的同学希望能帮你们少走一些弯路。1. 环境搭建与项目准备1.1 环境配置版本匹配才是第一道坎Yolov5对环境的要求其实不算苛刻但版本匹配问题是我见过最多的“劝退”原因。很多人一上来就装最新的PyTorch和CUDA结果跑官方权重时报出一堆底层错误其实是版本之间不兼容。我这里给出一个经过大量实测、比较稳妥的配置组合组件推荐版本备注Python3.8 ~ 3.103.11及以上部分依赖兼容性差PyTorch1.12 ~ 2.0过低不支持新算子过高可能有兼容问题CUDA11.3 ~ 11.8需与PyTorch编译版本对应cuDNN8.2及以上与CUDA配套安装安装时建议用Anaconda创建独立环境这个习惯能救你很多次。比如我有个项目同时要用Yolov5和另一个基于TensorFlow的检测框架如果没有独立环境两个框架的依赖冲突能让人怀疑人生。conda create -n yolov5 python3.9 conda activate yolov5 # 安装PyTorch务必根据官网选择对应CUDA版本 pip install torch1.13.1cu117 torchvision0.14.1cu117 --extra-index-url https://download.pytorch.org/whl/cu117安装完PyTorch后强烈建议先验证一下CUDA是否真的可用别等到训练时报“CUDA out of memory”才反应过来说是CPU在跑import torch print(torch.cuda.is_available()) # 必须输出True print(torch.cuda.get_device_name(0)) # 查看显卡型号1.2 源码获取GitHub下载还是镜像加速Yolov5的源码托管在GitHub上直接git clone https://github.com/ultralytics/yolov5.git就行。不过国内网络环境下直接clone经常卡在中间这里分享几个实测有效的办法一是使用GitHub加速镜像比如在clone链接前加https://gitclone.com/github.com/前缀二是在Gitee上搜索“yolov5”能找到不少同步仓库速度会快很多三是通过HuggingFace上的ultralytics/yolov5仓库下载zip包。这里需要特别注意下载源码后要安装依赖但不要无脑安装requirements.txt里的全部依赖建议先看清楚哪些是你当下需要的。cd yolov5 pip install -r requirements.txt如果只是做推理所需的核心依赖其实只有torch、opencv-python、numpy、Pillow这几个。而训练时还会用到tensorboard、matplotlib、pandas等。先全装也行但要有心理准备——某些依赖版本更新后可能会让Yolov5代码跑出莫名其妙的问题。1.3 权重文件选择不是越大越好源码clone下来后项目根目录下有个weights/文件夹如果没有就自己建一个。训练好的模型权重需要从官方Release页面下载有yolov5s.pt、yolov5m.pt、yolov5l.pt、yolov5x.pt四个等级。很多新手一上来就下yolov5x觉得“x最大肯定最强”但忽略了它的体积和速度代价。模型参数量单张图片推理耗时GPU适用场景yolov5s7.2M约6ms移动端、实时检测yolov5m21.2M约10ms一般业务场景yolov5l46.5M约14ms对精度要求较高yolov5x86.7M约20ms学术研究、高精度需求个人建议第一步先用yolov5s跑通流程确认代码、环境都没问题后再根据实际场景切换更大的模型。不要一开始就在权重上纠结模型的修正会体现在后续训练中而不是简单的换大模型就能解决。2. 基本功能使用流程从detect到predict2.1 推理入口detect.py的参数都是干什么的Yolov5的推理入口是detect.py你需要掌握的核心参数其实就那么几个先用一张表格整理清楚参数名作用使用示例--weights指定权重文件路径--weights yolov5s.pt--source指定推理源图片/视频/摄像头/文件夹--source data/images--conf-thres置信度阈值低于此值的目标被过滤--conf-thres 0.25--iou-thresNMS的IoU阈值控制重叠框的保留--iou-thres 0.45--img-size输入图片缩放的尺寸--img-size 640--device指定设备CPU用cpuGPU用0--device 0--classes只检测指定类别过滤不想要的类别--classes 0 2--project结果保存路径--project runs/detect最基本的推理命令很简单python detect.py --weights yolov5s.pt --source data/images/bus.jpg这条命令会读取data/images/bus.jpg用yolov5s模型进行检测在图片上画出检测框并保存到runs/detect/目录下。跑通这一步环境就算基本没问题了。2.2 不同推理源的实操细节除了单张图片日常使用中更多会碰到视频和摄像头的推理需求。这里按source参数的不同取值整理出对应的用法和注意点。图片文件夹推理把source指向一个文件夹路径模型会遍历文件夹内所有图片适合批量处理。但要注意Yolov5默认会递归扫描子目录吗不会它只处理当前目录下的文件。如果你的图片分散在多个子目录要么自己合并要么写个脚本先集中起来。python detect.py --weights yolov5s.pt --source ./my_images --conf-thres 0.3视频推理source直接指向mp4文件路径即可实现对视频逐帧检测并输出带标注结果的视频文件。这里的细节是Yolov5会对视频帧做缩放处理长宽比不是640:640的视频会被填充黑边如果你生成的视频文件播放时有黑边是正常的。python detect.py --weights yolov5s.pt --source test.mp4 --project runs/detect_video摄像头实时检测source传0代表调用第一个摄像头传1代表第二个。这个功能演示效果好但实际使用时要注意摄像头推理的实时性和模型大小直接相关。用yolov5x做实时推理就算有GPU也可能掉帧。python detect.py --weights yolov5s.pt --source 02.3 推理结果可视化与保存推理完成后Yolov5自动在runs/detect/下创建新文件夹比如exp、exp2等保存所有带标注的结果图。如果想在终端实时看到检测数量统计可以加上--verbose参数。一个容易被忽略的细节是检测结果的坐标信息detect.py默认是不保存到文件的。如果你想拿到每个目标的具体坐标、类别、置信度需要修改代码在detect.py里找到保存结果的部分加上一行np.savetxt(result.txt, det[:, :6].cpu().numpy(), fmt%.6f)这行代码会输出[x1, y1, x2, y2, conf, class]格式的检测结果方便后续做数据分析或接入业务系统。提示跑通detect.py只代表你的环境没问题离真正用起来还有一段路。接下来最重要的一步是训练属于自己的模型。3. 训练自己的数据集3.1 数据采集与标注什么样的数据喂出什么样的模型训练自己的数据集第一步不是写代码而是整理数据。很多人在这里没有给予足够重视导致后续训练效果很差还找不到原因。数据采集有几个原则都是我在实际项目中用真金白银换来的经验第一数据量不是越多越好而是越“贴近真实场景”越好。你训练的是果园里拍摄的苹果那就别只下载网上那些棚拍精修图模型的泛化能力取决于训练数据和真实分布的差距。一般来说每个类别收集500~2000张图片基本能满足初步训练需求。第二场景多样性比数量更关键。同一种目标要尽量覆盖不同角度、不同光照、不同距离、不同遮挡程度。我做过一个车牌检测项目刚一开始只用白天清晰的车牌图片训练结果夜间和雨天的检测效果惨不忍睹后来补了大量低光照、模糊的车牌数据才改善。第三标注质量直接决定模型上限。即使Yolov5本身有mosaic数据增强等手段也无法消除错误标注带来的负面影响。如果你的标注框比目标物体大了20%模型学习到的特征就是错误的检测效果自然飘。标注工具方面我推荐LabelImg或者Label Studio。LabelImg轻量级适合快速标注数量不多的数据集Label Studio功能更丰富支持团队协作和多人审核适合中大型项目。标注格式上Yolov5需要的是YOLO格式的txt文件每行内容为类别ID 中心点x坐标 中心点y坐标 宽度 高度注意这里的坐标是归一化的值在0~1之间需要用标注框的像素坐标除以图片的宽高。LabelImg直接支持YOLO格式输出不用自己转换。3.2 数据集目录结构一个最容易被忽视的细节Yolov5对数据集的目录结构有约定网上很多教程说得不清不楚这里直接给出经我验证的标准格式datasets/ └── my_dataset/ ├── images/ │ ├── train/ # 训练图片 │ └── val/ # 验证图片 ├── labels/ │ ├── train/ # 训练图片对应的标注txt │ └── val/ # 验证图片对应的标注txt └── my_dataset.yaml图片和标注文件必须一一对应images/train/001.jpg对应labels/train/001.txt同名文件缺一不可。另外Yolov5的训练脚本会去读取标签文件里的类别ID如果数据集里某个类别的ID不连续比如只有0和2没有1需要自己处理成连续的否则训练时会报错或导致类别对应错乱。很多人喜欢把训练集和验证集放在一个文件夹里然后按比例切分。这种做法虽然可行但会在后续实验中引入不确定性——Yolov5的划分子集工具split.py是按文件名随机切的如果图片是连续编号的比如无人机航拍视频抽帧出来的不按时间切分会导致验证集和训练集高度相似模型评估结果虚高。3.3 YAML配置文件训练的关键闸门my_dataset.yaml是训练时最重要的小文件它告诉Yolov5数据在哪、有几类、类名是什么。下面是一个案例配置# 数据集根目录路径 path: /home/user/datasets/my_dataset # 训练图片相对路径 train: images/train # 验证图片相对路径 val: images/val # 类别数量 nc: 2 # 类别名称 names: [cat, dog]注意path字段可以用绝对路径也可以用相对路径但相对路径的基准是运行命令时的当前目录。我之前就是在这个字段上吃了亏——明明数据都在却一直报AssertionError: train: No images found把路径改成绝对路径后立刻就好了。nc这个数字非常关键它必须是数据集中实际的类别数量多一个少一个都会出问题。如果类别数量不对训练时类别索引就会错位损失函数怎么都降不下去最后检测结果更是完全错乱。3.4 启动训练从train.py到模型出炉环境准备好后训练命令其实很简单python train.py --data my_dataset.yaml --weights yolov5s.pt --epochs 100 --batch-size 16 --img 640参数解释--data指定数据集的yaml配置文件--weights预训练权重。这一步至关重要强烈建议使用官方权重作为基础。Yolov5在COCO数据集上预训练过的模型底层特征提取器已经学会了通用物体的基础特征就像一个人已经认识了很多东西你只需要教他“什么是猫什么是狗”就可以了完全从零训练会慢得多效果也差得多--epochs训练轮数一般从50~100起步根据loss收敛情况再调--batch-size批次大小取决于显存大小。可以先用--batch-size -1让Yolov5自动检测最大适合的batch size但建议手动指定比较稳妥--img输入图片分辨率Yolov5官方默认640小目标多时可以尝试更大尺寸如1280但显存占用会翻倍训练开始后终端会显示类似这样的信息Epoch 0/99: 100%|████████████████████| 123/123 [04:1200:00, 2.05s/it] Class Images Instances P R mAP50 mAP50-95 all 20 35 0.814 0.771 0.792 0.523这几个指标是判断模型好坏的关键PPrecision代表预测为正的样本中有多少是真的正例RRecall代表所有真实正例中有多少被模型找出来了mAP50表示IoU阈值为0.5时的平均精度mAP50-95则是在不同IoU阈值下的平均更能反映模型的定位精度。注意训练日志里如果看到NaN或inf大概率是学习率太大或者数据有异常比如空标签文件先检查数据别急着调参。3.5 训练结果解析与模型验证训练结束后结果保存在runs/train/exp/或exp2等取决于已存在几个相同名称的文件夹里。重点关注这几个文件weights/best.pt验证集上表现最好的权重。推荐用它做后续推理和部署weights/last.pt最后一轮训练结束时的权重。如果你打算继续训练在last.pt基础上接着跑用这个results.png训练过程中loss、precision、recall、mAP的曲线图。从这里能直观看到模型是否收敛、是否过拟合confusion_matrix.png混淆矩阵帮你定位哪些类别容易混淆模型的最终验证用detect.py对新图片做一次推理就能直观看到效果python detect.py --weights runs/train/exp/weights/best.pt --source test.jpg --conf-thres 0.3注意验证场景的图片最好不要和训练图片太相似否则检测效果好看着热闹实际使用是完全两回事。4. 超参数与训练技巧提升效果的进阶之路4.1 超参数文件训练配置的核心引擎很多人训练时只用默认参数跑完发现效果一般就觉得“Yolov5不过如此”。事实上Yolov5的强项之一就是超参数搜索和自动调优data/hyps/hyp.scratch-low.yaml这个文件里定义了所有关键超参数。下面这几个是实际项目中效果影响最大、也最值得调的超参数默认值作用调整建议lr00.01初始学习率数据集小时可适当降低到0.005lrf0.01最终学习率初始学习率的系数一般不用动momentum0.937动量系数默认值已经很通用weight_decay0.0005权重衰减防止过拟合数据集大时可适当增大warmup_epochs3.0预热轮数先小学习率再逐渐增大数据集复杂可增加到5box0.05框回归损失的权重对定位精度要求高时加大cls0.5分类损失的权重类别多或类别不平衡时调整hsv_h / hsv_s / hsv_v0.015 / 0.7 / 0.4训练时颜色增强的幅度增强数据多样性的关键调整超参数的方法很简单训练时指定python train.py --data my_dataset.yaml --weights yolov5s.pt --hyp data/hyps/hyp.scratch-low.yaml如果你不想自己手动调Yolov5还提供遗传算法自动搜索超参数的功能运行python train.py --evolve即可。不过我的经验是新手阶段别盲目追求超参数调优。先把数据质量、标注准确度、训练轮数这几个基础环节做好模型效果通常已经能到80分。超参数调优是锦上添花不是雪中送炭。4.2 显存优化与训练加速显存不足是训练时最常见的问题之一特别是batch size设大了之后。几个有效的解法第一降低输入分辨率。同样一张图640和1280的显存占用差了4倍。如果你的目标物体不是非常小640或800通常够用。第二开启梯度累积。Yolov5官方支持--batch-size配合梯度累积来模拟更大的batch size。比如显存只够跑batch size为8但你想用16的效果可以在源码中修改梯度累积步数或者干脆用--batch-size 8训练久一点效果差距没想象中那么大。第三使用AutoBatch。--batch-size -1会自动检测显存并设置合适的batch size虽然不一定是最优值但至少不会OOM。训练速度方面如果你的GPU支持混合精度大部分NVIDIA显卡都支持在train.py里加--amp能减少显存占用并加速训练精度损失很小实战中几乎感知不到差异。4.3 数据增强提升模型泛化能力的隐形武器Yolov5内置的图像增强手段非常多mosaic四张图拼接、mixup图片混合、hsv色域变换、随机水平翻转、随机缩放裁剪等这些策略默认都是开启的这是Yolov5在小数据集上也能取得不错效果的重要原因。但要注意数据增强不是万能的也不是越强越好。比如mosaic增强在训练初期非常有效但训练末期可能会因为拼接出来的图片太过“非自然”导致模型在真实场景上表现不佳。Yolov5在训练后期会逐渐把mosaic关闭默认最后10个epoch关闭如果你发现自己的验证集表现比测试集差很多可以检查一下是不是训练轮数太短mosaic没来得及关闭。实战心得当你发现模型在训练集上mAP很高、验证集上却明显偏低时先别急着调超参数优先检查验证集图片是否和训练集来自同一分布。很多时候是数据划分问题而不是模型问题。5. 常见问题与排查技巧5.1 环境类问题速查现象可能原因解决方案import torch 报错CUDA版本和PyTorch不匹配根据PyTorch官网对应CUDA版本重新安装NumPy版本冲突其他框架依赖了旧版本NumPyconda环境内升级NumPy到1.21ModuleNotFoundError: No module named torchvision依赖不完整pip install torchvisionOSError: [WinError 126] 找不到指定的模块常见于Windows上PyTorch与cuDNN版本不匹配显卡驱动更新后重装PyTorch训练时报错“CUDA out of memory”显存不足降低batch size、降低img尺寸、开AMP训练时报错“AssertionError: train: No images found”数据集路径配置错误检查yaml中path、train、val路径是否正确环境问题往往是最大的时间杀手我见过不少人在环境配置上耗了一两天最后发现只是某个库的版本不对。建议记录一套自己常用、经过验证的环境配置组合以后每次开新项目直接复用能省太多事。5.2 训练过程异常排查训练时loss不降反升这是新手最容易感到绝望的情况。我的排查顺序是第一步先确认数据没问题。随机抽几张训练图片看看标注框是否贴合目标、有没有空标注文件、有没有类别ID越界。第二步检查学习率。如果初始学习率太高loss会在前面几个epoch先增大再降下来这是正常的。但如果50个epoch后loss还在震荡说明学习率设置过高或数据集本身噪声太大。第三步看loss曲线形态。训练集loss和验证集loss一起降说明正常如果训练集loss降了但验证集loss回升那就是过拟合了可以增加数据量、加大数据增强或调整weight_decay。还有一个容易被忽略的问题是类别不平衡。如果你的数据集中“背景”类占比极高比如检测密集场景中的小目标模型会把大量注意力放在学习“什么是背景”上导致前景目标检测不出。这时候可以尝试调整cls损失权重或者做一下类别重采样。5.3 推理阶段典型问题推理时检测不到目标最直接的原因是置信度阈值设得太高。Yolov5默认的--conf-thres 0.25在某些场景下会把低置信度的正确检测全部过滤掉。遇到检测不到的情况先把--conf-thres降下来比如0.1或0.05做测试看看是不是模型确实检测到了但被阈值卡掉了。检测框偏移或者定位不准一种典型的场景是小物体检测。这时可以考虑增大--img分辨率让输入图片中目标占用的像素更多也可以考虑使用Yolov5的P2检测层需要修改模型结构代码中有注释标记自行取消注释即可。6. “功能强大不要乱用”那些年我踩过的具体坑标题里说“功能强大不要乱用”不是调侃是真的想提醒三件具体的事。第一件别在一开始就追求大模型全功能。Yolov5的代码里集成了大量实用功能——模型EMA、自动锚框计算、标签平滑、多尺度训练等这些功能全部默认开启。功能多是好事但也意味着一旦出了问题排查变量非常困难。我建议第一步跑默认配置跑通后再逐步调整、逐一验证。第二件别盲目照搬别人的训练参数。不同数据集、不同场景最优超参数差异极大。官方在COCO数据集上验证过的参数拿到你的自定义数据集上不一定奏效。我见过一个项目在工业质检场景中套用了COCO的参数mAP只有0.6经过调整后到了0.95——差距就是这么大。第三件别在生产环境里直接跑Yolov5的推理脚本做实时服务。detect.py的设计初衷是演示和验证不是给高并发服务用的。如果真的要上线建议经过torchscript或onnx转换后再结合推理框架部署。这一步属于进阶内容但至少先有个意识别等项目上线流量大了才来改架构。7. 写在最后从入门到上手的个人体会把这篇自学笔记从头写到这里回过头来看其实Yolov5的学习路径并没有那么陡峭关键是按顺序做好每一步。先把环境搭好、把官方demo跑通再准备干净的数据、仔细检查标注最后训练时耐心等待模型收敛多看看曲线图分析原因。我个人在实际操作中的体会是Yolov5的成功率高度依赖数据质量尤其不要低估标注环节的重要性。你花在数据整理和清洗上的时间最终会以模型精度的形式回报给你。模型结构、训练参数反而是相对标准化的东西即使在实践中碰到问题也有大量现成的方案可以借鉴。最后分享一个我每次跑新数据集前必做的小习惯在训练前先随机抽取20张验证图片用刚训练好的模型哪怕只训练了10个epoch跑一遍推理肉眼看看检测框的位置是否大致合理。这个习惯能帮你提前发现标注错乱、类别颠倒、数据划分异常等严重问题等到50个epoch跑完才来检查浪费了一整晚那才是最“入狱”的时刻。