SuperGradients 配置文件与 Recipes 完全指南：用 YAML 零代码编排训练全流程

SuperGradients 配置文件与 Recipes 完全指南：用 YAML 零代码编排训练全流程

【免费下载链接】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 配置体系的入门与进阶实战指南，围绕仓库中的 configuration_files.md 展开，系统讲解 YAML 配置文件（即 Recipes）的定位、写法、组合机制与命令行使用方式。读完本文，你将掌握用一条命令启动完整训练、通过 Hydra 覆盖任意参数、理解defaults组合与_self_覆盖优先级，并能结合仓库内置的 40+ 份示例 Recipe 快速搭建自己的训练配置。

配置文件与 Recipes：什么是训练"菜谱"

SuperGradients 支持使用 YAML 格式的配置文件。这些文件可以容纳训练超参数（learning-rate、weight-decay、epochs 等）、模型架构参数（block 类型、激活函数）、数据集参数以及训练过程所需的任何其他参数。配置文件被解析后，会以递归字典或函数实参的形式传递给 SuperGradients 的各个模块。

这些 YAML 文件就像训练模型的"菜谱"（cookbook），因此它们被称为Recipes。

SuperGradients 的设计目标之一，就是把尽可能多的参数暴露到配置层，让使用者不用写一行代码就能完成训练调整：你可以控制学习率、权重衰减，甚至更换损失函数、评估指标，进一步还能控制模型内部的 block 类型与激活函数——所有这些都可以在配置文件中定义。

以下是仓库中真实的训练超参数配置示例（节选自 cifar10_resnet_train_params.yaml）：

defaults: - default_train_params max_epochs: 250 lr_updates: _target_: numpy.arange start: 100 stop: 250 step: 50 lr_decay_factor: 0.1 lr_mode: StepLRScheduler lr_warmup_epochs: 0 initial_lr: 0.1 loss: CrossEntropyLoss optimizer: SGD criterion_params: {} optimizer_params: weight_decay: 1e-4 momentum: 0.9

注意lr_updates中的_target_: numpy.arange：这是 Hydra/OmegaConf 的"对象实例化"语法，配置不再只是静态数值，而是可以直接声明调用哪个 Python 函数/类并传入参数。_convert_: all则告知 Hydra 在加载时完成从字符串到 Python 对象的转换。

为什么使用配置文件

刚接触时，配置文件可能显得繁琐甚至冗余；但一旦开始管理多个实验，它的价值立刻显现：

1. 统一管理资产：数据集、模型和训练方案（recipes）集中存放。代码文件保持干净、不含参数，同一份代码可以借助不同配置构造出不同对象。下面的例子中，训练集与验证集共用同一段代码，仅配置不同（Imagenet 示例，出自原文档）：

train_dataset_params: root: /data/Imagenet/train transforms: - RandomResizedCropAndInterpolation: size: 224 interpolation: default - RandomHorizontalFlip - ToTensor - Normalize: mean: [0.485, 0.456, 0.406] # mean for normalization std: [0.229, 0.224, 0.225] # std for normalization val_dataset_params: root: /data/Imagenet/val transforms: - Resize: size: 256 - CenterCrop: size: 224 - ToTensor - Normalize: mean: [0.485, 0.456, 0.406] # mean for normalization std: [0.229, 0.224, 0.225] # std for normalization

transforms列表中的每一项（如RandomResizedCropAndInterpolation、Normalize）都是已注册对象的名称，SuperGradients 的工厂机制会自动实例化它们（详见下文"配置即对象"部分）。

2. 实验可追踪：每个实验的精确设置都被固化在配置中，方便微调、回放与分享。所有参数集中一处，实验的可见性与可控性大幅提升。

3. 零代码复用：同一套训练代码，通过切换 Recipe 即可在 Cifar10 分类、COCO 检测、Cityscapes 分割等任务间复用。

注意：使用 SuperGradients可以不依赖任何配置文件，仓库src/super_gradients/examples/目录下提供了纯代码方式（如 cifar10_training_torch_objects_example.py）的完整示例。

如何从配置文件启动训练

一条命令跑通 ResNet18 / Cifar10

进入仓库根目录，执行：

python -m super_gradients.train_from_recipe --config-name=cifar10_resnet

训练会启动，几个周期后即可用Ctrl+C停止。这条命令背后的入口脚本是 train_from_recipe.py，其核心逻辑极为精简：

from omegaconf import DictConfig import hydra 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()

cifar10_resnet这份 Recipe 位于 cifar10_resnet.yaml，文件头部注释给出了更完整的启动方式与预期精度（约 250 个 epoch 后达到 ~94.9% 准确率）：

# Instructions: # 0. Make sure that the data is stored in dataset_params.dataset_dir or add "dataset_params.data_dir=<PATH-TO-DATASET>" at the end of the command below # 1. Move to the project root # 2. Run the command: # python -m super_gradients.train_from_recipe --config-name=cifar10_resnet +experiment_name=cifar10 # # To use equivalent Albumentations transforms pipeline set dataset_params to cifar10_albumentations_dataset_params: # python -m super_gradients.train_from_recipe --config-name=cifar10_resnet dataset_params=cifar10_albumentations_dataset_params 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 train_dataloader: cifar10_train val_dataloader: cifar10_val architecture: resnet18_cifar experiment_name: resnet18_cifar_interpolation_check multi_gpu: Off num_gpus: 1

--config-name参数决定了加载哪份 Recipe。在src/super_gradients/recipes/目录下，还存放着大量预定义 Recipe：从 cifar10_resnet.yaml、coco2017_yolox.yaml 到 coco2017_yolo_nas_s.yaml、cityscapes_ddrnet.yaml 等，覆盖分类、检测、分割、姿态估计等多种任务；每个 Recipe 的头部注释通常都写明其预期性能与对应的启动命令。

Hydra：配置加载与组合的引擎

@hydra.main做了什么

Hydra 是开源的 Python 配置框架，SuperGradients 借助它完成两件事：把 YAML 文件加载为字典，以及实例化 YAML 中引用的对象。@hydra.main(config_path="recipes", version_base="1.2")装饰器会按照命令行中传入的--config-name在super_gradients.recipes目录中查找同名 YAML 文件并加载为DictConfig：

import hydra from omegaconf import DictConfig @hydra.main(config_path="recipes", version_base="1.2") def main(cfg: DictConfig) -> None: print(cfg.experiment_name)

输出目录与.hydra子目录

每次运行时，Hydra 会在实验目录（默认由ckpt_root_dir与experiment_name决定）下创建.hydra子目录，把本次运行实际使用的全部配置快照保存其中，实现"实验可复现"。

两个必须掌握的 Hydra 特性

1. 命令行覆盖（Command-Line Overrides）：不修改任何 YAML，直接在命令行覆盖任意参数，例如training_hyperparams.initial_lr=0.03；
2. YAML 组合（Composition）：通过defaults列表把多份 YAML 拼接成一份完整配置——这正是 Recipe 体系的核心机制，下一节详细展开。

Recipe 结构剖析：defaults 组合与四大参数块

必备的四个参数块

一份标准 Recipe（SuperGradients 格式）由以下必需部分构成：

根级字段architecture指定具体模型（如resnet18_cifar），arch_params则提供该架构的构造参数，二者配套使用。train_dataloader/val_dataloader是可选的便捷字段，用于结合dataset_params实例化训练/验证 DataLoader。

defaults 组合与_self_的优先级

以 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

要点：

• defaults顺序即优先级顺序：列表中越靠后的条目优先级越高。因此_self_（当前文件自身）放在默认项之后，当前 Recipe 才能覆盖各默认块；variable_setup必须是列表最后一项（其作用见下文"快捷覆盖"）。
• 引用方式：training_hyperparams.initial_lr即指向cifar10_resnet_train_params.yaml中的initial_lr参数，这构成了跨文件的参数引用语法。
• 目录约定：为配合上述组合，Recipe 目录建议按如下结构组织（仓库 recipes 目录即遵循此约定）：

├─ 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 的默认解析逻辑无缝兼容。

训练超参数速查（default_train_params）

default_train_params.yaml 是所有训练配置的"地基"，其中常用的关键参数包括：

• 学习率调度：lr_mode支持StepLRScheduler、PolyLRScheduler、CosineLRScheduler、ExponentialLRScheduler、FunctionLRScheduler；lr_updates（配合step_lr_update_freq）、lr_decay_factor、lr_warmup_epochs、lr_cooldown_epochs、warmup_initial_lr、cosine_final_lr_ratio等；
• 优化器与损失：optimizer（Adam/SGD/RMSProp）、optimizer_params、loss、criterion_params、zero_weight_decay_on_bias_and_bn；
• 训练控制：max_epochs、batch_accumulate、run_validation_freq、seed（默认 42，保证可复现）、resume/resume_path/ckpt_name；
• 指标与检查点：train_metrics_list/valid_metrics_list、metric_to_watch（默认Accuracy）、greater_metric_to_watch_is_better、ckpt_best_name（默认ckpt_best.pth）；
• 工程化选项：ema（指数移动平均，默认关闭）、mixed_precision、sync_bn、precise_bn、torch_compile（需 PyTorch 2.0）、phase_callbacks、sg_logger与sg_logger_params（TensorBoard/WandB/Deci 平台）、clip_grad_norm。

数据集配置示例

cifar10_dataset_params.yaml 展示了完整的 dataset_params 写法——训练与验证分别定义变换、dataloader 参数：

train_dataset_params: root: ./data/cifar10 train: True transforms: - RandomCrop: size: 32 padding: 4 - RandomHorizontalFlip - ToTensor - Normalize: mean: [0.4914, 0.4822, 0.4465] std: [0.2023, 0.1994, 0.2010] target_transform: null download: True train_dataloader_params: shuffle: True batch_size: 256 num_workers: 8 drop_last: False pin_memory: True val_dataset_params: root: ./data/cifar10 train: False transforms: - Resize: size: 32 - ToTensor - Normalize: mean: [0.4914, 0.4822, 0.4465] std: [0.2023, 0.1994, 0.2010] target_transform: null download: True val_dataloader_params: batch_size: 512 num_workers: 8 drop_last: False pin_memory: True

命令行覆盖：不改文件改参数

通用覆盖语法

Hydra 覆盖的通用语法为：

python -m super_gradients.train_from_recipe --config-name=<config-name> param1=<val1> path.to.param2=<val2>

• 参数不带--前缀；
• 用.分隔配置树中的每一级路径。

例如修改 epochs 与学习率、更换数据集路径：

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>

再如 COCO 检测任务（8 卡训练 YoloX-Small）：

python -m super_gradients.train_from_recipe --config-name=coco2017_yolox architecture=yolox_s dataset_params.data_dir=/home/coco2017

注意：不同 Recipe 的参数命名可能有差异，使用前请先查看目标 Recipe 以确认正确的参数路径。

快捷覆盖：variable_setup 与内置短路参数

完整路径写起来冗长（例如改 batch size 要同时写训练与验证两条路径）。为此，variable_setup.yaml 定义了一组"快捷参数"，通过 Hydra CallbackRecipeShortcutsCallback（实现位于 omegaconf_utils.py）在加载时自动展开：

使用这些快捷参数的前提是 Recipe 的defaults中包含了variable_setup，且它必须位于列表最后。例如：

python -m super_gradients.train_from_recipe --config-name=cifar10_resnet lr=0.03 epochs=50 bs=128 num_workers=4

配置即对象：工厂与实例化机制

配置文件中出现的类名（如CrossEntropyLoss、RandomCrop、SGD）都依赖 SuperGradients 的工厂（Factories）与注册机制才能从字符串变成真实对象。以变换为例，Recipes_Factories.md 说明：对象（如SegColorJitter）先被register_transform注册到名称映射表，配置加载后由TransformsFactory依据映射实例化：

from super_gradients.common.registry import register_transform @register_transform(name="MyTransformName") class MyTransform: def __init__(self, prob: float): ...

注册后即可在 Recipe 中直接使用MyTransformName，并配合@resolve_param装饰器让函数同时接受"对象实例"或"配置字典"两种输入。SuperGradients 提供的注册装饰器非常丰富，涵盖模型、损失、指标、优化器、数据集、dataloader、回调、变换、采样器、LR 调度器等，详见 factories 模块。这一机制让"配置文件定义对象"成为可能，是 Recipes 体系区别于普通参数文件的根本所在。

自定义 Recipe：两种路径

如果你需要自己的训练配置，可以走两条路（详见 Recipes_Custom.md）：

1. SuperGradients 格式（推荐快速上手）：从 recipes 中挑选最接近你任务的 Recipe，复制到项目内专属 recipes 目录并改写参数；然后把 train_from_recipe.py 复制到项目，将config_path="recipes"改为你的配置目录路径，即可直接复用Trainer.train_from_config(cfg)一键启动。

2. 完全自定义格式：不受 SuperGradients 结构约束，但需自己在脚本中实例化所有对象。此时仍需保证training_hyperparams包含与默认格式一致的必填字段，且传给dataloaders.get的配置与目标数据集/加载器兼容。仓库 train_from_recipe_with_user_objects 示例 展示了这种手动装配 Trainer、模型与 DataLoader 的写法。

另外，借助 Hydra 的searchpath，你可以让自己的 Recipe 构建在 SuperGradients 预定义 Recipe 之上：

defaults: - training_hyperparams: default_train_params hydra: searchpath: - pkg://super_gradients.recipes ... # Continue with your recipe

小结与延伸阅读

回顾本文要点：

• Recipes 概述：YAML 格式的配置文件，集中定义数据集、模型与训练超参数，充当训练"菜谱"；
• SuperGradients 的用法：@hydra.main+Trainer.train_from_config将配置直接转为训练，defaults组合与工厂注册机制带来高度的可复用性、可复现性与灵活性；
• 实战上手：python -m super_gradients.train_from_recipe --config-name=cifar10_resnet一行启动训练，配合 Hydra 覆盖与快捷参数即时调整实验。

如果想继续深入，建议按顺序阅读同系列文档：

• Recipes_Training.md：更完整的训练启动方式与 Recipe 结构讲解；
• Recipes_Factories.md：工厂与对象实例化的底层原理；
• Recipes_Custom.md：编写自定义 Recipe 的完整实战；
• Data.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