Hugging Face's logo

Transformers documentation

Trainer

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

Trainer

A classe Trainer fornece uma API para treinamento completo em PyTorch e suporta treinamento distribuído em múltiplos GPUs/TPUs, precisão mista para NVIDIA GPUs, AMD GPUs e torch.amp para PyTorch. O Trainer funciona em conjunto com a classe TrainingArguments, que oferece uma ampla gama de opções para personalizar como um modelo é treinado. Juntas, essas duas classes fornecem uma API de treinamento completa.

Seq2SeqTrainer e Seq2SeqTrainingArguments herdam das classes Trainer e TrainingArguments e são adaptados para o treinamento de modelos em tarefas de sequência-para-sequência, como sumarização ou tradução.

A classe Trainer é otimizada para modelos do 🤗 Transformers e pode apresentar comportamentos inesperados quando usada com outros modelos. Ao utilizá-la com o seu próprio modelo, verifique se:

  • seu modelo sempre retorna tuplas ou subclasses de ModelOutput
  • seu modelo pode calcular a perda se um argumento labels for fornecido e essa perda é retornada como o primeiro elemento da tupla (se o seu modelo retornar tuplas)
  • seu modelo pode aceitar múltiplos argumentos de rótulo (use label_names em TrainingArguments para indicar seus nomes ao Trainer), mas nenhum deles deve ser chamado de "label"

Trainer

classe transformers.Trainer

< >

( model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, NoneType] = Noneargs: transformers.training_args.TrainingArguments | None = Nonedata_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = Nonetrain_dataset: Dataset | IterableDataset | datasets.Dataset | None = Noneeval_dataset: Dataset | dict[str, Dataset] | datasets.Dataset | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.image_processing_utils.BaseImageProcessor | transformers.feature_extraction_utils.FeatureExtractionMixin | transformers.processing_utils.ProcessorMixin | None = Nonemodel_init: collections.abc.Callable[..., transformers.modeling_utils.PreTrainedModel] | None = Nonecompute_loss_func: collections.abc.Callable | None = Nonecompute_metrics: collections.abc.Callable[[transformers.trainer_utils.EvalPrediction], dict] | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple = (None, None)optimizer_cls_and_kwargs: tuple[type[torch.optim.Optimizer], dict[str, typing.Any]] | None = Nonepreprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = None )

Parâmetros

  • model (PreTrainedModel ou torch.nn.Module, opcional) — O modelo a ser treinado, avaliado ou usado para previsões. Se não for fornecido, um model_init deve ser passado.

    O Trainer é otimizado para funcionar com o PreTrainedModel fornecido pela biblioteca. Você ainda pode usar seus próprios modelos definidos como torch.nn.Module, desde que funcionem da mesma forma que os modelos do 🤗 Transformers.

  • args (TrainingArguments, opcional) — Os argumentos para ajustar o treinamento. Se não fornecidos, o padrão será uma instância básica de TrainingArguments com o output_dir definido para um diretório chamado tmp_trainer no diretório atual.
  • data_collator (DataCollator, opcional) — A função a ser usada para formar um lote a partir de uma lista de elementos de train_dataset ou eval_dataset. O padrão será default_data_collator() se nenhum processing_class for fornecido; caso contrário, será uma instância de DataCollatorWithPadding se o processing_class for um feature extractor ou tokenizer.
  • train_dataset (torch.utils.data.Dataset | torch.utils.data.IterableDataset | datasets.Dataset, opcional) — O conjunto de dados a ser usado para o treinamento. Se for um Dataset, as colunas não aceitas pelo model.forward() método são removidas automaticamente. Observe que, se for um torch.utils.data.IterableDataset com alguma aleatorização e você estiver treinando de forma distribuída, seu conjunto de dados iterável deve usar um atributo interno gerador que seja um torch.Generator para a aleatorização, que deve ser idêntico em todos os processos (e o Trainer definirá manualmente a semente desse gerador a cada epoch) ou ter um método set_epoch() que defina internamente a semente dos RNGs usados. Se o conjunto de dados não implementar __len__ (por exemplo, um IterableDataset de streaming), max_steps deve ser definido, pois o número total de etapas de treinamento não pode ser inferido.

    Observe que, se for um torch.utils.data.IterableDataset com alguma aleatorização e você estiver treinando de forma distribuída, seu dataset iterável deve usar um atributo interno generator que seja um torch.Generator para a aleatorização, que deve ser idêntico em todos os processos (e o Trainer definirá manualmente a semente deste generator a cada epoch) ou ter um método set_epoch() que defina internamente a semente dos RNGs utilizados.

    Se o conjunto de dados não implementar __len__ (por exemplo, um IterableDataset de streaming), max_steps deve ser definido, pois o número total de etapas de treinamento não pode ser inferido.

  • eval_dataset (torch.utils.data.Dataset | dict[str, torch.utils.data.Dataset] | datasets.Dataset, opcional) — O conjunto de dados a ser usado para avaliação. Se for um Dataset, as colunas não aceitas pelo método model.forward() são removidas automaticamente. Se for um dicionário, a avaliação será realizada em cada conjunto de dados, prefixando o nome da métrica com a chave do dicionário.
  • processing_class (PreTrainedTokenizerBase ou BaseImageProcessor ou FeatureExtractionMixin ou ProcessorMixin, opcional) — Classe de processamento usada para processar os dados. Se fornecida, será usada para processar automaticamente as entradas do modelo e será salva junto com o modelo para facilitar a reexecução de um treinamento interrompido ou a reutilização do modelo ajustado.
  • model_init (Callable[[], PreTrainedModel], opcional) — Uma função que instancia o modelo a ser usado. Se fornecida, cada chamada para train() iniciará a partir de uma nova instância do modelo, conforme definido por esta função.

    A função pode ter zero argumentos, ou um único argumento contendo o objeto de trial do optuna/Ray Tune, para ser possível escolher diferentes arquiteturas de acordo com os hiperparâmetros (como o número de camadas, os tamanhos das camadas internas, as probabilidades de dropout, etc.).

  • compute_loss_func (Callable, opcional) — Uma função que aceita as saídas brutas do modelo, os rótulos e o número de itens em todo o lote acumulado (batch_size * gradient_accumulation_steps) e retorna a perda. Por exemplo, veja a função de perda padrão usada pelo Trainer.
  • compute_metrics (Callable[[EvalPrediction], Dict], opcional) — A função que será usada para calcular métricas na avaliação. Deve receber um EvalPrediction e retornar um dicionário de strings para valores de métricas. Nota Ao passar TrainingArgs com batch_eval_metrics definido como True, sua função compute_metrics deve receber um argumento booleano compute_result. Isso será acionado após o último lote de avaliação para sinalizar que a função precisa calcular e retornar as estatísticas resumidas globais, em vez de acumular as estatísticas no nível do lote
  • callbacks (Lista de TrainerCallback, opcional) — Uma lista de callbacks para personalizar o loop de treinamento. Esses callbacks serão adicionados à lista de callbacks padrão, detalhada aqui.

    Se você deseja remover um dos callbacks padrão utilizados, use o método Trainer.remove_callback().

  • optimizers (tuple[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR], opcional, padrão (None, None)) — Uma tupla contendo o otimizador e o agendador a serem usados. Por padrão, será uma instância de AdamW no seu modelo e um agendador definido por get_linear_schedule_with_warmup() controlado por args.
  • optimizer_cls_and_kwargs (tuple[Type[torch.optim.Optimizer], dict[str, Any]], opcional) — Uma tupla contendo a classe do otimizador e os argumentos de palavra-chave a serem usados. Substitui optim e optim_args em args. Incompatível com o argumento optimizers . Diferente de otimizers, este argumento evita a necessidade de colocar os parâmetros do modelo nos dispositivos corretos antes de inicializar o Trainer.

    Diferentemente de optimizers, este argumento evita a necessidade de colocar os parâmetros do modelo nos dispositivos corretos antes de inicializar o Trainer.

  • preprocess_logits_for_metrics (Callable[[torch.Tensor, torch.Tensor], torch.Tensor], opcional) — Uma função que pré-processa os logits logo antes de armazená-los em cache em cada etapa de avaliação. Deve receber dois tensores, os logits e os rótulos, e retornar os logits após o processamento desejado. As modificações feitas por esta função serão refletidas nas previsões recebidas por compute_metrics.

    Observe que os rótulos (segundo parâmetro) serão None se o conjunto de dados não os possuir.

O Trainer é um loop de treinamento e avaliação simples, porém completo, para PyTorch, otimizado para o 🤗 Transformers.

Atributos importantes:

  • model — Sempre aponta para o modelo principal. Se estiver usando um modelo do Transformers, será uma subclasse de PreTrainedModel.
  • model_wrapped — Sempre aponta para o modelo mais externo, caso um ou mais outros módulos envolvam o modelo original. Este é o modelo que deve ser usado para a passagem direta (forward pass). Por exemplo, sob DeepSpeed, o modelo interno é envolvido em DeepSpeed e, em seguida, novamente em torch.nn.DistributedDataParallel. Se o modelo interno não tiver sido envolvido, então self.model_wrapped é o mesmo que self.model.
  • is_model_parallel — Indica se um modelo foi alterado para o modo de paralelismo de modelo (diferente do paralelismo de dados, isso significa que algumas das camadas do modelo são divididas em diferentes GPUs).
  • place_model_on_device — Indica se o modelo deve ser colocado automaticamente no dispositivo. O valor padrão é True, exceto quando o paralelismo de modelos, DeepSpeed, FSDP, avaliação completa em fp16/bf16 ou SageMaker MP está ativo. Pode ser sobreposto por meio de uma subclasse de TrainingArguments e da redefinição da propriedade place_model_on_device.
  • is_in_train — Indica se um modelo está atualmente executando train (por exemplo, quando evaluate é chamado durante o train)
  • loss_is_scaled_for_ga — Indica se a loss retornada por compute_loss já foi escalonada para acúmulo de gradiente. True: training_step a utiliza como está. False: training_step a divide pelo número de passos de acúmulo de gradiente. None (padrão): a loss é considerada escalonada quando foi normalizada por num_items_in_batch, ou seja, quando o modelo aceita kwargs de loss ou quando uma compute_loss_func é passada. Subclasses que calculam sua própria loss devem definir esse valor.

add_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback )

Parâmetros

  • callback (type ou [`~transformers.TrainerCallback`]) — Uma classe TrainerCallback ou uma instância de TrainerCallback. No primeiro caso, será instanciado um membro dessa classe.

Adicione um callback à lista atual de TrainerCallback.

autocast_smart_context_manager

< >

( cache_enabled: bool | None = True )

Um wrapper auxiliar que cria um gerenciador de contexto apropriado para autocast, fornecendo os argumentos desejados, dependendo da situação. Como dependemos do accelerate para o autocast, não fazemos nada aqui.

call_model_init

< >

( trial: optuna.Trial | dict[str, Any] | None = None )

Chame model_init para obter uma nova instância do modelo, opcionalmente condicionada a um teste de hiperparâmetros.

compute_loss

< >

( model: Moduleinputs: dictreturn_outputs: bool = Falsenum_items_in_batch: typing.Union[torch.Tensor, int, NoneType] = None )

Parâmetros

  • model (nn.Module) — O modelo para o qual a perda será calculada.
  • inputs (dict[str, torch.Tensor | Any]) — Os dados de entrada para o modelo.
  • return_outputs (bool, opcional, padrão False) — Se deve retornar as saídas do modelo junto com a perda.
  • num_items_in_batch (Optional[torch.Tensor], opcional) — O número de itens no batch. Se não for informado, a perda é calculada usando a lógica padrão de redução pelo tamanho do batch.

Como a perda é calculada pelo Trainer. Por padrão, todos os modelos retornam a perda no primeiro elemento.

Subclasse e sobrescreva para um comportamento personalizado. Se você calcular sua própria perda, defina loss_is_scaled_for_ga para indicar se ela já foi escalada para o acúmulo de gradiente: False se for uma média por lote (o Trainer então a divide pelo número de etapas de acúmulo de gradiente), True se você já a normalizou sobre o lote acumulado inteiro.

compute_loss_context_manager

< >

( )

Um wrapper auxiliar para agrupar gerenciadores de contexto.

create_accelerator_and_postprocess

< >

( )

Crie o acelerador e execute a configuração pós-criação (FSDP, DeepSpeed, etc.).

create_model_card

< >

( language: str | None = Nonelicense: str | None = Nonetags: str | list[str] | None = Nonemodel_name: str | None = Nonefinetuned_from: str | None = Nonetasks: str | list[str] | None = Nonedataset_tags: str | list[str] | None = Nonedataset: str | list[str] | None = Nonedataset_args: str | list[str] | None = None )

Parâmetros

  • language (str, opcional) — O idioma do modelo (se aplicável)
  • license (str, opcional) — A licença do modelo. Será definida como a licença do modelo pré-treinado utilizado, caso o modelo original fornecido ao Trainer provenha de um repositório no Hub.
  • tags (str ou list[str], opcional) — Algumas tags a serem incluídas nos metadados do cartão do modelo.
  • model_name (str, opcional) — O nome do modelo.
  • finetuned_from (str, opcional) — O nome do modelo usado para fazer o fine-tuning deste (se aplicável). O valor padrão será o nome do repositório do modelo original fornecido ao Trainer (se ele vier do Hub).
  • tasks (str ou list[str], opcional) — Um ou vários identificadores de tarefa, a serem incluídos nos metadados do cartão do modelo.
  • dataset_tags (str ou list[str], opcional) — Uma ou várias tags de dataset, a serem incluídas nos metadados do cartão do modelo.
  • dataset (str ou list[str], opcional) — Um ou vários identificadores de dataset, a serem incluídos nos metadados do model card.
  • dataset_args (str ou list[str], opcional) — Um ou vários argumentos de dataset, a serem incluídos nos metadados do cartão do modelo.

Cria um rascunho de um cartão de modelo usando as informações disponíveis no Trainer.

create_optimizer

< >

( model = None ) → torch.optim.Optimizer

Retorna

torch.optim.Optimizer

A instância do otimizador.

Configure o otimizador.

Fornecemos um padrão razoável que funciona bem. Se você quiser usar outra coisa, pode passar uma tupla na inicialização do Trainer por meio de optimizers, ou criar uma subclasse e sobrescrever este método nela.

create_optimizer_and_scheduler

< >

( num_training_steps: int )

Configure o otimizador e o agendador de taxa de aprendizado.

Fornecemos um padrão razoável que funciona bem. Se você quiser usar outra coisa, pode passar uma tupla na inicialização do Trainer por meio de optimizers, ou criar uma subclasse e sobrescrever este método (ou create_optimizer e/ou create_scheduler) em uma subclasse.

create_scheduler

< >

( num_training_steps: intoptimizer: typing.Optional[torch.optim.Optimizer] = None ) → torch.optim.lr_scheduler.LRScheduler

Parâmetros

  • num_training_steps (int) — O número de etapas de treinamento a serem executadas.

Retorna

torch.optim.lr_scheduler.LRScheduler

A instância do agendador de taxa de aprendizado.

Configure o scheduler. O otimizador do trainer deve ter sido configurado antes da chamada deste método ou passado como argumento.

fim

< >

( )

Conclua os rastreadores e destrua o grupo de processo distribuído.

Chame isso uma única vez, no final de um script, depois de tudo que precisa dos outros processos: train(), evaluate(), predict(), save_model() e push_to_hub() se comunicam entre processos e falharão quando o grupo for removido.

Exemplo:

trainer.train()
trainer.evaluate()
trainer.push_to_hub()
trainer.end()

evaluate

< >

( eval_dataset: typing.Union[torch.utils.data.Dataset, dict[str, torch.utils.data.Dataset], NoneType] = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval' )

Parâmetros

  • eval_dataset (Dataset | dict[str, Dataset], opcional) — Passe um dataset se desejar substituir self.eval_dataset. Se for um Dataset, colunas não aceitas pelo model.forward() método são removidas automaticamente. Se for um dicionário, ele avaliará em cada dataset, prefixando o nome da métrica com a chave do dicionário.

    Se você passar um dicionário com os nomes dos conjuntos de dados como chaves e os conjuntos de dados como valores, o evaluate executará avaliações separadas em cada conjunto de dados. Isso pode ser útil para monitorar como o treinamento afeta outros conjuntos de dados ou simplesmente para obter uma avaliação mais detalhada. Ao usar com load_best_model_at_end, certifique-se de que metric_for_best_model referencie exatamente um dos conjuntos de dados. Se, por exemplo, você passar {"data1": data1, "data2": data2} para dois conjuntos de dados data1 e data2, você pode especificar metric_for_best_model="eval_data1_loss" para usar a perda em data1 e metric_for_best_model="eval_data2_loss" para a perda em data2.

  • ignore_keys (list[str], opcional) — Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao coletar as previsões.
  • metric_key_prefix (str, opcional, padrão "eval") — Um prefixo opcional a ser usado como prefixo da chave das métricas. Por exemplo, a métrica “bleu” será nomeada “eval_bleu” se o prefixo for “eval” (padrão)

Executa a avaliação e retorna as métricas.

O script de chamada será responsável por fornecer um método para calcular as métricas, pois elas dependem da tarefa (passe-o para o argumento compute_metrics de inicialização).

Você também pode criar uma subclasse e sobrescrever este método para injetar um comportamento personalizado.

evaluation_loop

< >

( dataloader: DataLoaderdescription: strprediction_loss_only: bool | None = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval' )

Loop de previsão/avaliação, compartilhado por Trainer.evaluate() e Trainer.predict().

Funciona com ou sem rótulos.

floating_point_ops

< >

( inputs: dict ) → int

Parâmetros

  • inputs (dict[str, torch.Tensor | Any]) — As entradas e os alvos do modelo.

Retorna

int

O número de operações de ponto flutuante.

Para modelos que herdam de PreTrainedModel, usa esse método para calcular o número de operações de ponto flutuante para cada passagem de retropropagação + propagação direta. Se estiver usando outro modelo, implemente um método assim no modelo ou crie uma subclasse e sobrescreva este método.

get_batch_samples

< >

( epoch_iterator: Iteratornum_batches: intdevice: device )

Coleta um número especificado de lotes do iterador de época e, opcionalmente, conta o número de itens nos lotes para escalar adequadamente a perda.

get_cp_size

< >

( )

Obter o tamanho do paralelismo de contexto

get_decay_parameter_names

< >

( model: Module )

Obtenha todos os nomes de parâmetros aos quais o weight decay será aplicado.

Esta função filtra parâmetros de duas maneiras:

  1. Por tipo de camada (instâncias de camadas especificadas em ALL_LAYERNORM_LAYERS)
  2. Por padrões de nome de parâmetro (contendo ‘bias’ ou variação de ‘norm’)

get_eval_dataloader

< >

( eval_dataset: typing.Union[str, torch.utils.data.Dataset, NoneType] = None )

Parâmetros

  • eval_dataset (str ou torch.utils.data.Dataset, opcional) — Se for uma str, usará self.eval_dataset[eval_dataset] como o conjunto de dados de avaliação. Se for um Dataset, substituirá self.eval_dataset. Se for um Dataset, as colunas não aceitas pelo método model.forward() são removidas automaticamente.

Retorna o ~torch.utils.data.DataLoader de avaliação.

Subclasse e sobrescreva este método se você quiser injetar algum comportamento personalizado.

get_learning_rates

< >

( )

Retorna a taxa de aprendizado de cada parâmetro de self.optimizer.

get_num_trainable_parameters

< >

( )

Obtenha o número de parâmetros treináveis.

get_optimizer_cls_and_kwargs

< >

( args: TrainingArgumentsmodel: transformers.modeling_utils.PreTrainedModel | None = None )

Parâmetros

  • args (transformers.training_args.TrainingArguments) — Os argumentos de treinamento para a sessão de treinamento.
  • model (PreTrainedModel, opcional) — O modelo em treinamento. Obrigatório para alguns otimizadores (GaLore, Apollo, LOMO).

Retorna a classe do otimizador e os parâmetros do otimizador com base nos argumentos de treinamento.

get_optimizer_group

< >

( param: typing.Union[str, torch.nn.parameter.Parameter, NoneType] = None )

Parâmetros

  • param (str ou torch.nn.parameter.Parameter, opcional) — O parâmetro para o qual o grupo do otimizador precisa ser retornado.

Retorna o grupo do otimizador para um parâmetro, se fornecido; caso contrário, retorna todos os grupos do otimizador para os parâmetros.

get_sp_size

< >

( )

Obter o tamanho do paralelismo de sequência

get_test_dataloader

< >

( test_dataset: Dataset )

Parâmetros

  • test_dataset (torch.utils.data.Dataset, opcional) — O conjunto de dados de teste a ser usado. Se for um Dataset, as colunas não aceitas pelo método model.forward() são removidas automaticamente.

Retorna o ~torch.utils.data.DataLoader de teste.

Subclasse e sobrescreva este método se você quiser injetar algum comportamento personalizado.

get_total_train_batch_size

< >

( args: TrainingArguments )

Calcula o tamanho total do lote (micro_batch grad_accum dp_world_size).

Leva em consideração todas as dimensões de paralelismo: TP, CP e SP.

Fórmula: dp_world_size = world_size // (tp_size cp_size sp_size)

Onde:

  • TP (Paralelismo de Tensor): Camadas do modelo divididas entre GPUs
  • CP (Paralelismo de Contexto): Sequências divididas usando Ring Attention (FSDP2)
  • SP (Paralelismo de Sequência): Sequências divididas usando ALST/Ulysses (DeepSpeed)

Todas as dimensões são separadas e multiplicativas: world_size = dp_size tp_size cp_size * sp_size

get_tp_size

< >

( )

Obtenha o tamanho do paralelismo de tensor a partir da configuração do modelo ou do DeepSpeed.

get_train_dataloader

< >

( )

Retorna o ~torch.utils.data.DataLoader de treinamento.

Usará nenhum sampler se train_dataset não implementar __len__, caso contrário, usará um sampler aleatório (adaptado para treinamento distribuído, se necessário).

Subclasse e sobrescreva este método se você quiser injetar algum comportamento personalizado.

hyperparameter_search

< >

( hp_space: collections.abc.Callable[['optuna.Trial'], dict[str, float]] | None = Nonecompute_objective: collections.abc.Callable[[dict[str, float]], float] | None = Nonen_trials: int = 20direction: str | list[str] = 'minimize'backend: str | transformers.trainer_utils.HPSearchBackend | None = Nonehp_name: collections.abc.Callable[['optuna.Trial'], str] | None = None**kwargs ) → [trainer_utils.BestRun or list[trainer_utils.BestRun]]

Parâmetros

  • hp_space (Callable[["optuna.Trial"], dict[str, float]], opcional) — Uma função que define o espaço de busca de hiperparâmetros. O padrão será default_hp_space_optuna() ou default_hp_space_ray() dependendo do seu backend.
  • compute_objective (Callable[[dict[str, float]], float], opcional) — Uma função que calcula o objetivo a ser minimizado ou maximizado a partir das métricas retornadas pelo método evaluate. O valor padrão será default_compute_objective().
  • n_trials (int, opcional, padrão 100) — O número de execuções de teste a serem realizadas.
  • direction (str ou list[str], opcional, padrão "minimize") — Se for otimização de objetivo único, str é a direção, podendo ser "minimize" ou "maximize". Você deve escolher "minimize" ao otimizar a perda de validação e "maximize" ao otimizar uma ou várias métricas. Se for otimização de múltiplos objetivos, list[str] é a direção, podendo ser uma lista de "minimize" e "maximize". Você deve escolher "minimize" ao otimizar a perda de validação e "maximize" ao otimizar uma ou várias métricas.
  • backend (str ou ~training_utils.HPSearchBackend, opcional) — O backend a ser usado para a busca de hiperparâmetros. O padrão será optuna ou Ray Tune, dependendo de qual estiver instalado. Se todos estiverem instalados, o padrão será optuna.
  • hp_name (Callable[["optuna.Trial"], str]], opcional) — Uma função que define o nome do trial/execução. O valor padrão é None.
  • kwargs (dict[str, Any], opcional) — Argumentos de palavra-chave adicionais para cada backend:

Retorna

[trainer_utils.BestRun ou list[trainer_utils.BestRun]]

Todas as informações sobre a melhor execução ou as melhores execuções para otimização multiobjetivo. O resumo do experimento pode ser encontrado no atributo run_summary para o backend Ray.

Inicie uma busca de hiperparâmetros usando optuna ou Ray Tune. A quantidade otimizada é determinada por compute_objective, que por padrão é uma função que retorna a perda de avaliação quando nenhuma métrica é fornecida, ou a soma de todas as métricas, caso contrário.

Para usar este método, você precisa ter fornecido um model_init ao inicializar seu Trainer: precisamos reinicializar o modelo em cada nova execução. Isso é incompatível com o argumento optimizers, então você precisa criar uma subclasse de Trainer e sobrescrever o método create_optimizer_and_scheduler() para um otimizador/agendador personalizado.

init_hf_repo

< >

( token: str | None = Noneprivate: bool | None = None )

Parâmetros

  • token (str, opcional) — Token com permissão de escrita. O valor padrão é self.args.hub_token.
  • private (bool, opcional) — Se o repositório deve ser privado quando for criado. O valor padrão é self.args.hub_private_repo. Não tem efeito se o repositório já existir.

Inicializa um repositório git em self.args.hub_model_id.

is_local_process_zero

< >

( )

Se este processo é o processo principal local (por exemplo, em uma única máquina, caso o treinamento seja distribuído em várias máquinas).

is_world_process_zero

< >

( )

Se este processo é o processo principal global (quando o treinamento é realizado de forma distribuída em várias máquinas, isso será True apenas para um processo).

log

< >

( logs: dictstart_time: float | None = None )

Parâmetros

  • logs (dict[str, float]) — Os valores a serem registrados.
  • start_time (Optional[float]) — O início do treinamento.

Registre logs nos diversos objetos que monitoram o treinamento.

Subclasseie e sobrescreva este método para injetar um comportamento personalizado.

log_metrics

< >

( splitmetrics )

Parâmetros

  • split (str) — Nome do modo/divisão: um de train, eval, test
  • metrics (dict[str, float]) — As métricas retornadas de train/evaluate/predictmetrics: dict de métricas

Registre métricas de uma forma especialmente formatada.

Em um ambiente distribuído, isso é feito apenas para o processo com rank 0.

Observações sobre os relatórios de memória:

Para obter o relatório de uso de memória, você precisa instalar psutil. Você pode fazer isso com pip install psutil.

Agora, quando este método é executado, você verá um relatório que incluirá:

init_mem_cpu_alloc_delta   =     1301MB
init_mem_cpu_peaked_delta  =      154MB
init_mem_gpu_alloc_delta   =      230MB
init_mem_gpu_peaked_delta  =        0MB
train_mem_cpu_alloc_delta  =     1345MB
train_mem_cpu_peaked_delta =        0MB
train_mem_gpu_alloc_delta  =      693MB
train_mem_gpu_peaked_delta =        7MB

Entendendo os relatórios:

  • o primeiro segmento, por exemplo, train__, indica em qual etapa as métricas se referem. Os relatórios que começam com init_ serão adicionados à primeira etapa que for executada. Assim, se apenas a avaliação for executada, o uso de memória do __init__ será reportado junto com as métricas de eval_.
  • o terceiro segmento, que é cpu ou gpu, indica se se trata da RAM geral ou da memória da gpu0.
  • *_alloc_delta - é a diferença no contador de memória usada/alocada entre o fim e o início da etapa - pode ser negativa se uma função liberou mais memória do que alocou.
  • *_peaked_delta - é qualquer memória extra que foi consumida e depois liberada - em relação ao contador atual de memória alocada - nunca é negativo. Ao analisar as métricas de qualquer etapa, você soma alloc_delta + peaked_delta e sabe quanto de memória foi necessário para concluir aquela etapa.

O relatório é gerado apenas para o processo de rank 0 e a gpu 0 (se houver uma gpu). Normalmente, isso é suficiente, pois o processo principal executa a maior parte do trabalho, mas pode não ser o caso se o paralelismo de modelo for utilizado, já que outras GPUs podem usar uma quantidade diferente de memória de gpu. Isso também não é o mesmo no DataParallel, onde a gpu0 pode exigir muito mais memória que as demais, pois armazena os gradientes e os estados do otimizador para todas as GPUs participantes. Talvez, no futuro, esses relatórios evoluam para medir esses aspectos também.

A métrica de RAM de CPU mede o RSS (Resident Set Size), que inclui tanto a memória exclusiva do processo quanto a memória compartilhada com outros processos. É importante observar que ela não inclui a memória trocada (swapped out), portanto, os relatórios podem ser imprecisos.

A memória de pico da CPU é medida usando uma thread de amostragem. Devido ao GIL do Python, ela pode perder parte da memória de pico se essa thread não tiver tido a chance de executar no momento em que o uso de memória mais alto ocorreu. Portanto, esse relatório pode ser menor que a realidade. O uso de tracemalloc teria reportado a memória de pico exata, mas ele não reporta alocações de memória fora do Python. Assim, se alguma extensão C++ CUDA alocou sua própria memória, ela não será reportada. E, por isso, ele foi descartado em favor da abordagem de amostragem de memória, que lê o uso atual de memória do processo.

O relatório de memória alocada e de pico na GPU é feito com torch.cuda.memory_allocated() e torch.cuda.max_memory_allocated(). Essa métrica relata apenas “deltas” para alocações específicas do PyTorch, pois o sistema de gerenciamento de memória do torch.cuda não rastreia nenhuma memória alocada fora do PyTorch. Por exemplo, a primeira chamada cuda normalmente carrega kernels CUDA, o que pode consumir de 0,5 a 2 GB de memória de GPU.

Observe que esse rastreador não leva em conta as alocações de memória fora das chamadas de __init__, train, evaluate e predict do Trainer.

Como as chamadas de evaluation podem ocorrer durante o train, não podemos lidar com invocações aninhadas, pois torch.cuda.max_memory_allocated é um contador único; se ele for reiniciado por uma chamada de eval aninhada, o rastreador do train reportará informações incorretas. Se essa questão do PyTorch for resolvida, será possível alterar esta classe para que ela seja reentrante. Até lá, rastrearemos apenas o nível externo dos métodos train, evaluate e predict. Isso significa que, se eval for chamado durante o train, será este último que contabilizará o uso de memória dele e do primeiro.

Isso também significa que, se qualquer outra ferramenta usada junto com o Trainer chamar torch.cuda.reset_peak_memory_stats, as estatísticas de pico de memória da GPU podem ficar inválidas. E o Trainer vai interferir no comportamento normal de qualquer ferramenta que dependa de chamar torch.cuda.reset_peak_memory_stats por conta própria.

Para o melhor desempenho, você pode considerar desativar o perfilamento de memória para execuções em produção.

metrics_format

< >

( metrics: dict ) → metrics (dict[str, float])

Parâmetros

  • metrics (dict[str, float]) — As métricas retornadas por train/evaluate/predict

Retorna

métricas (dict[str, float])

As métricas reformuladas

Reformate os valores das métricas do Trainer para um formato legível por humanos.

num_examples

< >

( dataloader: DataLoader )

Auxiliar para obter o número de amostras em um ~torch.utils.data.DataLoader acessando seu dataset. Quando dataloader.dataset não existe ou não tem comprimento, estima da melhor forma possível

pop_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback ) → TrainerCallback

Parâmetros

  • callback (type ou [`~transformers.TrainerCallback`]) — Uma classe TrainerCallback ou uma instância de TrainerCallback. No primeiro caso, será removido o primeiro membro dessa classe encontrado na lista de callbacks.

Retorna

TrainerCallback

O callback removido, se encontrado.

Remove um callback da lista atual de TrainerCallback e o retorna.

Se o callback não for encontrado, retorna None (e nenhum erro é lançado).

predict

< >

( test_dataset: Datasetignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'test' )

Parâmetros

  • test_dataset (Dataset) — Conjunto de dados para executar as previsões. Se for um datasets.Dataset, as colunas não aceitas pelo método model.forward() são removidas automaticamente.
  • ignore_keys (list[str], opcional) — Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao coletar as previsões.
  • metric_key_prefix (str, opcional, padrão "test") — Um prefixo opcional a ser usado como prefixo da chave das métricas. Por exemplo, a métrica “bleu” será nomeada “test_bleu” se o prefixo for “test” (padrão)

Executa a previsão e retorna as previsões e métricas potenciais.

Dependendo do conjunto de dados e do seu caso de uso, seu conjunto de teste pode conter rótulos. Nesse caso, este método também retornará métricas, como em evaluate().

Se as suas previsões ou rótulos tiverem comprimentos de sequência diferentes (por exemplo, porque você está fazendo padding dinâmico em uma tarefa de classificação de tokens), as previsões serão preenchidas (à direita) para permitir a concatenação em um único array. O índice de padding é -100.

Retorna: NamedTuple Uma namedtuple com as seguintes chaves:

  • predictions (np.ndarray): As previsões em test_dataset.
  • label_ids (np.ndarray, opcional): Os rótulos (se o conjunto de dados continha alguns).
  • metrics (dict[str, float], opcional): O dicionário potencial de métricas (se o conjunto de dados contivesse rótulos).

prediction_step

< >

( model: Moduleinputs: dictprediction_loss_only: boolignore_keys: list[str] | None = None ) → tuple[Optional[torch.Tensor], Optional[torch.Tensor], Optional[torch.Tensor]]

Parâmetros

  • model (nn.Module) — O modelo a ser avaliado.
  • inputs (dict[str, torch.Tensor | Any]) — As entradas e os alvos do modelo.

    O dicionário será descompactado antes de ser enviado ao modelo. A maioria dos modelos espera os alvos sob o argumento labels. Consulte a documentação do seu modelo para verificar todos os argumentos aceitos.

  • prediction_loss_only (bool) — Indica se apenas a perda deve ser retornada.
  • ignore_keys (list[str], opcional) — Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao coletar as previsões.

Retorna

tuple[Optional[torch.Tensor], Optional[torch.Tensor], Optional[torch.Tensor]]

Uma tupla com a perda, logits e rótulos (cada um sendo opcional).

Execute uma etapa de avaliação em model usando inputs.

Subclasse e sobrescreva para injetar comportamento personalizado.

push_to_hub

< >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )

Parâmetros

  • commit_message (str, opcional, padrão "End of training") — Mensagem a ser commitada durante o push.
  • blocking (bool, opcional, padrão True) — Se a função deve retornar apenas quando o git push tiver terminado.
  • token (str, opcional, padrão None) — Token com permissão de escrita para sobrescrever os argumentos originais do Trainer.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo da branch “main”.
  • private (bool, opcional) — Se o repositório deve ser privado quando for criado. O valor padrão é args.hub_private_repo. Não tem efeito se o repositório já existir.
  • kwargs (dict[str, Any], opcional) — Argumentos de palavra-chave adicionais passados para create_model_card().

Envie self.model e self.processing_class para o hub de modelos do 🤗 no repositório self.args.hub_model_id.

remove_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback )

Parâmetros

  • callback (type ou [`~transformers.TrainerCallback`]) — Uma classe TrainerCallback ou uma instância de TrainerCallback. No primeiro caso, removerá o primeiro membro dessa classe encontrado na lista de callbacks.

Remove um callback da lista atual de TrainerCallback.

save_metrics

< >

( splitmetricscombined = True )

Parâmetros

  • split (str) — Nome do modo/divisão: um de train, eval, test, all
  • metrics (dict[str, float]) — As métricas retornadas por train/evaluate/predict
  • combined (bool, opcional, padrão True) — Cria métricas combinadas atualizando o all_results.json com as métricas desta chamada

Salve as métricas em um arquivo json para essa divisão, por exemplo, train_results.json.

Em um ambiente distribuído, isso é feito apenas para o processo com rank 0.

Para entender as métricas, leia a docstring de log_metrics(). A única diferença é que números brutos e não formatados são salvos no método atual.

save_model

< >

( output_dir: str | None = None_internal_call: bool = False )

Salvará o modelo, permitindo que você o recarregue usando from_pretrained().

Será salvo apenas a partir do processo principal.

save_state

< >

( )

Salva o estado do Trainer, pois Trainer.save_model salva apenas o tokenizer junto com o modelo.

Em um ambiente distribuído, isso é feito apenas para o processo com rank 0.

set_initial_training_values

< >

( args: TrainingArgumentsdataloader: DataLoader )

Calcula e retorna os seguintes valores:

  • num_train_epochs
  • num_update_steps_per_epoch
  • num_examples
  • num_train_samples
  • total_train_batch_size
  • steps_in_epoch (total de lotes por época)
  • max_steps

store_flos

< >

( )

Armazene o número de operações de ponto flutuante que foram realizadas no modelo.

treino

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → TrainOutput

Parâmetros

  • resume_from_checkpoint (str ou bool, opcional) — Se for uma str, caminho local para um checkpoint salvo por uma instância anterior de Trainer. Se for um bool e for igual a True, carrega o último checkpoint em args.output_dir salvo por uma instância anterior de Trainer. Se presente, o treinamento será retomado a partir dos estados do modelo/otimizador/agendador carregados aqui.
  • trial (optuna.Trial ou dict[str, Any], opcional) — A execução do trial ou o dicionário de hiperparâmetros para a busca de hiperparâmetros.
  • ignore_keys_for_eval (list[str], opcional) — Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao coletar as previsões para avaliação durante o treinamento.

Retorna

TrainOutput

Objeto contendo a contagem global de etapas, a perda de treinamento e as métricas.

Ponto de entrada principal do treinamento.

training_step

< >

( model: Moduleinputs: dictnum_items_in_batch: typing.Union[torch.Tensor, int, NoneType] = None ) → torch.Tensor

Parâmetros

  • model (nn.Module) — O modelo a ser treinado.
  • inputs (dict[str, torch.Tensor | Any]) — As entradas e os alvos do modelo.

    O dicionário será descompactado antes de ser enviado ao modelo. A maioria dos modelos espera os alvos sob o argumento labels. Consulte a documentação do seu modelo para verificar todos os argumentos aceitos.

Retorna

torch.Tensor

O tensor com a perda de treinamento neste lote.

Execute um passo de treinamento em um lote de entradas.

Subclasse e sobrescreva para injetar comportamento personalizado.

Seq2SeqTrainer

classe transformers.Seq2SeqTrainer

< >

( model: typing.Union[ForwardRef('PreTrainedModel'), torch.nn.Module, NoneType] = Noneargs: typing.Optional[ForwardRef('TrainingArguments')] = Nonedata_collator: typing.Optional[ForwardRef('DataCollator')] = Nonetrain_dataset: typing.Union[torch.utils.data.Dataset, ForwardRef('IterableDataset'), ForwardRef('datasets.Dataset'), NoneType] = Noneeval_dataset: typing.Union[torch.utils.data.Dataset, dict[str, torch.utils.data.Dataset], NoneType] = Noneprocessing_class: typing.Union[ForwardRef('PreTrainedTokenizerBase'), ForwardRef('BaseImageProcessor'), ForwardRef('FeatureExtractionMixin'), ForwardRef('ProcessorMixin'), NoneType] = Nonemodel_init: collections.abc.Callable[[], 'PreTrainedModel'] | None = Nonecompute_loss_func: collections.abc.Callable | None = Nonecompute_metrics: collections.abc.Callable[['EvalPrediction'], dict] | None = Nonecallbacks: list['TrainerCallback'] | None = Noneoptimizers: tuple = (None, None)preprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = None )

evaluate

< >

( eval_dataset: typing.Optional[torch.utils.data.Dataset] = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval'**gen_kwargs )

Parâmetros

  • eval_dataset (Dataset, opcional) — Passe um dataset se desejar substituir self.eval_dataset. Se for um Dataset, as colunas não aceitas pelo método model.forward() são removidas automaticamente. Ele deve implementar o método __len__.
  • ignore_keys (list[str], opcional) — Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao coletar as previsões.
  • metric_key_prefix (str, opcional, padrão "eval") — Um prefixo opcional a ser usado como prefixo da chave das métricas. Por exemplo, a métrica “bleu” será nomeada “eval_bleu” se o prefixo for "eval" (padrão)
  • max_length (int, opcional) — O comprimento máximo do alvo a ser usado ao prever com o método generate.
  • num_beams (int, opcional) — Número de feixes para a busca por feixes que será usado ao prever com o método generate. 1 significa que não há busca por feixes.
  • gen_kwargs — Kwargs específicos adicionais de generate.

Executa a avaliação e retorna as métricas.

O script de chamada será responsável por fornecer um método para calcular as métricas, pois elas dependem da tarefa (passe-o para o argumento compute_metrics de inicialização).

Você também pode criar uma subclasse e sobrescrever este método para injetar um comportamento personalizado.

predict

< >

( test_dataset: Datasetignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'test'**gen_kwargs )

Parâmetros

  • test_dataset (Dataset) — Conjunto de dados em que as previsões serão executadas. Se for um Dataset, as colunas não aceitas pelo método model.forward() são removidas automaticamente. Deve implementar o método __len__
  • ignore_keys (list[str], opcional) — Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao coletar as previsões.
  • metric_key_prefix (str, opcional, padrão "eval") — Um prefixo opcional a ser usado como prefixo da chave das métricas. Por exemplo, a métrica “bleu” será nomeada “eval_bleu” se o prefixo for "eval" (padrão)
  • max_length (int, opcional) — O comprimento máximo do alvo a ser usado ao prever com o método generate.
  • num_beams (int, opcional) — Número de feixes para a busca por feixes que será usado ao prever com o método generate. 1 significa que não há busca por feixes.
  • gen_kwargs — Kwargs específicos adicionais de generate.

Executa a previsão e retorna as previsões e métricas potenciais.

Dependendo do conjunto de dados e do seu caso de uso, seu conjunto de teste pode conter rótulos. Nesse caso, este método também retornará métricas, como em evaluate().

Se as suas previsões ou rótulos tiverem comprimentos de sequência diferentes (por exemplo, porque você está fazendo padding dinâmico em uma tarefa de classificação de tokens), as previsões serão preenchidas (à direita) para permitir a concatenação em um único array. O índice de padding é -100.

Retorna: NamedTuple Uma namedtuple com as seguintes chaves:

  • predictions (np.ndarray): As previsões em test_dataset.
  • label_ids (np.ndarray, opcional): Os rótulos (se o conjunto de dados continha alguns).
  • metrics (dict[str, float], opcional): O dicionário potencial de métricas (se o conjunto de dados contivesse rótulos).

TrainingArguments

classe transformers.TrainingArguments

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 5e-05lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool = Falsefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool | None = Nonegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 500logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Falserestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: typing.Any | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Truelabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1 )

Parâmetros

  • output_dir (str, opcional, padrão "trainer_output") — O diretório de saída onde as previsões do modelo e os checkpoints serão gravados.

Duração do treinamento e tamanho do lote

  • per_device_train_batch_size (int, opcional, padrão 8) — O tamanho do lote por dispositivo. O tamanho global do lote é calculado como: per_device_train_batch_size * number_of_devices em configurações multi-GPU ou distribuídas.
  • num_train_epochs(float, opcional, padrão 3.0) — Número total de épocas de treinamento a serem executadas (se não for um número inteiro, executará a parte decimal em porcentagem da última época antes de interromper o treinamento).
  • max_steps (int, opcional, padrão -1) — Substitui num_train_epochs. Se definido para um número positivo, representa o número total de etapas de treinamento a serem executadas. Para um conjunto de dados finito, o treinamento é reiterado pelo conjunto de dados (se todos os dados forem esgotados) até que max_steps seja atingido. Deve ser definido para um valor positivo quando o conjunto de dados de treinamento não implementa __len__ (por exemplo, um conjunto de dados em streaming), pois o número total de etapas não pode ser inferido e é necessário para limitar o loop de treinamento e configurar o agendador de taxa de aprendizado.

Taxa de aprendizado e agendador

  • learning_rate (float, opcional, padrão 5e-5) — A taxa de aprendizado inicial do otimizador. Normalmente, este é o valor máximo da taxa de aprendizado ao usar um agendador com aquecimento.
  • lr_scheduler_type (str ou SchedulerType, opcional, padrão é "linear") — O tipo de agendador de taxa de aprendizado a ser usado. Consulte SchedulerType para todos os valores possíveis. Opções comuns:
  • lr_scheduler_kwargs (dict ou str, opcional, padrão None) — Os argumentos extras para o lr_scheduler. Consulte a documentação de cada scheduler para os valores possíveis.
  • warmup_steps (int ou float, opcional, padrão é 0) — Número de etapas para um aquecimento linear de 0 até learning_rate. O aquecimento ajuda a estabilizar o treinamento na fase inicial. Pode ser:
    • Um inteiro: número exato de etapas de aquecimento
    • Um float no intervalo [0, 1): interpretado como a proporção do total de etapas de treinamento

Otimizador

  • optim (str ou training_args.OptimizerNames, opcional, padrão é "adamw_torch" (para torch>=2.8 "adamw_torch_fused")) — O otimizador a ser usado. Opções comuns:
    • "adamw_torch": AdamW do PyTorch (padrão recomendado)
    • "adamw_torch_fused": Kernel de AdamW fundido
    • "adamw_hf": implementação do AdamW da HuggingFace
    • "sgd": Stochastic Gradient Descent com momentum
    • "adafactor": Otimizador eficiente em memória para modelos grandes
    • "adamw_8bit": AdamW de 8 bits (requer bitsandbytes) Veja OptimizerNames para a lista completa.
  • optim_args (str, opcional) — Argumentos opcionais fornecidos a otimizadores como AnyPrecisionAdamW, AdEMAMix e GaLore.
  • weight_decay (float, opcional, padrão 0) — Coeficiente de decaimento de peso aplicado pelo otimizador (não pela função de perda). Adiciona regularização L2 para evitar overfitting, penalizando pesos grandes. Excluído automaticamente dos parâmetros de bias e LayerNorm. Valores típicos: 0.01 (padrão), 0.1 (regularização mais forte), 0.0 (sem regularização).
  • adam_beta1 (float, opcional, padrão 0.9) — A taxa de decaimento exponencial para as estimativas do primeiro momento (momentum) em otimizadores baseados em Adam. Controla a quantidade de histórico de gradientes a ser mantida.
  • adam_beta2 (float, opcional, padrão 0.999) — A taxa de decaimento exponencial para as estimativas do segundo momento (variância) em otimizadores baseados em Adam. Controla a escala da taxa de aprendizado adaptativa.
  • adam_epsilon (float, opcional, padrão 1e-8) — Valor de epsilon para estabilidade numérica em otimizadores baseados em Adam. Impede a divisão por zero no denominador da regra de atualização.
  • optim_target_modules (Union[str, list[str]], opcional) — Os módulos-alvo a serem otimizados, ou seja, os nomes dos módulos que você deseja treinar. Atualmente usado para o algoritmo GaLore e o algoritmo APOLLO. Veja implementação do GaLore e implementação do APOLLO para mais detalhes. Você precisa garantir que passe um otimizador GaLore ou APOLLO válido, por exemplo, um dos seguintes: “apollo_adamw”, “galore_adamw”, “galore_adamw_8bit”, “galore_adafactor” e garantir que os módulos-alvo sejam apenas módulos nn.Linear.

Regularização e Estabilidade do Treinamento

  • gradient_accumulation_steps (int, opcional, padrão 1) — Número de etapas de atualização para acumular gradientes antes de executar uma passagem de retropropagação/atualização. Simula tamanhos de lote maiores sem memória adicional. Tamanho de lote efetivo = per_device_train_batch_size × num_devices × gradient_accumulation_steps.

    Ao usar acúmulo de gradiente, um “passo” é contado como um passo com uma passagem reversa. Portanto, o registro, a avaliação e o salvamento ocorrerão a cada gradient_accumulation_steps × xxx_step exemplos de treinamento.

  • average_tokens_across_devices (bool, opcional, padrão True) — Indica se as tokens devem ser médias entre os dispositivos. Se habilitado, usará all_reduce para sincronizar num_tokens_in_batch para um cálculo preciso da perda. Referência: https://github.com/huggingface/transformers/issues/34242
  • max_grad_norm (float, opcional, padrão 1.0) — Norma máxima do gradiente para o recorte de gradiente. Aplicada após a passagem reversa, antes da etapa do otimizador. Impede a explosão de gradientes ao reduzir os gradientes quando sua norma global excede esse limite. Defina como 0 para desativar o recorte. Valores típicos: 1.0 (padrão), 0.5 (mais conservador), 5.0 (menos agressivo).
  • label_smoothing_factor (float, opcional, padrão 0.0) — Fator de label smoothing para evitar excesso de confiança. Substitui os alvos rígidos 0/1 por alvos suaves: 0 se torna ε/num_labels e 1 se torna 1 - ε + ε/num_labels, onde ε = label_smoothing_factor. Zero significa que não há suavização. Faixa típica: 0.0 a 0.1.

Treinamento com Precisão Mista

  • bf16 (bool, opcional, padrão False) — Ativa o treinamento com precisão mista bfloat16 (BF16) Geralmente preferível ao FP16 devido à melhor estabilidade numérica e à ausência de necessidade de escalonamento de perda.
  • fp16 (bool, opcional, padrão False) — Ativa o treinamento com precisão mista float16 (FP16). Considere usar BF16 em vez disso, se o seu hardware for compatível.
  • bf16_full_eval (bool, opcional, padrão False) — Usa precisão BF16 completa para avaliação (não apenas precisão mista). Mais rápido e economiza memória, mas pode afetar ligeiramente os valores das métricas. Aplica-se apenas durante a avaliação.
  • fp16_full_eval (bool, opcional, padrão False) — Usa precisão FP16 completa para avaliação (não apenas precisão mista). Mais rápido e economiza memória, mas pode afetar ligeiramente os valores das métricas. Aplica-se apenas durante a avaliação.
  • tf32 (bool, opcional) — Ativa o modo TensorFloat-32 (TF32) em GPUs Ampere e mais recentes. O TF32 usa precisão de 19 bits para multiplicações de matrizes (em vez dos 23 bits do FP32), proporcionando até 8x de aceleração com perda de precisão negligível. O valor padrão depende da versão do PyTorch. Veja documentação do TF32.

Checkpointing de Ativação

  • activation_checkpointing (bool, opcional, padrão False) — Ativa o checkpointing de ativações para trocar computação por memória. Reduz o uso de memória limpando as ativações durante a passagem de frente e recalculando-as durante a passagem de trás. Permite treinar modelos maiores ou tamanhos de lote maiores, com o custo de um treinamento ~20% mais lento.
  • activation_checkpointing_kwargs (dict, opcional, padrão None) — Argumentos de palavra-chave passados para activation_checkpointing_enable(). every_n_layers aplica checkpoint apenas a cada n-ésima camada do decodificador, em vez de todas; 1 é o comportamento usual de tudo ou nada, e valores maiores devolvem alguma memória em troca de velocidade. offload mantém as ativações salvas em memória de host fixada, o que libera layers x sequence x hidden bytes de memória de dispositivo e torna o passo mais lento. Qualquer outra chave é encaminhada para torch.utils.checkpoint.checkpoint.
  • gradient_checkpointing (bool, opcional) — Alias descontinuado de activation_checkpointing, será removido na v6.
  • gradient_checkpointing_kwargs (dict, opcional) — Alias descontinuado de activation_checkpointing_kwargs, será removido na v6.

Compilação

  • torch_compile (bool, opcional, padrão False) — Compila o modelo usando o torch.compile() do PyTorch 2.0 para um treinamento mais rápido. Pode fornecer um ganho de 20-50% em velocidade sem alterações no código. Usa as configurações de compilação padrão, a menos que torch_compile_backend ou torch_compile_mode sejam especificados.
  • torch_compile_backend (str, opcional) — Backend para torch.compile(). Se definido, ativa automaticamente torch_compile. As opções incluem "inductor" (padrão), "aot_eager", "cudagraphs". Os backends variam conforme a versão do PyTorch - consulte a documentação do PyTorch para as opções disponíveis.
  • torch_compile_mode (str, opcional) — Modo de compilação para torch.compile(). Se definido, ativa automaticamente torch_compile. Opções: "default", "reduce-overhead" (minimizar sobrecarga do Python), "max-autotune" (otimização agressiva, tempo de compilação mais lento).

Kernels

  • use_liger_kernel (bool, opcional, padrão False) — Ativa as otimizações do Liger Kernel. Aumenta o throughput em multi-GPU em ~20% e reduz o uso de memória em ~60%. Funciona com Flash Attention, FSDP e DeepSpeed. Atualmente suporta os modelos Llama, Mistral, Mixtral e Gemma.
  • liger_kernel_config (Optional[dict], opcional) — Configuração para o Liger Kernel. Passado como kwargs para _apply_liger_kernel_to_instance(). As opções geralmente incluem: "rope", "swiglu", "cross_entropy", "fused_linear_cross_entropy", "rms_norm". Se None, usa a configuração padrão.

Otimizações adicionais

  • use_cache (bool, opcional, padrão False) — Indica se a cache do modelo deve ser ativada. Para treinamento, isso geralmente não é necessário, exceto em alguns métodos PEFT que utilizam past_key_values.
  • neftune_noise_alpha (Optional[float]) — Se não for None, isso ativará as embeddings de ruído do NEFTune. Isso pode melhorar drasticamente o desempenho do modelo para o ajuste fino de instruções. Consulte o artigo original e o código original. Suporta PreTrainedModel do transformers e também PeftModel do peft. O artigo original utilizou valores na faixa [5.0, 15.0].
  • torch_empty_cache_steps (int, opcional) — Número de etapas a aguardar antes de chamar torch.<device>.empty_cache(). Se não for definido ou for definido como None, o cache não será esvaziado. Isso pode ajudar a evitar erros de memória insuficiente na CUDA, reduzindo o uso de pico de VRAM, com um custo de aproximadamente 10% de desempenho mais lento.
  • auto_find_batch_size (bool, opcional, padrão False) — Se deve encontrar automaticamente um tamanho de lote de treinamento que caiba na memória, por meio de decaimento exponencial, evitando erros de CUDA Out-of-Memory. O tamanho do lote de avaliação não é ajustado.

Registro e monitoramento do treinamento

  • logging_strategy (str ou IntervalStrategy, opcional, padrão é "steps") — Estratégia de log a ser adotada durante o treinamento. Os valores possíveis são:
    • "no": Nenhum registro é feito durante o treinamento.
    • "epoch": O registro é feito no final de cada epoch.
    • "steps": O registro é feito a cada logging_steps.
  • logging_steps (int ou float, opcional, padrão 500) — Número de etapas de atualização entre dois registros, se logging_strategy="steps". Deve ser um inteiro ou um número flutuante no intervalo [0,1). Se for menor que 1, será interpretado como a proporção das etapas totais de treinamento.
  • logging_first_step (bool, opcional, padrão False) — Se deve registrar o primeiro global_step ou não.
  • log_on_each_node (bool, opcional, padrão True) — No treinamento distribuído multinó, se o registro deve ser feito usando log_level uma vez por nó ou apenas no nó principal.
  • logging_nan_inf_filter (bool, opcional, padrão True) — Filtra perdas NaN e Inf ao registrar logs. Se True, substitui as perdas de treinamento NaN/Inf pela média das perdas válidas recentes e exclui os lotes com NaN/Inf (por exemplo, lotes sem tokens de rótulo) da perda de avaliação. Não afeta o cálculo do gradiente, apenas o registro de logs.
  • include_num_input_tokens_seen (Optional[Union[str, bool]], opcional, padrão “no”) — Se deve rastrear o número de tokens de entrada vistos. Deve ser um dos valores [“all”, “non_padding”, “no”] ou um valor booleano que mapeia para “all” ou “no”. Pode ser mais lento em treinamento distribuído, pois operações de gather devem ser chamadas.

Registro de logs

  • log_level (str, opcional, padrão passive) — Nível de log para o processo principal. Opções: "debug", "info", "warning", "error", "critical" ou "passive" (não altera o nível de log atual do Transformers, que é "warning" por padrão)
  • log_level_replica (str, opcional, padrão "warning") — Nível de log para processos de réplica em treinamento distribuído. Mesmas opções de log_level.
  • disable_tqdm (bool, opcional) — Desativa as barras de progresso do tqdm. O valor padrão é True se log_level for warning ou inferior, e False caso contrário.

Integração com Rastreamento de Experimentos

  • report_to (str ou list[str], opcional, padrão "none") — A lista de integrações para as quais os resultados e os logs devem ser reportados. As plataformas suportadas são "azure_ml", "clearml", "codecarbon", "comet_ml", "dagshub", "dvclive", "flyte", "mlflow", "swanlab", "tensorboard", "trackio" e "wandb". Use "all" para reportar a todas as integrações instaladas e "none" para não usar nenhuma integração.
  • run_name (str, opcional) — Um descritor para a execução. Tipicamente usado para log de trackio, wandb, mlflow, comet e swanlab.
  • project (str, opcional, padrão "huggingface") — O nome do projeto a ser usado para registro de logs. Atualmente, usado apenas pelo Trackio.
  • trackio_space_id (str ou None, opcional, padrão None) — O ID do Space do Hugging Face a ser usado para o registro ao vivo do Trackio com um Space baseado em Gradio. Deve ser um nome completo de Space, como 'username/reponame' ou 'orgname/reponame', ou apenas 'reponame' (o Space será criado no namespace do usuário atualmente conectado). Se for None, as métricas serão registradas apenas em um diretório local (sem Space no Hub). Aquele Space Gradio tem acesso de leitura e escrita ao Bucket do Trackio, o que é desejável enquanto o treinamento está em andamento—por exemplo, ao retomar uma execução parcial ou agregar logs de várias máquinas. O Space será público, a menos que você defina hub_private_repo=True ou o padrão da sua organização seja criar Spaces privados.
  • trackio_bucket_id (str ou None, opcional, padrão None) — ID opcional de Bucket do Hugging Face para o Trackio. Se não for definido, o Trackio deriva um. Usado em conjunto com um Space do Gradio (trackio_space_id) e ao implantar um Space estático (trackio_static_space_id não é False).
  • trackio_static_space_id (str, False ou None, opcional, padrão None) — O ID do Hugging Face Space a ser usado para o Space estático criado após a conclusão do treinamento. Deve ser um nome completo de Space, como 'username/reponame' ou 'orgname/reponame', ou apenas 'reponame' (o Space será criado no namespace do usuário atualmente conectado). Se False, nenhum Space estático será criado. Se None e o modelo for enviado para o Hub, um Space estático será criado com um nome padrão e será vinculado a partir do cartão do modelo. O Space será público, a menos que você defina hub_private_repo=True ou o padrão da sua organização seja criar Spaces privados.

Avaliação

  • eval_strategy (str ou IntervalStrategy, opcional, padrão é "no") — Quando executar a avaliação. Opções:
    • "no": Sem avaliação durante o treinamento
    • "steps": Avaliar a cada eval_steps
    • "epoch": Avaliar no final de cada epoch
  • eval_steps (int ou float, opcional) — Número de etapas de atualização entre duas avaliações, se eval_strategy="steps". Se não for definido, o valor padrão será o mesmo de logging_steps. Deve ser um inteiro ou um número flutuante no intervalo [0,1). Se for menor que 1, será interpretado como a proporção das etapas totais de treinamento.
  • eval_delay (float, opcional) — Número de épocas ou passos a aguardar antes que a primeira avaliação possa ser realizada, dependendo do eval_strategy.
  • per_device_eval_batch_size (int, opcional, padrão 8) — O tamanho do lote por núcleo de acelerador/CPU do dispositivo para avaliação.
  • prediction_loss_only (bool, opcional, padrão False) — Ao realizar a avaliação e gerar previsões, retorna apenas a perda.
  • eval_on_start (bool, opcional, padrão False) — Se deve executar uma etapa de avaliação (verificação de sanidade) antes do treinamento para garantir que as etapas de validação funcionem corretamente.
  • eval_do_concat_batches (bool, opcional, padrão True) — Se deve concatenar recursivamente entradas/perdas/rótulos/previsões entre lotes. Se False, serão armazenados como listas, mantendo cada lote separado.
  • eval_use_gather_object (bool, opcional, padrão False) — Se deve executar o gather recursivo de objetos em uma lista/tupla/dicionário aninhado de objetos a partir de todos os dispositivos. Isso deve ser habilitado apenas se os usuários não estiverem retornando apenas tensores, e isso é ativamente desencorajado pelo PyTorch. Isso é útil quando a estrutura dos rótulos é não padrão, como em tarefas de visão computacional.
  • eval_accumulation_steps (int, opcional) — Número de etapas de predição para acumular os tensores de saída antes de mover os resultados para a CPU. Se deixado sem definir, todas as predições são acumuladas no acelerador do dispositivo antes de serem movidas para a CPU (mais rápido, mas requer mais memória).

Cálculo de métricas

  • include_for_metrics (list[str], opcional, padrão é []) — Inclui dados adicionais na compute_metrics função, caso necessário para o cálculo de métricas. Opções possíveis para adicionar à include_for_metrics lista:
    • "inputs": Dados de entrada passados ao modelo, destinados ao cálculo de métricas dependentes da entrada.
    • "loss": Valores de perda calculados durante a avaliação, destinados ao cálculo de métricas dependentes de perda.
  • batch_eval_metrics (bool, opcional, padrão False) — Se definido como True, a avaliação chamará compute_metrics no final de cada lote para acumular estatísticas, em vez de salvar todos os logits de avaliação na memória. Quando definido como True, você deve passar uma função compute_metrics que aceite um argumento booleano compute_result, que, quando receber True, acionará as estatísticas globais finais a partir das estatísticas resumidas por lote que você acumulou ao longo do conjunto de avaliação.

Checkpointing e salvamento

  • save_only_model (bool, opcional, padrão False) — Salva apenas os pesos do modelo, sem o estado do otimizador/agendador/RNG. Isso reduz significativamente o tamanho do checkpoint, mas impede a retomada do treinamento a partir dele. Use quando você precisar apenas do modelo treinado para inferência, e não para continuar o treinamento. Com essa opção definida como True, você só pode carregar o modelo usando from_pretrained.
  • save_strategy (str ou SaveStrategy, opcional, padrão é "steps") — Estratégia de salvamento de checkpoints a ser adotada durante o treinamento. Os valores possíveis são:
    • "no": Nenhum salvamento é realizado durante o treinamento.
    • "epoch": O salvamento é realizado ao final de cada epoch.
    • "steps": O salvamento é realizado a cada save_steps.
    • "best": O salvamento é realizado sempre que uma nova best_metric é alcançada.
  • save_steps (int ou float, opcional, padrão 500) — Número de etapas de atualização entre duas gravações de checkpoint, se save_strategy="steps". Deve ser um inteiro ou um float no intervalo [0,1). Se for menor que 1, será interpretado como a proporção das etapas totais de treinamento.
  • save_on_each_node (bool, opcional, padrão False) — Ao realizar treinamento distribuído em vários nós, se os modelos e checkpoints devem ser salvos em cada nó ou apenas no principal. Isso não deve ser ativado quando os diferentes nós usam o mesmo armazenamento, pois os arquivos serão salvos com os mesmos nomes em cada nó.
  • save_total_limit (int, opcional) — Número máximo de checkpoints a serem mantidos. Exclui checkpoints mais antigos em output_dir. Quando load_best_model_at_end=True, o melhor checkpoint é sempre mantido, além dos mais recentes. Por exemplo, save_total_limit=5 mantém os 4 mais recentes, além do melhor
  • enable_jit_checkpoint (bool, opcional, padrão False) — Ativa o checkpointing Just-In-Time no sinal SIGTERM para encerramento gracioso em cargas de trabalho preemptíveis. Importante: Configure o período de encerramento gracioso do seu orquestrador para permitir tempo suficiente. Para Kubernetes, defina terminationGracePeriodSeconds (o padrão de 30s geralmente é insuficiente). Para Slurm, use --signal=TERM@<seconds>. O período de graça necessário ≥ tempo da iteração mais longa + tempo de salvamento do checkpoint.

Integração com o Hugging Face Hub

  • push_to_hub (bool, opcional, padrão False) — Indica se o modelo deve ser enviado ao Hub sempre que for salvo. Se ativado, output_dir iniciará um diretório git sincronizado com o repositório (determinado por hub_model_id) e o conteúdo será enviado sempre que um salvamento for acionado (dependendo do seu save_strategy). A chamada de save_model() também acionará um envio.
  • hub_token (str, opcional) — O token a ser usado para enviar o modelo para o Hub. Por padrão, será utilizado o token na pasta de cache obtido com hf auth login.
  • hub_private_repo (bool, opcional) — Se a repositório deve ser privado. Se None (padrão), o repositório será público, a menos que o padrão da organização seja privado. Este valor é ignorado se o repositório já existir. Se o relatório for enviado ao Trackio com o deploy para Hugging Face Spaces habilitado, a mesma lógica determina se o Space é privado.
  • hub_model_id (str, opcional) — O nome do repositório que deve ser mantido em sincronia com o output_dir local. Pode ser um ID de modelo simples, caso em que o modelo será enviado no seu namespace. Caso contrário, deve ser o nome completo do repositório, por exemplo "user_name/model", o que permite enviar para uma organização da qual você é membro com "organization_name/model". O valor padrão será user_name/output_dir_name, sendo output_dir_name o nome de output_dir.
  • hub_strategy (str ou HubStrategy, opcional, padrão é "every_save") — Define o que e quando enviar para o Hub. Opções:
    • "end": Empurrar apenas no final do treinamento
    • "every_save": Fazer push a cada salvamento (assíncrono para não bloquear o treinamento)
    • "checkpoint": Assim como "every_save", além de enviar o checkpoint mais recente para a subpasta "last-checkpoint" para facilitar a retomada
    • "all_checkpoints": Envie todos os checkpoints conforme eles aparecem
  • hub_always_push (bool, opcional, padrão False) — A menos que seja True, o Trainer ignorará o envio de um checkpoint quando o envio anterior não tiver sido concluído.
  • hub_revision (str, opcional) — A revisão a ser usada ao fazer push para o Hub. Pode ser o nome de uma branch, uma tag ou um hash de commit.

Melhor rastreamento de modelos

  • load_best_model_at_end (bool, opcional, padrão False) — Carrega o melhor checkpoint ao final do treinamento. Exige que eval_strategy esteja definido. Quando habilitado, o melhor checkpoint é sempre salvo (veja save_total_limit). Quando `True`, `save_strategy` deve corresponder a `eval_strategy` (a menos que `save_strategy` seja `"best"`), e, se usar `"steps"`, `save_steps` deve ser um múltiplo de `eval_steps`.
  • metric_for_best_model (str, opcional) — Métrica a ser usada para comparar modelos quando load_best_model_at_end=True. Deve ser um nome de métrica retornado pela avaliação, com ou sem o prefixo "eval_". O padrão é "loss". Se você definir isso, greater_is_better terá como padrão True, a menos que o nome termine com "loss". Exemplos: "accuracy", "f1", "eval_bleu".
  • greater_is_better (bool, opcional) — Indica se valores maiores da métrica são melhores. O valor padrão é baseado em metric_for_best_model: True se o nome da métrica não terminar em "loss", False caso contrário.

Retomando o Treinamento

  • ignore_data_skip (bool, opcional, padrão False) — Ao retomar o treinamento, ignora a adiantamento rápido pelo conjunto de dados para alcançar o estado anterior. Se True, o treinamento começa do início do conjunto de dados (retomada mais rápida, mas os resultados não corresponderão ao treinamento interrompido). Se False, pula os dados já vistos (retomada mais lenta, mas continuação exata).
  • restore_callback_states_from_checkpoint (bool, opcional, padrão False) — Restaura os estados dos callbacks a partir do checkpoint ao retomar. Se True, sobrescreverá os callbacks passados para o Trainer, caso existam no checkpoint.

Reprodutibilidade

  • full_determinism (bool, opcional, padrão False) — Se True, enable_full_determinism() é chamado em vez de set_seed() para garantir resultados reproduzíveis no treinamento distribuído. Importante: isso impactará negativamente o desempenho, portanto, use apenas para depuração.
  • seed (int, opcional, padrão 42) — Semente aleatória que será definida no início do treinamento. Para garantir a reprodutibilidade entre execuções, use a função ~Trainer.model_init para instanciar o modelo, caso ele possua parâmetros inicializados aleatoriamente.
  • data_seed (int, opcional) — Semente aleatória a ser usada com amostradores de dados. Se não for definida, os geradores aleatórios para amostragem de dados usarão a mesma semente que seed. Isso pode ser usado para garantir a reprodutibilidade da amostragem de dados, independentemente da semente do modelo.

Configuração de Hardware

  • use_cpu (bool, opcional, padrão False) — Indica se deve ou não usar a CPU. Se definido como False, usaremos o dispositivo/backend do torch disponível.

Configuração do Accelerate

  • accelerator_config (str, dict, ou AcceleratorConfig, opcional) — Configuração para a integração interna do Accelerate. Pode ser: Caminho para um arquivo de configuração JSON: "accelerator_config.json" Dicionário com opções de configuração Instância de AcceleratorConfig Opções principais: split_batches (bool, padrão False): Se deve dividir os lotes entre os dispositivos. Se True, o tamanho real do lote é o mesmo em todos os dispositivos (o total deve ser divisível por num_processes). Se False, cada dispositivo recebe o tamanho de lote especificado. dispatch_batches (bool): Se True, apenas o processo principal itera pelo dataloader e distribui os lotes para os dispositivos. Padrão True para IterableDataset, False caso contrário. even_batches (bool, padrão True): Duplica amostras do início do dataset para garantir que todos os workers recebam tamanhos de lote iguais. use_seedable_sampler (bool, padrão True): Usa um amostrador aleatório totalmente semeadável para reprodutibilidade. use_configured_state (bool, padrão False): Usa um AcceleratorState/PartialState pré-inicializado em vez de criar um novo. Pode causar problemas com o ajuste de hiperparâmetros.
    • Caminho para o arquivo de configuração JSON: "accelerator_config.json"
    • Dicionário com opções de configuração
    • instância de AcceleratorConfig Opções principais:
    • split_batches (bool, padrão False): Se deve dividir os lotes entre os dispositivos. Se True, o tamanho real do lote é o mesmo em todos os dispositivos (o total deve ser divisível por num_processes). Se False, cada dispositivo recebe o tamanho de lote especificado.
    • dispatch_batches (bool): Se True, apenas o processo principal itera pelo dataloader e distribui os lotes para os dispositivos. O valor padrão é True para IterableDataset e False caso contrário.
    • even_batches (bool, padrão True): Duplica amostras do início do conjunto de dados para garantir que todos os workers recebam tamanhos de lote iguais.
    • use_seedable_sampler (bool, padrão True): Use um amostrador aleatório totalmente semeadável para reprodutibilidade.
    • use_configured_state (bool, padrão False): Utiliza um AcceleratorState/PartialState pré-inicializado em vez de criar um novo. Pode causar problemas com o ajuste de hiperparâmetros.
  • parallelism_config (ParallelismConfig, opcional) — Configuração de paralelismo para a execução de treinamento. Requer Accelerate 1.10.1

Dataloader

  • dataloader_drop_last (bool, opcional, padrão False) — Se deve descartar o último lote incompleto (caso o comprimento do conjunto de dados não seja divisível pelo tamanho do lote) ou não.
  • dataloader_num_workers (int, opcional, padrão 0) — Número de subprocessos a serem usados para o carregamento de dados (somente PyTorch). 0 significa que os dados serão carregados no processo principal.
  • dataloader_pin_memory (bool, opcional, padrão True) — Se você deseja fixar a memória nos carregadores de dados ou não. O padrão será True.
  • dataloader_persistent_workers (bool, opcional, padrão False) — Se True, o data loader não encerrará os processos de worker após um dataset ter sido consumido uma vez. Isso permite manter as instâncias de Dataset dos workers ativas. Pode potencialmente acelerar o treinamento, mas aumentará o uso de RAM. O padrão será False.
  • dataloader_prefetch_factor (int, opcional) — Número de lotes carregados antecipadamente por cada worker. 2 significa que haverá um total de 2 * num_workers lotes pré-carregados em todos os workers.
  • dataloader_multiprocessing_context (str, opcional) — O método de inicialização de multiprocessamento a ser usado para os workers de carregamento de dados ("fork", "spawn" ou "forkserver"). O padrão é o método de inicialização padrão do PyTorch, exceto no MPS com dataloader_num_workers > 1, onde o padrão é "fork". Use "spawn" ao fazer streaming de fontes cujos objetos não são seguros para fork (por exemplo, HDFS via pyarrow). Sob "spawn", qualquer collate_fn personalizado ou código de dataset deve ser importável no nível do módulo (sem lambdas/closures).
  • dataloader_in_order (bool, opcional, padrão True) — Se True, o data loader fornece lotes na ordem em que os workers foram despachados. Defina como False para fornecer lotes assim que estiverem prontos, o que pode reduzir a latência de cauda para cargas de trabalho de streaming de IterableDataset. Requer PyTorch >= 2.6.
  • remove_unused_columns (bool, opcional, padrão True) — Se as colunas não utilizadas pelo método forward do modelo devem ser removidas automaticamente.
  • label_names (list[str], opcional) — A lista de chaves no seu dicionário de entradas que correspondem aos rótulos. Eventualmente, o padrão será a lista de nomes de argumentos aceitos pelo modelo que contenham a palavra “label”, exceto se o modelo utilizado for um dos XxxForQuestionAnswering, caso em que também incluirá as chaves ["start_positions", "end_positions"]. Você deve especificar label_names apenas se estiver usando nomes de rótulos personalizados ou se o forward do seu modelo consumir múltiplos tensores de rótulos (por exemplo, QA extrativo).
  • train_sampling_strategy (str, opcional, padrão é "random") — O sampler a ser usado para o dataloader de treinamento. Os valores possíveis são:
    • "random": Usa RandomSampler (padrão).
    • "sequential": Usa SequentialSampler.
    • "group_by_length": usa LengthGroupedSampler para agrupar amostras de comprimento aproximadamente igual (junto, para minimizar o padding e ser mais eficiente).
    • "batch_rebalance": Usa BatchRebalanceSampler para equilibrar o custo de tokens de padding entre os dispositivos e as etapas de acúmulo de gradiente dentro de cada lote efetivo, reduzindo o desperdício de padding e a memória de pico em comparação com "group_by_length". Atualmente, é suportado apenas para treinamento paralelo de dados (o paralelismo de tensor ainda não é suportado).

    Observação: ao usar um IterableDataset, este argumento é ignorado.

  • length_column_name (str, opcional, padrão "length") — Nome da coluna para comprimentos pré-calculados. Se a coluna existir, o agrupamento por comprimento usará esses valores em vez de calculá-los na inicialização do treinamento. Ignorado, a menos que train_sampling_strategy seja "group_by_length" ou "batch_rebalance" e o conjunto de dados seja uma instância de Dataset.

DDP (DistributedDataParallel)

  • ddp_find_unused_parameters (bool, opcional) — Ao usar treinamento distribuído, o valor da flag find_unused_parameters passada para DistributedDataParallel. O valor padrão será False se gradient checkpointing for usado, True caso contrário.
  • ddp_bucket_cap_mb (int, opcional) — Ao usar treinamento distribuído, o valor da flag bucket_cap_mb passada para DistributedDataParallel.
  • ddp_broadcast_buffers (bool, opcional) — Ao usar treinamento distribuído, o valor da flag broadcast_buffers passada para DistributedDataParallel. Será False por padrão se o gradient checkpointing for usado, True caso contrário.
  • ddp_static_graph (bool, opcional) — Ao usar treinamento distribuído, o valor da flag static_graph passada para DistributedDataParallel.
  • ddp_backend (str, opcional) — O backend a ser usado para treinamento distribuído. Deve ser um dos seguintes: "nccl", "mpi", "xccl", "gloo", "hccl".
  • ddp_timeout (int, opcional, padrão 1800) — O tempo limite para as chamadas de torch.distributed.init_process_group, usado para evitar timeouts de socket da GPU ao executar operações lentas em execuções distribuídas. Consulte a documentação do PyTorch para mais informações.

FSDP (Fully Sharded Data Parallel)

  • fsdp (bool, opcional, padrão None) — Ativa o PyTorch Fully Sharded Data Parallel (FSDP) para treinamento distribuído. Passe True para habilitar o FSDP.
  • fsdp_config (str or dict, optional) — Configuration settings for when fsdp is enabled. Pass a path to a JSON config file, such as fsdp_config.json, or an already-loaded dict.

    Chaves suportadas:

    • version (int, opcional, padrão 2): A versão do FSDP a ser usada (2 para FSDP2, 1 para o FSDP1 legado).
    • reshard_after_forward (bool, opcional, padrão True): Se deve redividir os parâmetros após a passagem de propagação direta. Defina como False para manter os parâmetros agregados entre as passagens de propagação direta e reversa, evitando o re-all-gather e utilizando mais memória de pico.
    • cpu_offload (bool, opcional, padrão False): Desloca parâmetros e gradientes para a CPU quando não estão em uso, para economizar memória de GPU.
    • activation_checkpointing (bool, opcional, padrão False): Defina como True para reduzir a memória recalculando as ativações durante a passagem reversa. Ao usar FSDP, prefira isso ao argumento de treinamento activation_checkpointing, que introduz um all-gather redundante na passagem reversa.
    • cpu_ram_efficient_loading (bool, opcional, padrão False): Defina como True para carregar o checkpoint pré-treinado apenas no primeiro processo. Os outros processos iniciam com pesos vazios e recebem os pesos por broadcast.
    • state_dict_type (str, opcional, padrão "FULL_STATE_DICT"): Formato do checkpoint: "FULL_STATE_DICT" (arquivo único compatível com HF) ou "SHARDED_STATE_DICT" (um arquivo por rank, mais rápido para modelos grandes).
    • auto_wrap_policy (str, opcional, padrão "TRANSFORMER_BASED_WRAP"): Política de auto-wrap a ser utilizada. Escolha "TRANSFORMER_BASED_WRAP", "SIZE_BASED_WRAP" ou "NO_WRAP".
    • transformer_layer_cls_to_wrap (list[str], opcional): Nomes das classes de camadas de Transformer (sensíveis a maiúsculas e minúsculas) a serem envolvidas, por exemplo, LlamaDecoderLayer. Geralmente não é necessário: a política de envolvimento usa como fallback o _no_split_modules do modelo, que cobre a maioria dos modelos de transformers.
    • min_num_params (int, opcional, padrão 0): Número mínimo de parâmetros por módulo para o auto-wrapping baseado em tamanho (usado com auto_wrap_policy="SIZE_BASED_WRAP").
    • xla (bool, opcional, padrão False): Se deve usar o treinamento PyTorch/XLA Fully Sharded Data Parallel. Experimental.
    • xla_fsdp_settings (dict, opcional): Dicionário de parâmetros de encapsulamento do XLA FSDP. Para a lista completa de opções, consulte o código-fonte do XLA FSDP.
    • xla_fsdp_grad_ckpt (bool, opcional, padrão False): Defina como True para usar gradient checkpointing em cada camada aninhada envolvida por XLA FSDP. Exige xla=True e uma política de auto-wrapping (min_num_params ou transformer_layer_cls_to_wrap).

DeepSpeed

  • deepspeed (str ou dict, opcional) — Ativa a integração com o O valor pode ser:
    • Caminho para o arquivo de configuração JSON do DeepSpeed: "ds_config.json"
    • Config carregada como dicionário

      Se estiver usando a inicialização ZeRO, instancie seu modelo após a inicialização de TrainingArguments; caso contrário, o ZeRO não será aplicado.

Depuração e Análise de Desempenho (Experimental)

  • debug (str ou lista de DebugOption, opcional, padrão é "") — Ativa um ou mais recursos de depuração. Este é um recurso experimental. As opções possíveis são:
    • “underflow_overflow”: detecta estouro nos entradas/saídas do modelo e relata os últimos quadros que levaram ao evento
    • “tpu_metrics_debug”: exibe métricas de depuração em TPU
  • skip_memory_metrics (bool, opcional, padrão True) — Se deve ignorar a adição de relatórios do perfilador de memória às métricas. Isso é ignorado por padrão, pois reduz a velocidade de treinamento e avaliação.

Flags de script externo (não usadas pelo Trainer)

  • do_train (bool, opcional, padrão False) — Indica se o treinamento deve ser executado ou não. Este argumento não é usado diretamente pelo Trainer; ele destina-se a ser utilizado pelos seus scripts de treinamento/avaliação.
  • do_eval (bool, opcional) — Indica se a avaliação deve ser executada no conjunto de validação. Será definido como True se eval_strategy for diferente de "no". Este argumento não é usado diretamente pelo Trainer; ele destina-se a ser utilizado pelos seus scripts de treinamento/avaliação.
  • do_predict (bool, opcional, padrão False) — Indica se as previsões devem ser executadas no conjunto de teste ou não. Este argumento não é usado diretamente pelo Trainer; ele destina-se a ser utilizado pelos seus scripts de treinamento/avaliação.
  • resume_from_checkpoint (str, opcional) — O caminho para uma pasta com um checkpoint válido para o seu modelo. Este argumento não é usado diretamente pelo Trainer; ele é destinado a ser usado pelos seus scripts de treinamento/avaliação.

Classe de configuração para controlar todos os aspectos do treinamento do modelo com o Trainer. TrainingArguments centraliza todos os hiperparâmetros, configurações de otimização, preferências de registro e escolhas de infraestrutura necessárias para o treinamento.

HfArgumentParser pode converter esta classe em argumentos de argparse que podem ser especificados na linha de comando.

get_process_log_level

< >

( )

Retorna o nível de log a ser usado, dependendo se este processo é o processo principal do nó 0, o processo principal de um nó diferente de 0 ou um processo não principal.

Para o processo principal, o nível de log padrão é o nível de log definido (logging.WARNING se você não fez nada), a menos que seja sobrescrito pelo argumento log_level.

Para os processos de réplica, o nível de log padrão é logging.WARNING, a menos que seja sobrescrito pelo argumento log_level_replica.

A escolha entre as configurações do processo principal e do processo de réplica é feita de acordo com o valor de retorno de should_log.

get_warmup_steps

< >

( num_training_steps: int )

Obtém o número de etapas usadas para um aquecimento linear.

main_process_first

< >

( local = Truedesc = 'work' )

Parâmetros

  • local (bool, opcional, padrão True) — se True, "first" significa o processo de rank 0 de cada nó; se False, "first" significa o processo de rank 0 do nó rank 0. Em um ambiente multi-nó com sistema de arquivos compartilhado, provavelmente você quererá usar local=False para que apenas o processo principal do primeiro nó execute o processamento. No entanto, se o sistema de arquivos não for compartilhado, o processo principal de cada nó precisará executar o processamento, o que é o comportamento padrão.
  • desc (str, opcional, padrão "work") — uma descrição do trabalho a ser usada em logs de depuração

Um gerenciador de contexto para o ambiente distribuído do torch, no qual é necessário executar algo no processo principal, enquanto os réplicas ficam bloqueados, e, ao final, os réplicas são liberados.

Um desses usos é para o recurso map dos datasets, que, para ser eficiente, deve ser executado uma única vez no processo principal, o qual, ao concluir, salva uma versão em cache dos resultados e que, em seguida, é carregada automaticamente pelas réplicas.

set_dataloader

< >

( train_batch_size: int = 8eval_batch_size: int = 8drop_last: bool = Falsenum_workers: int = 0pin_memory: bool = Truepersistent_workers: bool = Falseprefetch_factor: int | None = Nonemultiprocessing_context: str | None = Nonein_order: bool = Trueauto_find_batch_size: bool = Falseignore_data_skip: bool = Falsesampler_seed: int | None = None )

Parâmetros

  • drop_last (bool, opcional, padrão False) — Se deve descartar o último lote incompleto (caso o comprimento do conjunto de dados não seja divisível pelo tamanho do lote) ou não.
  • num_workers (int, opcional, padrão 0) — Número de subprocessos a serem usados para o carregamento de dados (somente PyTorch). 0 significa que os dados serão carregados no processo principal.
  • pin_memory (bool, opcional, padrão True) — Se você deseja fixar a memória nos carregadores de dados ou não. O padrão será True.
  • persistent_workers (bool, opcional, padrão False) — Se True, o data loader não encerrará os processos de worker após o dataset ter sido consumido uma vez. Isso permite manter as instâncias de Dataset dos workers ativas. Pode potencialmente acelerar o treinamento, mas aumentará o uso de RAM. O padrão será False.
  • prefetch_factor (int, opcional) — Número de lotes carregados antecipadamente por cada worker. 2 significa que haverá um total de 2 * num_workers lotes pré-carregados em todos os workers.
  • multiprocessing_context (str, opcional) — O método de inicialização de multiprocessamento a ser usado para os workers de carregamento de dados ("fork", "spawn" ou "forkserver"). O padrão é o método de inicialização padrão do PyTorch. Use "spawn" ao fazer streaming de fontes cujos objetos não são seguros para fork (por exemplo, HDFS via pyarrow). Sob "spawn", qualquer collate_fn ou código de dataset personalizado deve ser importável no nível do módulo (sem lambdas/closures).
  • in_order (bool, opcional, padrão True) — Se True, o data loader fornece lotes na ordem em que os workers foram despachados. Defina como False para fornecer os lotes assim que estiverem prontos, o que pode reduzir a latência de cauda para cargas de trabalho de streaming de IterableDataset. Requer PyTorch >= 2.6.
  • auto_find_batch_size (bool, opcional, padrão False) — Se deve encontrar automaticamente um tamanho de lote que caiba na memória, por meio de decaimento exponencial, evitando erros de CUDA Out-of-Memory. Requer que o accelerate esteja instalado (pip install accelerate)
  • ignore_data_skip (bool, opcional, padrão False) — Ao retomar o treinamento, define se os epochs e batches devem ser ignorados para que o carregamento de dados esteja na mesma etapa do treinamento anterior. Se definido como True, o treinamento começará mais rápido (pois a etapa de ignorar pode levar muito tempo), mas não produzirá os mesmos resultados que o treinamento interrompido teria gerado.
  • sampler_seed (int, opcional) — Semente aleatória a ser usada com amostradores de dados. Se não for definida, os geradores aleatórios para amostragem de dados usarão a mesma semente de self.seed. Isso pode ser usado para garantir a reprodutibilidade da amostragem de dados, independentemente da semente do modelo.

Um método que agrupa todos os argumentos relacionados à criação dos dataloaders.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_dataloader(train_batch_size=16, eval_batch_size=64)
>>> args.per_device_train_batch_size
16

set_evaluate

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'no'steps: int = 500batch_size: int = 8accumulation_steps: int | None = Nonedelay: float | None = Noneloss_only: bool = False )

Parâmetros

  • strategy (str ou IntervalStrategy, opcional, padrão é "no") — Estratégia de avaliação a ser adotada durante o treinamento. Os valores possíveis são:
    • "no": Nenhuma avaliação é realizada durante o treinamento.
    • "steps": A avaliação é realizada (e registrada) a cada steps.
    • "epoch": A avaliação é realizada no final de cada epoch.

    Definir um strategy diferente de "no" definirá self.do_eval como True.

  • steps (int, opcional, padrão 500) — Número de etapas de atualização entre duas avaliações quando strategy="steps".
  • batch_size (int opcional, padrão 8) — O tamanho do lote por dispositivo (núcleo de GPU/TPU/CPU…) usado para avaliação.
  • accumulation_steps (int, opcional) — Número de etapas de predição para acumular os tensores de saída antes de mover os resultados para a CPU. Se não for definido, todas as predições são acumuladas na GPU/TPU antes de serem movidas para a CPU (mais rápido, mas requer mais memória).
  • delay (float, opcional) — Número de épocas ou passos a aguardar antes que a primeira avaliação possa ser realizada, dependendo do eval_strategy.
  • loss_only (bool, opcional, padrão False) — Ignora todas as saídas, exceto a perda.

Um método que agrupa todos os argumentos relacionados à avaliação.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_evaluate(strategy="steps", steps=100)
>>> args.eval_steps
100

set_logging

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'steps'steps: int = 500report_to: str | list[str] = 'none'level: str = 'passive'first_step: bool = Falsenan_inf_filter: bool = Falseon_each_node: bool = Falsereplica_level: str = 'passive' )

Parâmetros

  • strategy (str ou IntervalStrategy, opcional, padrão é "steps") — A estratégia de log a ser adotada durante o treinamento. Os valores possíveis são:
    • "no": Nenhum registro é feito durante o treinamento.
    • "epoch": O registro é feito no final de cada epoch.
    • "steps": O registro é feito a cada logging_steps.
  • steps (int, opcional, padrão 500) — Número de etapas de atualização entre dois registros, se strategy="steps".
  • level (str, opcional, padrão "passive") — Nível de log do logger a ser usado no processo principal. As opções possíveis são os níveis de log como strings: "debug", "info", "warning", "error" e "critical", além do nível "passive", que não define nada e permite que a aplicação defina o nível.
  • report_to (str ou list[str], opcional, padrão "none") — A lista de integrações para as quais os resultados e os logs devem ser reportados. As plataformas suportadas são "azure_ml", "clearml", "codecarbon", "comet_ml", "dagshub", "dvclive", "flyte", "mlflow", "swanlab", "tensorboard", "trackio" e "wandb". Use "all" para reportar a todas as integrações instaladas e "none" para não usar nenhuma integração.
  • first_step (bool, opcional, padrão False) — Indica se o primeiro global_step deve ser registrado e avaliado.
  • nan_inf_filter (bool, opcional, padrão é True) — Se deve filtrar nan e inf perdas para registro. Se definido como True a perda de cada passo que for nan ou inf é filtrada e a perda média da janela de registro atual é usada no lugar. O parâmetro nan_inf_filter influencia apenas o registro dos valores de perda; ele não altera o comportamento do cálculo do gradiente nem sua aplicação ao modelo.

    nan_inf_filter influencia apenas o registro dos valores de perda; ele não altera a forma como o gradiente é calculado ou aplicado ao modelo.

  • on_each_node (bool, opcional, padrão True) — No treinamento distribuído multinó, se o registro deve ser feito usando log_level uma vez por nó ou apenas no nó principal.
  • replica_level (str, opcional, padrão "passive") — Nível de log do logger a ser usado nas réplicas. Mesmas opções de log_level

Um método que agrupa todos os argumentos relacionados ao registro de logs.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_logging(strategy="steps", steps=100)
>>> args.logging_steps
100

set_lr_scheduler

< >

( name: str | transformers.trainer_utils.SchedulerType = 'linear'num_epochs: float = 3.0max_steps: int = -1warmup_steps: float = 0 )

Parâmetros

  • name (str ou SchedulerType, opcional, padrão "linear") — O tipo de scheduler a ser utilizado. Consulte a documentação de SchedulerType para todos os valores possíveis.
  • num_epochs(float, opcional, padrão 3.0) — Número total de épocas de treinamento a serem executadas (se não for um número inteiro, executará a parte decimal em porcentagem da última época antes de interromper o treinamento).
  • max_steps (int, opcional, padrão -1) — Se definido como um número positivo, representa o número total de etapas de treinamento a serem executadas. Sobrepõe num_train_epochs. Para um conjunto de dados finito, o treinamento é reiterado através do conjunto de dados (se todos os dados forem esgotados) até que max_steps seja atingido. Deve ser definido como um valor positivo quando o conjunto de dados de treinamento não implementa __len__ (por exemplo, um conjunto de dados em streaming), pois o número total de etapas não pode ser inferido e é necessário para limitar o loop de treinamento e configurar o agendador de taxa de aprendizado.
  • warmup_steps (float, opcional, padrão 0) — Número de etapas usadas para um aquecimento linear de 0 até learning_rate. Deve ser um inteiro ou um float no intervalo [0,1). Se for menor que 1, será interpretado como a proporção de etapas usadas para um aquecimento linear de 0 até learning_rate.

Um método que agrupa todos os argumentos relacionados ao agendador de taxa de aprendizado e seus hiperparâmetros.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_lr_scheduler(name="cosine", warmup_steps=0.05)
>>> args.warmup_steps
0.05

set_optimizer

< >

( name: str | transformers.training_args.OptimizerNames = 'adamw_torch'learning_rate: float = 5e-05weight_decay: float = 0beta1: float = 0.9beta2: float = 0.999epsilon: float = 1e-08args: str | None = None )

Parâmetros

  • name (str ou training_args.OptimizerNames, opcional, padrão "adamw_torch") — O otimizador a ser usado: "adamw_torch", "adamw_torch_fused", "adamw_anyprecision" ou "adafactor".
  • learning_rate (float, opcional, padrão 5e-5) — A taxa de aprendizado inicial.
  • weight_decay (float, opcional, padrão 0) — O decaimento de peso a ser aplicado (se não for zero) a todas as camadas, exceto aos pesos de todos os vieses e LayerNorm.
  • beta1 (float, opcional, padrão 0.9) — O hiperparâmetro beta1 para o otimizador adam ou suas variantes.
  • beta2 (float, opcional, padrão 0.999) — O hiperparâmetro beta2 para o otimizador adam ou suas variantes.
  • epsilon (float, opcional, padrão 1e-8) — O hiperparâmetro epsilon para o otimizador adam ou suas variantes.
  • args (str, opcional) — Argumentos opcionais fornecidos ao AnyPrecisionAdamW (útil apenas quando optim="adamw_anyprecision").

Um método que agrupa todos os argumentos relacionados ao otimizador e aos seus hiperparâmetros.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_optimizer(name="adamw_torch", beta1=0.8)
>>> args.optim
'adamw_torch'

set_push_to_hub

< >

( model_id: strstrategy: str | transformers.trainer_utils.HubStrategy = 'every_save'token: str | None = Noneprivate_repo: bool | None = Nonealways_push: bool = Falserevision: str | None = None )

Parâmetros

  • model_id (str) — O nome do repositório que deve ser mantido em sincronia com o output_dir local. Pode ser um ID de modelo simples, caso em que o modelo será enviado no seu namespace. Caso contrário, deve ser o nome completo do repositório, por exemplo "user_name/model", o que permite enviar para uma organização da qual você é membro com "organization_name/model".
  • strategy (str ou HubStrategy, opcional, padrão é "every_save") — Define o escopo do que é enviado para o Hub e quando. Os valores possíveis são:
    • "end": envia o modelo, sua configuração, a processing_class, por exemplo, o tokenizer (se for passada para o Trainer) e um rascunho de uma model card quando o método save_model() é chamado.
    • "every_save": faz o push do modelo, da sua configuração, da processing_class (por exemplo, o tokenizer, se for passada para o Trainer) e de um rascunho de uma model card sempre que houver um save do modelo. Os pushes são assíncronos para não bloquear o treinamento, e, caso os saves sejam muito frequentes, um novo push só é tentado se o anterior tiver terminado. Um push final é feito com o modelo final ao término do treinamento.
    • "checkpoint": como "every_save", mas o checkpoint mais recente também é enviado para uma subpasta chamada last-checkpoint, permitindo que você retome o treinamento facilmente com trainer.train(resume_from_checkpoint="last-checkpoint").
    • "all_checkpoints": como "checkpoint", mas todos os checkpoints são enviados conforme aparecem na pasta de saída (ou seja, você terá uma pasta de checkpoint para cada pasta no seu repositório final)
  • token (str, opcional) — O token a ser usado para enviar o modelo ao Hub. Por padrão, será utilizado o token da pasta de cache obtido com hf auth login.
  • private_repo (bool, opcional, padrão False) — Se o repositório deve ser privado. Se None (padrão), o repositório será público, a menos que o padrão da organização seja privado. Este valor é ignorado se o repositório já existir.
  • always_push (bool, opcional, padrão False) — A menos que este valor seja True, o Trainer ignorará o envio de um checkpoint se o envio anterior não tiver sido concluído.
  • revision (str, opcional) — A revisão a ser usada ao fazer push no Hub. Pode ser o nome de uma branch, uma tag ou um hash de commit.

Um método que agrupa todos os argumentos relacionados à sincronização de checkpoints com o Hub.

Chamar este método definirá self.push_to_hub como True, o que significa que o output_dir iniciará um diretório git sincronizado com o repositório (determinado por model_id) e o conteúdo será enviado cada vez que um salvamento for acionado (dependendo do seu self.save_strategy). Chamar save_model() também acionará um envio.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_push_to_hub("me/awesome-model")
>>> args.hub_model_id
'me/awesome-model'

set_save

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'steps'steps: int = 500total_limit: int | None = Noneon_each_node: bool = False )

Parâmetros

  • strategy (str ou IntervalStrategy, opcional, padrão é "steps") — Estratégia de salvamento de checkpoints a ser adotada durante o treinamento. Os valores possíveis são:
    • "no": Nenhum salvamento é realizado durante o treinamento.
    • "epoch": O salvamento é realizado ao final de cada epoch.
    • "steps": O salvamento é realizado a cada save_steps.
  • steps (int, opcional, padrão 500) — Número de etapas de atualização entre duas gravações de checkpoint, se strategy="steps".
  • total_limit (int, opcional) — Se um valor for passado, limitará a quantidade total de checkpoints. Exclui os checkpoints mais antigos em output_dir.
  • on_each_node (bool, opcional, padrão é False) — Ao realizar treinamento distribuído em vários nós, se os modelos e checkpoints devem ser salvos em cada nó ou apenas no principal.

    Isso não deve ser ativado quando os diferentes nós usam o mesmo armazenamento, pois os arquivos serão salvos com os mesmos nomes em cada nó.

Um método que agrupa todos os argumentos relacionados ao salvamento de checkpoints.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_save(strategy="steps", steps=100)
>>> args.save_steps
100

set_testing

< >

( batch_size: int = 8loss_only: bool = False )

Parâmetros

  • batch_size (int opcional, padrão 8) — O tamanho do lote por dispositivo (núcleo de GPU/TPU/CPU…) usado para testes.
  • loss_only (bool, opcional, padrão False) — Ignora todas as saídas, exceto a perda.

Um método que agrupa todos os argumentos básicos relacionados ao teste em um conjunto de dados retido.

A chamada deste método definirá automaticamente self.do_predict como True.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_testing(batch_size=32)
>>> args.per_device_eval_batch_size
32

set_training

< >

( learning_rate: float = 5e-05batch_size: int = 8weight_decay: float = 0num_epochs: float = 3max_steps: int = -1gradient_accumulation_steps: int = 1seed: int = 42activation_checkpointing: bool = Falsegradient_checkpointing: bool | None = None )

Parâmetros

  • learning_rate (float, opcional, padrão 5e-5) — A taxa de aprendizado inicial para o otimizador.
  • batch_size (int opcional, padrão 8) — O tamanho do lote por dispositivo (núcleo de GPU/TPU/CPU…) usado para o treinamento.
  • weight_decay (float, opcional, padrão 0) — O decaimento de peso a ser aplicado (se não for zero) a todas as camadas, exceto os pesos de bias e LayerNorm, no otimizador.
  • num_epochs (float, opcional, padrão 3.0) — Número total de épocas de treinamento a serem executadas (se não for um número inteiro, executará a parte decimal em porcentagem da última época antes de interromper o treinamento).
  • max_steps (int, opcional, padrão -1) — Se definido como um número positivo, representa o número total de etapas de treinamento a serem executadas. Sobrepõe num_train_epochs. Para um conjunto de dados finito, o treinamento é reiterado através do conjunto de dados (se todos os dados forem esgotados) até que max_steps seja atingido. Deve ser definido como um valor positivo quando o conjunto de dados de treinamento não implementa __len__ (por exemplo, um conjunto de dados em streaming), pois o número total de etapas não pode ser inferido e é necessário para limitar o loop de treinamento e configurar o agendador de taxa de aprendizado.
  • gradient_accumulation_steps (int, opcional, padrão 1) — Número de etapas de atualização para acumular os gradientes antes de executar uma etapa de retropropagação/atualização.

    Ao usar acúmulo de gradiente, um passo é contado como um passo com passagem reversa. Portanto, o registro, a avaliação e o salvamento serão realizados a cada gradient_accumulation_steps * xxx_step exemplos de treinamento.

  • seed (int, opcional, padrão 42) — Semente aleatória que será definida no início do treinamento. Para garantir a reprodutibilidade entre execuções, use a função ~Trainer.model_init para instanciar o modelo, caso ele possua parâmetros inicializados aleatoriamente.
  • activation_checkpointing (bool, opcional, padrão False) — Se True, usa activation checkpointing para economizar memória em troca de um backward pass mais lento.
  • gradient_checkpointing (bool, opcional) — Alias descontinuado de activation_checkpointing, será removido na v6.

Um método que agrupa todos os argumentos básicos relacionados ao treinamento.

A chamada deste método definirá automaticamente self.do_train como True.

Exemplo:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_training(learning_rate=1e-4, batch_size=32)
>>> args.learning_rate
1e-4

to_dict

< >

( )

Serializa esta instância substituindo Enum pelos seus valores (para suporte à serialização JSON). Ele ofusca os valores dos tokens removendo seus valores.

to_json_string

< >

( )

Serializa esta instância em uma string JSON.

to_sanitized_dict

< >

( )

Serialização sanitizada para uso com hparams do TensorBoard

Seq2SeqTrainingArguments

classe transformers.Seq2SeqTrainingArguments

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 5e-05lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool = Falsefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool | None = Nonegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 500logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Falserestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: typing.Any | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Truelabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1sortish_sampler: bool = Falsepredict_with_generate: bool = Falsegeneration_max_length: int | None = Nonegeneration_num_beams: int | None = Nonegeneration_config: str | pathlib.Path | transformers.generation.configuration_utils.GenerationConfig | None = None )

Parâmetros

  • output_dir (str, opcional, padrão "trainer_output") — O diretório de saída onde as previsões do modelo e os checkpoints serão gravados.

Duração do treinamento e tamanho do lote

  • per_device_train_batch_size (int, opcional, padrão 8) — O tamanho do lote por dispositivo. O tamanho global do lote é calculado como: per_device_train_batch_size * number_of_devices em configurações multi-GPU ou distribuídas.
  • num_train_epochs(float, opcional, padrão 3.0) — Número total de épocas de treinamento a serem executadas (se não for um número inteiro, executará a parte decimal em porcentagem da última época antes de interromper o treinamento).
  • max_steps (int, opcional, padrão -1) — Substitui num_train_epochs. Se definido para um número positivo, representa o número total de etapas de treinamento a serem executadas. Para um conjunto de dados finito, o treinamento é reiterado pelo conjunto de dados (se todos os dados forem esgotados) até que max_steps seja atingido. Deve ser definido para um valor positivo quando o conjunto de dados de treinamento não implementa __len__ (por exemplo, um conjunto de dados em streaming), pois o número total de etapas não pode ser inferido e é necessário para limitar o loop de treinamento e configurar o agendador de taxa de aprendizado.

Taxa de aprendizado e agendador

  • learning_rate (float, opcional, padrão 5e-5) — A taxa de aprendizado inicial do otimizador. Normalmente, este é o valor máximo da taxa de aprendizado ao usar um agendador com aquecimento.
  • lr_scheduler_type (str ou SchedulerType, opcional, padrão é "linear") — O tipo de agendador de taxa de aprendizado a ser usado. Consulte SchedulerType para todos os valores possíveis. Opções comuns:
  • lr_scheduler_kwargs (dict ou str, opcional, padrão None) — Os argumentos extras para o lr_scheduler. Consulte a documentação de cada scheduler para os valores possíveis.
  • warmup_steps (int ou float, opcional, padrão é 0) — Número de etapas para um aquecimento linear de 0 até learning_rate. O aquecimento ajuda a estabilizar o treinamento na fase inicial. Pode ser:
    • Um inteiro: número exato de etapas de aquecimento
    • Um float no intervalo [0, 1): interpretado como a proporção do total de etapas de treinamento

Otimizador

  • optim (str ou training_args.OptimizerNames, opcional, padrão é "adamw_torch" (para torch>=2.8 "adamw_torch_fused")) — O otimizador a ser usado. Opções comuns:
    • "adamw_torch": AdamW do PyTorch (padrão recomendado)
    • "adamw_torch_fused": Kernel de AdamW fundido
    • "adamw_hf": implementação do AdamW da HuggingFace
    • "sgd": Stochastic Gradient Descent com momentum
    • "adafactor": Otimizador eficiente em memória para modelos grandes
    • "adamw_8bit": AdamW de 8 bits (requer bitsandbytes) Veja OptimizerNames para a lista completa.
  • optim_args (str, opcional) — Argumentos opcionais fornecidos a otimizadores como AnyPrecisionAdamW, AdEMAMix e GaLore.
  • weight_decay (float, opcional, padrão 0) — Coeficiente de decaimento de peso aplicado pelo otimizador (não pela função de perda). Adiciona regularização L2 para evitar overfitting, penalizando pesos grandes. Excluído automaticamente dos parâmetros de bias e LayerNorm. Valores típicos: 0.01 (padrão), 0.1 (regularização mais forte), 0.0 (sem regularização).
  • adam_beta1 (float, opcional, padrão 0.9) — A taxa de decaimento exponencial para as estimativas do primeiro momento (momentum) em otimizadores baseados em Adam. Controla a quantidade de histórico de gradientes a ser mantida.
  • adam_beta2 (float, opcional, padrão 0.999) — A taxa de decaimento exponencial para as estimativas do segundo momento (variância) em otimizadores baseados em Adam. Controla a escala da taxa de aprendizado adaptativa.
  • adam_epsilon (float, opcional, padrão 1e-8) — Valor de epsilon para estabilidade numérica em otimizadores baseados em Adam. Impede a divisão por zero no denominador da regra de atualização.
  • optim_target_modules (Union[str, list[str]], opcional) — Os módulos-alvo a serem otimizados, ou seja, os nomes dos módulos que você deseja treinar. Atualmente usado para o algoritmo GaLore e o algoritmo APOLLO. Veja implementação do GaLore e implementação do APOLLO para mais detalhes. Você precisa garantir que passe um otimizador GaLore ou APOLLO válido, por exemplo, um dos seguintes: “apollo_adamw”, “galore_adamw”, “galore_adamw_8bit”, “galore_adafactor” e garantir que os módulos-alvo sejam apenas módulos nn.Linear.

Regularização e Estabilidade do Treinamento

  • gradient_accumulation_steps (int, opcional, padrão 1) — Número de etapas de atualização para acumular gradientes antes de executar uma passagem de retropropagação/atualização. Simula tamanhos de lote maiores sem memória adicional. Tamanho de lote efetivo = per_device_train_batch_size × num_devices × gradient_accumulation_steps.

    Ao usar acúmulo de gradiente, um “passo” é contado como um passo com uma passagem reversa. Portanto, o registro, a avaliação e o salvamento ocorrerão a cada gradient_accumulation_steps × xxx_step exemplos de treinamento.

  • average_tokens_across_devices (bool, opcional, padrão True) — Indica se as tokens devem ser médias entre os dispositivos. Se habilitado, usará all_reduce para sincronizar num_tokens_in_batch para um cálculo preciso da perda. Referência: https://github.com/huggingface/transformers/issues/34242
  • max_grad_norm (float, opcional, padrão 1.0) — Norma máxima do gradiente para o recorte de gradiente. Aplicada após a passagem reversa, antes da etapa do otimizador. Impede a explosão de gradientes ao reduzir os gradientes quando sua norma global excede esse limite. Defina como 0 para desativar o recorte. Valores típicos: 1.0 (padrão), 0.5 (mais conservador), 5.0 (menos agressivo).
  • label_smoothing_factor (float, opcional, padrão 0.0) — Fator de label smoothing para evitar excesso de confiança. Substitui os alvos rígidos 0/1 por alvos suaves: 0 se torna ε/num_labels e 1 se torna 1 - ε + ε/num_labels, onde ε = label_smoothing_factor. Zero significa que não há suavização. Faixa típica: 0.0 a 0.1.

Treinamento com Precisão Mista

  • bf16 (bool, opcional, padrão False) — Ativa o treinamento com precisão mista bfloat16 (BF16) Geralmente preferível ao FP16 devido à melhor estabilidade numérica e à ausência de necessidade de escalonamento de perda.
  • fp16 (bool, opcional, padrão False) — Ativa o treinamento com precisão mista float16 (FP16). Considere usar BF16 em vez disso, se o seu hardware for compatível.
  • bf16_full_eval (bool, opcional, padrão False) — Usa precisão BF16 completa para avaliação (não apenas precisão mista). Mais rápido e economiza memória, mas pode afetar ligeiramente os valores das métricas. Aplica-se apenas durante a avaliação.
  • fp16_full_eval (bool, opcional, padrão False) — Usa precisão FP16 completa para avaliação (não apenas precisão mista). Mais rápido e economiza memória, mas pode afetar ligeiramente os valores das métricas. Aplica-se apenas durante a avaliação.
  • tf32 (bool, opcional) — Ativa o modo TensorFloat-32 (TF32) em GPUs Ampere e mais recentes. O TF32 usa precisão de 19 bits para multiplicações de matrizes (em vez dos 23 bits do FP32), proporcionando até 8x de aceleração com perda de precisão negligível. O valor padrão depende da versão do PyTorch. Veja documentação do TF32.

Checkpointing de Ativação

  • activation_checkpointing (bool, opcional, padrão False) — Ativa o checkpointing de ativações para trocar computação por memória. Reduz o uso de memória limpando as ativações durante a passagem de frente e recalculando-as durante a passagem de trás. Permite treinar modelos maiores ou tamanhos de lote maiores, com o custo de um treinamento ~20% mais lento.
  • activation_checkpointing_kwargs (dict, opcional, padrão None) — Argumentos de palavra-chave passados para activation_checkpointing_enable(). every_n_layers aplica checkpoint apenas a cada n-ésima camada do decodificador, em vez de todas; 1 é o comportamento usual de tudo ou nada, e valores maiores devolvem alguma memória em troca de velocidade. offload mantém as ativações salvas em memória de host fixada, o que libera layers x sequence x hidden bytes de memória de dispositivo e torna o passo mais lento. Qualquer outra chave é encaminhada para torch.utils.checkpoint.checkpoint.
  • gradient_checkpointing (bool, opcional) — Alias descontinuado de activation_checkpointing, será removido na v6.
  • gradient_checkpointing_kwargs (dict, opcional) — Alias descontinuado de activation_checkpointing_kwargs, será removido na v6.

Compilação

  • torch_compile (bool, opcional, padrão False) — Compila o modelo usando o torch.compile() do PyTorch 2.0 para um treinamento mais rápido. Pode fornecer um ganho de 20-50% em velocidade sem alterações no código. Usa as configurações de compilação padrão, a menos que torch_compile_backend ou torch_compile_mode sejam especificados.
  • torch_compile_backend (str, opcional) — Backend para torch.compile(). Se definido, ativa automaticamente torch_compile. As opções incluem "inductor" (padrão), "aot_eager", "cudagraphs". Os backends variam conforme a versão do PyTorch - consulte a documentação do PyTorch para as opções disponíveis.
  • torch_compile_mode (str, opcional) — Modo de compilação para torch.compile(). Se definido, ativa automaticamente torch_compile. Opções: "default", "reduce-overhead" (minimizar sobrecarga do Python), "max-autotune" (otimização agressiva, tempo de compilação mais lento).

Kernels

  • use_liger_kernel (bool, opcional, padrão False) — Ativa as otimizações do Liger Kernel. Aumenta o throughput em multi-GPU em ~20% e reduz o uso de memória em ~60%. Funciona com Flash Attention, FSDP e DeepSpeed. Atualmente suporta os modelos Llama, Mistral, Mixtral e Gemma.
  • liger_kernel_config (Optional[dict], opcional) — Configuração para o Liger Kernel. Passado como kwargs para _apply_liger_kernel_to_instance(). As opções geralmente incluem: "rope", "swiglu", "cross_entropy", "fused_linear_cross_entropy", "rms_norm". Se None, usa a configuração padrão.

Otimizações adicionais

  • use_cache (bool, opcional, padrão False) — Indica se a cache do modelo deve ser ativada. Para treinamento, isso geralmente não é necessário, exceto em alguns métodos PEFT que utilizam past_key_values.
  • neftune_noise_alpha (Optional[float]) — Se não for None, isso ativará as embeddings de ruído do NEFTune. Isso pode melhorar drasticamente o desempenho do modelo para o ajuste fino de instruções. Consulte o artigo original e o código original. Suporta PreTrainedModel do transformers e também PeftModel do peft. O artigo original utilizou valores na faixa [5.0, 15.0].
  • torch_empty_cache_steps (int, opcional) — Número de etapas a aguardar antes de chamar torch.<device>.empty_cache(). Se não for definido ou for definido como None, o cache não será esvaziado. Isso pode ajudar a evitar erros de memória insuficiente na CUDA, reduzindo o uso de pico de VRAM, com um custo de aproximadamente 10% de desempenho mais lento.
  • auto_find_batch_size (bool, opcional, padrão False) — Se deve encontrar automaticamente um tamanho de lote de treinamento que caiba na memória, por meio de decaimento exponencial, evitando erros de CUDA Out-of-Memory. O tamanho do lote de avaliação não é ajustado.

Registro e monitoramento do treinamento

  • logging_strategy (str ou IntervalStrategy, opcional, padrão é "steps") — Estratégia de log a ser adotada durante o treinamento. Os valores possíveis são:
    • "no": Nenhum registro é feito durante o treinamento.
    • "epoch": O registro é feito no final de cada epoch.
    • "steps": O registro é feito a cada logging_steps.
  • logging_steps (int ou float, opcional, padrão 500) — Número de etapas de atualização entre dois registros, se logging_strategy="steps". Deve ser um inteiro ou um número flutuante no intervalo [0,1). Se for menor que 1, será interpretado como a proporção das etapas totais de treinamento.
  • logging_first_step (bool, opcional, padrão False) — Se deve registrar o primeiro global_step ou não.
  • log_on_each_node (bool, opcional, padrão True) — No treinamento distribuído multinó, se o registro deve ser feito usando log_level uma vez por nó ou apenas no nó principal.
  • logging_nan_inf_filter (bool, opcional, padrão True) — Filtra perdas NaN e Inf ao registrar logs. Se True, substitui as perdas de treinamento NaN/Inf pela média das perdas válidas recentes e exclui os lotes com NaN/Inf (por exemplo, lotes sem tokens de rótulo) da perda de avaliação. Não afeta o cálculo do gradiente, apenas o registro de logs.
  • include_num_input_tokens_seen (Optional[Union[str, bool]], opcional, padrão “no”) — Se deve rastrear o número de tokens de entrada vistos. Deve ser um dos valores [“all”, “non_padding”, “no”] ou um valor booleano que mapeia para “all” ou “no”. Pode ser mais lento em treinamento distribuído, pois operações de gather devem ser chamadas.

Registro de logs

  • log_level (str, opcional, padrão passive) — Nível de log para o processo principal. Opções: "debug", "info", "warning", "error", "critical" ou "passive" (não altera o nível de log atual do Transformers, que é "warning" por padrão)
  • log_level_replica (str, opcional, padrão "warning") — Nível de log para processos de réplica em treinamento distribuído. Mesmas opções de log_level.
  • disable_tqdm (bool, opcional) — Desativa as barras de progresso do tqdm. O valor padrão é True se log_level for warning ou inferior, e False caso contrário.

Integração com Rastreamento de Experimentos

  • report_to (str ou list[str], opcional, padrão "none") — A lista de integrações para as quais os resultados e os logs devem ser reportados. As plataformas suportadas são "azure_ml", "clearml", "codecarbon", "comet_ml", "dagshub", "dvclive", "flyte", "mlflow", "swanlab", "tensorboard", "trackio" e "wandb". Use "all" para reportar a todas as integrações instaladas e "none" para não usar nenhuma integração.
  • run_name (str, opcional) — Um descritor para a execução. Tipicamente usado para log de trackio, wandb, mlflow, comet e swanlab.
  • project (str, opcional, padrão "huggingface") — O nome do projeto a ser usado para registro de logs. Atualmente, usado apenas pelo Trackio.
  • trackio_space_id (str ou None, opcional, padrão None) — O ID do Space do Hugging Face a ser usado para o registro ao vivo do Trackio com um Space baseado em Gradio. Deve ser um nome completo de Space, como 'username/reponame' ou 'orgname/reponame', ou apenas 'reponame' (o Space será criado no namespace do usuário atualmente conectado). Se for None, as métricas serão registradas apenas em um diretório local (sem Space no Hub). Aquele Space Gradio tem acesso de leitura e escrita ao Bucket do Trackio, o que é desejável enquanto o treinamento está em andamento—por exemplo, ao retomar uma execução parcial ou agregar logs de várias máquinas. O Space será público, a menos que você defina hub_private_repo=True ou o padrão da sua organização seja criar Spaces privados.
  • trackio_bucket_id (str ou None, opcional, padrão None) — ID opcional de Bucket do Hugging Face para o Trackio. Se não for definido, o Trackio deriva um. Usado em conjunto com um Space do Gradio (trackio_space_id) e ao implantar um Space estático (trackio_static_space_id não é False).
  • trackio_static_space_id (str, False ou None, opcional, padrão None) — O ID do Hugging Face Space a ser usado para o Space estático criado após a conclusão do treinamento. Deve ser um nome completo de Space, como 'username/reponame' ou 'orgname/reponame', ou apenas 'reponame' (o Space será criado no namespace do usuário atualmente conectado). Se False, nenhum Space estático será criado. Se None e o modelo for enviado para o Hub, um Space estático será criado com um nome padrão e será vinculado a partir do cartão do modelo. O Space será público, a menos que você defina hub_private_repo=True ou o padrão da sua organização seja criar Spaces privados.

Avaliação

  • eval_strategy (str ou IntervalStrategy, opcional, padrão é "no") — Quando executar a avaliação. Opções:
    • "no": Sem avaliação durante o treinamento
    • "steps": Avaliar a cada eval_steps
    • "epoch": Avaliar no final de cada epoch
  • eval_steps (int ou float, opcional) — Número de etapas de atualização entre duas avaliações, se eval_strategy="steps". Se não for definido, o valor padrão será o mesmo de logging_steps. Deve ser um inteiro ou um número flutuante no intervalo [0,1). Se for menor que 1, será interpretado como a proporção das etapas totais de treinamento.
  • eval_delay (float, opcional) — Número de épocas ou passos a aguardar antes que a primeira avaliação possa ser realizada, dependendo do eval_strategy.
  • per_device_eval_batch_size (int, opcional, padrão 8) — O tamanho do lote por núcleo de acelerador/CPU do dispositivo para avaliação.
  • prediction_loss_only (bool, opcional, padrão False) — Ao realizar a avaliação e gerar previsões, retorna apenas a perda.
  • eval_on_start (bool, opcional, padrão False) — Se deve executar uma etapa de avaliação (verificação de sanidade) antes do treinamento para garantir que as etapas de validação funcionem corretamente.
  • eval_do_concat_batches (bool, opcional, padrão True) — Se deve concatenar recursivamente entradas/perdas/rótulos/previsões entre lotes. Se False, serão armazenados como listas, mantendo cada lote separado.
  • eval_use_gather_object (bool, opcional, padrão False) — Se deve executar o gather recursivo de objetos em uma lista/tupla/dicionário aninhado de objetos a partir de todos os dispositivos. Isso deve ser habilitado apenas se os usuários não estiverem retornando apenas tensores, e isso é ativamente desencorajado pelo PyTorch. Isso é útil quando a estrutura dos rótulos é não padrão, como em tarefas de visão computacional.
  • eval_accumulation_steps (int, opcional) — Número de etapas de predição para acumular os tensores de saída antes de mover os resultados para a CPU. Se deixado sem definir, todas as predições são acumuladas no acelerador do dispositivo antes de serem movidas para a CPU (mais rápido, mas requer mais memória).

Cálculo de métricas

  • include_for_metrics (list[str], opcional, padrão é []) — Inclui dados adicionais na compute_metrics função, caso necessário para o cálculo de métricas. Opções possíveis para adicionar à include_for_metrics lista:
    • "inputs": Dados de entrada passados ao modelo, destinados ao cálculo de métricas dependentes da entrada.
    • "loss": Valores de perda calculados durante a avaliação, destinados ao cálculo de métricas dependentes de perda.
  • batch_eval_metrics (bool, opcional, padrão False) — Se definido como True, a avaliação chamará compute_metrics no final de cada lote para acumular estatísticas, em vez de salvar todos os logits de avaliação na memória. Quando definido como True, você deve passar uma função compute_metrics que aceite um argumento booleano compute_result, que, quando receber True, acionará as estatísticas globais finais a partir das estatísticas resumidas por lote que você acumulou ao longo do conjunto de avaliação.

Checkpointing e salvamento

  • save_only_model (bool, opcional, padrão False) — Salva apenas os pesos do modelo, sem o estado do otimizador/agendador/RNG. Isso reduz significativamente o tamanho do checkpoint, mas impede a retomada do treinamento a partir dele. Use quando você precisar apenas do modelo treinado para inferência, e não para continuar o treinamento. Com essa opção definida como True, você só pode carregar o modelo usando from_pretrained.
  • save_strategy (str ou SaveStrategy, opcional, padrão é "steps") — Estratégia de salvamento de checkpoints a ser adotada durante o treinamento. Os valores possíveis são:
    • "no": Nenhum salvamento é realizado durante o treinamento.
    • "epoch": O salvamento é realizado ao final de cada epoch.
    • "steps": O salvamento é realizado a cada save_steps.
    • "best": O salvamento é realizado sempre que uma nova best_metric é alcançada.
  • save_steps (int ou float, opcional, padrão 500) — Número de etapas de atualização entre duas gravações de checkpoint, se save_strategy="steps". Deve ser um inteiro ou um float no intervalo [0,1). Se for menor que 1, será interpretado como a proporção das etapas totais de treinamento.
  • save_on_each_node (bool, opcional, padrão False) — Ao realizar treinamento distribuído em vários nós, se os modelos e checkpoints devem ser salvos em cada nó ou apenas no principal. Isso não deve ser ativado quando os diferentes nós usam o mesmo armazenamento, pois os arquivos serão salvos com os mesmos nomes em cada nó.
  • save_total_limit (int, opcional) — Número máximo de checkpoints a serem mantidos. Exclui checkpoints mais antigos em output_dir. Quando load_best_model_at_end=True, o melhor checkpoint é sempre mantido, além dos mais recentes. Por exemplo, save_total_limit=5 mantém os 4 mais recentes, além do melhor
  • enable_jit_checkpoint (bool, opcional, padrão False) — Ativa o checkpointing Just-In-Time no sinal SIGTERM para encerramento gracioso em cargas de trabalho preemptíveis. Importante: Configure o período de encerramento gracioso do seu orquestrador para permitir tempo suficiente. Para Kubernetes, defina terminationGracePeriodSeconds (o padrão de 30s geralmente é insuficiente). Para Slurm, use --signal=TERM@<seconds>. O período de graça necessário ≥ tempo da iteração mais longa + tempo de salvamento do checkpoint.

Integração com o Hugging Face Hub

  • push_to_hub (bool, opcional, padrão False) — Indica se o modelo deve ser enviado ao Hub sempre que for salvo. Se ativado, output_dir iniciará um diretório git sincronizado com o repositório (determinado por hub_model_id) e o conteúdo será enviado sempre que um salvamento for acionado (dependendo do seu save_strategy). A chamada de save_model() também acionará um envio.
  • hub_token (str, opcional) — O token a ser usado para enviar o modelo para o Hub. Por padrão, será utilizado o token na pasta de cache obtido com hf auth login.
  • hub_private_repo (bool, opcional) — Se a repositório deve ser privado. Se None (padrão), o repositório será público, a menos que o padrão da organização seja privado. Este valor é ignorado se o repositório já existir. Se o relatório for enviado ao Trackio com o deploy para Hugging Face Spaces habilitado, a mesma lógica determina se o Space é privado.
  • hub_model_id (str, opcional) — O nome do repositório que deve ser mantido em sincronia com o output_dir local. Pode ser um ID de modelo simples, caso em que o modelo será enviado no seu namespace. Caso contrário, deve ser o nome completo do repositório, por exemplo "user_name/model", o que permite enviar para uma organização da qual você é membro com "organization_name/model". O valor padrão será user_name/output_dir_name, sendo output_dir_name o nome de output_dir.
  • hub_strategy (str ou HubStrategy, opcional, padrão é "every_save") — Define o que e quando enviar para o Hub. Opções:
    • "end": Empurrar apenas no final do treinamento
    • "every_save": Fazer push a cada salvamento (assíncrono para não bloquear o treinamento)
    • "checkpoint": Assim como "every_save", além de enviar o checkpoint mais recente para a subpasta "last-checkpoint" para facilitar a retomada
    • "all_checkpoints": Envie todos os checkpoints conforme eles aparecem
  • hub_always_push (bool, opcional, padrão False) — A menos que seja True, o Trainer ignorará o envio de um checkpoint quando o envio anterior não tiver sido concluído.
  • hub_revision (str, opcional) — A revisão a ser usada ao fazer push para o Hub. Pode ser o nome de uma branch, uma tag ou um hash de commit.

Melhor rastreamento de modelos

  • load_best_model_at_end (bool, opcional, padrão False) — Carrega o melhor checkpoint ao final do treinamento. Exige que eval_strategy esteja definido. Quando habilitado, o melhor checkpoint é sempre salvo (veja save_total_limit). Quando `True`, `save_strategy` deve corresponder a `eval_strategy` (a menos que `save_strategy` seja `"best"`), e, se usar `"steps"`, `save_steps` deve ser um múltiplo de `eval_steps`.
  • metric_for_best_model (str, opcional) — Métrica a ser usada para comparar modelos quando load_best_model_at_end=True. Deve ser um nome de métrica retornado pela avaliação, com ou sem o prefixo "eval_". O padrão é "loss". Se você definir isso, greater_is_better terá como padrão True, a menos que o nome termine com "loss". Exemplos: "accuracy", "f1", "eval_bleu".
  • greater_is_better (bool, opcional) — Indica se valores maiores da métrica são melhores. O valor padrão é baseado em metric_for_best_model: True se o nome da métrica não terminar em "loss", False caso contrário.

Retomando o Treinamento

  • ignore_data_skip (bool, opcional, padrão False) — Ao retomar o treinamento, ignora a adiantamento rápido pelo conjunto de dados para alcançar o estado anterior. Se True, o treinamento começa do início do conjunto de dados (retomada mais rápida, mas os resultados não corresponderão ao treinamento interrompido). Se False, pula os dados já vistos (retomada mais lenta, mas continuação exata).
  • restore_callback_states_from_checkpoint (bool, opcional, padrão False) — Restaura os estados dos callbacks a partir do checkpoint ao retomar. Se True, sobrescreverá os callbacks passados para o Trainer, caso existam no checkpoint.

Reprodutibilidade

  • full_determinism (bool, opcional, padrão False) — Se True, enable_full_determinism() é chamado em vez de set_seed() para garantir resultados reproduzíveis no treinamento distribuído. Importante: isso impactará negativamente o desempenho, portanto, use apenas para depuração.
  • seed (int, opcional, padrão 42) — Semente aleatória que será definida no início do treinamento. Para garantir a reprodutibilidade entre execuções, use a função ~Trainer.model_init para instanciar o modelo, caso ele possua parâmetros inicializados aleatoriamente.
  • data_seed (int, opcional) — Semente aleatória a ser usada com amostradores de dados. Se não for definida, os geradores aleatórios para amostragem de dados usarão a mesma semente que seed. Isso pode ser usado para garantir a reprodutibilidade da amostragem de dados, independentemente da semente do modelo.

Configuração de Hardware

  • use_cpu (bool, opcional, padrão False) — Indica se deve ou não usar a CPU. Se definido como False, usaremos o dispositivo/backend do torch disponível.

Configuração do Accelerate

  • accelerator_config (str, dict, ou AcceleratorConfig, opcional) — Configuração para a integração interna do Accelerate. Pode ser: Caminho para um arquivo de configuração JSON: "accelerator_config.json" Dicionário com opções de configuração Instância de AcceleratorConfig Opções principais: split_batches (bool, padrão False): Se deve dividir os lotes entre os dispositivos. Se True, o tamanho real do lote é o mesmo em todos os dispositivos (o total deve ser divisível por num_processes). Se False, cada dispositivo recebe o tamanho de lote especificado. dispatch_batches (bool): Se True, apenas o processo principal itera pelo dataloader e distribui os lotes para os dispositivos. Padrão True para IterableDataset, False caso contrário. even_batches (bool, padrão True): Duplica amostras do início do dataset para garantir que todos os workers recebam tamanhos de lote iguais. use_seedable_sampler (bool, padrão True): Usa um amostrador aleatório totalmente semeadável para reprodutibilidade. use_configured_state (bool, padrão False): Usa um AcceleratorState/PartialState pré-inicializado em vez de criar um novo. Pode causar problemas com o ajuste de hiperparâmetros.
    • Caminho para o arquivo de configuração JSON: "accelerator_config.json"
    • Dicionário com opções de configuração
    • instância de AcceleratorConfig Opções principais:
    • split_batches (bool, padrão False): Se deve dividir os lotes entre os dispositivos. Se True, o tamanho real do lote é o mesmo em todos os dispositivos (o total deve ser divisível por num_processes). Se False, cada dispositivo recebe o tamanho de lote especificado.
    • dispatch_batches (bool): Se True, apenas o processo principal itera pelo dataloader e distribui os lotes para os dispositivos. O valor padrão é True para IterableDataset e False caso contrário.
    • even_batches (bool, padrão True): Duplica amostras do início do conjunto de dados para garantir que todos os workers recebam tamanhos de lote iguais.
    • use_seedable_sampler (bool, padrão True): Use um amostrador aleatório totalmente semeadável para reprodutibilidade.
    • use_configured_state (bool, padrão False): Utiliza um AcceleratorState/PartialState pré-inicializado em vez de criar um novo. Pode causar problemas com o ajuste de hiperparâmetros.
  • parallelism_config (ParallelismConfig, opcional) — Configuração de paralelismo para a execução de treinamento. Requer Accelerate 1.10.1

Dataloader

  • dataloader_drop_last (bool, opcional, padrão False) — Se deve descartar o último lote incompleto (caso o comprimento do conjunto de dados não seja divisível pelo tamanho do lote) ou não.
  • dataloader_num_workers (int, opcional, padrão 0) — Número de subprocessos a serem usados para o carregamento de dados (somente PyTorch). 0 significa que os dados serão carregados no processo principal.
  • dataloader_pin_memory (bool, opcional, padrão True) — Se você deseja fixar a memória nos carregadores de dados ou não. O padrão será True.
  • dataloader_persistent_workers (bool, opcional, padrão False) — Se True, o data loader não encerrará os processos de worker após um dataset ter sido consumido uma vez. Isso permite manter as instâncias de Dataset dos workers ativas. Pode potencialmente acelerar o treinamento, mas aumentará o uso de RAM. O padrão será False.
  • dataloader_prefetch_factor (int, opcional) — Número de lotes carregados antecipadamente por cada worker. 2 significa que haverá um total de 2 * num_workers lotes pré-carregados em todos os workers.
  • dataloader_multiprocessing_context (str, opcional) — O método de inicialização de multiprocessamento a ser usado para os workers de carregamento de dados ("fork", "spawn" ou "forkserver"). O padrão é o método de inicialização padrão do PyTorch, exceto no MPS com dataloader_num_workers > 1, onde o padrão é "fork". Use "spawn" ao fazer streaming de fontes cujos objetos não são seguros para fork (por exemplo, HDFS via pyarrow). Sob "spawn", qualquer collate_fn personalizado ou código de dataset deve ser importável no nível do módulo (sem lambdas/closures).
  • dataloader_in_order (bool, opcional, padrão True) — Se True, o data loader fornece lotes na ordem em que os workers foram despachados. Defina como False para fornecer lotes assim que estiverem prontos, o que pode reduzir a latência de cauda para cargas de trabalho de streaming de IterableDataset. Requer PyTorch >= 2.6.
  • remove_unused_columns (bool, opcional, padrão True) — Se as colunas não utilizadas pelo método forward do modelo devem ser removidas automaticamente.
  • label_names (list[str], opcional) — A lista de chaves no seu dicionário de entradas que correspondem aos rótulos. Eventualmente, o padrão será a lista de nomes de argumentos aceitos pelo modelo que contenham a palavra “label”, exceto se o modelo utilizado for um dos XxxForQuestionAnswering, caso em que também incluirá as chaves ["start_positions", "end_positions"]. Você deve especificar label_names apenas se estiver usando nomes de rótulos personalizados ou se o forward do seu modelo consumir múltiplos tensores de rótulos (por exemplo, QA extrativo).
  • train_sampling_strategy (str, opcional, padrão é "random") — O sampler a ser usado para o dataloader de treinamento. Os valores possíveis são:
    • "random": Usa RandomSampler (padrão).
    • "sequential": Usa SequentialSampler.
    • "group_by_length": usa LengthGroupedSampler para agrupar amostras de comprimento aproximadamente igual (junto, para minimizar o padding e ser mais eficiente).
    • "batch_rebalance": Usa BatchRebalanceSampler para equilibrar o custo de tokens de padding entre os dispositivos e as etapas de acúmulo de gradiente dentro de cada lote efetivo, reduzindo o desperdício de padding e a memória de pico em comparação com "group_by_length". Atualmente, é suportado apenas para treinamento paralelo de dados (o paralelismo de tensor ainda não é suportado).

    Observação: ao usar um IterableDataset, este argumento é ignorado.

  • length_column_name (str, opcional, padrão "length") — Nome da coluna para comprimentos pré-calculados. Se a coluna existir, o agrupamento por comprimento usará esses valores em vez de calculá-los na inicialização do treinamento. Ignorado, a menos que train_sampling_strategy seja "group_by_length" ou "batch_rebalance" e o conjunto de dados seja uma instância de Dataset.

DDP (DistributedDataParallel)

  • ddp_find_unused_parameters (bool, opcional) — Ao usar treinamento distribuído, o valor da flag find_unused_parameters passada para DistributedDataParallel. O valor padrão será False se gradient checkpointing for usado, True caso contrário.
  • ddp_bucket_cap_mb (int, opcional) — Ao usar treinamento distribuído, o valor da flag bucket_cap_mb passada para DistributedDataParallel.
  • ddp_broadcast_buffers (bool, opcional) — Ao usar treinamento distribuído, o valor da flag broadcast_buffers passada para DistributedDataParallel. Será False por padrão se o gradient checkpointing for usado, True caso contrário.
  • ddp_static_graph (bool, opcional) — Ao usar treinamento distribuído, o valor da flag static_graph passada para DistributedDataParallel.
  • ddp_backend (str, opcional) — O backend a ser usado para treinamento distribuído. Deve ser um dos seguintes: "nccl", "mpi", "xccl", "gloo", "hccl".
  • ddp_timeout (int, opcional, padrão 1800) — O tempo limite para as chamadas de torch.distributed.init_process_group, usado para evitar timeouts de socket da GPU ao executar operações lentas em execuções distribuídas. Consulte a documentação do PyTorch para mais informações.

FSDP (Fully Sharded Data Parallel)

  • fsdp (bool, opcional, padrão None) — Ativa o PyTorch Fully Sharded Data Parallel (FSDP) para treinamento distribuído. Passe True para habilitar o FSDP.
  • fsdp_config (str or dict, optional) — Configuration settings for when fsdp is enabled. Pass a path to a JSON config file, such as fsdp_config.json, or an already-loaded dict.

    Chaves suportadas:

    • version (int, opcional, padrão 2): A versão do FSDP a ser usada (2 para FSDP2, 1 para o FSDP1 legado).
    • reshard_after_forward (bool, opcional, padrão True): Se deve redividir os parâmetros após a passagem de propagação direta. Defina como False para manter os parâmetros agregados entre as passagens de propagação direta e reversa, evitando o re-all-gather e utilizando mais memória de pico.
    • cpu_offload (bool, opcional, padrão False): Desloca parâmetros e gradientes para a CPU quando não estão em uso, para economizar memória de GPU.
    • activation_checkpointing (bool, opcional, padrão False): Defina como True para reduzir a memória recalculando as ativações durante a passagem reversa. Ao usar FSDP, prefira isso ao argumento de treinamento activation_checkpointing, que introduz um all-gather redundante na passagem reversa.
    • cpu_ram_efficient_loading (bool, opcional, padrão False): Defina como True para carregar o checkpoint pré-treinado apenas no primeiro processo. Os outros processos iniciam com pesos vazios e recebem os pesos por broadcast.
    • state_dict_type (str, opcional, padrão "FULL_STATE_DICT"): Formato do checkpoint: "FULL_STATE_DICT" (arquivo único compatível com HF) ou "SHARDED_STATE_DICT" (um arquivo por rank, mais rápido para modelos grandes).
    • auto_wrap_policy (str, opcional, padrão "TRANSFORMER_BASED_WRAP"): Política de auto-wrap a ser utilizada. Escolha "TRANSFORMER_BASED_WRAP", "SIZE_BASED_WRAP" ou "NO_WRAP".
    • transformer_layer_cls_to_wrap (list[str], opcional): Nomes das classes de camadas de Transformer (sensíveis a maiúsculas e minúsculas) a serem envolvidas, por exemplo, LlamaDecoderLayer. Geralmente não é necessário: a política de envolvimento usa como fallback o _no_split_modules do modelo, que cobre a maioria dos modelos de transformers.
    • min_num_params (int, opcional, padrão 0): Número mínimo de parâmetros por módulo para o auto-wrapping baseado em tamanho (usado com auto_wrap_policy="SIZE_BASED_WRAP").
    • xla (bool, opcional, padrão False): Se deve usar o treinamento PyTorch/XLA Fully Sharded Data Parallel. Experimental.
    • xla_fsdp_settings (dict, opcional): Dicionário de parâmetros de encapsulamento do XLA FSDP. Para a lista completa de opções, consulte o código-fonte do XLA FSDP.
    • xla_fsdp_grad_ckpt (bool, opcional, padrão False): Defina como True para usar gradient checkpointing em cada camada aninhada envolvida por XLA FSDP. Exige xla=True e uma política de auto-wrapping (min_num_params ou transformer_layer_cls_to_wrap).

DeepSpeed

  • deepspeed (str ou dict, opcional) — Ativa a integração com o O valor pode ser:
    • Caminho para o arquivo de configuração JSON do DeepSpeed: "ds_config.json"
    • Config carregada como dicionário

      Se estiver usando a inicialização ZeRO, instancie seu modelo após a inicialização de TrainingArguments; caso contrário, o ZeRO não será aplicado.

Depuração e Análise de Desempenho (Experimental)

  • debug (str ou lista de DebugOption, opcional, padrão é "") — Ativa um ou mais recursos de depuração. Este é um recurso experimental. As opções possíveis são:
    • “underflow_overflow”: detecta estouro nos entradas/saídas do modelo e relata os últimos quadros que levaram ao evento
    • “tpu_metrics_debug”: exibe métricas de depuração em TPU
  • skip_memory_metrics (bool, opcional, padrão True) — Se deve ignorar a adição de relatórios do perfilador de memória às métricas. Isso é ignorado por padrão, pois reduz a velocidade de treinamento e avaliação.

Flags de script externo (não usadas pelo Trainer)

  • do_train (bool, opcional, padrão False) — Indica se o treinamento deve ser executado ou não. Este argumento não é usado diretamente pelo Trainer; ele destina-se a ser utilizado pelos seus scripts de treinamento/avaliação.
  • do_eval (bool, opcional) — Indica se a avaliação deve ser executada no conjunto de validação. Será definido como True se eval_strategy for diferente de "no". Este argumento não é usado diretamente pelo Trainer; ele destina-se a ser utilizado pelos seus scripts de treinamento/avaliação.
  • do_predict (bool, opcional, padrão False) — Indica se as previsões devem ser executadas no conjunto de teste ou não. Este argumento não é usado diretamente pelo Trainer; ele destina-se a ser utilizado pelos seus scripts de treinamento/avaliação.
  • resume_from_checkpoint (str, opcional) — O caminho para uma pasta com um checkpoint válido para o seu modelo. Este argumento não é usado diretamente pelo Trainer; ele é destinado a ser usado pelos seus scripts de treinamento/avaliação.
  • sortish_sampler (bool, opcional, padrão é False) — Se deve usar um sortish sampler ou não. Possível apenas se os datasets subjacentes forem Seq2SeqDataset por enquanto, mas estará disponível de forma geral em breve.

    Ele ordena as entradas de acordo com os comprimentos, a fim de minimizar o tamanho do padding, com um pouco de aleatoriedade para o conjunto de treinamento.

  • predict_with_generate (bool, opcional, padrão False) — Se deve usar generate para calcular métricas generativas (ROUGE, BLEU).
  • generation_max_length (int, opcional) — O max_length a ser usado em cada loop de avaliação quando predict_with_generate=True. O valor padrão será o max_length da configuração do modelo.
  • generation_num_beams (int, opcional) — O num_beams a ser usado em cada loop de avaliação quando predict_with_generate=True. O valor padrão será o num_beams da configuração do modelo.
  • generation_config (str ou Path ou GenerationConfig, opcional) — Permite carregar um GenerationConfig a partir do método from_pretrained Isso pode ser:
    • uma string, o model id de uma configuração de modelo pré-treinado hospedada em um repositório de modelos no huggingface.co.
    • um caminho para um diretório contendo um arquivo de configuração salvo usando o método save_pretrained(), por exemplo, ./my_model_directory/.
    • um objeto GenerationConfig.

Classe de configuração para controlar todos os aspectos do treinamento do modelo com o Trainer. TrainingArguments centraliza todos os hiperparâmetros, configurações de otimização, preferências de registro e escolhas de infraestrutura necessárias para o treinamento.

HfArgumentParser pode converter esta classe em argumentos de argparse que podem ser especificados na linha de comando.

to_dict

< >

( )

Serializa esta instância substituindo Enum pelos seus valores e GenerationConfig por dicionários (para suporte à serialização JSON). Ele ofusca os valores dos tokens removendo seus valores.

Update on GitHub

←Tokenizer DeepSpeed→