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 モジュールは以下を提供します:

  • weight decayが固定されたオプティマイザーで、モデルのファインチューニングに使用でき、
  • _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) — 最終的な勾配更新の二乗平均平方根(RMS)の閾値
  • 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 を設定してください。

この実装は低精度(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)

lr=None を Trainer と一緒に使用する場合は、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 (callable, 任意) — モデルを再評価して損失を返すクロージャ。

1回の最適化ステップを実行します

スケジュール

SchedulerType

クラス transformers.SchedulerType

< >

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

TrainingArgumentsのパラメータlr_scheduler_typeに指定するスケジューラー名。 デフォルトでは“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, 任意) — cosine with restarts などのスケジューラ用の追加パラメータです。スケジューラの種類とスケジューラのパラメータが一致しない場合、スケジューラ関数から TypeError が発生します。

Unified API を使用して、名前から任意のスケジューラーを取得します。

get_constant_schedule

transformers.get_constant_schedule

< >

( optimizer: Optimizerlast_epoch: int = -1 )

パラメータ

  • optimizer (~torch.optim.Optimizer) — 学習率のスケジュールを設定するオプティマイザー。
  • last_epoch (int、任意、デフォルトは -1) — 学習を再開する際の最後のエポックのインデックス。

optimizerで設定された学習率を使用して、一定の学習率でスケジュールを作成します。

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) — 学習を再開する際の最後のエポックのインデックス。

0からオプティマイザーで設定された初期lrまで線形に増加するウォームアップ期間に続き、一定の学習率でスケジュールを作成します。

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) — 学習を再開する際の最後のエポックのインデックス。

optimizerで設定された初期lrから0へ、コサイン関数の値に従って減少する学習率のスケジュールを作成します。この際、0からoptimizerで設定された初期lrまで線形に増加するウォームアップ期間を設けます。

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) — 学習を再開する際の最後のエポックのインデックス。

optimizerで設定された初期lrから0までの値を、コサイン関数の値に従って減少させるスケジュールを作成します。このスケジュールには、0からoptimizerで設定された初期lrまで線形に増加するウォームアップ期間の後に、複数のハードリスタートが含まれます。

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) — 学習を再開する際の最後のエポックのインデックス。
  • min_lr (float, 省略可) — コサインスケジュールの終了後に到達する最小学習率です。
  • min_lr_rate (float、任意) — 初期学習率に対する最小学習率の比率です。設定した場合、min_lr は設定しないでください。

optimizerで設定された初期lrからmin_lrまで、コサイン関数の値に従って減少する学習率のスケジュールを作成します。この際、ウォームアップ期間中は0からoptimizerで設定された初期lrまで線形に増加します。

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) — 学習を再開する際の最後のエポックのインデックス。
  • min_lr (float, 省略可) — コサインスケジュールの終了後に到達する最小学習率です。
  • min_lr_rate (float、任意) — 初期学習率に対する最小学習率の比率です。設定した場合、min_lr は設定しないでください。
  • warmup_lr_rate (float, 任意) — 開始学習率に対する最小学習率の比率です。設定されていない場合、warmup_lr_rate は float(1/num_warmup_steps) として扱われます。

optimizerで設定された初期lrからmin_lrまで、コサイン関数の値に従って減少する学習率のスケジュールを作成します。この際、ウォームアップ期間中は0からoptimizerで設定された初期lrまで線形に増加します。

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) — 学習率が調整されるまでの、改善が見られないエポック数。
  • threshold (float、任意、デフォルト値: 1e-06) — 新しい最適解を測定するための閾値。
  • threshold_mode (str、任意、デフォルトは "abs") — ‘rel’ または ‘abs’ のいずれかです。
  • cooldown (int、任意、デフォルトは 0) — LR が削減された後、通常の動作を再開するまで待機するエポック数。
  • warmup (int、任意、デフォルトは 0)— LR が増加した後に通常の動作を再開するまで待機するエポック数。
  • min_lr (float または list[float]、任意、デフォルト値は 0.001) — 学習率の下限値です。
  • max_lr (float または list[float]、任意、デフォルト値は 1.0) — 学習率の上限値です。
  • eps (float、任意、デフォルト値は 1e-08) — lr に適用される最小の減衰量。
  • verbose (bool、任意、デフォルトはFalse) — True の場合、各更新ごとにメッセージを標準出力に出力します。
  • smooth (bool、任意、デフォルトは False) — True の場合、メトリクスにストリーミング平均スムージングを適用します。
  • window_size (int, 任意, デフォルトは 50) — smooth=True の場合のストリーミング平均のウィンドウサイズです。
  • reset_start (int、任意、デフォルト値は 500)— 初期状態にリセットする前に min_lr で待機するステップ数。

学習メトリクスに応じて反応する適応型学習率スケジューラ。

GreedyLR は、トレーニングの性能に基づいて学習率を動的に調整します:

  • メトリクスが一貫して改善した場合にLRを増加させます(係数で割る)
  • メトリクスが頭打ちになるとLRを減少させます(係数を乗算)

これは、コサインアニーリングのような従来のスケジューラーとは異なり、事前に決められたスケジュールに従うのではなく、実際のトレーニングの動向に応じて学習率を調整します。

参考文献: 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) — LR調整の判断に使用するメトリックの値。
  • epoch (int, 省略可) — 現在のエポック番号。None の場合は、内部のカウンターを使用します。

与えられたメトリクスに基づいてスケジューラーのステップを実行します。

get_greedy_schedule

transformers.get_greedy_schedule

< >

( optimizer: Optimizer**kwargs )

パラメータ

  • optimizer (~torch.optim.Optimizer) — 学習率のスケジュールを設定するオプティマイザー。
  • kwargs (dict、任意) — スケジューラに渡す追加のパラメータ。使用可能なパラメータについては、GreedyLRを参照してください。

学習指標に基づいて学習率を調整する適応型学習率スケジューラを作成します。

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) — 学習を再開する際の最後のエポックのインデックス。

オプティマイザーで設定された初期lrから0へ線形に減少する学習率のスケジュールを作成します。この際、0からオプティマイザーで設定された初期lrへ線形に増加するウォームアップ期間を設けます。

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) — 学習を再開する際の最後のエポックのインデックス。

オプティマイザーに設定された初期学習率から、lr_endで定義される終了学習率まで、多項式減衰によって減少するスケジュールを作成します。この際、ウォームアップ期間中は、オプティマイザーに設定された初期学習率まで0から線形に増加します。

注: powerは、fairseqの実装と同様にデフォルトで1.0です。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) — 学習を再開する際の最後のエポックのインデックス。

オプティマイザーで設定された初期lrから、lrを0から初期lrまで線形に増加させるウォームアップ期間の後に、逆平方根の学習率スケジュールを作成します。

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、任意) — トレーニングステップの総数です。これは、ウォームアップ、安定、減衰のステップ数の合計です。num_stable_steps が指定されていない場合、安定フェーズは 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) — 学習を再開する際の最後のエポックのインデックス。

3段階の学習率を持つスケジュールを作成します:

  1. warmup: warmup_type に従い、初期学習率の min_lr_ratio 倍から初期学習率まで段階的に増加させます。
  2. stable: 一定の学習率。
  3. decay: 初期学習率から、decay_typeに従って初期学習率のmin_lr_ratio倍まで減少します。
Update on GitHub