# HParams

多年来，随着库和模型的不断演进，许多 `timm` 模型都使用不同的超参数进行了训练。我并没有记录每一个实例，但已记录了其中许多实例，它们可以作为非常好的起点。

从已记录运行的[config 文件 gists](#config-file-gists)开始，或者使用下方[选定的配方](#selected-recipes)中可复制到 YAML 文件的配置。[训练脚本示例](training_script#imagenet-training-recipes)展示了它们的命令行等效形式。

## 标签

大多数 `timm` 训练模型在其预训练标签中都有一个标识符，用于将其（大致）关联到我多年来使用过的超参数家族/版本。

配方族是一个提示，而非完整的配置。在选择配置时，请匹配完整的检查点名称、训练数据集和分辨率。例如，`vit_medium_patch16_reg4_gap_256.sbb_in1k` 是在 ImageNet-1k 上训练的，而 `.sbb_in12k_ft_in1k` 表示先在 ImageNet-12k 上进行预训练，然后在 ImageNet-1k 上进行微调。某些标签编码的是训练计划和分辨率，而非配方族名称：MobileNetV4 的 `e500_r256_in1k` 属于 `ra4` 族，尽管标签中未包含 `ra4`。

| 标签 | 描述 | 优化器 | 学习率调度 | 其他说明 |
|--------|-------------|-----------|-------------|-------------|
| `a1h` | 基于 [ResNet Strikes Back](https://arxiv.org/abs/2110.00476) `A1` 配方 | LAMB | 带预热阶段的余弦 | 比论文 `A1` 方案更强的 dropout、随机深度和 RandAugment |
| `ah` | 基于 [ResNet Strikes Back](https://arxiv.org/abs/2110.00476) `A1` 配方 | LAMB | 带预热阶段的余弦 | 未使用 CutMix。比论文 `A1` 配方中更强的 dropout、随机深度和 RandAugment |
| `a1`, `a2`, `a3` | ResNet 强势回归 `A{1,2,3}` 配方 | 采用 BCE 损失的 LAMB | 带预热阶段的余弦 | — |
| `b1`, `b2`, `b1k`, `b2k` | 基于 [ResNet Strikes Back](https://arxiv.org/abs/2110.00476) `B` 配方（相当于 `timm` `RA2` 配方） | RMSProp（TF 1.0 行为） | 带预热（阶梯式指数衰减）的 Step | — |
| `c`, `c1`, `c2`, `c3` | 基于 [ResNet Strikes Back](https://arxiv.org/abs/2110.00476) `C` 配方 | SGD（Nesterov）与 AGC | 带预热阶段的余弦 | — |
| `ch` | 基于 [ResNet Strikes Back](https://arxiv.org/abs/2110.00476) `C` 配方 | SGD（Nesterov）与 AGC | 带预热阶段的余弦 | 比论文`C1`/`C2`配方更强的 dropout、随机深度和 RandAugment |
| `d`, `d1`, `d2` | 基于 [ResNet Strikes Back](https://arxiv.org/abs/2110.00476) `D` 配方 | 采用 BCE 损失的 AdamW | 带预热阶段的余弦 | — |
| `sw` | DeiT / Swin 风格的训练/预训练方案，同样适用于 ConvNeXt 和混合模型 | AdamW，通常配合梯度裁剪 | 带预热阶段的余弦 | EMA 因运行而异 |
| `sbb` | [寻找更好的 ViT 基线](https://huggingface.co/blog/rwightman/vit-sbb-imagenet-full) | AdamW 或 NAdamW | 带预热阶段的余弦 | 重复增强；用于微调的层衰减 |
| `ra`, `ra2`, `ra3`, `racm`, `raa` | RandAugment 配方。受 EfficientNet 的 RandAugment 配方启发。涵盖在 [ResNet Strikes Back](https://arxiv.org/abs/2110.00476) 中的 `B` 配方中。 | RMSProp（TF 1.0 行为），EMA | 带预热（阶梯式指数衰减）的 Step | — |
| `ra4` | RandAugment v4。灵感来自 MobileNetV4 超参数。 | AdamW 或 NAdamW，EMA | 带预热阶段的余弦 | 包含长周期 ResNet 训练方案；不同模型的优化器 betas 参数有所不同 |
| `am` | AugMix 配方 | 使用 JSD 损失的 SGD（Nesterov） | 带预热阶段的余弦 | — |
| `ram` | AugMix（搭配 RandAugment）配方 | 使用 JSD 损失的 SGD（Nesterov） | 带预热阶段的余弦 | — |
| `bt` | Bag-of-Tricks 配方 | SGD（Nesterov） | 带预热阶段的余弦 | — |

## 配置文件 Gists

这些集合包含已记录的 YAML 配置文件，其中包括针对原始机器和训练脚本版本的特定设置。打开一个 gist，选择某个模型的 YAML 文件，并使用 **Raw** 将其保存到本地。

| Gist 集合 | 配方系列 | 内容和原始设置 |
|-----------------|---------------|-----------------------------|
| [MobileNetV4 和长周期 ResNets](https://gist.github.com/rwightman/f6705cb65c03daeebca8aa129b1b94ad) | `ra4` | Conv 和混合 MobileNetV4 的运行结果；GPU 数量包含在文件名中。此外还包括 3600 个 epoch 的 ResNet 配置。 |
| [寻找更好的 ViT 基线](https://gist.github.com/rwightman/fb37c339efd2334177ff99a8083ebbc4) | `sbb` | ImageNet-1k 训练、ImageNet-12k 预训练以及微调；每个文件中指定的 2 或 4 个 GPU。 |
| [ConvNeXt 的训练与微调](https://gist.github.com/rwightman/ee0b02c1e99a0761264d1d1319e95e5b) | ConvNeXt 配方 | 在 4 个 GPU 上进行 Atto/Nano 训练；在 8 个 GPU 上进行 Tiny/Small 的 ImageNet-12k 到 ImageNet-1k 微调。 |
| [ViT、ConvNeXt、CoAtNet 和 MaxViT](https://gist.github.com/rwightman/943c0fe59293b44024bbd2d5d23e6303) | DeiT / Swin 风格 | 混合训练和微调配置；4–8 个 GPU 或 TPU 设备。许多使用 TFDS。 |
| [ResNet-D 和 ECA-ResNet RA2](https://gist.github.com/rwightman/07839a82d0f50e42840168bc43df70b3) | `ra2` | ResNet-18D/34D/50D 和 ECA-ResNet-26D；2 个 GPU，显式学习率。 |
| [RegNet 和 RegNetZ](https://gist.github.com/rwightman/37252f8d7d850a94e43f1fcb7b3b8322) | `ra3`，SGD + AGC | 8 个 TPU 核心。部分文件是包含 `model: xxx` 的模板；README 指出 RegNetY-064 存在配方/检查点不匹配的问题。 |
| [采用自适应梯度裁剪的 NFNet](https://gist.github.com/rwightman/e69d5f456047c16773a77182cea68c3c) | SGD + AGC | `nfnet.yaml` 中的历史 ECA-NFNet-L1 配置；使用 Apex `fusedsgd`。 |
| [TPU 上的 MLP 模型](https://gist.github.com/rwightman/d6c264a9001f9167e06c209f630b2cc6) | AdamW | 与实验性分支 `bits_and_tpu` 关联的历史 gMLP、gMixer 和 ResMLP 运行记录。 |
| [小型测试模型](https://gist.github.com/rwightman/9ba8efc39a546426e99055720d2f705f) | 基于 MobileNetV4 | 使用 1600–1800 个 epoch 的训练计划，测试小型 ViT 和 ConvNeXt 模型。 |

### 适配已记录的配置

通过 `--config hparams.yaml` 传入本地文件；命令行参数会覆盖其中的值。有关详细信息，请参阅 [配置文件](training_script#config-files)。

* 为机器设置 `--data-dir`。对于 ImageFolder 数据集，还需使用 `--dataset imagefolder/` 覆盖已保存的 TFDS 数据集。训练要求在 `train/` 和 `validation/` 下存在类别子文件夹（或使用 `--val-split` 选择验证目录）。
* 请检查 `model`、`pretrained`、`num_classes` 以及任何检查点路径。微调配置需要其原始的预训练检查点；仅凭架构名称，如今可能会选择不同的默认权重。
* 旧文件可能包含已移除的选项，例如 `apex_amp`、`native_amp`、`amp_impl` 或 `force_cpu`。当前的 `train.py` 会对未知键发出警告。以下内联配置使用的是当前选项。旧的 `fusedadamw` / `fusedsgd` 优化器名称指的是 Apex 实现；将其切换为 `adamw` / `sgd` 是对该运行的一次适配。

对于固定大小的训练，有效全局批处理大小为：

```text
batch_size × number of training processes × grad_accum_steps
```

`batch_size` is per process (normally one GPU). A nonzero `lr` is used directly and is **not** automatically rescaled. With `lr` unset (`null` in YAML), `lr_base` is scaled relative to `lr_base_size`. Set `lr_base_scale: sqrt` for the AdamW/NAdamW recipes below; linear scaling is commonly used for SGD/RMSProp. Large batch-size changes still need tuning. Gradient accumulation preserves the effective batch size but does not enlarge the batch seen by BatchNorm.

对于余弦调度，`warmup_prefix: true` 会在 `epochs` 调度之前添加预热阶段；`cooldown_epochs` 会在末尾添加一个处于最小学习率的阶段。在适配旧运行时，请保留这些设置。

## 精选配方

这些示例保留了特定 gist 文件中的训练设置，并省略了机器路径和未使用的选项。模型标签用于固定预处理配置；仅当 `pretrained: true` 时才会加载权重。下方的参考准确率是对 [results-imagenet.csv](https://github.com/huggingface/pytorch-image-models/blob/main/results/results-imagenet.csv) 中已发布检查点的评估结果，而非重新运行这些示例所得到的测量值。在比较结果时，分辨率和验证裁剪方式至关重要。

| 已发布的检查点 | 训练 | 评估大小 / 裁剪 | ImageNet-1k top-1 |
|----------------------|----------|------------------------|------------------|
| [mobilenetv4_conv_medium.e500_r256_in1k](https://huggingface.co/timm/mobilenetv4_conv_medium.e500_r256_in1k) | ImageNet-1k，256px | 256 / 0.95; 320 / 1.0 | 79.916%; 80.890% |
| [vit_medium_patch16_reg4_gap_256.sbb_in1k](https://huggingface.co/timm/vit_medium_patch16_reg4_gap_256.sbb_in1k) | ImageNet-1k，256px | 256 / 0.95 | 83.466% |
| [convnext_tiny.in12k_ft_in1k](https://huggingface.co/timm/convnext_tiny.in12k_ft_in1k) | ImageNet-12k → ImageNet-1k，224px | 224 / 0.95; 288 / 1.0 | 84.192%; 84.448% |

### MobileNetV4 Conv Medium

源文件：[mnv4_cm_r256_e500_gpu2.yaml](https://gist.github.com/rwightman/f6705cb65c03daeebca8aa129b1b94ad#file-mnv4_cm_r256_e500_gpu2-yaml)。原始运行使用了 2 个 GPU × 512 张图像 = 1024 的全局 batch，学习率固定为 0.002。调度策略为 20 个 warmup epoch，随后是 500 个 cosine epoch（共 520 个 epoch）。保存为 `mobilenetv4.yaml`：

```yaml
model: mobilenetv4_conv_medium.e500_r256_in1k
pretrained: false
img_size: 256
crop_pct: 0.95
batch_size: 512
opt: adamw
lr: 0.002
weight_decay: 0.1
clip_grad: 5.0
sched: cosine
sched_on_updates: true
epochs: 500
warmup_epochs: 20
warmup_prefix: true
warmup_lr: 0.0
min_lr: 0.0
cooldown_epochs: 0
aa: rand-m8-inc1-mstd1.0
mixup: 0.2
mixup_prob: 0.8
smoothing: 0.1
reprob: 0.25
remode: pixel
drop: 0.2
drop_path: 0.1
model_ema: true
model_ema_decay: 0.9998
model_ema_warmup: true
dist_bn: reduce
amp: true
amp_dtype: bfloat16
torchcompile: inductor
```

此示例与源运行一样使用 bfloat16 AMP；在不支持 bfloat16 的 GPU 上，请使用 `--amp-dtype float16`。如果不需要编译，可以省略 `torchcompile`。

### 带寄存器（registers）的 ViT Medium

来源：[train-vit_medium_reg4-4gpu-in1k.yaml](https://gist.github.com/rwightman/fb37c339efd2334177ff99a8083ebbc4#file-train-vit_medium_reg4-4gpu-in1k-yaml)，也可作为检查点的 [train_hparams.yaml](https://huggingface.co/timm/vit_medium_patch16_reg4_gap_256.sbb_in1k/blob/main/train_hparams.yaml)。该 SBB 运行使用了 4 个 GPU × 256 张图像 = 1024 的全局批次。平方根缩放给出 `0.0008 × sqrt(1024 / 512) ≈ 0.001131`。其 600 个 epoch 包含预热，并额外增加了 10 个冷却 epoch。保存为 `vit-medium.yaml`：

```yaml
model: vit_medium_patch16_reg4_gap_256.sbb_in1k
pretrained: false
model_kwargs:
  fix_init: true
head_init_scale: 0.0
img_size: 256
crop_pct: 0.95
batch_size: 256
opt: adamw
opt_eps: 1.0e-8
lr: null
lr_base: 0.0008
lr_base_size: 512
lr_base_scale: sqrt
weight_decay: 0.07
clip_grad: 5.0
sched: cosine
sched_on_updates: true
epochs: 600
warmup_epochs: 20
warmup_prefix: false
warmup_lr: 5.0e-7
min_lr: 5.0e-7
cooldown_epochs: 10
aa: rand-m7-inc1-mstd1.0-n3
aug_repeats: 3
color_jitter: 0.0
mixup: 0.8
cutmix: 1.0
smoothing: 0.1
reprob: 0.2
remode: pixel
drop_path: 0.2
model_ema: false
seed: 0
amp: true
amp_dtype: float16
torchcompile: inductor
```

初始化设置（`fix_init` 和零初始化的分类器）是该配方的一部分。本次运行使用了 AdamW，未使用 EMA；其他 SBB 文件则使用 NAdamW 或不同的预训练设置。

### ConvNeXt Tiny 微调

源文件：[hparams_84_00-convnext_tiny.in12k-args.yaml](https://gist.github.com/rwightman/ee0b02c1e99a0761264d1d1319e95e5b#file-hparams_84_00-convnext_tiny-in12k-args-yaml)。从 [convnext_tiny.in12k](https://huggingface.co/timm/convnext_tiny.in12k) 开始，将其分类器替换为 1000 个类别，并在 ImageNet-1k 上进行微调。原始运行使用了 8 个 GPU × 512 张图像 = 4096 的全局批次，以及固定的学习率 0.0001。它包含 75 个 epoch（含 warmup），外加 10 个 cooldown epoch。源文件使用 1.0 的裁剪进行评估；上述检查点的基准测试结果使用了所注明的评估裁剪。保存为 `convnext-tiny-ft.yaml`：

```yaml
model: convnext_tiny.in12k
pretrained: true
num_classes: 1000
img_size: 224
crop_pct: 1.0
batch_size: 512
grad_checkpointing: true
opt: adamw
lr: 0.0001
weight_decay: 0.05
layer_decay: 0.75
clip_grad: 3.0
sched: cosine
sched_on_updates: false
epochs: 75
warmup_epochs: 10
warmup_prefix: false
warmup_lr: 1.0e-6
min_lr: 5.0e-7
cooldown_epochs: 10
lr_noise: [0.1, 1.0]
aa: rand-m8-inc1-mstd101
mixup: 0.8
cutmix: 1.0
smoothing: 0.1
reprob: 0.3
remode: pixel
drop_path: 0.1
model_ema: true
model_ema_decay: 0.9998
amp: true
amp_dtype: float16
```

例如，使用以下命令启动已保存的 MobileNetV4 配置：

```bash
torchrun --standalone --nproc_per_node=2 train.py \
  --config mobilenetv4.yaml --data-dir /data/imagenet --experiment mobilenetv4-cm
```

对于 `vit-medium.yaml` 使用 4 个进程，对于 `convnext-tiny-ft.yaml` 使用 8 个进程，以匹配原始的全局批次大小，或者根据您的硬件调整批次大小、累积和 LR。