深度学习项目结构（整理版）

原始资料: Deep Learning Best Practices；原始仓库 fork 版本：yumf24/minimal-lightning-hydra-template created: 2026-07-02 21:34 整理说明: 本版本结合原始笔记和可读取的原始教程重排、补全和翻译，保留常用英文术语。

内容简要概括

这份笔记整理了基于 PyTorch Lightning、Hydra 和 Wandb 的深度学习项目模板结构。核心原则是把配置、源代码、数据、日志、脚本、测试和文档分开管理，让训练、评估、推理和实验复现都有明确入口。最值得记住的是：src/ 管代码逻辑，configs/ 管实验参数，data/ 管输入数据，logs/ 管输出结果。

PyTorch Lightning、Hydra、Wandb、configs/、src/、datamodules、LightningModule、Trainer、logs/、tests/、Makefile、pyproject.toml、项目模板、实验复现

目录

• 1. 总体目录结构
• 2. 核心目录职责
• 3. 根目录文件职责
• 4. 环境安装和依赖管理
• 5. 一次训练流程如何运行
• 6. 新项目启动建议
• 待确认问题

1. 总体目录结构

典型模板结构如下：

Copy├── .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                    # 项目说明文档

一句话总览：

Copysrc/      负责代码逻辑
configs/ 负责实验参数
data/    负责输入数据
logs/    负责输出结果
tests/   负责可运行性和关键逻辑检查

2. 核心目录职责

2.1 configs/：实验配置目录

configs/ 是 Hydra 配置目录，用来管理训练、评估、推理过程中的参数，避免把参数硬编码到 Python 文件中。

不要在代码中写死：

Copylr = 1e-3
batch_size = 64
max_epochs = 50

更推荐放到配置文件里，再通过命令行覆盖：

Copypython src/train.py trainer.max_epochs=50 datamodule.batch_size=64 model.lr=1e-3

重要子目录：

主配置文件：

2.2 src/：核心源代码目录

src/ 存放主要 Python 源代码。推荐原则：

Copy训练入口只负责任务调度
模型文件只负责模型定义
数据文件只负责数据读取和预处理
工具函数单独放到 utils

典型结构：

Copysrc/
├── datamodules/
├── models/
├── utils/
├── train.py
├── eval.py
└── inference.py

子目录说明：

入口脚本说明：

2.3 data/：数据目录

data/ 用于存放项目数据，常见拆分：

Copydata/
├── raw/             # 原始数据
├── processed/       # 预处理后的数据
└── external/        # 外部数据或第三方数据

大规模数据通常不要直接提交到 Git。可以在 .gitignore 中忽略：

Copydata/

然后在 README.md 中写清楚下载方式、解压位置和数据目录格式。

2.4 logs/：日志和实验结果目录

logs/ 保存训练、评估、推理产生的结果，包括：

Copy训练日志
评估结果
模型 checkpoint
Hydra 保存的配置文件
Wandb 日志
TensorBoard 日志

示例：

Copylogs/
├── train/
│   └── runs/
├── eval/
│   └── runs/
└── inference/
    └── runs/

logs/ 通常也不提交到 Git。

2.5 notebooks/：探索性实验目录

notebooks/ 适合放探索性工作：

Copy数据可视化
数据探索
模型原型验证
错误案例分析
快速实验

正式训练逻辑不建议长期写在 notebook 中。推荐命名：

Copy1.0-jqp-initial-data-exploration.ipynb

含义：

Copy编号-作者缩写-简短描述

2.6 tests/：测试目录

深度学习项目中的测试不只测试模型精度，更重要的是确认代码能跑通：

CopyDataLoader 是否能返回正确 batch
模型 forward 输出 shape 是否正确
loss 是否能正常计算
配置文件是否能正常加载
训练脚本是否能跑通一个 mini batch

示例：

Copytests/
├── test_datamodule.py
├── test_model.py
└── test_train.py

2.7 scripts/：脚本目录

scripts/ 存放 Shell 脚本或辅助脚本，常见用途：

Copy下载数据
启动训练
批量跑实验
提交集群任务
运行超参数搜索

示例：

Copyscripts/
├── download_data.sh
├── train.sh
└── sweep.sh

2.8 .github/：GitHub Actions 配置

.github/ 通常用于 GitHub Actions workflow：

Copy自动运行测试
自动检查代码格式
自动构建文档
自动发布包

示例：

Copy.github/
└── workflows/
    ├── tests.yaml
    └── docs.yaml

3. 根目录文件职责

.env.example 示例：

CopyWANDB_API_KEY=your_wandb_key
DATA_DIR=/path/to/data
LOG_DIR=/path/to/logs

真实 .env 通常包含敏感信息，不应提交到 Git。

.gitignore 常见内容：

Copydata/
logs/
.env
__pycache__/
*.ckpt
wandb/

Makefile 示例：

Copytrain:
	python src/train.py

test:
	pytest tests/

format:
	ruff check src tests

README.md 推荐包含：

Copy项目简介
环境安装方法
数据准备方法
训练命令
评估命令
推理命令
项目结构
实验结果
引用方式
License

4. 环境安装和依赖管理

environment.yaml 负责创建基础 Conda 环境，requirements.txt 负责列出 pip 依赖。

完整示例：

Copyconda env create -f environment.yaml
conda activate my_project
pip install -r requirements.txt

命令说明：

如果想手动命名环境：

Copyconda create -n my_project python=3.9
conda activate my_project
pip install -r requirements.txt

建议环境名用项目短名，例如 mnist-lightning、segmentation-exp，不要用过于宽泛的 test 或 env。

5. 一次训练流程如何运行

假设运行：

Copypython src/train.py model=cnn datamodule=cifar10 trainer=gpu logger=wandb

整体流程：

Copy1. 启动 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

命令中的配置含义：

6. 新项目启动建议

1. 先用模板默认配置跑通 python src/train.py。
2. 在 src/datamodules/ 中实现自己的数据读取逻辑。
3. 在 configs/datamodule/ 中写数据路径、batch size 和 worker 数。
4. 在 src/models/ 中实现 LightningModule。
5. 在 configs/model/ 中写模型和优化器配置。
6. 用 configs/experiment/ 保存一组完整实验配置，方便复现。
7. 用 tests/ 保证数据、模型 forward、loss 和 mini-batch train 能跑通。
8. 用 .gitignore 排除 data/、logs/、.env、checkpoint 和缓存文件。
9. 在 README.md 中记录安装、数据准备、训练、评估和推理命令。

待确认问题

• 原始笔记中的 fork 仓库链接 https://github.com/yumf24/minimal-lightning-hydra-template.git 未能通过浏览工具读取具体仓库内容；本整理版保留该链接，并参考了可读取的官方教程首页和原始模板仓库页面。