Hugging Face's logo

Transformers documentation

Otimização

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

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 (https://discuss.huggingface.co/t/t5-finetuning-tips/684/3):

  • Não é recomendado treinar sem aquecimento de taxa de aprendizado (LR warmup) ou sem clip_threshold.

  • Desativar atualizações relativas

  • Use scale_parameter=False

  • Operações adicionais do otimizador, como o recorte de gradiente, não devem ser usadas em conjunto com o Adafactor

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

←Geração de texto Saídas do modelo→