Hugging Face's logo

Transformers documentation

优化

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

优化

.optimization 模块提供：

  • 一种权重衰减固定的优化器，可用于微调模型，以及
  • 多个以继承自 _LRSchedule 的调度对象形式存在的调度：
  • 一个梯度累积类，用于累积多个批次的梯度

AdaFactor

class transformers.Adafactor

< >

( paramslr = Noneeps = (1e-30, 0.001)clip_threshold = 1.0decay_rate = -0.8beta1 = Noneweight_decay = 0.0scale_parameter = Truerelative_step = Truewarmup_init = False )

参数

  • params (Iterable[nn.parameter.Parameter]) — 要优化的参数迭代器，或定义参数组的字典。
  • lr (float, 可选) — 外部学习率。
  • eps (tuple[float, float]，可选，默认为 (1e-30, 0.001)) — 分别用于平方梯度和参数尺度的正则化常数
  • clip_threshold (float，可选，默认为 1.0) — 最终梯度更新的均方根阈值
  • decay_rate (float，可选，默认值为 -0.8) — 用于计算平方运行平均值的系数
  • beta1 (float, 可选) — 用于计算梯度移动平均的系数
  • weight_decay (float，可选，默认值为 0.0) — 权重衰减（L2 惩罚）
  • scale_parameter (bool，可选，默认为 True) — 如果为 True，学习率将按均方根进行缩放
  • relative_step (bool，可选，默认为 True) — 如果为 True，则计算基于时间的学习率，而不是使用外部学习率
  • warmup_init（bool，可选，默认为 False）— 基于时间的学习率计算取决于是否使用了预热初始化

AdaFactor 的 PyTorch 实现可以直接替换 Adam，原始 fairseq 代码：https://github.com/pytorch/fairseq/blob/master/fairseq/optim/adafactor.py

论文：Adafactor: Adaptive Learning Rates with Sublinear Memory Cost https://huggingface.co/papers/1804.04235 请注意，该优化器会根据 scale_parameter、relative_step 和 warmup_init 选项在内部调整学习率。若要使用手动（外部）学习率调度，应将 scale_parameter=False 和 relative_step=False 设置为 False。

此实现支持低精度（FP16、bfloat）值，但我们尚未对其进行充分测试。

推荐的 T5 微调设置（https://discuss.huggingface.co/t/t5-finetuning-tips/684/3）：

  • 不建议在不使用 LR warmup 或 clip_threshold 的情况下进行训练。

  • 禁用相对更新

  • 使用 scale_parameter=False

  • 诸如梯度裁剪之类的额外优化器操作不应与 Adafactor 同时使用

示例：

Adafactor(model.parameters(), scale_parameter=False, relative_step=False, warmup_init=False, lr=1e-3)

其他人报告了以下组合效果良好：

Adafactor(model.parameters(), scale_parameter=True, relative_step=True, warmup_init=True, lr=None)

使用 Trainer 时，如果设置 lr=None，通常需要使用 AdafactorSchedule。

调度器如下：

from transformers.optimization import Adafactor, AdafactorSchedule

optimizer = Adafactor(model.parameters(), scale_parameter=True, relative_step=True, warmup_init=True, lr=None)
lr_scheduler = AdafactorSchedule(optimizer)
trainer = Trainer(..., optimizers=(optimizer, lr_scheduler))

用法：

# replace AdamW with Adafactor
optimizer = Adafactor(
    model.parameters(),
    lr=1e-3,
    eps=(1e-30, 1e-3),
    clip_threshold=1.0,
    decay_rate=-0.8,
    beta1=None,
    weight_decay=0.0,
    relative_step=False,
    scale_parameter=False,
    warmup_init=False,
)

步骤

< >

( closure = None )

参数

  • closure（可调用对象，可选）— 一个闭包，用于重新评估模型并返回损失。

执行单个优化步骤

计划

SchedulerType

类 transformers.SchedulerType

< >

( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1boundary = None )

lr_scheduler_type 参数在 TrainingArguments 中可用的调度器名称。 默认情况下，它使用 “linear”。内部实现中，这将从 Trainer 中获取 get_linear_schedule_with_warmup 调度器。 调度器类型：

get_scheduler

transformers.get_scheduler

< >

( name: str | SchedulerTypeoptimizer: Optimizernum_warmup_steps: int | None = Nonenum_training_steps: int | None = Nonescheduler_specific_kwargs: dict | None = None )

参数

  • name (str 或 SchedulerType) — 要使用的调度器名称。
  • optimizer (torch.optim.Optimizer) — 训练期间将使用的优化器。
  • num_warmup_steps (int, 可选) — 预热步数。并非所有调度器都需要此参数（因此该参数为可选），如果未设置且调度器类型要求该参数，函数将抛出错误。
  • num_training_steps (`int“, 可选) — 要执行的训练步数。并非所有调度器都要求此参数（因此该参数是可选的），如果未设置且调度器类型需要该参数，函数将引发错误。
  • scheduler_specific_kwargs (dict, 可选) — 用于调度器的额外参数，例如带重启的余弦调度器。调度器类型与调度器参数不匹配会导致调度器函数抛出 TypeError。

统一 API，用于根据名称获取任意调度器。

get_constant_schedule

transformers.get_constant_schedule

< >

( optimizer: Optimizerlast_epoch: int = -1 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。

使用优化器中设置的学习率，创建一个恒定学习率的调度器。

get_constant_schedule_with_warmup

transformers.get_constant_schedule_with_warmup

< >

( optimizer: Optimizernum_warmup_steps: intlast_epoch: int = -1 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。

创建一个学习率调度器，其学习率保持恒定，但在之前有一个预热阶段，在该阶段中，学习率从 0 线性增加到优化器中设置的初始学习率。

get_cosine_schedule_with_warmup

transformers.get_cosine_schedule_with_warmup

< >

( optimizer: Optimizernum_warmup_steps: intnum_training_steps: intnum_cycles: float = 0.5last_epoch: int = -1 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • num_training_steps (int) — 训练步数的总数。
  • num_cycles (float，可选，默认值为 0.5) — 余弦调度中的波数（默认行为是遵循半余弦曲线，从最大值递减至 0）。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。

创建一个学习率调度器，在预热阶段，学习率从 0 线性增加到优化器中设置的初始学习率；预热结束后，学习率按照余弦函数的值，从优化器中设置的初始学习率逐渐衰减至 0。

get_cosine_with_hard_restarts_schedule_with_warmup

transformers.get_cosine_with_hard_restarts_schedule_with_warmup

< >

( optimizer: Optimizernum_warmup_steps: intnum_training_steps: intnum_cycles: int = 1last_epoch: int = -1 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • num_training_steps (int) — 训练步数的总数。
  • num_cycles (int，可选，默认为 1) — 要使用的硬重启次数。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。

创建一个学习率调度器，其学习率按照余弦函数的值，从优化器中设置的初始学习率衰减至 0，并包含多次硬重启；在此之前有一个预热阶段，学习率在该阶段内从 0 线性增加到优化器中设置的初始学习率。

get_cosine_with_min_lr_schedule_with_warmup

transformers.get_cosine_with_min_lr_schedule_with_warmup

< >

( optimizer: Optimizernum_warmup_steps: intnum_training_steps: intnum_cycles: float = 0.5last_epoch: int = -1min_lr: float | None = Nonemin_lr_rate: float | None = None )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • num_training_steps (int) — 训练步数的总数。
  • num_cycles (float，可选，默认值为 0.5) — 余弦调度中的波数（默认行为是遵循半余弦曲线，从最大值递减至 0）。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。
  • min_lr (float, 可选) — 余弦调度结束后要达到的最小学习率。
  • min_lr_rate (float, 可选) — 作为初始学习率的比例的最小学习率。如果设置了该参数，则不应设置 min_lr。

创建一个学习率调度器，其学习率按照余弦函数的值从优化器中设置的初始学习率衰减至 min_lr，在此之前经历一个预热阶段，在该阶段中学习率从 0 线性增加到优化器中设置的初始学习率。

get_cosine_with_min_lr_schedule_with_warmup_lr_rate

transformers.get_cosine_with_min_lr_schedule_with_warmup_lr_rate

< >

( optimizer: Optimizernum_warmup_steps: intnum_training_steps: intnum_cycles: float = 0.5last_epoch: int = -1min_lr: float | None = Nonemin_lr_rate: float | None = Nonewarmup_lr_rate: float | None = None )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • num_training_steps (int) — 训练步数的总数。
  • num_cycles (float，可选，默认值为 0.5) — 余弦调度中的波数（默认行为是遵循半余弦曲线，从最大值递减至 0）。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。
  • min_lr (float, 可选) — 余弦调度结束后要达到的最小学习率。
  • min_lr_rate (float, 可选) — 作为初始学习率的比例的最小学习率。如果设置了该参数，则不应设置 min_lr。
  • warmup_lr_rate (float, 可选) — 作为起始学习率比例的最小学习率。如果未设置，warmup_lr_rate 将被视为 float(1/num_warmup_steps)。

创建一个学习率调度器，其学习率按照余弦函数的值从优化器中设置的初始学习率衰减至 min_lr，在此之前经历一个预热阶段，在该阶段中学习率从 0 线性增加到优化器中设置的初始学习率。

GreedyLR

class transformers.GreedyLR

< >

( optimizer: Optimizermode: str = 'min'factor: float = 0.95patience: int = 10threshold: float = 1e-06threshold_mode: str = 'abs'cooldown: int = 0warmup: int = 0min_lr: float | list[float] = 0.001max_lr: float | list[float] = 1.0eps: float = 1e-08verbose: bool = Falsesmooth: bool = Falsewindow_size: int = 50reset_start: int = 500 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • mode (str，可选，默认为 "min") — 取值为 ‘min’ 或 ‘max’ 之一。在 ‘min’ 模式下，当指标停止下降时，学习率（LR）将被降低；在 ‘max’ 模式下，当指标停止上升时，学习率将被降低。
  • factor (float, 可选，默认为 0.95) — 用于调整学习率的因子。在平台期，学习率乘以 factor；在改进时，学习率除以 factor。必须 < 1.0。
  • patience (int，可选，默认为 10) — 在调整学习率之前，允许连续多少个 epoch 没有改进。
  • threshold (float，可选，默认值为 1e-06) — 用于衡量新最优值的阈值。
  • threshold_mode (str，可选，默认为 "abs") — 取值为 ‘rel’ 或 ‘abs’ 之一。
  • cooldown (int，可选，默认为 0) — 在降低学习率后，恢复正常训练前需要等待的 epoch 数。
  • warmup（int，可选，默认为 0）—— 在 LR 提升后，恢复正常操作前需要等待的 epoch 数。
  • min_lr (float 或 list[float]，可选，默认值为 0.001) — 学习率的下限。
  • max_lr（float 或 list[float]，可选，默认为 1.0）—— 学习率的上限。
  • eps (float，可选，默认为 1e-08) — 应用于学习率的最小衰减。
  • verbose (bool，可选，默认为 False) — 如果为 True，则每次更新时向 stdout 打印一条消息。
  • smooth (bool，可选，默认为 False) — 如果为 True，则对指标应用流式平均平滑。
  • window_size (int，可选，默认为 50) — 当 smooth=True 时，流式平均的窗口大小。
  • reset_start (int, 可选，默认为 500) — 在重置为初始状态之前，在 min_lr 处等待的步数。

一种根据训练指标做出响应的自适应学习率调度器。

GreedyLR 会根据训练表现动态调整学习率：

  • 当指标持续改善时，增加学习率（除以因子）
  • 当指标趋于平稳时降低学习率（乘以指定因子）

这与余弦退火等传统调度器不同，它根据实际的训练动态做出响应，而不是遵循预设的调度计划。

参考文献：GreedyLR: A Novel Adaptive Learning Rate Scheduler <https://arxiv.org/abs/2512.14527>_

示例：

>>> optimizer = torch.optim.SGD(model.parameters(), lr=0.1)
>>> scheduler = GreedyLR(optimizer, mode="min", patience=10)
>>> for epoch in range(100):
...     train(...)
...     val_loss = validate(...)
...     scheduler.step(val_loss)

get_last_lr

< >

( )

返回当前调度器最后计算的学习率。

load_state_dict

< >

( state_dict: dict[str, Any] )

从字典加载状态。

state_dict

< >

( )

以字典形式返回调度器的状态。

步骤

< >

( metrics: floatepoch: int | None = None )

参数

  • metrics (float) — 用于学习率调整决策的指标值。
  • epoch (int，可选) — 当前 epoch 编号。如果为 None，则使用内部计数器。

根据给定的指标执行一次调度器步骤。

get_greedy_schedule

transformers.get_greedy_schedule

< >

( optimizer: Optimizer**kwargs )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • kwargs (dict，可选) — 传递给调度器的额外参数。有关可能的参数，请参阅 GreedyLR。

创建一个自适应学习率调度器，根据训练指标调整 LR。

get_linear_schedule_with_warmup

transformers.get_linear_schedule_with_warmup

< >

( optimizernum_warmup_stepsnum_training_stepslast_epoch = -1 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • num_training_steps (int) — 训练步数的总数。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。

创建一个学习率调度器，在预热阶段内，学习率从 0 线性增加到优化器中设置的初始学习率；预热结束后，学习率从该初始值线性衰减至 0。

get_polynomial_decay_schedule_with_warmup

transformers.get_polynomial_decay_schedule_with_warmup

< >

( optimizernum_warmup_stepsnum_training_stepslr_end = 1e-07power = 1.0last_epoch = -1 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • num_training_steps (int) — 训练步数的总数。
  • lr_end (float，可选，默认为 1e-7) — 结束学习率。
  • power (float，可选，默认为 1.0) — 幂因子。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。

创建一个学习率调度器，其学习率从优化器中设置的初始学习率开始，经过一个线性从 0 增加到该初始学习率的预热期后，以多项式衰减的方式降低至由 lr_end 定义的最终学习率。

注意：power 的默认值为 1.0，与 fairseq 的实现一致，而 fairseq 的实现又基于 https://github.com/google-research/bert/blob/f39e881b169b9d53bea03d2d341b31707a6c052b/optimization.py#L37 中的原始 BERT 实现。

get_inverse_sqrt_schedule

transformers.get_inverse_sqrt_schedule

< >

( optimizer: Optimizernum_warmup_steps: inttimescale: int | None = Nonelast_epoch: int = -1 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • timescale (int，可选，默认为 num_warmup_steps) — 时间尺度。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。

创建一个采用平方根倒数学习率调度的计划，在预热阶段结束后，学习率从优化器中设置的初始学习率开始按平方根倒数规律衰减；预热阶段内，学习率从 0 线性增加到优化器中设置的初始学习率。

get_reduce_on_plateau_schedule

transformers.get_reduce_on_plateau_schedule

< >

( optimizer: Optimizer**kwargs )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • kwargs (dict，可选) — 传递给调度器的额外参数。有关可能的参数，请参阅 torch.optim.lr_scheduler.ReduceLROnPlateau。

创建一个学习率调度器，在指标停止改善时降低恒定的学习率。

get_wsd_schedule

transformers.get_wsd_schedule

< >

( optimizer: Optimizernum_warmup_steps: intnum_decay_steps: intnum_training_steps: int | None = Nonenum_stable_steps: int | None = Nonewarmup_type: str = 'linear'decay_type: str = 'cosine'min_lr_ratio: float = 0num_cycles: float = 0.5last_epoch: int = -1 )

参数

  • optimizer (~torch.optim.Optimizer) — 用于调度学习率的优化器。
  • num_warmup_steps (int) — 预热阶段的步数。
  • num_decay_steps (int) — 衰减阶段的步数。
  • num_training_steps (int, 可选) — 训练步数的总和。该值等于 warmup、stable 和 decay 步数之和。如果未提供 num_stable_steps，则 stable 阶段的步数为 num_training_steps - num_warmup_steps - num_decay_steps。
  • num_stable_steps (int, 可选) — 稳定阶段的步数。请确保 num_warmup_steps + num_stable_steps + num_decay_steps 等于 num_training_steps，否则其他阶段的步数将默认使用最小学习率。
  • warmup_type (str, 可选，默认为 “linear”) — 要使用的预热类型。可以是 ‘linear’、‘cosine’ 或 ‘1-sqrt’。
  • decay_type (str，可选，默认为 “cosine”) — 要使用的衰减类型。可以是 ‘linear’、‘cosine’ 或 ‘1-sqrt’。
  • min_lr_ratio (float，可选，默认为 0) — 初始学习率的最小学习率比例。
  • num_cycles (float，可选，默认值为 0.5) — 余弦调度中的波数（默认行为是遵循半余弦曲线，从最大值递减至 0）。
  • last_epoch (int，可选，默认为 -1) — 恢复训练时最后一个 epoch 的索引。

创建一个具有三个阶段的学习率计划：

  1. warmup：按照 warmup_type，将学习率从初始学习率的 min_lr_ratio 倍逐步提升至初始学习率。
  2. stable：恒定学习率。
  3. decay：按照 decay_type 从初始学习率衰减至初始学习率的 min_lr_ratio 倍。
Update on GitHub

←文本生成 模型输出→