做目标检测的朋友应该都清楚YOLO系列在工业界的地位而YOLOv5在很长一段时间里是绝对的主流。不管是做安防、缺陷检测还是自动驾驶感知很多项目最后都落在YOLOv5上。这篇文章我不打算复读官方文档而是从一个实际用过的角度把YOLOv5的安装、训练、调试和部署完整捋一遍包含我踩过的坑和注意事项希望能帮刚接触的人少走弯路。YOLOv5这个项目用起来其实很简单但简单的前提是你得把环境、数据格式、训练参数这几块搞明白。否则卡在安装阶段就够你受的。我见过很多人装了一天依赖最后发现是Python版本不对或者CUDA没配好。这篇文章会覆盖从环境准备到模型导出部署的全流程适合刚入门的同学也适合已经跑通过但想优化训练细节的人。1. 项目概览与环境准备1.1 YOLOv5是什么解决什么问题YOLOv5是一种基于单阶段检测思路的目标检测模型它的核心优势是速度快、精度高、部署方便。相比两阶段检测器YOLOv5只需要一次前向就能同时输出目标框和类别概率在保持较高精度的同时把推理速度拉到实时级别。对很多业务场景来说比如生产线上的零件计数、园区里的车辆行人检测、工地的安全帽佩戴检测YOLOv5可以说是第一选择。它的另一个特点是工程化做得非常好。官方仓库把训练、验证、推理、导出都封装成了命令行工具几乎不需要自己写模型代码。你只要准备好标注好的数据改一下配置文件就能训练出一个可用模型。这一点是早期YOLO版本不具备的也是YOLOv5能在社区里广泛流行的重要原因。1.2 环境要求与依赖分析先说结论YOLOv5对硬件的要求不算高但也不低。如果你只用CPU推理那基本是个电脑就能跑但训练的话强烈建议有NVIDIA显卡。显存方面以默认的YOLOv5s模型为例输入尺寸640x640batch size设为16在8GB显存上能跑但很紧张。我建议至少12GB显存如果用YOLOv5l或者更大的模型最好上24GB。操作系统方面Windows、Linux、macOS都可以但我个人推荐Ubuntu系统尤其是用Docker部署的时候。Windows也能跑只是有些编译依赖需要额外装比如pycocotools在Windows下要装预编译版本否则会编译报错。Python版本建议3.8到3.11太老或太新的版本容易出现兼容性问题。PyTorch建议使用1.12以上的稳定版我自己用的比较多的是PyTorch 1.13和2.0系列配合CUDA 11.7或12.1整体很稳。如果你装了GPU版PyTorch还需要对应的NVIDIA驱动和CUDA runtime这些装好后用nvidia-smi确认一下。1.3 获取代码与安装依赖YOLOv5的安装分三步拉代码、建虚拟环境、装依赖。我一般会先用Anaconda创建独立的虚拟环境避免把系统环境搞乱。conda create -n yolov5 python3.9 conda activate yolov5然后是拉取官方仓库代码git clone https://github.com/ultralytics/yolov5 cd yolov5接下来安装依赖。官方提供了一个requirements.txt你可以直接pip install -r requirements.txt但这里有个小坑默认的requirements.txt会把torch和torchvision也装进去。如果你已经有可用的PyTorch比如已经在其他环境里装好对应CUDA的版本建议把这两行注释掉只装其他依赖。否则pip可能会重新装一个CPU版或者不匹配的版本白白浪费下载时间。我自己习惯先手动装PyTorch再装其余依赖# 先装PyTorch选择匹配你CUDA的版本 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 再装其他依赖 pip install -r requirements.txt装完后跑一个简单的检测命令验证环境python detect.py --weights yolov5s.pt --source data/images/bus.jpg如果没有报错并且在runs/detect/exp下生成了带框的图片说明安装成功。1.4 验证安装以及常见环境坑第一次跑detect.py会自动下载yolov5s.pt权重如果网络比较慢可以手动下载放到项目根目录。另外国内网络有时候访问GitHub不稳定建议提前配置好代理或者从镜像站下载。这里不展开你自己想办法。验证过程中我最常遇到的问题是torch.cuda.is_available()返回False。遇到这种情况先别急着卸载重装按顺序排查第一NVIDIA驱动是否正常运行nvidia-smi看看能不能输出第二PyTorch是否装了CUDA版pip list | grep torch看看版本号里有没有cu标记第三如果用的是conda环境确认自己激活的是哪个Python。还有一个小细节首次运行会下载yolov5s.pt大约14MB但如果你的网络对下载域名有限制可能会卡很久。我建议下载后把权重文件放在项目根目录同时确认一下文件的扩展名是.pt不要因为浏览器自动改名变成.pt.txt这种低级错误真有人遇到过。2. 核心概念与模型结构解读2.1 从YOLOv5的模型结构看它的设计思路虽然我们只是用工具但了解模型结构能帮你在调参的时候明白每一步在做什么。YOLOv5整体分为三部分Backbone、Neck和Head。Backbone负责提取图像特征YOLOv5用的是修改过的CSPDarknet简单说就是通过跨阶段部分连接让梯度流动更高效在减少计算量的同时保持特征提取能力。Neck负责融合不同尺度的特征YOLOv5用的是PANet结构自顶向下和自底向上的路径都能把语义信息和位置信息揉在一起。Head则输出三个尺度的预测结果分别对应大目标、中目标和小目标。为什么要分三个尺度因为目标检测任务里目标大小差异很大。如果只在一个尺度上做预测小目标很容易被下采样之后的信息丢掉。YOLOv5通过不同步长的特征层让模型既能检测大目标也能捕捉小目标。理解了这一点你就知道为什么输入尺寸不能随便缩得太小否则小目标就没了。2.2 模型配置文件的作用与选择YOLOv5的模型定义不是直接写在代码里的而是通过YAML文件配置。在models/目录下有yolov5s.yaml、yolov5m.yaml、yolov5l.yaml等文件对应不同体量的模型。后缀s、m、l、x分别代表small、medium、large、xlarge递增的是网络宽度和深度也就是通道数和骨干层数。为什么官方要提供这么多配置因为在不同场景下你对速度和精度的取舍不一样。比如嵌入式设备上推理你可能会选yolov5s或者更轻的n模型如果是离线做高精度检测对速度不敏感就可以上yolov5x。选择的原则是先跑默认的yolov5s建立baseline再根据自己的设备算力和精度要求逐步尝试更大的模型。这个YAML文件里几个关键参数值得看一下nc: 80 depth_multiple: 0.33 width_multiple: 0.50 anchors: - [10,13, 16,30, 33,23] - [30,61, 62,45, 59,119] - [116,90, 156,198, 373,326]nc是类别数量一定要改成你自己的类别数。depth_multiple和width_multiple是缩放系数决定了模型的大小。anchors是预设的锚框如果你不想自己计算训练时代码会自动使用k-means重新算保持默认也行但改类别数的时候要注意锚框数量是否跟检测层匹配。2.3 预训练权重与迁移学习YOLOv5训练时强烈建议使用预训练模型。官方提供了COCO数据集上训练好的权重文件比如yolov5s.pt、yolov5m.pt。这些权重在学习新任务时是很好的起点。因为你自己的数据集通常没有COCO那么多类别直接用随机初始化的权重去训练收敛会很慢而且最终精度往往不如用预训练权重微调。使用预训练权重的原理很直观网络在COCO上已经学会了通用的边缘、纹理、形状等特征迁移到你的数据集时只需要微调高层参数去适配新的类别。这就像你请了一个在通用领域很有经验的工程师他来做新项目上手速度肯定比一个什么经验都没有的新人快。在训练命令里通过--weights yolov5s.pt指定预训练权重即可。注意如果你的数据集类别数和COCO不一致代码会自动处理最后一层输出你不用手动改权重文件。官方实现里加载权重时会调整类别输出层的维度。2.4 几个你必须清楚的训练参数YOLOv5的训练参数很多但常用的核心参数就这几个--epochs训练轮数一般等于100到300取决于数据量和任务复杂度。--batch-size批大小越大显存占用越高一般来说batch size越大梯度估计越准确但会受到显存限制。--img输入图像尺寸默认640越大越能检测小目标但速度越慢。--device指定GPU编号比如--device 0多卡用0,1。--data数据集配置文件路径后面会详细说。--hyp超参数配置默认是data/hyps/hyp.scratch-low.yaml里面包含学习率、动量、数据增强的各种设置。还要注意一个参数--cache它可以预先加载数据到内存加速训练。如果内存够大比如32GB以上加上这个参数能让每个epoch的时间明显缩短。但如果你内存不够加了反而会因为换页导致变慢甚至崩溃。3. 数据集准备与标注格式3.1 数据目录结构规范YOLOv5使用的数据集目录结构比较固定你需要按下面的方式组织your_dataset/ ├── images/ │ ├── train/ │ └── val/ └── labels/ ├── train/ └── val/其中images/train放训练图片images/val放验证图片labels目录下放对应图片的标注文件文件名要和图片名保持一致只是扩展名是.txt。比如一张img001.jpg的图片对应的标注文件就是labels/train/img001.txt。很多人习惯把数据集直接copy到YOLOv5项目里其实没必要。你完全可以用绝对路径或相对路径指向外部数据集只要在数据配置文件里写好就行。这样项目的干净度和灵活性都更高。3.2 YOLO标注格式详解YOLO的标签格式是每一行一个目标每行有五个数字class_id x_center y_center width height注意这里的x_center、y_center、width、height全部是相对于图片宽高的归一化值范围在0到1之间。比如一张宽1000像素、高800像素的图片某个目标的中心点落在(500, 400)宽为200高为160那么在标签文件中这行数据是0 0.5 0.5 0.2 0.2这里的class_id从0开始计算对应你数据集yaml中类别列表里的顺序。写标注的时候很容易出错的是归一化计算很多人直接把像素坐标写进去不归一化或者除以错误的值导致模型怎么训都不收敛。建议写完标注后先用可视化工具检查一遍。3.3 自定义数据集的yaml配置在训练之前你需要创建一个数据配置文件内容大致如下# data.yaml train: /path/to/your_dataset/images/train val: /path/to/your_dataset/images/val nc: 2 names: [person, car]这里train和val指向图片目录nc是类别数量names是类别名称列表。注意类别顺序要跟标注文件中的class_id一致。官方代码还支持把图片路径写成txt文件列表的形式但我比较推荐直接写目录路径简单明了。配置好之后验证一下数据路径是否正确。可以写个小脚本或者直接跑训练前的一句话检查。我通常会用下面这个命令看标注和图片是否匹配python train.py --data data.yaml --weights yolov5s.pt --epochs 1 --img 640 --batch-size 2跑一个epoch如果没有报错再看log里的指标曲线基本就能确认数据没问题。3.4 数据增强与标注检查的注意事项YOLOv5内置了不少数据增强策略比如Mosaic、MixUp、随机裁剪等。在训练过程中这些增强策略会自动生效你不需要额外配置但要注意一点如果数据增强过强而你的数据集本身已经很小模型可能反而欠拟合或训练不稳定。官方默认的超参数文件是不同的增强档位初学者直接使用hyp.scratch-low.yaml即可如果你对增强比较熟悉可以再尝试hyp.scratch-med.yaml或者自定义。另外一个非常关键是检查标注框的完整性。训练前务必做一次可视化检查把标注框画在图上看看有没有错位、漏标、类别标错的问题。我这里有个简单的方式用官方提供的一个小脚本思路读取图片和对应的txt用OpenCV画矩形框。批量检查几百张图片能帮你发现很多隐含问题。标注质量直接决定了模型上限这个环节省不得。4. 训练自己的模型4.1 训练命令与参数选择一切就绪后就可以开始训练了。一个典型的训练命令是python train.py \ --weights yolov5s.pt \ --data data.yaml \ --epochs 100 \ --batch-size 16 \ --img 640 \ --device 0如果你想从头训练不推荐就把--weights换成--weights 。如果你想从某个中间状态的权重继续训练可以通过--resume参数指定权重路径。训练过程会自动在runs/train/exp下生成日志和模型检查点默认每10个epoch保存一次同时保存最佳模型best.pt和最后一个模型last.pt。刚开始训练时建议先把--epochs设小一点比如50跑通整个流程确认没有问题后再加大轮数。否则一次性设300轮跑了一天发现数据路径有误那就太心痛了。4.2 训练过程监控与指标解读训练过程中终端会实时打印P、R、mAP、box loss、obj loss等信息。这几个指标怎么看PPrecision是查准率表示预测出的目标里有多少是正确目标。RRecall是查全率表示实际目标里有多少被检测到了。mAP是综合P和R的评估指标YOLOv5默认用mAP0.5和mAP0.5:0.95。box loss是边界框损失的均值越低代表框得越准。obj loss是目标置信度损失越低代表分类和定位整体越可靠。训练时观察曲线一般前10个epoch loss会快速下降之后变缓。如果box_loss和obj_loss持续下降但很平缓说明模型还在学习如果loss反弹或者震荡剧烈可能是学习率太高或batch size太小。mAP曲线在最后阶段会趋于平稳如果还没有平稳说明epoch数可能不够。4.3 调优技巧分享我自己在实际项目中总结过几个调优方向不一定适合所有场景但可以参考。第一学习率。官方默认学习率是0.01配合warm-up一般来说没问题。但如果你发现loss前期下降太慢可以稍微调高到0.02试试如果震荡降到0.005。调学习率时要把--hyp对应的yaml文件改一下比如修改lr0和lrf。第二输入尺寸。在显存允许的情况下把--img从640提高到768甚至896往往能显著提高小目标检测能力。代价是训练时间变长。我当时在检测小零件的时候把img从640改到768mAP涨了接近3个点。但要注意推理时的图片尺寸最好和训练尺寸保持一致不然会有精度损失。第三训练轮数和早停。YOLOv5自带早停机制patience默认100轮。如果你观察到mAP连续很多轮没有提升训练会提前结束这样省时间。第四类别不平衡。如果你的数据集中某些类别的样本很少可以考虑调整每个类别在损失中的权重或者在采样时做类别重加权。YOLOv5没有直接提供这个参数需要修改代码但可以在准备数据集时通过过采样或者数据增强来缓解。4.4 中断恢复与多卡训练训练途中因为电脑重启或者显存不够被kill是再正常不过的事。这时候不要慌用--resume就能接上。比如python train.py --resume runs/train/exp/weights/last.pt注意恢复训练时要保证数据和参数与之前一致代码会自己读取opt.yaml保存的配置。如果你手动改了参数可能会导致结果对不上。多卡训练也很简单python train.py --device 0,1,2,3 --batch-size 64这里batch size是总batch代码会自动分配到各卡上。个人经验多卡训练时batch size可以适当调大因为全局梯度平均后相当于更大的batch有时能提升稳定性。但要注意学习率也要相应调整可以参考线性缩放规则batch size翻一倍学习率也翻一倍。5. 模型测试与推理部署5.1 使用测试集评估模型效果训练完成后要用测试集或者验证集评估模型而不是只看训练时的mAP。因为训练时的mAP是在验证集上算的可能存在过拟合风险。如果你有单独的测试集可以这样跑python val.py --weights runs/train/exp/weights/best.pt --data data.yaml --img 640val.py会输出各类别的P、R、mAP以及一个混淆矩阵图同时在runs/val/exp下保存预测结果图。我一般重点关注难类别的mAP尤其是样本少的类别如果这些类别的AP明显偏低说明数据不够或者特征不明显需要补充数据。5.2 对图片、视频、摄像头进行推理推理是部署前最常做的事。YOLOv5的detect.py支持多种输入源例如python detect.py --weights runs/train/exp/weights/best.pt --source ./test_img.jpg python detect.py --weights runs/train/exp/weights/best.pt --source ./test_video.mp4 python detect.py --weights runs/train/exp/weights/best.pt --source 0最后一个0表示调用摄像头。--source甚至可以传入一个目录会批量推理目录下所有图片。输出结果保存在runs/detect/exp下。--conf参数可以调整置信度阈值默认0.25。如果你觉得误检太多可以调高到0.5如果漏检多可以调低到0.1。推理速度方面在GPU上YOLOv5s处理640x640的图片单张大约只要几个毫秒到几十毫秒具体看显卡型号。CPU上则慢很多可能达到几百毫秒。5.3 导出为ONNX和TensorRT训练好的模型要部署到服务或者边缘设备通常需要导出成中间格式。YOLOv5官方提供了export.py脚本支持多种导出格式python export.py --weights runs/train/exp/weights/best.pt --include onnx engine--include可以传多个格式比如onnx、engine、torchscript、openvino等。导出ONNX前需要安装onnx和onnxruntime导出TensorRT engine需要TensorRT库。这里最大的坑是版本匹配尤其是TensorRT和PyTorch的算子兼容性。如果导出失败优先检查CUDA、TensorRT、PyTorch三者版本是否匹配网上版本对应表很多对着表检查一遍基本能解决。导出ONNX后你可以用ONNX Runtime跑推理速度比PyTorch快不少而且不依赖PyTorch环境。TensorRT又比ONNX Runtime进一步提速适合高端GPU部署。我实测过YOLOv5s在T4上用TensorRT推理单张640x640的延迟能降到5毫秒以内这个性能在很多实时场景已经非常能打了。5.4 部署到边缘设备与Web服务把导出的engine文件拷到目标设备用TensorRT python API写推理逻辑或者直接用官方提供的detect.py替换权重路径也可以把它嵌入更轻量的推理框架。边缘设备比如Jetson系列同样是用TensorRT但要注意算力版本。做Web服务的话比较简单的方式是直接用Flask或FastAPI包装一个接口接收图片调用ONNX Runtime推理返回坐标和类别。响应速度主要取决于推理时间和图片解码时间把图片解码也放在GPU上会更快。还有一个容易被忽略的地方输入前要把图片resize到模型输入尺寸并且做相同的填充方式YOLOv5默认是letterbox也就是保持长宽比填充灰边。推理代码里一定要和训练时的预处理保持一致否则精度会掉。6. 常见问题与排查技巧实录6.1 安装阶段的问题安装依赖时最经典的问题是pycocotools在Windows下编译失败。解决办法是不要直接pip install pycocotools而是安装pycocotools-windows或者先安装Visual C Build Tools再重新编译。还有个常见问题是torch和torchvision版本不匹配导致无法导入。这通常是因为分别安装时版本号没对应上建议用PyTorch官网的命令一次性装好避免混装。另外git clone速度慢甚至中断可以改用镜像地址或者直接在浏览器下载压缩包解压。这个不影响后续工作只要目录结构完整就行。6.2 训练时显存不足显存不足是新手最常碰到的拦路虎。报错通常是CUDA out of memory。处理方法从轻到重有三种减小batch size、减小img尺寸、换更小的模型。比如把batch size从16降到8或者img从640降到480显存占用立刻下降。如果这些还不够就把模型从yolov5s换成yolov5n这是最轻量的版本。还有一个技巧是开启梯度累积。YOLOv5代码里没有直接给这个参数但你可以通过--batch-size很小但训练多步再更新来实现。不过最简单的还是调低配置。我一般建议在跑通流程时用最小配置等验证无误后再逐步放大。6.3 训练不收敛或精度差如果你发现loss始终不降先检查数据标注是否正确这是最常见的原因。把训练图片和标注可视化出来看一遍很多问题立刻暴露。比如框坐标归一化出错、类别ID跟names对不上、图片扩展名和标注文件不一致这些都会导致模型学不到规律。精度低还有可能是key数据太少。如果每个类别只有几十张图片数据增强再强也很难学好。我的经验是每个类别至少几百张并且要有不同角度、不同光照下的图像。另外迁移学习时预训练权重是否选对也很重要不要拿着yolov5x的权重去训你只有几百张图的小数据集那样容易过拟合反而不如山规模小一点的模型。最后一点确认训练和验证是否使用了同一个数据分布。有时候训练集是白天图像验证集是夜间图像效果当然好不了。尽量让训练集与验证集分布一致或者通过数据增强模拟多种风格。6.4 推理结果不理想推理结果不理想分两种情况。第一种是目标检测出来了但框不准这种情况往往是模型本身精度不够需要重新训练或者提高输入分辨率。第二种是漏检或误检可以先调节置信度阈值。如果还不行再看是不是测试图片跟训练场景差异太大。比如训练时用的是高空俯拍测试时用低角度仰拍模型没见过这种视角自然表现不好。另外检查预处理是否一致。我在实际项目中就遇到过训练时用letterbox填充推理代码里却直接resize导致目标拉伸变形模型精度掉了很多。确保使用同样的预处理函数这里我推荐直接复用YOLOv5仓库里的letterbox函数。还有一个容易忽略的细节类别输出顺序。当你把模型导出成ONNX或TensorRT后得到的结果是按训练时names的顺序排列的。如果你在demo代码里用另一套顺序解析那结果全乱。所以导出前确认类别表部署端跟训练端保持一致。个人经验总结一路用下来我的体会是YOLOv5确实是工程落地利器很多细节官方已经帮你处理好了但真正决定项目成败的还是数据质量和对训练机制的理解。你在上面投入的每一分精力最终都会反映在模型精度上。最后分享一个我常用的排查思路每次跑新实验前先用最小数据集、最小模型、最小epoch数验证整条链路通的再逐步增加数据量和训练规模。这样能避免很多低级错误浪费大量时间。如果你准备开始做自己的目标检测项目不妨先拿YOLOv5s配合公开数据集跑一遍流程把训练、验证、导出、推理全走通再替换成自己的数据集。这个过程走下来你基本就入门了。后续再根据硬件条件和需求探索模型剪枝、量化、知识蒸馏这些进阶方向路会越走越宽。