计算机视觉 / 系统课时

认识项目目录结构

认识项目目录结构

本课带你建立 YOLOv5 项目的目录地图,弄清训练、验证、推理、模型定义、数据配置和工具脚本分别放在哪里。完成后,你能从任务入口快速定位代码,而不是在仓库中盲目搜索。

学习目标

  • 识别训练、验证和推理入口脚本的职责。
  • 找到模型结构、数据配置与通用工具所在位置。
  • 根据修改目标判断应查看哪个目录或文件。

先建立目录地图

YOLOv5 仓库可以按“入口脚本、模型定义、数据配置、通用工具”四层理解。入口脚本负责组织任务,models 描述网络,data 保存数据集与超参数配置,utils 提供加载、评估、日志和可视化等共享能力。

YOLOv5 项目目录职责图

根目录中的脚本是最常用的任务入口。先从入口确认“正在做什么”,再沿导入关系进入模型或工具代码,通常比从底层文件反向追踪更高效。

认识三个主要入口

文件 主要职责 常见输入 主要结果
train.py 组织训练循环、优化器、保存权重 数据配置、模型配置、预训练权重 best.pt、last.pt、训练指标
val.py 计算精确率、召回率和 mAP 权重、验证集配置 指标与评估图表
detect.py 对图片、视频或摄像头执行推理 权重、数据源、阈值 标注后的媒体与检测结果

这些脚本不是彼此替代的关系。训练过程中可以触发验证,但单独运行 val.py 更适合复测某个权重;detect.py 关注实际预测,不负责反向传播或更新参数。

找到模型、数据与工具代码

models 目录包含网络模块和模型配置解析逻辑。修改 Backbone、Neck、检测头或 YAML 网络结构时,应优先查看这里,而不是直接改训练循环。

data 目录通常保存数据集 YAML、类别名称、训练集与验证集路径,以及部分超参数配置。自定义数据集最常修改的是数据 YAML,而不是仓库中的 Python 源码。

utils 目录集中放置数据加载、通用计算、指标、绘图、日志和设备选择等功能。多个入口都可能调用这里,因此修改公共函数前要确认是否会同时影响训练、验证和推理。

下面的脚本可在仓库根目录运行,用于检查关键路径是否齐全。

python
from pathlib import Path

required = [
    "train.py",
    "val.py",
    "detect.py",
    "models",
    "data",
    "utils",
]

root = Path(".")
for item in required:
    status = "OK" if (root / item).exists() else "MISSING"
    print(f"{item:<12} {status}")

预期输出

text
train.py     OK
val.py       OK
detect.py    OK
models       OK
data         OK
utils        OK

若某项显示 MISSING,先确认当前目录是否真的是 YOLOv5 仓库根目录。不同版本可能增加其他文件,但这些核心入口和目录通常应存在。

按修改目标定位文件

准备训练自定义数据集时,先修改数据 YAML,再通过 train.py 传入配置。需要改变网络规模或层结构时,查看模型 YAML 与 models 中的解析代码。出现指标异常时,沿 val.py 进入指标计算;出现图片读取、坐标缩放或 NMS 问题时,再定位 utils 中对应函数。

不要直接在 utils 中大范围修改公共逻辑来“快速修复”单个问题。公共函数被多个入口复用,局部改动可能导致训练正常但推理异常,或不同图像尺寸下出现新的偏差。

本课总结

  • 根目录入口脚本决定任务类型,models、data、utils 分别承担模型、配置和公共能力。
  • 定位问题时应先确认入口,再沿调用关系查找底层实现。
  • 修改共享工具前要评估它对训练、验证和推理的连带影响。

下一课预告

下一课将进入数据集制作流程,从业务目标出发定义检测类别,并明确类别边界与容易混淆的标注情况。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

认识项目目录结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通