1. 项目概述从零上手YOLOv5最近在项目里又用到了YOLOv5虽然现在v8、v9甚至v10都出来了但v5凭借其极致的工程友好性和庞大的社区生态依然是很多快速原型验证和工业部署的首选。特别是对于刚接触目标检测的新手或者需要在有限时间内跑通一个完整流程的开发者YOLOv5的“开箱即用”特性简直是救命稻草。这篇笔记不是什么高深的研究就是把我自己从环境搭建、数据准备、训练调参到模型导出的完整流程以及中间踩过的各种坑系统地梳理一遍。目标很明确让你拿到这篇笔记就能在自己的电脑上用你自己的数据训练出一个能用的YOLOv5模型避开我走过的弯路。2. 环境搭建与项目初始化2.1 选择合适的版本与环境YOLOv5的官方仓库更新非常活跃但并不意味着你一定要用最新的版本。对于学习和稳定使用我强烈建议选择一个经过时间检验的发布版本比如v7.0。你可以通过以下命令克隆特定版本git clone -b v7.0 https://github.com/ultralytics/yolov5.git cd yolov5接下来是环境配置。官方推荐使用Python3.8和PyTorch1.8。我的经验是如果你的显卡是NVIDIA的并且想用GPU加速训练那么去PyTorch官网用它的安装命令生成器是最稳妥的。以CUDA 11.3为例pip install torch1.12.1cu113 torchvision0.13.1cu113 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113安装完PyTorch后再安装YOLOv5的其他依赖就很简单了pip install -r requirements.txt注意requirements.txt里包含opencv-python在国内网络环境下可能会安装缓慢或失败。如果遇到问题可以尝试更换pip源或者先单独安装opencv-python-headless一个更轻量的版本对于训练和推理通常够用。2.2 验证安装与简单推理环境装好后第一件事不是急着训练而是先验证基础功能是否正常。官方提供了一个预训练模型和示例图片我们可以用以下命令快速测试python detect.py --source data/images/bus.jpg --weights yolov5s.pt这条命令会从云端自动下载yolov5s.pt最小的模型权重文件并对bus.jpg这张图片进行推理。如果一切正常你会在runs/detect/exp目录下看到生成的结果图片上面画出了检测到的物体框。这个步骤至关重要它能帮你排除掉90%的环境问题比如PyTorch是否成功识别了CUDAOpenCV是否能正常读图等。如果这一步报错通常错误信息会非常明确根据提示去搜索解决即可。3. 准备自己的数据集3.1 数据标注与格式转换YOLOv5训练需要的数据格式是特定的。每一张图片对应一个同名的.txt标注文件。标注文件里每一行代表一个物体格式为class_id x_center y_center width height这里的坐标是归一化后的即x_center、y_center、width、height都是相对于图片宽度和高度的比例值范围在0到1之间。对于标注工具我推荐使用LabelImg或Roboflow。LabelImg是本地开源工具设置好格式为YOLO即可。Roboflow是在线平台功能更强大支持团队协作和数据增强对于大型项目非常友好。无论用哪种工具最终都要整理成如下目录结构your_dataset/ ├── images/ │ ├── train/ │ │ ├── image1.jpg │ │ └── image2.jpg │ └── val/ │ ├── image3.jpg │ └── image4.jpg └── labels/ ├── train/ │ ├── image1.txt │ └── image2.txt └── val/ ├── image3.txt └── image4.txttrain和val分别代表训练集和验证集这是必须的。验证集用于在训练过程中评估模型性能防止过拟合。3.2 创建数据集配置文件接下来我们需要创建一个数据集配置文件.yaml文件告诉YOLOv5我们的数据在哪里、有哪些类别。这个文件通常放在yolov5/data/目录下例如my_data.yaml# 训练和验证图像的路径可以是相对路径或绝对路径 train: ../your_dataset/images/train/ val: ../your_dataset/images/val/ # 类别数量 nc: 2 # 例如2个类别猫和狗 # 类别名称列表 names: [cat, dog]路径的写法很关键。如果使用相对路径它是相对于你启动训练命令时所在的目录通常是yolov5/根目录来计算的。我个人的习惯是把数据集放在项目根目录的同级然后用../来引用这样结构更清晰也便于版本管理工具忽略大数据集。4. 模型训练全流程解析4.1 启动训练与核心参数解读准备好数据和配置文件后就可以开始训练了。最基本的训练命令如下python train.py --img 640 --batch 16 --epochs 100 --data ./data/my_data.yaml --weights yolov5s.pt这条命令的每一个参数都至关重要--img 640输入图像的大小会被自动缩放到 640x640。更大的尺寸如1280可能提升精度但会显著增加显存消耗和训练时间。--batch 16批次大小。这是单次输入模型的图片数量。这个值的大小直接受限于你的GPU显存。如果出现“CUDA out of memory”错误首先就要降低batch大小。也可以尝试使用--batch-size参数。--epochs 100训练轮数。数据集小或简单可能50轮就收敛数据集大且复杂可能需要300轮甚至更多。观察后面提到的损失曲线来判断。--data ./data/my_data.yaml指定上一步创建的数据集配置文件路径。--weights yolov5s.pt指定预训练权重。强烈建议使用预训练权重这能让你从模型在COCO大数据集上学到的通用特征开始实现更快的收敛和更好的最终精度。除了yolov5s.pt还有yolov5m.ptyolov5l.ptyolov5x.pt模型越大精度通常越高但速度越慢。训练开始后控制台会输出每一轮epoch的训练损失和验证指标。更重要的是YOLOv5会在runs/train/exp每次训练会自动递增如exp2exp3目录下生成一系列非常重要的可视化结果。4.2 训练过程监控与结果分析在runs/train/exp目录下你会找到几个关键文件它们是诊断模型训练状态的“仪表盘”results.png或results.csv这是最重要的图表。它包含了训练和验证集上的边界框损失、分类损失、目标性损失以及精度precision、召回率recall、mAP0.5、mAP0.5:0.95等指标随训练轮数的变化曲线。看损失训练损失和验证损失都应该随着轮数增加而平稳下降并最终趋于平缓。如果验证损失在中后期开始上升而训练损失持续下降这是典型的过拟合现象。看mAPmAP平均精度均值是核心评估指标。mAP0.5是交并比IoU阈值为0.5时的mAPmAP0.5:0.95是在多个IoU阈值从0.5到0.95步长0.05上的平均值后者更严格。我们希望看到这两个值随着训练轮数增加而上升。confusion_matrix.png混淆矩阵。可以清晰地看到模型最容易混淆哪些类别。比如“猫”和“狗”如果有不少相互误检说明这两个类别在特征上可能比较接近需要检查数据标注质量或者考虑增加更多有区分度的样本。val_batchX_labels.jpg和val_batchX_pred.jpg分别展示了验证批次图片的真实标签和模型预测结果。直观对比可以快速发现模型在哪里漏检False Negative或误检False Positive。实操心得不要一上来就训练几百轮然后干等。我通常先设置一个较小的轮数如--epochs 20用最快的速度跑一遍看看损失曲线是否正常下降mAP是否有上升趋势。如果曲线异常例如损失为NaN或剧烈震荡说明学习率、数据或模型可能有问题需要及时中断调整。确认流程无误后再放开轮数进行完整训练。5. 超参数调优与模型选择5.1 理解与调整关键超参数YOLOv5的超参数配置文件位于data/hyps/hyp.scratch-low.yaml默认或hyp.scratch-high.yaml等。我们可以在训练时通过--hyp参数指定。对于初学者我建议先使用默认超参数等有了baseline后再尝试微调。几个最关键的超参数是学习率lr0这是最重要的超参数。太大容易震荡甚至发散太小则收敛缓慢。YOLOv5默认使用了带热身的余弦退火学习率调度器已经比较鲁棒。如果你发现训练初期损失下降极慢可以尝试适当增大lr0例如从0.01调到0.1如果训练不稳定损失出现NaN则需减小lr0。动量momentum和权重衰减weight_decay这两个是优化器SGD的参数用于加速收敛和防止过拟合。通常保持默认值即可除非你非常清楚自己在做什么。数据增强参数在hyp文件的augment部分。例如hsv_hhsv_shsv_v控制色相、饱和度、明度的抖动幅度degrees控制旋转角度。适度的数据增强可以显著提升模型泛化能力防止过拟合。但如果你的数据集本身质量不高或场景特殊过强的增强如大角度旋转可能会引入噪声反而有害。对于工业检测中方向固定的零件我会大幅降低甚至关闭旋转增强。5.2 模型尺寸选择策略YOLOv5提供了S、M、L、X四个尺寸的模型它们的深度和宽度逐级增加。YOLOv5s最小最快适合移动端或边缘设备如RK3568在资源受限场景下部署。精度相对较低。YOLOv5m精度和速度的平衡点是我最常使用的版本适用于大多数对实时性有要求的服务器或PC端应用。YOLOv5l / YOLOv5x更大更慢精度最高。适合对精度要求极端苛刻且不计较推理速度和模型大小的场景比如一些离线分析任务。选择策略很简单从yolov5s.pt开始。如果它的精度mAP达不到你的应用要求再换用yolov5m.pt重新训练。通常换用更大的模型是提升精度最直接有效的方法远比你花大量时间调参来得快。6. 模型导出与部署前验证6.1 模型格式导出训练完成后最好的模型权重会保存在runs/train/exp/weights/best.pt。这个.pt文件是PyTorch格式包含了模型架构和训练好的参数。为了在不同平台部署我们需要将其导出为其他格式。最常用的导出命令是转为ONNX格式python export.py --weights runs/train/exp/weights/best.pt --include onnxONNX是一种开放的模型交换格式可以被TensorRT OpenVINO ONNX Runtime等多种推理引擎支持。导出时你可以通过--img-size指定输入尺寸通过--batch-size指定动态或静态批次。例如--batch-size 1会导出静态批次为1的模型有利于某些推理引擎的优化。注意导出ONNX时务必用训练时相同的--img-size否则输入输出维度可能不匹配。导出后建议使用netron工具一个网页应用打开生成的.onnx文件可视化检查模型输入输出节点是否正确。6.2 部署前完整性验证导出的模型绝对不能直接拿去部署必须进行严格的验证。YOLOv5的export.py脚本在导出后会自动运行一次验证但这还不够。你应该手动使用导出的模型对一组新的、未参与训练和验证的图片进行推理测试。python detect.py --weights runs/train/exp/weights/best.onnx --source path/to/test_images --img-size 640对比使用原始.pt权重和导出后的.onnx权重推理的结果。理想情况下两者的检测框和置信度应该几乎完全一致。如果发现差异巨大可能是导出过程出了问题需要检查PyTorch和ONNX版本兼容性或者回顾训练时是否有特殊的预处理/后处理操作没有在导出中体现。7. 疑难杂症排查与实战技巧7.1 训练MAP总是0的深度排查这是新手遇到最多也最头疼的问题。如果训练了很久mAP始终为0请按以下顺序排查检查数据标注这是最常见的原因。首先用代码或可视化工具如labelImg再次打开检查你的.txt标注文件。确认class_id是从0开始连续编号的并且与my_data.yaml中的names列表顺序一致。确认坐标值是否真的在0-1之间。一个快速检查脚本import os label_path ‘your_label.txt’ with open(label_path ‘r’) as f: for line in f: cls xc yc w h map(float line.strip().split()) if not (0 xc 1 and 0 yc 1 and 0 w 1 and 0 h 1): print(f“异常坐标: {cls} {xc} {yc} {w} {h}“)检查数据集配置文件路径确保my_data.yaml中的train:和val:路径绝对正确。一个笨但有效的方法是使用Python的os.path.exists()函数在训练脚本里打印一下路径看是否能找到图片。检查数据集划分确保训练集和验证集没有重叠。如果验证集图片和训练集一模一样可能会导致评估指标计算异常。检查类别不平衡如果你的某个类别样本数极少比如只有几个模型可能很难学到其特征导致对该类别的AP为0。此时需要收集更多数据或使用数据增强、类别权重等技术。降低学习率过高的学习率可能导致模型在训练初期就“跑飞”无法学到有效特征。尝试将--hyp指定为hyp.scratch-low.yaml其学习率更低或者直接在命令中指定一个极小的学习率试试。从预训练权重开始确保你使用了--weights yolov5s.pt这样的参数。从零开始训练scratch需要精心设计超参数和大量数据对新手不友好。7.2 在RK3568等边缘设备上的部署考量如果你计划在像RK3568这样的ARM架构边缘计算设备上部署YOLOv5那么从训练阶段就要开始规划模型选型毫不犹豫地选择YOLOv5s甚至可以考虑后续对其进行剪枝、量化来进一步压缩模型。输入尺寸训练时就用--img 320或--img 416而不是640。更小的输入尺寸能极大减少边缘设备上的计算量和内存占用。导出为RKNN格式瑞芯微提供了RKNN-Toolkit2工具链可以将ONNX模型转换和量化为其NPU专用的RKNN格式。这个过程通常涉及在x86开发机上安装RKNN-Toolkit2。准备一个代表数据集几十张图片即可用于量化校准。执行转换命令生成.rknn文件。将.rknn文件部署到RK3568上使用C或Python的RKNN API进行推理。性能调优在边缘设备上需要关注NPU利用率、内存占用和推理帧率FPS。可能需要在精度和速度之间做权衡比如使用更低精度的量化int8而非float16。7.3 其他常见问题速查表问题现象可能原因排查与解决思路CUDA out of memory批次太大或图像尺寸太大减小--batch-size 减小--img-size。也可尝试使用--workers 0关闭数据加载的多进程有时能减少一些显存开销。训练损失为NaN学习率过高数据中有损坏的图片或标注梯度爆炸大幅降低学习率。检查数据集中是否有损坏的JPEG文件可以用PIL.Image.open()尝试打开所有图片。在train.py中尝试添加梯度裁剪--gradient-clipping。推理时检测框混乱训练时和推理时图片预处理不一致确保训练和推理使用了相同的--img-size。检查训练时是否启用了特殊的数据增强如mosaic在推理时这些增强是关闭的通常没问题但自定义预处理需保持一致。某个类别检测效果极差该类别样本数量不足或质量差分析混淆矩阵为该类别收集更多样化、更高质量的样本。尝试使用焦点损失Focal Loss相关的超参数调整在hyp文件中减轻类别不平衡的影响。导出ONNX失败PyTorch版本与ONNX opset版本不兼容模型中有不支持的操作尝试固定ONNX opset版本如--opset 12。检查模型中是否包含动态控制流如if-elseYOLOv5默认模型是静态的一般没问题。简化模型结构后重试。训练一个高质量的模型数据质量占7成模型选择和调参占3成。不要把全部希望寄托在魔改模型或调整超参数上回头花时间清洗和丰富你的数据集往往能获得最大的回报。另外养成随时保存训练结果runs/train/exp目录和记录实验日志的习惯每次调整超参数或数据后都新建一个实验文件夹这样你才能清晰地知道什么改变带来了什么影响。YOLOv5是一个强大的工具但把它用好的关键还是在于使用者的耐心、细致的观察和系统性的实验方法。