SuperGradients 训练配方（Training Recipes）完全指南：从命令行一键训练到深度定制
【免费下载链接】super-gradientsEasily train or fine-tune SOTA computer vision models with one open source training library. The home of Yolo-NAS.项目地址: https://gitcode.com/GitHub_Trending/su/super-gradients
本文是 SuperGradients 训练配方（Training Recipes）的完整实战指南，核心讲解如何通过.yaml配方文件以一条命令启动模型训练、如何用 Hydra 命令行覆盖（overrides）快速调整超参数，以及配方文件内部的模块化结构与覆盖优先级。读完本文，你将能够读懂仓库内置的任何配方（如cifar10_resnet、coco2017_yolox），掌握从零组织自己的配方目录，并理解train_from_recipe入口到底做了什么。
前置知识
Recipe 体系的底层依赖是配置文件的组织方式，因此阅读本文前建议先通读 Introduction to Configuration Files。SuperGradients 使用hydra库配合.yaml配方（recipe）来管理训练配置，配方的可组合、可覆盖能力正是建立在这套配置机制之上的。
从配方启动训练
SuperGradients 的目标是"用最简单的方式复现一次训练"。一条命令即可完成从数据加载、模型构建到训练启动的全过程，基础语法如下：
python -m super_gradients.train_from_recipe --config-name=<config-name>其中<config-name>对应某个配方的文件名（不含.yaml后缀）。所有预定义配方都存放在仓库的 src/super_gradients/recipes 目录下，覆盖图像分类、目标检测、语义分割、姿态估计（Pose Estimation）等任务。
值得注意的一个惯例是：配方文件的头部注释通常会记录该配方的预期性能指标与可直接复制的启动命令。例如 cifar10_resnet.yaml 的头部注明"约 250 个 epoch 后达到约 94.9% 精度"，coco2017_yolox.yaml 的头部则给出了各个 YoloX 变体在 8 卡 GPU 上的 mAP 与训练时长。因此拿到一个新配方时，先读头部注释是最快的上手方式。
示例一：在 Cifar10 上训练 ResNet18
仓库内置的 cifar10_resnet.yaml 是最典型的分类入门配方，启动命令：
python -m super_gradients.train_from_recipe --config-name=cifar10_resnet该配方会：
- 使用
resnet18_cifar架构（10 分类，见 arch_params/resnet18_cifar_arch_params.yaml 中的num_classes: 10）； - 加载 Cifar10 数据集（
download: True会自动下载，见 dataset_params/cifar10_dataset_params.yaml）； - 使用 250 epoch、初始学习率 0.1、SGD 优化器等训练超参数（见 training_hyperparams/cifar10_resnet_train_params.yaml）。
配方头部还给出了两个常见变体：可通过+experiment_name=cifar10自定义实验名；如需使用 Albumentations 变换管线，可把数据集配置切换为内置的 albumentations 版本：
python -m super_gradients.train_from_recipe --config-name=cifar10_resnet dataset_params=cifar10_albumentations_dataset_params示例二：在 COCO2017 上训练 YoloX Small（8 卡 DDP）
目标检测配方的用法完全一致，coco2017_yolox.yaml 是 8 卡 DDP 训练的范例：
python -m super_gradients.train_from_recipe --config-name=coco2017_yolox architecture=yolox_s dataset_params.data_dir=/home/coco2017这个命令演示了两个关键点：
- 通过
architecture=yolox_s覆盖默认架构（配方默认architecture: yolox_s，其arch_params默认引用yolox_s_arch_params）； - 通过
dataset_params.data_dir=/home/coco2017指向本机的 COCO 数据集路径，无需改动配方文件。
配方的multi_gpu: DDP、num_gpus: 8声明了分布式训练方式，头部注释还说明了其有效批量大小是 16 × 8 = 128。
定制训练的两种方式
实际使用中几乎总要调整某些参数，SuperGradients 提供了两条互补的路径：
- Hydra Overrides（命令行覆盖）——不改动任何文件，适合快速实验；
- 修改配方文件——直接编辑 YAML，适合固化一个正式的训练方案。
方式一：Hydra Overrides
Hydra 覆盖允许你直接从命令行修改任意配置参数，语法如下：
python -m super_gradients.train_from_recipe --config-name=<config-name> param1=<val1> path.to.param2=<val2>两条规则需要牢记：
- 参数名不带
--前缀：直接写param1=...即可； - 使用完整路径：配置树每一层用
.分隔，例如training_hyperparams.max_epochs。
假设某配方大致结构如下：
training_hyperparams: max_epochs: 250 initial_lr: 0.1 ... dataset_params: data_dir: /local/mydataset ... ... # Many other parameters修改 epoch 数与学习率：
python -m super_gradients.train_from_recipe --config-name=<config-name> training_hyperparams.max_epochs=250 training_hyperparams.initial_lr=0.03修改数据集路径：
python -m super_gradients.train_from_recipe --config-name=<config-name> dataset_params.data_dir=<path-to-dataset>注意：不同配方的参数名可能不一致（例如
resume同时出现在根级与training_hyperparams级），请以具体配方文件中的键名为准。
方式二：直接修改配方
- 如果你使用的是
git clone得到的仓库副本，可以直接编辑 src/super_gradients/recipes 下的现有配方； - 如果是通过
pip install super-gradients安装，则无法修改预定义配方文件。正确做法是在你自己的项目中新建配方目录，并在其中基于 SuperGradients 内置配方组合出自己的配方。
这属于自定义配方的范畴，完整方法见后续教程 Recipes_Custom.md。官方建议先完成本教程，因为自定义配方依赖对默认值、覆盖顺序等概念的理解。
配方结构剖析
浏览recipes目录下的 YAML 文件时，会发现部分文件开头带有defaults键。下面是最小化的配方示例（同时也是理解整个体系的关键）：
defaults: - training_hyperparams: cifar10_resnet_train_params - dataset_params: cifar10_dataset_params - arch_params: resnet18_cifar_arch_params - checkpoint_params: default_checkpoint_params - _self_ - variable_setup architecture: resnet18 train_dataloader: cifar10_train # Optional, see comments below val_dataloader: cifar10_val # Optional, see comments below multi_gpu: Off num_gpus: 1 experiment_suffix: "" experiment_name: cifar10_${architecture}${experiment_suffix}仓库中真实的 cifar10_resnet.yaml 与该最小示例结构完全一致（实际使用architecture: resnet18_cifar）。这个文件包含了训练一个模型所需的全部必备属性。
配方组成部分
defaults：整个配方体系的核心，使用 OmegaConf 语法，作用是指向其他配方文件，从而实现模块化、可复用的配置组合。- 参数引用（Referencing Parameters）：通过点分路径引用配置，例如
training_hyperparams.initial_lr指的就是cifar10_resnet_train_params.yaml中的initial_lr。 _self_：代表当前配方文件自身，允许当前配方覆盖上面列出的默认配置；它在defaults列表中的位置决定了覆盖优先级。variable_setup：启用常用命令行快捷方式所必需的配置段，必须位于defaults列表的最后一项（详见下文"命令行快捷方式"）。
配方文件必须包含以下四个必备配置段：
training_hyperparams——训练策略相关的全部超参数：学习率、epoch 数、优化器、损失函数、学习率调度、EMA、验证频率、随机种子等。cifar10_resnet_train_params.yaml以 default_train_params.yaml 为基础，仅覆盖差异项（如max_epochs: 250、initial_lr: 0.1、optimizer: SGD）。dataset_params——训练/验证数据集与 DataLoader 的配置，包括数据变换（transforms）、batch_size、num_workers等。它与根级参数train_dataloader、val_dataloader紧密耦合：这两个参数用于按名称实例化训练与验证 DataLoader，属于便捷性参数，在 SG 内置配方中普遍存在但并非广义上的必备项。外部自定义数据集的使用方式见 Data.md 中的 Using Custom Datasets 章节。arch_params——模型架构参数，与根级architecture参数成对出现：architecture决定具体模型，arch_params决定该模型的参数（如num_classes）。checkpoint_params——检查点相关设置，包括迁移学习时加载权重、是否使用预训练权重、严格加载模式等，支持的完整参数见 checkpoint_params/default_checkpoint_params.yaml（load_checkpoint、load_backbone、checkpoint_path、external_checkpoint_path、strict_load、pretrained_weights、checkpoint_num_classes等）。
理解覆盖顺序
🚨警告：
defaults列表中的条目顺序至关重要！覆盖优先级遵循列表顺序：列表中靠后的配置可以覆盖靠前的配置。构造配方时务必注意这一点。
以cifar10_resnet.yaml的实际顺序为例：
defaults: - training_hyperparams: cifar10_resnet_train_params - dataset_params: cifar10_dataset_params - arch_params: resnet18_cifar_arch_params - checkpoint_params: default_checkpoint_params - _self_ - variable_setup_self_位于四个子配置之后，因此配方自身的顶层键（如architecture、experiment_name）可以覆盖四个子配置中的同名项；而variable_setup位于最后，可以覆盖_self_中的内容。
组织你的配方文件夹
为了与上述组合机制匹配，配方文件夹建议按以下结构组织：
├─ cifar10_resnet.yaml ├─ ... ├─training_hyperparams │ ├─ cifar10_resnet_train_params.yaml │ └─ ... ├─dataset_params │ ├─ cifar10_dataset_params.yaml │ └─ ... ├─arch_params │ ├─ resnet18_cifar_arch_params.yaml │ └─ ... └─checkpoint_params ├─ default_checkpoint_params.yaml └─ ...并非强制要求完全遵循此结构，但保持这一约定可以确保与 SuperGradients 的默认查找逻辑兼容。
命令行覆盖快捷方式
虽然任何参数都可以通过命令行完整路径覆盖，但手写完整路径相当繁琐。例如修改学习率要写training_hyperparams.initial_lr=0.02，修改批量大小要同时写：
dataset_params.train_dataloader_params.batch_size=128 dataset_params.val_dataloader_params.batch_size=128为此，SuperGradients 为最常用的参数定义了快捷方式：
| 快捷方式 | 等价于（完整路径） |
|---|---|
lr=0.02 | training_hyperparams.initial_lr=0.02 |
bs=128 | dataset_params.train_dataloader_params.batch_size=128 dataset_params.val_dataloader_params.batch_size=128 |
epochs=100 | training_hyperparams.max_epochs=100 |
num_workers=4 | dataset_params.train_dataloader_params.num_workers=4 dataset_params.val_dataloader_params.num_workers=4 |
resume=True | training_hyperparams.resume=True |
ema=true | training_hyperparams.ema=true |
使用这些快捷方式的前提是配方的defaults中包含了variable_setup段，且variable_setup必须是defaults列表的最后一项。
从源码实现看，快捷方式并非硬编码在训练逻辑中，而是由 variable_setup.yaml 中声明的 Hydra 回调RecipeShortcutsCallback在启动时完成的。该回调位于 src/super_gradients/common/environment/omegaconf_utils.py，其on_run_start逻辑逐一将快捷值（如config.lr）与完整路径值（如config.training_hyperparams.initial_lr）合并——快捷方式未设置时自动回填完整路径值，两者都会被写入最终配置以便日志记录清晰。
两个值得注意的源码级细节：
- 当前仓库实现中，快捷方式键名实际为
batch_size与val_batch_size（分别对应训练与验证 DataLoader 的batch_size），而非文档中的bs，建议以 variable_setup.yaml 的实际键名为准； - 由于快捷方式依赖 Hydra 回调机制完成插值，它们不会在其他 YAML 配置文件中生效（即插值只发生在回调运行时）。
此外variable_setup.yaml还承担了输出目录的设置：通过hydra.run.dir: ${hydra_output_dir:${ckpt_root_dir}, ${experiment_name}}把 Hydra 输出目录指向get_checkpoints_dir_path计算出的检查点目录，便于集中管理实验产物。
底层执行流程：train_from_recipe 做了什么
命令python -m super_gradients.train_from_recipe的入口是 src/super_gradients/train_from_recipe.py：
import hydra from omegaconf import DictConfig from super_gradients import Trainer, init_trainer @hydra.main(config_path="recipes", version_base="1.2") def _main(cfg: DictConfig) -> None: Trainer.train_from_config(cfg) def main() -> None: init_trainer() # `init_trainer` needs to be called before `@hydra.main` _main() if __name__ == "__main__": main()@hydra.main(config_path="recipes")告诉 Hydra 从recipes目录解析配方，--config-name即指定其中的某个文件。真正干活的是Trainer.train_from_config（见 src/super_gradients/training/sg_trainer/sg_trainer.py#L234-L298），其执行流程可以概括为：
- 设备设置：根据
device、multi_gpu、num_gpus配置初始化单卡/DDP 运行环境； - 配置解析：将
DictConfig解析为纯字典并记录到日志（recipe_logged_cfg）； - 实例化全部对象：调用
hydra.utils.instantiate(cfg)，把 YAML 中的_target_声明（如lr_updates的numpy.arange、strict_load的StrictLoad）实例化为真实对象； - 触发配置修改回调：执行
pre_launch_callbacks_list中注册的预启动回调； - 构建模型：通过
models.get(model_name=cfg.architecture, num_classes=cfg.arch_params.num_classes, ...)按architecture+arch_params构建网络，并按checkpoint_params加载权重； - 构建 DataLoader：通过
dataloaders.get(name=cfg.train_dataloader / cfg.val_dataloader, ...)实例化训练与验证加载器（以及可选的测试加载器）； - 启动训练：调用
trainer.train(model, train_loader, valid_loader, test_loaders, training_params=cfg.training_hyperparams, ...)。
可以看到，配方的四大配置段与architecture、train_dataloader、val_dataloader、experiment_name等根级键，正是沿着这条调用链被逐一消费的。理解了这条链路，就能理解为什么配方的结构约定如此重要。
结语与下一步
通过本教程，你已经掌握了 SuperGradients 训练配方的完整使用方式：
- 训练模型：用
.yaml配方一条命令启动训练，配方头部通常会自带可执行命令与性能说明； - 定制训练：通过 Hydra 命令行覆盖快速实验，或直接修改/组合配方文件固化方案；
- 理解配方结构：掌握
defaults组合机制、四大必备配置段、_self_与覆盖顺序，以及variable_setup快捷方式的底层实现。
配方是"声明式训练"的基石，而真正让配方动态实例化各类对象（模型、数据集、损失、优化器、回调）的，是 SuperGradients 的工厂（Factory）机制。下一步请继续阅读 Recipes_Factories.md，了解工厂如何与配方协同工作，从而为你的独特需求组装出更强大的训练流程。
【免费下载链接】super-gradientsEasily train or fine-tune SOTA computer vision models with one open source training library. The home of Yolo-NAS.项目地址: https://gitcode.com/GitHub_Trending/su/super-gradients
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
