ultralytics/yolov5 · 上手攻略

• 仓库：ultralytics/yolov5
• 链接：https://github.com/ultralytics/yolov5
• 分类：ai · computer-vision · object-detection
• 作者：Tom
• 更新：2026-07-22

它是什么

Ultralytics YOLOv5 是 YOLO（You Only Look Once）目标检测算法的第五代官方 PyTorch 实现，由 Ultralytics 公司维护。它在原始 YOLOv4 的基础上完全重写，以「极致简洁」为设计核心，集目标检测、实例分割、图像分类三大任务于一体，并在 v7.0（2022年）引入了实时实例分割模型，成为当时全球最快最准确的分割模型。

注意：Ultralytics 后续又发布了 YOLOv8、YOLO11、YOLO26 等更新版本。YOLOv5 本身已不再是最先进模型，但它成熟、稳定、社区庞大、资料极多，在工业界仍有大量部署。若你需要最新架构和统一 CLI，推荐迁移到 ultralytics 包（pip install ultralytics）。

解决什么问题

• 实时目标检测：在 GPU 上以毫秒级速度对图片/视频进行多目标检测（COCO 数据集 80 类）。
• 实例分割：在检测基础上进一步输出像素级掩码（mask），区分同类别不同个体。
• 图像分类：基于预训练 backbone 做整图分类。
• 模型导出部署：一键导出为 ONNX、TensorRT、CoreML、TFLite、OpenVINO、PaddlePaddle 等格式，服务端/边缘端均可部署。
• 自定义数据训练：用自己标注的数据集微调预训练权重。

快速安装

方式一：直接用 pip（推荐，无需 clone）

pip install -U ultralytics

⚠️ 注意：ultralytics 包（新版统一包）包含了 YOLOv5 及更新的 YOLOv8/YOLO11 等多个模型。安装后 import 会默认加载最新模型。需明确指定路径或版本时再看下方方式二。

方式二：Clone 仓库（使用 YOLOv5 专属脚本）

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

环境要求： - Python ≥ 3.8 - PyTorch ≥ 1.8（建议 PyTorch 2.x 以获得更好性能） - CUDA ≥ 11.2（如需 GPU 推理）

硬件推荐： - 推理：消费级 GPU（如 RTX 3060）即可实时处理视频；纯 CPU 也能跑（小模型）。 - 训练：从零训练 COCO 需要 V100×8 约 1-8 天；仅微调自定义数据通常几小时。

核心用法

推理（PyTorch Hub，无需 clone）

import torch

# 加载预训练模型（自动从 GitHub Release 下载权重）
# 可选: yolov5n / yolov5s / yolov5m / yolov5l / yolov5x
model = torch.hub.load("ultralytics/yolov5", "yolov5s")

# 推理（支持 URL、本地图片路径、PIL Image、numpy array、视频路径等）
results = model("https://ultralytics.com/images/zidane.jpg")

# 输出结果
results.print()       # 打印到控制台
results.show()        # 显示图像窗口
results.save()        # 保存到 runs/detect/exp/
results.pandas()      # 返回 pandas DataFrame 格式坐标

自定义模型路径（加载本地或导出的模型）：

model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.pt")              # PyTorch
model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.onnx")             # ONNX
model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.engine")           # TensorRT
model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s_openvino_model/") # OpenVINO

detect.py 推理脚本（支持更多数据源）

# 图片
python detect.py --weights yolov5s.pt --source img.jpg

# 文件夹
python detect.py --weights yolov5s.pt --source path/to/images/

# 摄像头（0 = 默认摄像头）
python detect.py --weights yolov5s.pt --source 0

# 视频文件
python detect.py --weights yolov5s.pt --source vid.mp4

# YouTube 视频
python detect.py --weights yolov5s.pt --source 'https://youtu.be/LNwODJXcvt4'

# RTSP 流
python detect.py --weights yolov5s.pt --source 'rtsp://example.com/media.mp4'

训练（自定义数据集）

第一步：准备数据——按 YOLO 格式标注，目录结构如下：

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

每个 label 文件为纯文本，每行：class_id x_center y_center width height（归一化到 0-1）。

第二步：编写数据配置 my_data.yaml：

path: ./dataset          # 数据根目录
train: images/train
val: images/val

# COCO 80 类或你自己的类别列表
names:
  0: person
  1: bicycle
  # ...

第三步：启动训练：

# 从预训练权重微调（推荐，速度快、精度好）
python train.py --data my_data.yaml --epochs 100 --weights yolov5s.pt --img 640

# 从头训练（需要更多数据和时间）
python train.py --data my_data.yaml --epochs 300 --weights '' --cfg yolov5s.yaml --img 640

高级训练参数：

# 多 GPU 分布式训练（DDDP）
python -m torch.distributed.run --nproc_per_node 4 train.py \
  --data my_data.yaml --epochs 100 --weights yolov5s.pt --device 0,1,2,3

# AutoBatch（自动选择最大 batch size，V100-16GB 上 yolov5s 约 batch 128）
python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov5s.yaml --batch -1

# 启用 Mosaic 数据增强（默认开启，提升泛化）
python train.py --data my_data.yaml --epochs 100 --weights yolov5s.pt --img 640

# 冻结 backbone 主干网络，仅训练头部（适合数据少的情况）
python train.py --data my_data.yaml --epochs 100 --weights yolov5s.pt --freeze 10

验证/测试

# 在 COCO val2017 上验证精度
python val.py --data coco.yaml --weights yolov5s.pt --img 640

# 测速（不含 NMS）
python val.py --data coco.yaml --task speed --batch 1 --weights yolov5s.pt

# 完整评测（含 mAP 曲线）
python val.py --data coco.yaml --weights yolov5s.pt --task study

模型导出

# 导出为多种格式
python export.py --weights yolov5s.pt --include onnx engine tflite coreml

# 指定输入尺寸
python export.py --weights yolov5s.pt --include onnx --img 640

# TensorRT FP16 加速（需已安装 tensorrt）
python export.py --weights yolov5s.pt --include engine --device 0 --half

实例分割（v7.0+）

# PyTorch Hub 加载分割模型（WARNING: 推理暂不支持，需用 predict.py）
model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s-seg.pt")

# 训练分割模型
python segment/train.py --data coco128-seg.yaml --weights yolov5s-seg.pt --epochs 5 --img 640

# 推理
python segment/predict.py --weights yolov5m-seg.pt --source bus.jpg

# 导出
python export.py --weights yolov5s-seg.pt --include onnx engine --img 640

模型规格速查

¹ mAPval 50-95，衡量标准：COCO val2017，batch=1，无 TTA。数据来源：YOLOv5 README。

典型适用场景

坑与注意

⚠️ 版本坑

1. 最新 ultralytics 包 ≠ YOLOv5：2023 年后 Ultralytics 将所有 YOLO 模型统一到 ultralytics 一个包里。pip install ultralytics 默认加载 YOLOv8。想要 YOLOv5 特定行为（独立脚本、数据格式、参数）需 clone 仓库或明确指定版本/路径。
2. v7.0 分割模型 PyTorch Hub 推理未完全支持：README 明确标注 WARNING: inference not yet supported via PyTorch Hub；请用 segment/predict.py。

⚠️ 训练坑

3. 类别 id 从 0 开始：YOLO 格式要求 class_id 必须从 0 开始连续编号，不能跳过或从 1 开始。
4. 标注坐标归一化：标注文件中的 x_center y_center width height 必须归一化到 [0,1]，不是像素值。
5. batch size 内存爆炸：V100-16GB 上，yolov5x 的 --batch-size 16 是上限，yolov5s 可到 64。设 --batch -1 开启 AutoBatch 自动选择。
6. Windows 路径分隔符：数据配置 YAML 中 path 使用 / 正斜杠，Windows 用户需注意或改用绝对路径。
7. 多 GPU 训练 port 冲突：DDP 多机训练时需指定不同 --master_port。

⚠️ 推理坑

8. NMS 后处理约 1ms/image：评测速度时通常不包含 NMS，实际部署流水线需计入。
9. 模型下载缓存位置：~/.cache/torch/hub/。下载失败时删除该目录或加 force_reload=True。
10. 输入图像格式：默认接受 BGR（OpenCV 格式）；PIL Image 自动转 RGB，内部会再转回 BGR 进行推理，注意颜色通道一致性。

⚠️ 部署坑

11. ONNX 输入尺寸动态轴：导出时建议显式指定 --img 640 或所需尺寸，避免动态轴带来的推理兼容性问题。
12. TensorRT 版本对齐：TensorRT 推理需确保导出时使用的 TensorRT 版本与运行时一致，否则可能加载失败。

与同类对比

结论：YOLOv5 的最大优势是成熟稳定、资料最多、踩坑有解。新项目若追求最新模型和统一体验用 YOLOv8；若追求稳定、可解释、社区丰富的工业方案，YOLOv5 依然值得。

一句话推荐结论

YOLOv5 是计算机视觉入门的最佳起点、工业部署的最稳选择——上手零门槛、社区资料丰富、一行命令即可推理/训练/部署，虽然模型本身已被超越，但它积累的生态和文档是无价资产。新项目建议用 ultralytics 包（YOLOv8/11），老项目迁移不划算就先别动。