项目结构
正文
原始仓库(fork版本): https://github.com/yumf24/minimal-lightning-hydra-template.git
深度学习项目结构
一、整体目录结构
├── .github/ # GitHub Actions 工作流配置
│
├── configs/ # Hydra 配置文件目录
│ ├── callbacks/ # 回调函数配置，如 checkpoint、early stopping
│ ├── datamodule/ # 数据模块配置，如数据路径、batch size、num_workers
│ ├── debug/ # 调试模式配置，用于快速跑通或定位问题
│ ├── experiment/ # 实验配置，用于保存一组完整实验参数
│ ├── extras/ # 额外工具配置，如日志打印、异常处理等
│ ├── hparams_search/ # 超参数搜索配置
│ ├── hydra/ # Hydra 自身的配置
│ ├── local/ # 本地环境配置，通常不提交到远程仓库
│ ├── logger/ # 日志工具配置，如 Wandb、TensorBoard
│ ├── model/ # 模型配置，如网络结构、学习率、优化器参数
│ ├── paths/ # 路径配置，如数据目录、日志目录、输出目录
│ ├── trainer/ # PyTorch Lightning Trainer 配置，如 epoch、GPU、精度
│ │
│ ├── eval.yaml # 评估主配置文件
│ ├── train.yaml # 训练主配置文件
│ └── inference.yaml # 推理主配置文件
│
├── data/ # 项目数据目录
│
├── logs/ # 日志和实验结果目录
│
├── notebooks/ # Jupyter Notebook 目录，用于探索性分析和原型实验
│
├── scripts/ # Shell 脚本目录，如训练脚本、数据下载脚本
│
├── src/ # 项目核心源代码
│ ├── datamodules/ # 数据加载与预处理代码
│ ├── models/ # 模型结构、LightningModule、loss、optimizer 等代码
│ ├── utils/ # 工具函数，如日志、路径、配置辅助函数
│ │
│ ├── eval.py # 评估入口脚本
│ ├── train.py # 训练入口脚本
│ └── inference.py # 推理入口脚本
│
├── tests/ # 测试代码目录
│
├── .env.example # 环境变量示例文件
├── .gitignore # Git 忽略文件配置
├── .pre-commit-config.yaml # pre-commit 代码检查和格式化配置
├── .project-root # 项目根目录标记文件
├── environment.yaml # Conda 环境配置文件
├── Makefile # 常用命令快捷入口
├── pyproject.toml # Python 项目配置文件
├── requirements.txt # pip 依赖列表
└── README.md # 项目说明文档
pip install -r requirements.txt
其中 -r 是 --requirement 的缩写，意思是“从这个依赖文件读取要安装的包”。
environment.yaml 负责创建基础环境 requirements.txt 负责列出 Python pip 依赖
使用示例
conda env create -f environment.yaml
conda activate my_project
pip install -r requirements.txt
从创建conda环境开始的完整使用示例是什么，如何命名环境? ...
二、核心目录说明
1. configs/：实验配置目录
configs/ 是 Hydra 配置文件目录，用于管理训练、评估、推理过程中涉及的各种参数。
它的作用是避免把参数硬编码到 Python 文件中。
例如不要在代码里写死：
lr = 1e-3
batch_size = 64
max_epochs = 50
而是放到配置文件中统一管理。
常见配置内容包括：
学习率
batch size
训练轮数
模型结构
数据路径
日志工具
checkpoint 设置
GPU 设置
使用配置后，可以通过命令行覆盖参数：
python src/train.py trainer.max_epochs=50 datamodule.batch_size=64 model.lr=1e-3
重要子目录
| 路径 | 说明 |
|---|---|
configs/model/ |
存放模型相关配置 |
configs/datamodule/ |
存放数据加载相关配置 |
configs/trainer/ |
存放训练器配置 |
configs/logger/ |
存放日志工具配置 |
configs/callbacks/ |
存放回调函数配置 |
configs/experiment/ |
存放完整实验配置 |
configs/debug/ |
存放调试配置 |
configs/paths/ |
存放路径配置 |
主配置文件
| 文件 | 说明 |
|---|---|
configs/train.yaml |
训练主配置 |
configs/eval.yaml |
评估主配置 |
configs/inference.yaml |
推理主配置 |
2. src/：核心源代码目录
src/ 存放项目的主要 Python 源代码。
推荐原则是：
训练入口只负责任务调度
模型文件只负责模型定义
数据文件只负责数据读取和预处理
工具函数单独放到 utils
典型结构
src/
├── datamodules/
├── models/
├── utils/
├── train.py
├── eval.py
└── inference.py
子目录说明
| 路径 | 说明 |
|---|---|
src/datamodules/ |
数据加载、数据预处理、Dataset、DataLoader |
src/models/ |
神经网络结构、LightningModule、loss、optimizer |
src/utils/ |
通用工具函数，如日志、路径、配置处理 |
入口脚本说明
| 文件 | 说明 |
|---|---|
src/train.py |
训练入口，负责读取配置、创建模型、创建数据模块、启动训练 |
src/eval.py |
评估入口，负责加载 checkpoint 并在验证集或测试集上评估 |
src/inference.py |
推理入口，负责加载模型并对新样本进行预测 |
3. data/：数据目录
data/ 用于存放项目数据。
常见结构可以进一步拆分为：
data/
├── raw/ # 原始数据
├── processed/ # 预处理后的数据
└── external/ # 外部数据或第三方数据
通常不建议把大规模数据直接提交到 Git 仓库。
可以在 .gitignore 中忽略：
data/
然后在 README 中说明数据如何下载和放置。
4. logs/：日志和实验结果目录
logs/ 用于保存训练过程中产生的结果。
常见内容包括：
训练日志
评估结果
模型 checkpoint
Hydra 保存的配置文件
Wandb 日志
TensorBoard 日志
例如：
logs/
├── train/
│ └── runs/
├── eval/
│ └── runs/
└── inference/
└── runs/
logs/ 通常也不提交到 Git。
5. notebooks/：探索性实验目录
notebooks/ 用于存放 Jupyter Notebook。
适合放：
数据可视化
数据探索
模型原型验证
错误案例分析
快速实验
但正式训练逻辑不建议长期写在 notebook 中。
推荐命名方式：
1.0-jqp-initial-data-exploration.ipynb
含义是：
编号-作者缩写-简短描述
6. tests/：测试目录
tests/ 用于存放测试代码。
深度学习项目中的测试通常不只是测试模型精度，而是测试代码能否正常运行。
常见测试包括：
DataLoader 是否能返回正确 batch
模型 forward 输出 shape 是否正确
loss 是否能正常计算
配置文件是否能正常加载
训练脚本是否能跑通一个 mini batch
例如：
tests/
├── test_datamodule.py
├── test_model.py
└── test_train.py
7. scripts/：脚本目录
scripts/ 用于存放 Shell 脚本或辅助脚本。
常见用途：
下载数据
启动训练
批量跑实验
提交集群任务
运行超参数搜索
例如：
scripts/
├── download_data.sh
├── train.sh
└── sweep.sh
8. .github/：GitHub Actions 配置
.github/ 通常用于存放 GitHub Actions 工作流。
常见用途：
自动运行测试
自动检查代码格式
自动构建文档
自动发布包
例如：
.github/
└── workflows/
├── tests.yaml
└── docs.yaml
三、根目录文件说明
1. .env.example
环境变量示例文件。
用于说明项目需要哪些环境变量，例如：
WANDB_API_KEY=your_wandb_key
DATA_DIR=/path/to/data
LOG_DIR=/path/to/logs
真实的 .env 文件通常包含私密信息，不应提交到 Git。
2. .gitignore
Git 忽略文件配置。
用于避免提交不必要或敏感文件，例如：
data/
logs/
.env
__pycache__/
*.ckpt
wandb/
3. .pre-commit-config.yaml
pre-commit 配置文件。
用于在提交代码前自动执行代码检查和格式化。
常见工具包括：
black
ruff
isort
mypy
prettier
它可以帮助团队保持统一的代码风格。
4. .project-root
项目根目录标记文件。
用于让代码自动识别项目根路径，避免路径混乱。
例如可以帮助代码从任意子目录定位到项目根目录。
5. environment.yaml
Conda 环境配置文件。
用于创建项目运行环境，例如：
conda env create -f environment.yaml
conda activate your_env_name
适合管理 Python 版本、CUDA 版本和较复杂依赖。
6. requirements.txt
pip 依赖文件。
用于安装 Python 包：
pip install -r requirements.txt
适合列出项目需要的 Python 依赖，例如：
torch
pytorch-lightning
hydra-core
wandb
einops
7. Makefile
常用命令快捷入口。
可以把复杂命令封装成简单命令。
例如：
make train
make test
make format
对应的 Makefile 可能类似：
train:
python src/train.py
test:
pytest tests/
format:
ruff check src tests
8. pyproject.toml
Python 项目配置文件。
常见用途包括：
配置项目元信息
配置打包方式
配置代码格式化工具
配置 lint 工具
配置测试工具
例如可以配置：
black
ruff
pytest
setuptools
poetry
9. README.md
项目说明文档。
通常应该包括：
项目简介
环境安装方法
数据准备方法
训练命令
评估命令
推理命令
项目结构
实验结果
引用方式
License
一个好的 README 可以让别人快速理解和复现项目。
四、一次训练流程如何运行
假设运行命令：
python src/train.py model=cnn datamodule=cifar10 trainer=gpu logger=wandb
整体流程是：
1. 启动 src/train.py
2. Hydra 读取 configs/train.yaml
3. train.yaml 组合 model、datamodule、trainer、logger、callbacks 等配置
4. 根据 datamodule 配置创建数据模块
5. 根据 model 配置创建模型
6. 根据 trainer 配置创建 PyTorch Lightning Trainer
7. 开始训练
8. 日志、配置和 checkpoint 保存到 logs/
9. 如果启用 Wandb，同步实验结果到 Wandb
可以概括为：
src/ 负责代码逻辑
configs/ 负责实验参数
data/ 负责输入数据
logs/ 负责输出结果