YOLOv5 使用指南：从环境搭建到推理与训练

一、YOLOv5 简介

YOLOv5 是 Ultralytics 开源的目标检测框架，基于 PyTorch 实现。它并不是 YOLO 系列的第五个官方版本，而是由 Ultralytics 团队在 YOLOv3 基础上持续迭代的工程化实现。相比早期版本，YOLOv5 的优势主要体现在三点：

• 工程化完善：数据准备、训练、验证、推理、导出全流程脚本齐备，开箱即用。
• 性能均衡：提供 n、s、m、l、x 五种规模，参数量从约 1.9M 到 86M，可按算力灵活选择。
• 生态成熟：支持 ONNX、TensorRT、OpenVINO、CoreML 等多种部署格式，社区文档和问题解答丰富。

本文按照「环境搭建 → 数据准备 → 推理 → 训练 → 导出部署」的顺序，完整走一遍 YOLOv5 的使用流程。

二、环境搭建

2.1 基础依赖

建议使用 Python 3.8 及以上版本，并准备一块可用的 NVIDIA 显卡（CPU 也能跑，但训练速度会慢很多）。先确认 CUDA 与 PyTorch 版本匹配：

nvidia-smi
python –version

2.2 克隆仓库并安装依赖

git clone https://github.com/ultralytics/yolov5.git
cd yolov5
pip install -r requirements.txt

如果使用 GPU，请先按 PyTorch 官网 的指引安装对应 CUDA 版本的 torch，再执行上面的依赖安装，避免 pip 自动装成 CPU 版本。

2.3 验证安装

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

输出中 True 表示 GPU 可用。随后运行一次官方推理脚本，若能正常输出检测结果，说明环境就绪。

三、快速推理

3.1 命令行推理

YOLOv5 提供了 detect.py 脚本，加载官方预训练权重即可直接检测：

python detect.py –weights yolov5s.pt –source data/images –img-size 640 –conf-thres 0.25

常用参数说明：

结果默认保存在 runs/detect/exp 目录下。

3.2 Python 代码调用

在业务代码中更常用的是直接调用模型接口：

import torch
加载模型（首次运行会自动下载权重）
model = torch.hub.load('ultralytics/yolov5', 'yolov5s', pretrained=True)
设置推理参数
model.conf = 0.25
model.iou = 0.45
推理
results = model('data/images/bus.jpg')
打印结果并保存可视化图片
results.print()
results.save('runs/detect/custom')
获取结构化结果：xmin, ymin, xmax, ymax, confidence, class, name
df = results.pandas().xyxy[0]
print(df)

如果不想依赖 torch.hub 在线拉取，也可以在本地仓库目录下使用：

import sys
sys.path.append('/path/to/yolov5')
import torch
from models.common import DetectMultiBackend
device = torch.device('cuda:0' if torch.cuda.is_available() else 'cpu')
model = DetectMultiBackend('yolov5s.pt', device=device)

四、准备自定义数据集

4.1 数据标注

YOLOv5 使用 YOLO 格式标注：每张图片对应一个同名 .txt 文件，每行表示一个目标，格式为：

class_id x_center y_center width height

其中坐标均为相对图片宽高的归一化值，取值范围 0 到 1。推荐使用 LabelImg、Label Studio 或 Roboflow 进行标注，导出时选择 YOLO 格式。

4.2 目录结构

dataset/
├── images/
│ ├── train/
│ └── val/
└── labels/
├── train/
└── val/

注意 images 与 labels 下的子目录名必须一一对应，图片与标签文件名保持一致（仅扩展名不同）。

4.3 编写数据配置文件

在 data/ 目录下新建 mydata.yaml：

path: ../dataset
train: images/train
val: images/val
nc: 3
names: ['person', 'car', 'dog']

nc 为类别数，names 的顺序必须与标注文件中的 class_id 严格对应。

五、模型训练

5.1 从预训练权重开始训练

python train.py \\
–img 640 \\
–batch 16 \\
–epochs 100 \\
–data data/mydata.yaml \\
–weights yolov5s.pt \\
–device 0

关键参数说明：

• –img：训练分辨率，显存不足时可降到 416 或 320。
• –batch：批大小，显存不足时优先调小该值。
• –weights：强烈建议加载预训练权重，收敛速度和精度都明显优于从零训练。
• –hyp：超参数文件，默认 data/hyps/hyp.scratch-low.yaml。

5.2 训练过程监控

训练日志和权重保存在 runs/train/exp 目录，其中 results.png 汇总了损失曲线和 mAP 曲线。也可以启动 TensorBoard 实时查看：

tensorboard –logdir runs/train

重点关注 mAP@0.5 与 mAP@0.5:0.95 两个指标，以及验证集损失是否出现反弹（过拟合信号）。

5.3 断点续训

python train.py –resume runs/train/exp/weights/last.pt

六、模型验证与推理

6.1 在验证集上评估

python val.py –weights runs/train/exp/weights/best.pt –data data/mydata.yaml –img 640

输出会给出每一类的 Precision、Recall、mAP@0.5 和 mAP@0.5:0.95，可据此判断哪一类效果较差，再针对性补充数据。

6.2 用自训练模型推理

python detect.py –weights runs/train/exp/weights/best.pt –source test_images –img 640 –conf-thres 0.3

七、模型导出与部署

YOLOv5 内置 export.py，可将模型导出为多种推理格式：

# 导出 ONNX
python export.py –weights best.pt –include onnx –img 640
导出 TensorRT（需要 GPU 与 TensorRT 环境）
python export.py –weights best.pt –include engine –img 640 –device 0
导出 OpenVINO
python export.py –weights best.pt –include openvino –img 640

导出后可用 ONNX Runtime 做轻量推理：

import onnxruntime as ort
import numpy as np
session = ort.InferenceSession('best.onnx', providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
input_name = session.get_inputs()[0].name
输入需为 NCHW、归一化到 0-1 的 float32 数组
blob = np.random.rand(1, 3, 640, 640).astype(np.float32)
outputs = session.run(None, {input_name: blob})
print([o.shape for o in outputs])

注意导出后的模型输出仍是原始预测张量，需要自行实现 NMS 后处理，或直接使用 Ultralytics 提供的推理封装。

八、常见问题与调优建议

• 显存不足（CUDA out of memory）：依次尝试减小 –batch、降低 –img、改用更小的模型（yolov5n / yolov5s）。
• 训练不收敛：检查标注文件路径与类别 id 是否正确，确认 nc 与 names 数量一致，并确保加载了预训练权重。
• 漏检严重：适当降低 –conf-thres，或补充小目标、遮挡场景的训练样本。
• 误检过多：提高置信度阈值，检查是否存在标注错误或类别混淆。
• 推理速度慢：导出 TensorRT 或 ONNX 并使用 FP16 推理，通常可获得数倍加速。

九、小结

YOLOv5 的使用可以概括为一条清晰的流水线：安装依赖并验证 GPU 环境，用 detect.py 跑通官方权重建立信心，按 YOLO 格式整理自定义数据集并编写 yaml 配置，加载预训练权重开始训练，最后通过 val.py 评估、export.py 导出部署。掌握这条链路后，迁移到其他检测任务基本只需要替换数据集和调整超参数。