Hugging Face's logo

Transformers documentation

Optimisation

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Optimisation

Le module .optimization fournit :

  • un optimiseur avec un décroissement de poids fixe, utilisable pour l’ajustement fin des modèles, et
  • plusieurs plans sous forme d'objets de plan qui héritent de _LRSchedule :
  • une classe d'accumulation de gradients pour accumuler les gradients de plusieurs lots

AdaFactor

classe 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 )

Paramètres

  • params (Iterable[nn.parameter.Parameter]) — Itérable de paramètres à optimiser ou dictionnaires définissant des groupes de paramètres.
  • lr (float, facultatif) — Le taux d'apprentissage externe.
  • eps (tuple[float, float], facultatif, par défaut (1e-30, 0.001)) — Constantes de régularisation pour le gradient carré et l'échelle des paramètres, respectivement
  • clip_threshold (float, facultatif, valeur par défaut 1.0) — Seuil de la racine de la moyenne carrée de la mise à jour finale du gradient
  • decay_rate (float, facultatif, valeur par défaut -0.8) — Coefficient utilisé pour calculer les moyennes mobiles des carrés
  • beta1 (float, facultatif) — Coefficient utilisé pour le calcul des moyennes mobiles des gradients
  • weight_decay (float, facultatif, valeur par défaut 0.0) — Décroissance du poids (pénalité L2)
  • scale_parameter (bool, facultatif, par défaut True) — Si True, le taux d'apprentissage est mis à l'échelle par la racine de la moyenne des carrés
  • relative_step (bool, facultatif, par défaut True) — Si True, le taux d’apprentissage dépendant du temps est calculé au lieu du taux d’apprentissage externe
  • warmup_init (bool, facultatif, par défaut False) — Le calcul du taux d'apprentissage dépendant du temps dépend de l'utilisation ou non de l'initialisation de la montée en température

L'implémentation pytorch d'AdaFactor peut être utilisée comme remplacement direct du code original fairseq d'Adam : https://github.com/pytorch/fairseq/blob/master/fairseq/optim/adafactor.py

Article : Adafactor: Adaptive Learning Rates with Sublinear Memory Cost https://huggingface.co/papers/1804.04235 Notez que cet optimiseur ajuste en interne le taux d'apprentissage en fonction des options scale_parameter, relative_step et warmup_init. Pour utiliser un calendrier de taux d'apprentissage manuel (externe), vous devez définir scale_parameter=False et relative_step=False.

Cette implémentation gère les valeurs à basse précision (FP16, bfloat), mais nous ne l'avons pas testée de manière exhaustive.

Paramètres de fine-tuning T5 recommandés (https://huggingface.co/proxy/discuss.huggingface.co/t/t5-finetuning-tips/684/3) :

  • L'entraînement sans LR warmup ni clip_threshold n'est pas recommandé.

  • Désactiver les mises à jour relatives

  • Utilisez scale_parameter=False

  • Les opérations d'optimiseur supplémentaires, comme le clipping des gradients, ne doivent pas être utilisées en même temps qu'Adafactor

Exemple :

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

D'autres ont signalé que la combinaison suivante fonctionnait bien :

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

Lors de l'utilisation de lr=None avec Trainer, vous aurez très probablement besoin d'utiliser AdafactorSchedule

scheduler comme suit :

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))

Utilisation :

# 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,
)

étape

< >

( closure = None )

Paramètres

  • closure (appelable, facultatif) — Une fermeture qui réévalue le modèle et renvoie la perte.

Effectue une étape d'optimisation unique

Planifications

SchedulerType

classe transformers.SchedulerType

< >

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

Noms des planificateurs pour le paramètre lr_scheduler_type dans TrainingArguments. Par défaut, il utilise « linear ». En interne, cela récupère le planificateur get_linear_schedule_with_warmup de Trainer. Types de planificateurs :

get_scheduler

transformers.get_scheduler

< >

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

Paramètres

  • name (str ou SchedulerType) — Le nom du planificateur à utiliser.
  • optimizer (torch.optim.Optimizer) — L’optimiseur qui sera utilisé pendant l’entraînement.
  • num_warmup_steps (int, facultatif) — Le nombre d'étapes de mise en route à effectuer. Ce paramètre n'est pas requis par tous les planificateurs (d'où le caractère facultatif de l'argument) ; la fonction lèvera une erreur s'il n'est pas défini alors que le type de planificateur l'exige.
  • num_training_steps (`int“, facultatif) — Le nombre d’étapes d’entraînement à effectuer. Ce paramètre n’est pas requis par tous les planificateurs (d’où le caractère facultatif de l’argument) ; la fonction lèvera une erreur s’il n’est pas défini alors que le type de planificateur l’exige.
  • scheduler_specific_kwargs (dict, facultatif) — Paramètres supplémentaires pour les planificateurs tels que cosine with restarts. Un type de planificateur et des paramètres de planificateur non correspondants provoqueront l’élévation d’une TypeError par la fonction de planificateur.

API unifiée pour obtenir n'importe quel planificateur à partir de son nom.

get_constant_schedule

transformers.get_constant_schedule

< >

( optimizer: Optimizerlast_epoch: int = -1 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.

Créez un planning avec un taux d'apprentissage constant, en utilisant le taux d'apprentissage défini dans optimizer.

get_constant_schedule_with_warmup

transformers.get_constant_schedule_with_warmup

< >

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

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.

Créez un planning avec un taux d'apprentissage constant précédé d'une période de warmup au cours de laquelle le taux d'apprentissage augmente linéairement entre 0 et le lr initial défini dans l'optimiseur.

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 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • num_training_steps (int) — Le nombre total d'étapes d'entraînement.
  • num_cycles (float, facultatif, valeur par défaut 0.5) — Le nombre d'ondulations dans le planificateur cosinus (la valeur par défaut consiste simplement à diminuer de la valeur maximale à 0 suivant une demi-cosinus).
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.

Créez un planning avec un taux d’apprentissage qui diminue en suivant les valeurs de la fonction cosinus entre le lr initial défini dans l’optimiseur et 0, après une période de montée en charge au cours de laquelle il augmente linéairement entre 0 et le lr initial défini dans l’optimiseur.

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 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • num_training_steps (int) — Le nombre total d'étapes d'entraînement.
  • num_cycles (int, facultatif, par défaut 1) — Le nombre de redémarrages durs à utiliser.
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.

Créez un planning avec un taux d’apprentissage qui diminue en suivant les valeurs de la fonction cosinus entre le lr initial défini dans l’optimiseur et 0, avec plusieurs redémarrages durs, après une période de montée en charge au cours de laquelle il augmente linéairement entre 0 et le lr initial défini dans l’optimiseur.

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 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • num_training_steps (int) — Le nombre total d'étapes d'entraînement.
  • num_cycles (float, facultatif, valeur par défaut 0.5) — Le nombre d'ondulations dans le planificateur cosinus (la valeur par défaut consiste simplement à diminuer de la valeur maximale à 0 suivant une demi-cosinus).
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.
  • min_lr (float, facultatif) — Le taux d'apprentissage minimal à atteindre après le calendrier cosinus.
  • min_lr_rate (float, facultatif) — Le taux d'apprentissage minimal en tant que ratio du taux d'apprentissage initial. S'il est défini, min_lr ne doit pas être défini.

Créez un planning avec un taux d’apprentissage qui diminue en suivant les valeurs de la fonction cosinus entre le lr initial défini dans l’optimiseur et min_lr, après une période de montée en charge au cours de laquelle il augmente linéairement entre 0 et le lr initial défini dans l’optimiseur.

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 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • num_training_steps (int) — Le nombre total d'étapes d'entraînement.
  • num_cycles (float, facultatif, valeur par défaut 0.5) — Le nombre d'ondulations dans le planificateur cosinus (la valeur par défaut consiste simplement à diminuer de la valeur maximale à 0 suivant une demi-cosinus).
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.
  • min_lr (float, facultatif) — Le taux d'apprentissage minimal à atteindre après le calendrier cosinus.
  • min_lr_rate (float, facultatif) — Le taux d'apprentissage minimal en tant que ratio du taux d'apprentissage initial. S'il est défini, min_lr ne doit pas être défini.
  • warmup_lr_rate (float, facultatif) — Le taux d'apprentissage minimal en tant que ratio du taux d'apprentissage initial. S'il n'est pas défini, warmup_lr_rate sera traité comme float(1/num_warmup_steps).

Créez un planning avec un taux d’apprentissage qui diminue en suivant les valeurs de la fonction cosinus entre le lr initial défini dans l’optimiseur et min_lr, après une période de montée en charge au cours de laquelle il augmente linéairement entre 0 et le lr initial défini dans l’optimiseur.

GreedyLR

classe 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 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • mode (str, facultatif, par défaut "min") — L’un des ‘min’ ou ‘max’. En mode ‘min’, le taux d’apprentissage est réduit lorsque la métrie cesse de diminuer ; en mode ‘max’, lorsque elle cesse d’augmenter.
  • factor (float, facultatif, valeur par défaut 0.95) — Facteur par lequel le taux d'apprentissage sera ajusté. Le taux d'apprentissage est multiplié par factor en cas de palier et divisé par factor en cas d'amélioration. Doit être < 1.0.
  • patience (int, facultatif, valeur par défaut 10) — Nombre d'époques sans amélioration après lesquelles le taux d'apprentissage sera ajusté.
  • threshold (float, facultatif, par défaut 1e-06) — Seuil pour mesurer le nouvel optimum.
  • threshold_mode (str, facultatif, par défaut "abs") — Soit ‘rel’, soit ‘abs’.
  • cooldown (int, facultatif, valeur par défaut 0) — Nombre d'époques à attendre avant de reprendre le fonctionnement normal après une réduction du taux d'apprentissage.
  • warmup (int, facultatif, valeur par défaut 0) — Nombre d'époques à attendre avant de reprendre le fonctionnement normal après l'augmentation du taux d'apprentissage.
  • min_lr (float ou list[float], facultatif, valeur par défaut 0.001) — Une borne inférieure pour le taux d'apprentissage.
  • max_lr (float ou list[float], facultatif, valeur par défaut 1.0) — Une limite supérieure pour le taux d'apprentissage.
  • eps (float, facultatif, valeur par défaut 1e-08) — Décroissance minimale appliquée au lr.
  • verbose (bool, facultatif, par défaut False) — Si True, affiche un message sur la sortie standard pour chaque mise à jour.
  • smooth (bool, facultatif, par défaut False) — Si True, applique un lissage par moyenne glissante aux métriques.
  • window_size (int, facultatif, par défaut 50) — Taille de la fenêtre pour la moyenne glissante lorsque smooth=True.
  • reset_start (int, facultatif, valeur par défaut 500) — Nombre d'étapes à attendre à min_lr avant de réinitialiser à l'état initial.

Planificateur de taux d'apprentissage adaptatif qui réagit aux métriques d'entraînement.

GreedyLR ajuste dynamiquement le taux d’apprentissage en fonction des performances d’entraînement :

  • Augmente le LR lorsque les métriques s'améliorent de manière constante (divise par le facteur)
  • Diminue le taux d'apprentissage lorsque les métriques stagnent (multiplie par un facteur)

Cela diffère des planificateurs traditionnels comme le recuit cosinus, car il réagit aux dynamiques réelles de l'entraînement plutôt que de suivre un planning prédéterminé.

Référence : GreedyLR: A Novel Adaptive Learning Rate Scheduler <https://arxiv.org/abs/2512.14527>_

Exemple :

>>> 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

< >

( )

Retourne le dernier taux d'apprentissage calculé par le planificateur actuel.

load_state_dict

< >

( state_dict: dict[str, Any] )

Charger l'état à partir d'un dictionnaire.

state_dict

< >

( )

Retourne l'état du planificateur sous forme de dictionnaire.

étape

< >

( metrics: floatepoch: int | None = None )

Paramètres

  • metrics (float) — La valeur de la métrique à utiliser pour les décisions d'ajustement du taux d'apprentissage.
  • epoch (int, facultatif) — Numéro de l'époque actuelle. Si None, utilise le compteur interne.

Effectuer une étape du planificateur en fonction des métriques fournies.

get_greedy_schedule

transformers.get_greedy_schedule

< >

( optimizer: Optimizer**kwargs )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • kwargs (dict, facultatif) — Paramètres supplémentaires transmis à l’ordonnanceur. Consultez GreedyLR pour les paramètres possibles.

Créez un planificateur de taux d'apprentissage adaptatif qui ajuste le LR en fonction des métriques d'entraînement.

get_linear_schedule_with_warmup

transformers.get_linear_schedule_with_warmup

< >

( optimizernum_warmup_stepsnum_training_stepslast_epoch = -1 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • num_training_steps (int) — Le nombre total d'étapes d'entraînement.
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.

Créez un planning avec un taux d'apprentissage qui diminue linéairement depuis le lr initial défini dans l'optimiseur jusqu'à 0, après une période de montée en charge au cours de laquelle il augmente linéairement de 0 jusqu'au lr initial défini dans l'optimiseur.

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 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • num_training_steps (int) — Le nombre total d'étapes d'entraînement.
  • lr_end (float, facultatif, valeur par défaut 1e-7) — Le LR final.
  • power (float, facultatif, valeur par défaut 1.0) — Facteur de puissance.
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.

Créez un planning avec un taux d’apprentissage qui diminue selon une décroissance polynomiale depuis le lr initial défini dans l’optimiseur jusqu’au lr final défini par lr_end, après une période de montée en charge au cours de laquelle il augmente linéairement de 0 jusqu’au lr initial défini dans l’optimiseur.

Note : power est défini par défaut à 1.0, comme dans l'implémentation fairseq, qui est elle-même basée sur l'implémentation originale de BERT située à https://github.com/google-research/bert/blob/f39e881b169b9d53bea03d2d341b31707a6c052b/optimization.py#L37

get_inverse_sqrt_schedule

transformers.get_inverse_sqrt_schedule

< >

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

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • timescale (int, facultatif, par défaut num_warmup_steps) — Échelle de temps.
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.

Créez un planning avec un taux d’apprentissage en racine carrée inverse, à partir du lr initial défini dans l’optimiseur, après une période de warmup qui augmente le lr linéairement de 0 jusqu’au lr initial défini dans l’optimiseur.

get_reduce_on_plateau_schedule

transformers.get_reduce_on_plateau_schedule

< >

( optimizer: Optimizer**kwargs )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • kwargs (dict, facultatif) — Paramètres supplémentaires à passer au planificateur. Consultez torch.optim.lr_scheduler.ReduceLROnPlateau pour les paramètres possibles.

Créez un planning avec un taux d'apprentissage constant qui diminue lorsqu'une métrie cesse de s'améliorer.

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 )

Paramètres

  • optimizer (~torch.optim.Optimizer) — L’optimiseur pour lequel planifier le taux d’apprentissage.
  • num_warmup_steps (int) — Le nombre d'étapes pour la phase de montée en température.
  • num_decay_steps (int) — Le nombre d'étapes de la phase de décroissance.
  • num_training_steps (int, facultatif) — Le nombre total d'étapes d'entraînement. Il s'agit de la somme des étapes de montée en charge, stables et de décroissance. Si num_stable_steps n'est pas fourni, la phase stable sera num_training_steps - num_warmup_steps - num_decay_steps.
  • num_stable_steps (int, facultatif) — Le nombre d'étapes pour la phase stable. Veuillez vous assurer que num_warmup_steps + num_stable_steps + num_decay_steps est égal à num_training_steps, sinon les autres étapes utiliseront le taux d'apprentissage minimal par défaut.
  • warmup_type (str, facultatif, par défaut “linear”) — Le type de warmup à utiliser. Peut être ‘linear’, ‘cosine’ ou ‘1-sqrt’.
  • decay_type (str, facultatif, par défaut “cosine”) — Le type de décroissance à utiliser. Peut être ‘linear’, ‘cosine’ ou ‘1-sqrt’.
  • min_lr_ratio (float, facultatif, valeur par défaut 0) — Le taux d'apprentissage minimal en tant que ratio du taux d'apprentissage initial.
  • num_cycles (float, facultatif, valeur par défaut 0.5) — Le nombre d'ondulations dans le planificateur cosinus (la valeur par défaut consiste simplement à diminuer de la valeur maximale à 0 suivant une demi-cosinus).
  • last_epoch (int, facultatif, valeur par défaut : -1) — L'index de la dernière époque lors de la reprise de l'entraînement.

Créez un planning avec un taux d'apprentissage en trois étapes :

  1. warmup : augmenter le taux d'apprentissage initial multiplié par min_lr_ratio jusqu'au taux d'apprentissage initial en suivant warmup_type.
  2. stable : taux d'apprentissage constant.
  3. decay : diminution du taux d'apprentissage initial jusqu'à min_lr_ratio fois le taux d'apprentissage initial, selon un decay_type.
Update on GitHub

←Génération de texte Sorties du modèle→