📚 课程目录第3章 YOLO v5源码获取与结构概览

3. YOLO v5 源码获取与结构概览

好，咱们正式开始动手。这一章我带你做两件事：第一，把 YOLO v5 的源码拉到本地；第二，把项目目录拆开看看，搞清楚每个文件夹、每个核心文件是干嘛的。

很多同学拿到一个开源项目，习惯直接双击运行。结果报错了才回头翻目录，效率很低。我个人习惯是：先读结构，再跑代码。你花 10 分钟把目录摸透了，后面调试能省 2 小时。

3.1 从 GitHub 克隆仓库

YOLO v5 的官方仓库在 Ultralytics 名下。地址我直接给你：

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

这三行命令，我解释一下：

第一行：把整个项目拉到本地，大概 10 MB 左右，网速正常的话十几秒搞定。
第二行：进入项目根目录。
第三行：安装依赖。这里要注意，requirements.txt 里列了 PyTorch、OpenCV、matplotlib 这些库。如果你之前装过 PyTorch，记得核对一下版本。

我曾经踩过的坑： 直接 pip install -r requirements.txt 会把 PyTorch 也装一遍。如果你有 CUDA 环境，建议先手动装 PyTorch 的 CUDA 版本，再装其他依赖。否则默认装 CPU 版，训练慢到怀疑人生。

3.2 项目目录结构解析

克隆完以后，用 tree 命令或者直接打开文件夹，你会看到这样的结构：

yolov5/
├── data/               # 数据集配置和超参数
├── models/             # 模型定义文件
├── utils/              # 工具函数
├── weights/            # 预训练权重存放处
├── runs/               # 训练和推理的输出结果
├── detect.py           # 推理脚本
├── train.py            # 训练脚本
├── val.py              # 验证脚本
├── export.py           # 模型导出脚本
├── requirements.txt    # 依赖列表
└── hubconf.py          # PyTorch Hub 入口

嗯，这里我挑几个重点目录展开说。

3.2.1 data/ —— 数据和超参数的家

这个目录下放的是 数据集配置文件 和 超参数文件。比如 coco128.yaml 定义了 COCO 数据集的路径、类别数、类别名称。你训练自己的数据集时，也要在这里新建一个 .yaml 文件。

文件	作用
`coco128.yaml`	COCO 128 子集的数据配置，适合快速测试
`hyp.scratch.yaml`	训练超参数，比如学习率、动量、数据增强参数
`VOC.yaml`	VOC 数据集配置

小技巧： 我刚开始用 YOLO v5 时，总在代码里硬编码数据路径。后来发现直接改 .yaml 文件更干净。你训练不同数据集时，只需要换一个 --data 参数就行。

3.2.2 models/ —— 模型的核心

这个目录是 YOLO v5 的灵魂。里面放了三个版本的模型定义：

yolov5s.yaml —— 小模型，速度快，适合移动端
yolov5m.yaml —— 中等模型，平衡速度和精度
yolov5l.yaml —— 大模型，精度高，速度慢
yolov5x.yaml —— 超大模型，追求极致精度

每个 .yaml 文件定义了网络的深度和宽度。说白了，就是控制卷积层的数量和通道数。你打开 yolov5s.yaml 看一眼，会发现它其实是一个结构化的配置文件：

# parameters
nc: 80  # number of classes
depth_multiple: 0.33  # model depth multiple
width_multiple: 0.50  # layer channel multiple

# anchors
anchors:
  - [10,13, 16,30, 33,23]  # P3/8
  - [30,61, 62,45, 59,119]  # P4/16
  - [116,90, 156,198, 373,326]  # P5/32

# backbone
backbone:
  # [from, number, module, args]
  [[-1, 1, Conv, [64, 6, 2, 2]],  # 0-P1/2
   [-1, 1, Conv, [128, 3, 2]],    # 1-P2/4
   ...
  ]

你看，depth_multiple 和 width_multiple 就是控制模型大小的开关。s 版本把这两个值设得很小，所以模型轻量。x 版本设得大，模型就胖。

  核心理解： YOLO v5 的 s/m/l/x 不是四个不同的网络结构，而是同一个结构的不同缩放版本。你改两个参数就能生成不同大小的模型。这个设计思路非常优雅。

3.2.3 utils/ —— 工具箱

这个目录下全是辅助函数。我挑几个常用的：

datasets.py —— 数据加载和增强，包括 Mosaic、MixUp 这些高级技巧
general.py —— 通用工具，比如坐标转换、非极大值抑制（NMS）
loss.py —— 损失函数计算，包括 GIoU、CIoU 这些
plots.py —— 可视化工具，画 PR 曲线、混淆矩阵
torch_utils.py —— PyTorch 相关工具，比如模型融合、EMA

说实话，这些文件你不需要全部读懂。但 datasets.py 和 general.py 我建议你翻一翻。因为后面你训练自己的数据时，大概率要改数据加载的逻辑。

3.3 核心文件功能说明

根目录下那几个 .py 文件，是项目的入口。我按使用频率排个序：

文件	功能	常用参数示例
`detect.py`	用训练好的模型做推理	`--weights yolov5s.pt --source data/images`
`train.py`	训练新模型	`--data coco128.yaml --weights yolov5s.pt`
`val.py`	验证模型精度，计算 mAP	`--weights runs/train/exp/weights/best.pt --data coco128.yaml`
`export.py`	导出模型为 ONNX/TensorRT/OpenVINO 格式	`--weights yolov5s.pt --include onnx`

你想想看，这四个文件覆盖了深度学习项目的完整流程：训练 → 验证 → 推理 → 部署。后面几章我们会逐个深入。

3.4 整体结构流程图

下面这张图，我把 YOLO v5 的项目结构和核心流程画出来了。你对照着看，会更清楚：

3.5 本章小结

这一章我们做了三件事：

从 GitHub 克隆了 YOLO v5 源码
拆解了项目目录结构，重点看了 data/、models/、utils/
梳理了四个核心脚本的功能和调用方式