Hydra（整理版）
原始资料: Learn Hydra - ReCoDE Deep Learning Best Practices created: 2026-07-02 22:12 整理说明: 本版本结合原始笔记和可读取的原始教程重排、补全和翻译，保留常用英文术语。
内容简要概括
Hydra 用来管理复杂项目的配置，尤其适合机器学习实验中频繁切换模型、数据、训练参数和 logger 的场景。它把配置拆成多个 YAML 文件，通过组合和命令行 override 生成最终配置，避免把学习率、batch size、路径等参数硬编码进 Python。最实用的记法是：配置写在 configs/，入口函数用 @hydra.main 读取配置，实验时用命令行临时覆盖参数。
Hydra、hydra-core、OmegaConf、YAML、@hydra.main、config_path、config_name、override、config composition、multirun、variable interpolation、实验配置
目录
1. Hydra 解决什么问题
深度学习项目常见参数很多：
学习率
batch size
训练轮数
模型结构
数据路径
logger
checkpoint
GPU 设置
如果这些参数散落在 Python 文件里，实验切换会很难维护。Hydra 的作用是把配置集中放进 configs/，并允许按模块拆分，例如：
configs/
├── datamodule/
├── model/
├── trainer/
├── logger/
├── callbacks/
└── train.yaml
这样可以让代码专注逻辑，让 YAML 专注参数。
2. 安装与最小配置
安装：
pip install hydra-core
最小配置文件：
# config.yaml
model:
name: linear_regression
learning_rate: 0.01
字段说明：
| 字段 | 作用 |
|---|---|
model |
配置分组名，这里表示模型相关参数。 |
name |
模型名称，可用于选择模型类或记录实验。 |
learning_rate |
学习率，训练时传给 optimizer。 |
3. 在 Python 入口中读取配置
基本写法：
import hydra
@hydra.main(version_base="1.2", config_path="configs", config_name="train.yaml")
def main(cfg):
print(f"Model: {cfg.model.name}")
print(f"Learning Rate: {cfg.model.learning_rate}")
if __name__ == "__main__":
main()
参数说明：
| 参数 | 作用 |
|---|---|
version_base="1.2" |
指定 Hydra 兼容行为版本，减少版本升级带来的行为歧义。 |
config_path="configs" |
配置目录路径，通常相对当前 Python 文件或工作目录。 |
config_name="train.yaml" |
主配置文件名，也常写成不带扩展名的 train。 |
cfg |
Hydra 组合后的最终配置对象，通常是 DictConfig。 |
运行：
python your_script.py
Hydra 会读取主配置，并把内容传给 main(cfg)。
4. 命令行覆盖参数
Hydra 最常用的能力是命令行 override：
python your_script.py model.name=svm model.learning_rate=0.001
含义：
| override | 作用 |
|---|---|
model.name=svm |
把配置中的 model.name 改成 svm。 |
model.learning_rate=0.001 |
把学习率改成 0.001。 |
在深度学习模板中，常见写法：
python src/train.py trainer.max_epochs=50 datamodule.batch_size=64 model.lr=1e-3
python src/train.py trainer=gpu logger=wandb
两类 override 要区分：
| 类型 | 示例 | 说明 |
|---|---|---|
| 字段覆盖 | trainer.max_epochs=50 |
修改已有字段的值。 |
| 配置组切换 | trainer=gpu |
切换到某个配置组文件，例如 configs/trainer/gpu.yaml。 |
5. 层级化配置与项目组织
Hydra 支持把配置拆成多个文件和目录，再由主配置组合。机器学习项目里推荐按职责拆：
| 配置目录 | 内容 |
|---|---|
configs/model/ |
模型结构、学习率、optimizer 参数。 |
configs/datamodule/ |
数据路径、batch size、num_workers。 |
configs/trainer/ |
epoch、accelerator、devices、precision。 |
configs/logger/ |
Wandb、TensorBoard 等日志配置。 |
configs/callbacks/ |
checkpoint、early stopping 等回调。 |
configs/experiment/ |
一组完整实验配置，用于复现实验。 |
常用高级能力：
| 功能 | 作用 |
|---|---|
multirun |
一次运行多组参数，适合网格实验或超参数搜索。 |
| variable interpolation | 在配置里引用其他字段，避免重复路径或重复参数。 |
| composition | 组合多个配置组，形成最终实验配置。 |
| plugin system | 扩展 Hydra 功能，例如不同 launcher 或 sweeper。 |
6. Notebook 中的 compose 用法
Hydra 主要面向命令行入口，但在 Notebook 或交互环境中可以用 initialize 和 compose：
import hydra
from hydra import compose, initialize
from omegaconf import OmegaConf
with initialize(config_path="./", job_name="test_app", version_base="1.2"):
cfg = compose(
config_name="hydra_example",
overrides=["+mlp.dropout=0.5", "mlp.in_channels=150"],
)
print(OmegaConf.to_yaml(cfg))
参数说明：
| 名称 | 作用 |
|---|---|
initialize |
初始化 Hydra 配置上下文。 |
config_path="./" |
指向配置文件所在目录。 |
job_name="test_app" |
当前 Hydra job 的名称。 |
compose |
根据配置文件和 overrides 生成 cfg。 |
+mlp.dropout=0.5 |
新增一个原配置中不存在的字段。 |
OmegaConf.to_yaml(cfg) |
把配置对象打印成 YAML，便于检查最终配置。 |
注意：Notebook 适合学习和调试配置，但完整训练实验最好仍通过命令行入口运行，这样更容易复现运行目录、日志和覆盖参数。