Transformers documentation

优化

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.23.0).
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://huggingface.co/proxy/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