Quick Start（整理版）
原始资料: Quick Start - ReCoDE Deep Learning Best Practices created: 2026-07-02 21:57 整理说明: 本版本结合原始笔记和可读取的原始教程重排、补全和翻译，保留常用英文术语。
内容简要概括
这份 Quick Start 说明如何从模板开始搭建一个深度学习项目：准备环境、初始化项目、配置数据和模型、设置训练、启动训练，并完成日志、评估与推理。核心思路是把代码逻辑放在 src/，把实验参数放在 configs/，用 PyTorch Lightning 管训练流程，用 Hydra 管配置覆盖，用 Wandb 记录实验结果。最值得记住的是：先跑通模板默认训练，再逐步替换数据模块、模型配置和训练参数。
PyTorch Lightning、Hydra、Wandb、Trainer、DataModule、configs/train.yaml、ckpt_path、GPU 训练、实验配置、项目模板、评估、推理
目录
1. 环境准备
新项目先建立独立 Python 环境，再安装项目依赖。教程示例使用 Python 3.9：
conda create -n myenv python=3.9
conda activate myenv
pip install -r requirements.txt
参数说明：
| 命令或参数 | 作用 |
|---|---|
conda create -n myenv python=3.9 |
创建名为 myenv 的 Conda 环境，并指定 Python 版本。 |
conda activate myenv |
进入该环境，后续安装和运行都在隔离环境中完成。 |
pip install -r requirements.txt |
根据 requirements.txt 安装 Python 依赖；-r 是 --requirement 的缩写。 |
建议把环境名改成项目相关名称，例如：
conda create -n dl-best-practice python=3.9
conda activate dl-best-practice
pip install -r requirements.txt
2. 项目初始化
教程推荐从 Minimal Lightning Hydra Template 开始。常见做法是从 GitHub 页面点击 Use this template，或者克隆模板后删除原仓库历史：
git clone https://github.com/antonibigata/minimal-lightning-hydra-template.git <project-name>
cd <project-name>
rm -rf .git
参数说明：
| 命令或参数 | 作用 |
|---|---|
<project-name> |
本地项目目录名，替换为自己的项目名。 |
cd <project-name> |
进入项目目录。 |
rm -rf .git |
删除模板仓库的 Git 历史，让当前目录可以作为一个新项目重新初始化。 |
删除 .git 后，如果要创建自己的仓库：
git init
git add .
git commit -m "chore: initialize project from template"
3. 数据、模型与训练配置
项目的关键分工如下：
| 模块 | 推荐位置 | 负责内容 |
|---|---|---|
| 数据读取与预处理 | src/datamodules/、src/datamodules/components/ |
Dataset、DataLoader、数据变换、batch 组织。 |
| 数据配置 | configs/datamodule/ |
数据路径、batch_size、num_workers、数据集名称等。 |
| 网络结构 | src/models/components/nets/ |
CNN、MLP、Transformer 等纯模型结构。 |
| 模型训练逻辑 | src/models/ |
LightningModule、training_step、loss、optimizer。 |
| 模型配置 | configs/model/ |
网络选择、学习率、优化器、模型超参数。 |
| 训练控制 | configs/trainer/ |
epoch、accelerator、devices、precision 等 Trainer 参数。 |
configs/train.yaml 是训练入口的主配置，通常组合 datamodule、model、callbacks、logger、trainer、paths 等配置组。
4. 启动训练与命令行覆盖
最小训练命令：
python src/train.py
如果要覆盖配置，不需要改 YAML 文件，可以在命令行追加 Hydra override：
python src/train.py trainer.max_epochs=20
python src/train.py model/net=conv_net
python src/train.py trainer=gpu
参数说明：
| 命令或参数 | 作用 |
|---|---|
trainer.max_epochs=20 |
把训练轮数覆盖为 20。 |
model/net=conv_net |
切换模型网络配置组，具体名称取决于 configs/model/net/ 中的文件。 |
trainer=gpu |
使用 GPU 训练配置，通常对应 configs/trainer/gpu.yaml。 |
建议第一次运行先用 CPU 或小数据快速跑通，再切到 GPU 和完整数据。
5. 日志、评估与推理
Wandb 日志
启用 Wandb 前先安装、注册并登录账号。模板通常支持用配置组切换 logger：
python src/train.py logger=wandb
logger=wandb 会把日志配置切到 Wandb，用于记录训练指标、图像、超参数和实验对比信息。
评估
训练完成后，用 checkpoint 做评估：
python src/eval.py ckpt_path=<path_to_checkpoint>
参数说明：
| 参数 | 作用 |
|---|---|
ckpt_path |
checkpoint 文件路径，通常在 logs/train/runs/ 或 logger/checkpoint 配置指定的位置。 |
评估时优先使用 test set，避免用训练集或验证集高估模型效果。
推理
对新样本做预测：
python src/inference.py ckpt_path=<checkpoint> image_path=<image_path>
参数说明：
| 参数 | 作用 |
|---|---|
ckpt_path |
要加载的模型 checkpoint。 |
image_path |
待推理图片或输入样本路径，具体格式取决于项目的 inference.py。 |
6. 快速执行清单
- 创建并激活 Conda 环境。
- 安装
requirements.txt。 - 从模板创建项目，并确认 Git 历史是否需要重置。
- 先运行
python src/train.py，确认默认流程可执行。 - 替换
src/datamodules/中的数据逻辑，并同步修改configs/datamodule/。 - 替换
src/models/和configs/model/。 - 用 Hydra override 调整
trainer.max_epochs、batch_size、GPU、logger 等参数。 - 训练后用
src/eval.py评估，再用src/inference.py做单样本或批量推理。