YOLOv5实战指南：从零跑通推理、训练到ONNX导出全链路

简介这份资源是YOLOv5目标检测的完整源码包面向计算机视觉方向的研究人员、深度学习开发者及希望上手目标检测实践的学生。包内共121个文件以34个Python脚本、45个YAML配置、13张JPG与6张PNG示例图为主另含4个预训练权重文件、5个Shell脚本及Dockerfile等压缩包约114.05MB。代码结构清晰models文件夹定义了小、中、大型网络架构data与cfg提供数据集和超参数配置train.py与test.py覆盖训练和推理流程utils汇集指标计算、可视化等辅助函数requirements.txt便于快速搭建环境。已有1165人学习下载。借助这份源码读者可理解Darknet主干与检测头的设计思路掌握数据增强、模型训练与预测的完整链路并基于预训练权重在自有数据上迁移实验是入门与进阶目标检测的实用起点。1. 拿到 yolov5-master (1).zip 之后先别急着训练把这条链路跑通很多人拿到yolov5-master (1).zip的第一反应是解压、装依赖、train.py一把梭结果卡在环境、卡在数据格式、卡在显存三天过去连一张推理图都没出来。这个压缩包本质上是 YOLOv5 的完整工程目录里面包含模型定义、训练脚本、推理脚本、数据配置模板和导出工具它解决的是「从零搭一套目标检测流水线」的问题而不是一个开箱即用的成品模型。适合谁适合手上有标注数据、想快速验证检测方案可行性的算法工程师也适合刚入门想搞懂检测工程全貌的学生。我一般会先把「推理 → 训练 → 导出」这条最小链路跑通再回头调参这样每一步都有反馈不会陷入玄学调参的黑匣子里。这一章先讲清楚这个包的结构和它到底能干什么后面几章再拆开揉碎讲每一步怎么落地。2. 解压后的目录结构与最小推理链路用一张图验证环境是否真的通了2.1 目录里到底有什么哪些文件是必须动的解压yolov5-master (1).zip后你会看到一个典型的工程目录。核心目录和文件大致如下不同版本略有差异但主干一致路径作用是否需要改models/模型结构 yaml 与公共模块一般不改data/数据集配置 yaml 与示例图片必须改utils/数据加载、指标、通用工具一般不改train.py训练入口按需传参detect.py推理入口按需传参export.py模型导出按需传参requirements.txt依赖清单必须装hubconf.py供 torch.hub 调用不改真正需要你动手的只有三处依赖环境、数据配置、训练/推理参数。其余代码是工程骨架除非你要改网络结构否则不要动。很多人一上来就改utils/里的代码改完报错又找不到原因这是典型的翻车起点。2.2 环境安装用 conda 隔离别污染主环境我一般用 conda 建一个独立环境Python 版本选 3.8 到 3.10 之间太新或太旧都容易在 torch 版本上踩坑。# 创建独立环境避免和主环境冲突 conda create -n yolov5_env python3.9 -y conda activate yolov5_env # 安装 PyTorch具体 CUDA 版本按你显卡驱动来选 # 这里以 CUDA 11.8 为例驱动版本不够就降级 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 安装工程依赖 cd yolov5-master pip install -r requirements.txt逻辑说明先隔离环境是为了避免不同项目间的 torch 版本打架这是血泪经验。requirements.txt里通常包含numpy、opencv-python、pyyaml、tqdm、matplotlib等安装过程中如果某个包编译失败优先检查是不是缺系统级依赖比如libGL。参数说明--index-url指定 PyTorch 官方源国内网络环境可以换成镜像源但要注意镜像源里 torch 版本是否齐全。2.3 用官方权重跑通第一张推理图环境装好后不要急着训练先用官方预训练权重跑一张推理图验证整条链路是否通畅。# 推理单张图片--weights 指定权重--source 指定输入 python detect.py --weights yolov5s.pt --source data/images/bus.jpg --device 0 # 如果想用 CPU 跑把 --device 改成 cpu python detect.py --weights yolov5s.pt --source data/images/bus.jpg --device cpu逻辑说明detect.py会自动下载yolov5s.pt如果本地没有然后对bus.jpg做推理结果默认保存在runs/detect/exp/下。参数说明--weights可以是官方权重也可以是你自己训练出来的best.pt--source支持单图、目录、视频、摄像头填0--device填0表示第一块 GPU填cpu表示用 CPU。如果这一步报错八成是 torch 没装好或者 CUDA 版本不匹配先解决环境问题再往下走。提示第一次运行会自动下载权重如果网络不通可以手动下载后放到工程根目录再用--weights指向本地文件。3. 数据准备与训练配置把标注数据喂给 YOLOv5 的正确姿势3.1 数据格式YOLO 格式的标注文件长什么样YOLOv5 只认 YOLO 格式的标注每张图片对应一个同名.txt文件每行表示一个目标格式为class_id x_center y_center width height其中坐标都是归一化到 0 到 1 之间的浮点数。举个例子一张 640x480 的图里有一个类别为 0 的目标框在左上角 (100, 80) 到 (300, 240)那么0 0.3125 0.3333 0.3125 0.3333计算方式x_center (100300)/2/640 0.3125y_center (80240)/2/480 0.3333width (300-100)/640 0.3125height (240-80)/480 0.3333。如果你手上是 VOC 的 XML 或 COCO 的 JSON需要先转换转换脚本网上很多但要注意类别映射和坐标越界问题。3.2 数据集配置文件一个 yaml 决定训练读什么在data/下新建一个mydata.yaml内容如下# 训练集和验证集的路径可以是绝对路径或相对路径 train: ../datasets/mydata/images/train val: ../datasets/mydata/images/val # 类别数 nc: 3 # 类别名称顺序要和标注里的 class_id 对应 names: [cat, dog, person]逻辑说明train和val指向图片目录YOLOv5 会自动去找同名的.txt标注文件。nc是类别数names是类别名列表顺序不能错否则训练出来的模型会把猫认成狗。参数说明路径可以用相对路径但相对的是你执行train.py时的工作目录建议用绝对路径避免歧义。3.3 启动训练关键参数怎么设# 从预训练权重开始训练--data 指定数据配置--weights 指定初始权重 python train.py --data data/mydata.yaml --weights yolov5s.pt --img 640 --batch 16 --epochs 100 --device 0 # 如果显存不够减小 batch 或 img python train.py --data data/mydata.yaml --weights yolov5s.pt --img 416 --batch 8 --device 0逻辑说明--weights yolov5s.pt表示从预训练权重开始微调这比从零训练收敛快得多也是我一般会推荐的做法。--img是输入分辨率越大精度越高但显存占用也越大。--batch是批大小显存不够就往下调。--epochs是训练轮数小数据集 100 到 300 轮通常够用。参数说明--device可以指定多卡比如0,1但要注意 batch 要相应调整。训练日志和权重默认保存在runs/train/exp/下best.pt是验证集上表现最好的权重last.pt是最后一轮的权重。注意训练前务必检查标注文件里有没有空文件或坐标越界否则训练过程中会出现 loss 为 nan 的情况排查起来很费时间。4. 避坑与排查那些让训练翻车的细节4.1 显存爆炸现象是 CUDA out of memory原因是 batch 或 img 太大现象训练刚开始就报RuntimeError: CUDA out of memory。原因--batch或--img设置过大超出了显卡显存。解决先把--batch降到 8 或 4再把--img降到 416 或 320跑通后再逐步往上加。如果还是不够可以用--accumulate做梯度累积模拟大 batch 的效果。4.2 loss 不下降现象是 loss 震荡或保持高位原因是学习率或数据有问题现象训练几十轮后 loss 几乎不变或者剧烈震荡。原因学习率太大、标注质量差、类别不平衡。解决先用小学习率比如--lr0 0.001试跑检查标注文件里有没有漏标或错标类别不平衡可以通过--weights加权或过采样少数类来缓解。4.3 推理结果全是同一类现象是检测框都标成同一个类别原因是类别映射错位现象推理时所有目标都被识别成同一个类别。原因mydata.yaml里的names顺序和标注文件里的class_id不对应。解决重新核对标注生成时的类别映射表确保names列表的顺序和生成标注时用的顺序完全一致。4.4 训练中断后无法恢复现象是想接着上次训练但报错原因是权重和优化器状态不匹配现象用--resume恢复训练时报错。原因last.pt里保存的优化器状态和当前代码或配置不兼容。解决如果只是想做微调直接用--weights last.pt重新开始训练不要用--resume如果一定要恢复确保代码版本和训练时完全一致。4.5 验证集指标虚高现象是 mAP 很高但实际推理效果差原因是验证集和训练集分布太接近现象验证集 mAP 到 0.9 以上但拿新图片推理效果很差。原因训练集和验证集来自同一批数据分布太相似模型过拟合。解决重新划分数据集确保验证集里的场景、光照、角度和训练集有差异或者用交叉验证的方式评估。5. 模型导出与部署验证从 best.pt 到可落地的推理格式5.1 导出 ONNX跨平台部署的第一步# 导出 ONNX 格式--weights 指定训练好的权重 python export.py --weights runs/train/exp/weights/best.pt --include onnx --img 640 --batch 1 # 导出时指定 opset 版本兼容性更好 python export.py --weights runs/train/exp/weights/best.pt --include onnx --opset 12逻辑说明export.py会把 PyTorch 模型转成 ONNX 格式方便在 TensorRT、OpenVINO 或其他推理引擎里加载。--include指定导出格式--opset指定 ONNX 算子集版本版本太高可能不被某些推理引擎支持。参数说明--img要和训练时的分辨率一致--batch一般设为 1 用于推理。5.2 导出后的验证用 onnxruntime 跑一遍import onnxruntime as ort import numpy as np import cv2 # 加载 ONNX 模型 session ort.InferenceSession(best.onnx) # 预处理图片注意要和训练时的预处理一致 img cv2.imread(test.jpg) img cv2.resize(img, (640, 640)) img img[:, :, ::-1].transpose(2, 0, 1) # BGR 转 RGBHWC 转 CHW img np.expand_dims(img, axis0).astype(np.float32) / 255.0 # 推理 outputs session.run(None, {session.get_inputs()[0].name: img}) print(outputs[0].shape) # 输出形状通常是 [1, 25200, 5nc]逻辑说明这段代码用 onnxruntime 加载导出的模型做一次前向推理验证输出形状是否符合预期。参数说明预处理要和训练时保持一致特别是归一化和通道顺序否则结果会完全不对。输出形状里的 25200 是候选框数量5nc是框坐标、置信度和类别概率。5.3 一个容易被忽略的技巧用 TTA 提升小目标检测效果在推理阶段可以对同一张图做多次不同尺度的变换再把结果融合这叫 TTATest Time Augmentation。YOLOv5 的detect.py里可以通过--augment开启python detect.py --weights best.pt --source test.jpg --augment逻辑说明--augment会对输入做翻转、缩放等变换然后对多次推理结果做 NMS 融合通常能提升 1 到 3 个点的 mAP代价是推理速度变慢。参数说明这个参数适合对精度要求高、对速度不敏感的场景实时检测不建议开。我自己的习惯是每次训练完先导出 ONNX用 onnxruntime 跑一遍验证输出形状和数值范围确认无误后再上生产环境。这一步能提前发现很多导出时的算子兼容问题比上线后报错再回头查要省事得多。希望帮到你。本文还有配套的精品资源点击获取