Transformers documentation

Otimização

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Otimização

O módulo .optimization fornece:

  • um otimizador com decaimento de peso fixo que pode ser usado para ajustar finamente modelos, e
  • vários agendamentos na forma de objetos de agendamento que herdam de _LRSchedule:
  • uma classe de acúmulo de gradiente para acumular os gradientes de vários lotes

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 )

Parâmetros

  • params (Iterable[nn.parameter.Parameter]) — Iterável de parâmetros a serem otimizados ou dicionários definindo grupos de parâmetros.
  • lr (float, opcional) — A taxa de aprendizado externa.
  • eps (tuple[float, float], opcional, padrão (1e-30, 0.001)) — Constantes de regularização para o gradiente quadrado e a escala dos parâmetros, respectivamente
  • clip_threshold (float, opcional, padrão 1.0) — Limiar da raiz quadrada da média quadrática da atualização final do gradiente
  • decay_rate (float, opcional, padrão -0.8) — Coeficiente usado para calcular as médias móveis dos quadrados
  • beta1 (float, opcional) — Coeficiente usado para calcular as médias móveis dos gradientes
  • weight_decay (float, opcional, padrão 0.0) — Decaimento de peso (penalidade L2)
  • scale_parameter (bool, opcional, padrão True) — Se True, a taxa de aprendizado é escalada pela raiz quadrada da média dos quadrados
  • relative_step (bool, opcional, padrão True) — Se True, a taxa de aprendizado dependente do tempo é calculada em vez da taxa de aprendizado externa
  • warmup_init (bool, opcional, padrão False) — O cálculo da taxa de aprendizado dependente do tempo depende de se a inicialização de aquecimento está sendo utilizada

A implementação do AdaFactor em PyTorch pode ser usada como substituto direto do código original do fairseq para Adam: https://github.com/pytorch/fairseq/blob/master/fairseq/optim/adafactor.py

Artigo: Adafactor: Adaptive Learning Rates with Sublinear Memory Cost https://huggingface.co/papers/1804.04235 Observe que este otimizador ajusta internamente a taxa de aprendizado com base nas opções scale_parameter, relative_step e warmup_init. Para usar um agendamento manual (externo) da taxa de aprendizado, você deve definir scale_parameter=False e relative_step=False.

Esta implementação trata valores de baixa precisão (FP16, bfloat), mas não foi testada de forma exaustiva.

Configurações recomendadas para o finetuning do T5 (/static-proxy?url=https%3A%2F%2Fdiscuss.huggingface.co%2Ft%2Ft5-finetuning-tips%2F684%2F3%3C%2Fa%3E)%3A%3C%2Fp%3E

Exemplo:

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

Outros relataram que a seguinte combinação funciona bem:

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

Ao usar lr=None com Trainer, você provavelmente precisará usar AdafactorSchedule

scheduler da seguinte forma:

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

Uso:

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

etapa

< >

( closure = None )

Parâmetros

  • closure (callable, opcional) — Uma closure que reavalia o modelo e retorna a perda.

Executa um único passo de otimização

Agendamentos

SchedulerType

classe transformers.SchedulerType

< >

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

Nomes de agendadores para o parâmetro lr_scheduler_type em TrainingArguments. Por padrão, ele usa “linear”. Internamente, isso recupera o agendador get_linear_schedule_with_warmup do Trainer. Tipos de agendador:

get_scheduler

transformers.get_scheduler

< >

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

Parâmetros

  • name (str ou SchedulerType) — O nome do scheduler a ser utilizado.
  • optimizer (torch.optim.Optimizer) — O otimizador que será usado durante o treinamento.
  • num_warmup_steps (int, opcional) — O número de etapas de aquecimento a serem executadas. Isso não é exigido por todos os agendadores (daí o argumento ser opcional); a função lançará um erro se não for definido e o tipo de agendador exigir.
  • num_training_steps (`int“, opcional) — O número de etapas de treinamento a serem executadas. Isso não é exigido por todos os agendadores (daí o argumento ser opcional); a função lançará um erro se não for definido e o tipo de agendador exigir.
  • scheduler_specific_kwargs (dict, opcional) — Parâmetros extras para agendadores, como o cosine with restarts. Tipos de agendador e parâmetros de agendador incompatíveis farão com que a função do agendador lance um TypeError.

API unificada para obter qualquer agendador pelo seu nome.

get_constant_schedule

transformers.get_constant_schedule

< >

( optimizer: Optimizerlast_epoch: int = -1 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.

Crie um agendamento com uma taxa de aprendizado constante, usando a taxa de aprendizado definida no optimizer.

get_constant_schedule_with_warmup

transformers.get_constant_schedule_with_warmup

< >

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

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.

Crie um agendamento com uma taxa de aprendizado constante, precedido por um período de aquecimento (warmup) durante o qual a taxa de aprendizado aumenta linearmente entre 0 e a lr inicial definida no otimizador.

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 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • num_training_steps (int) — O número total de etapas de treinamento.
  • num_cycles (float, opcional, padrão 0.5) — O número de ondas no agendamento cosseno (o padrão é simplesmente diminuir do valor máximo até 0 seguindo um meio-cosseno).
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.

Crie um agendamento com uma taxa de aprendizado que diminui seguindo os valores da função cosseno entre a lr inicial definida no otimizador e 0, após um período de aquecimento durante o qual ela aumenta linearmente entre 0 e a lr inicial definida no otimizador.

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 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • num_training_steps (int) — O número total de etapas de treinamento.
  • num_cycles (int, opcional, padrão 1) — O número de reinícios duros a serem usados.
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.

Crie um agendamento com uma taxa de aprendizado que diminui seguindo os valores da função cosseno entre a lr inicial definida no otimizador e 0, com vários reinícios duros, após um período de aquecimento durante o qual ela aumenta linearmente entre 0 e a lr inicial definida no otimizador.

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 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • num_training_steps (int) — O número total de etapas de treinamento.
  • num_cycles (float, opcional, padrão 0.5) — O número de ondas no agendamento cosseno (o padrão é simplesmente diminuir do valor máximo até 0 seguindo um meio-cosseno).
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.
  • min_lr (float, opcional) — A taxa de aprendizado mínima a ser atingida após o agendamento cosseno.
  • min_lr_rate (float, opcional) — A taxa de aprendizado mínima como uma proporção da taxa de aprendizado inicial. Se definida, min_lr não deve ser definida.

Crie um agendamento com uma taxa de aprendizado que diminui seguindo os valores da função cosseno entre a lr inicial definida no otimizador e min_lr, após um período de aquecimento durante o qual ela aumenta linearmente entre 0 e a lr inicial definida no otimizador.

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 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • num_training_steps (int) — O número total de etapas de treinamento.
  • num_cycles (float, opcional, padrão 0.5) — O número de ondas no agendamento cosseno (o padrão é simplesmente diminuir do valor máximo até 0 seguindo um meio-cosseno).
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.
  • min_lr (float, opcional) — A taxa de aprendizado mínima a ser atingida após o agendamento cosseno.
  • min_lr_rate (float, opcional) — A taxa de aprendizado mínima como uma proporção da taxa de aprendizado inicial. Se definida, min_lr não deve ser definida.
  • warmup_lr_rate (float, opcional) — A taxa de aprendizado mínima como uma proporção da taxa de aprendizado inicial. Se não for definida, warmup_lr_rate será tratada como float(1/num_warmup_steps).

Crie um agendamento com uma taxa de aprendizado que diminui seguindo os valores da função cosseno entre a lr inicial definida no otimizador e min_lr, após um período de aquecimento durante o qual ela aumenta linearmente entre 0 e a lr inicial definida no otimizador.

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 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • mode (str, opcional, padrão "min") — Um dos valores ‘min’ ou ‘max’. No modo ‘min’, a LR será reduzida quando a métrica deixar de diminuir; no modo ‘max’, quando ela deixar de aumentar.
  • factor (float, opcional, padrão 0.95) — Fator pelo qual a taxa de aprendizado será ajustada. A taxa de aprendizado é multiplicada pelo fator em platôs e dividida pelo fator em caso de melhora. Deve ser < 1.0.
  • patience (int, opcional, padrão 10) — Número de épocas sem melhoria após as quais a taxa de aprendizado será ajustada.
  • threshold (float, opcional, padrão 1e-06) — Limiar para medir o novo ótimo.
  • threshold_mode (str, opcional, padrão "abs") — Um de ‘rel’ ou ‘abs’.
  • cooldown (int, opcional, padrão 0) — Número de épocas a aguardar antes de retomar a operação normal após a redução da taxa de aprendizado.
  • warmup (int, opcional, padrão 0) — Número de épocas a aguardar antes de retomar a operação normal após o aumento da taxa de aprendizado.
  • min_lr (float ou list[float], opcional, padrão 0.001) — Um limite inferior para a taxa de aprendizado.
  • max_lr (float ou list[float], opcional, padrão 1.0) — Um limite superior para a taxa de aprendizado.
  • eps (float, opcional, padrão 1e-08) — Decaimento mínimo aplicado ao lr.
  • verbose (bool, opcional, padrão False) — Se True, imprime uma mensagem no stdout para cada atualização.
  • smooth (bool, opcional, padrão False) — Se True, aplica suavização por média móvel em streaming às métricas.
  • window_size (int, opcional, padrão 50) — O tamanho da janela para a média em streaming quando smooth=True.
  • reset_start (int, opcional, padrão 500) — Número de etapas a aguardar em min_lr antes de redefinir para o estado inicial.

Agendador de taxa de aprendizado adaptativo que responde a métricas de treinamento.

O GreedyLR ajusta dinamicamente a taxa de aprendizado com base no desempenho do treinamento:

  • Aumenta a taxa de aprendizado quando as métricas melhoram consistentemente (divide pelo fator)
  • Diminui a taxa de aprendizado quando as métricas estagnam (multiplica por um fator)

Isso difere de agendadores tradicionais, como o cosine annealing, ao responder às dinâmicas reais do treinamento em vez de seguir um agendamento predeterminado.

Referência: GreedyLR: A Novel Adaptive Learning Rate Scheduler <https://arxiv.org/abs/2512.14527>_

Exemplo:

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

< >

( )

Retorna a última taxa de aprendizado calculada pelo agendador atual.

load_state_dict

< >

( state_dict: dict[str, Any] )

Carrega o estado a partir de um dicionário.

state_dict

< >

( )

Retorna o estado do agendador como um dicionário.

etapa

< >

( metrics: floatepoch: int | None = None )

Parâmetros

  • metrics (float) — O valor da métrica a ser usado para as decisões de ajuste de LR.
  • epoch (int, opcional) — O número da epoch atual. Se for None, usa o contador interno.

Execute um passo do agendador com base nas métricas fornecidas.

get_greedy_schedule

transformers.get_greedy_schedule

< >

( optimizer: Optimizer**kwargs )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • kwargs (dict, opcional) — Parâmetros extras passados para o scheduler. Consulte GreedyLR para os parâmetros possíveis.

Crie um agendador de taxa de aprendizado adaptativo que ajusta a taxa de aprendizado com base nas métricas de treinamento.

get_linear_schedule_with_warmup

transformers.get_linear_schedule_with_warmup

< >

( optimizernum_warmup_stepsnum_training_stepslast_epoch = -1 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • num_training_steps (int) — O número total de etapas de treinamento.
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.

Crie um agendamento com uma taxa de aprendizado que diminui linearmente da lr inicial definida no otimizador até 0, após um período de aquecimento durante o qual ela aumenta linearmente de 0 até a lr inicial definida no otimizador.

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 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • num_training_steps (int) — O número total de etapas de treinamento.
  • lr_end (float, opcional, padrão 1e-7) — A taxa de aprendizado final.
  • power (float, opcional, padrão 1.0) — Fator de potência.
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.

Crie um agendamento com uma taxa de aprendizado que diminui por decaimento polinomial a partir da lr inicial definida no otimizador até a lr final definida por lr_end, após um período de aquecimento durante o qual ela aumenta linearmente de 0 até a lr inicial definida no otimizador.

Observação: power tem valor padrão de 1.0, conforme a implementação do fairseq, que por sua vez é baseada na implementação original do BERT em 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 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • timescale (int, opcional, padrão num_warmup_steps) — Escala de tempo.
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.

Crie um agendamento com uma taxa de aprendizado de raiz quadrada inversa, a partir da lr inicial definida no otimizador, após um período de aquecimento que aumenta a lr linearmente de 0 até a lr inicial definida no otimizador.

get_reduce_on_plateau_schedule

transformers.get_reduce_on_plateau_schedule

< >

( optimizer: Optimizer**kwargs )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • kwargs (dict, opcional) — Parâmetros extras a serem passados para o agendador. Consulte torch.optim.lr_scheduler.ReduceLROnPlateau para os parâmetros possíveis.

Crie um agendamento com uma taxa de aprendizado constante que diminui quando uma métrica deixa de melhorar.

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 )

Parâmetros

  • optimizer (~torch.optim.Optimizer) — O otimizador para o qual a taxa de aprendizado será agendada.
  • num_warmup_steps (int) — O número de etapas para a fase de aquecimento.
  • num_decay_steps (int) — O número de etapas para a fase de decaimento.
  • num_training_steps (int, opcional) — O número total de etapas de treinamento. Esta é a soma das etapas de aquecimento, estáveis e de decaimento. Se num_stable_steps não for fornecido, a fase estável será num_training_steps - num_warmup_steps - num_decay_steps.
  • num_stable_steps (int, opcional) — O número de etapas para a fase estável. Certifique-se de que num_warmup_steps + num_stable_steps + num_decay_steps seja igual a num_training_steps; caso contrário, as outras etapas usarão a taxa de aprendizado mínima por padrão.
  • warmup_type (str, opcional, padrão “linear”) — O tipo de warmup a ser usado. Pode ser ‘linear’, ‘cosine’ ou ‘1-sqrt’.
  • decay_type (str, opcional, padrão “cosine”) — O tipo de decaimento a ser usado. Pode ser ‘linear’, ‘cosine’ ou ‘1-sqrt’.
  • min_lr_ratio (float, opcional, padrão 0) — A taxa de aprendizado mínima como uma proporção da taxa de aprendizado inicial.
  • num_cycles (float, opcional, padrão 0.5) — O número de ondas no agendamento cosseno (o padrão é simplesmente diminuir do valor máximo até 0 seguindo um meio-cosseno).
  • last_epoch (int, opcional, padrão -1) — O índice da última época ao retomar o treinamento.

Crie um cronograma com uma taxa de aprendizado que possui três etapas:

  1. warmup: aumenta de min_lr_ratio vezes a taxa de aprendizado inicial até a taxa de aprendizado inicial seguindo um warmup_type.
  2. estável: taxa de aprendizado constante.
  3. decay: diminuição a partir da taxa de aprendizado inicial até min_lr_ratio vezes a taxa de aprendizado inicial, seguindo um decay_type.
Update on GitHub