# Callbacks

Callbacks são objetos que podem personalizar o comportamento do loop de treinamento no [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer) do PyTorch, inspecionar o estado do loop de treinamento (para relatórios de progresso, registro no TensorBoard ou outras plataformas de ML...) e tomar decisões (como parada antecipada).

Os callbacks são trechos de código "somente leitura"; exceto pelo objeto [TrainerControl](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerControl) que retornam, eles não podem alterar nada no loop de treinamento. Para personalizações que exigem mudanças no loop de treinamento, você deve criar uma subclasse de [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer) e sobrescrever os métodos necessários (veja [trainer](trainer) para exemplos).

Por padrão, `TrainingArguments.report_to` é definido como `"none"`.

A classe principal que implementa os callbacks é [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback). Ela recebe os [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) usados para instanciar o [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer), pode acessar o estado interno desse Trainer por meio de [TrainerState](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerState) e pode executar algumas ações no loop de treinamento por meio de [TrainerControl](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerControl).

## Callbacks Disponíveis[[transformers.integrations.CometCallback]]

Aqui está a lista dos [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) disponíveis na biblioteca:

#### transformers.integrations.CometCallback[[transformers.integrations.CometCallback]]

```python
transformers.integrations.CometCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1133)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que envia os logs para o [Comet ML](https://www.comet.com/site/).

#### setup[[transformers.integrations.CometCallback.setup]]

```python
setup(args, state, model)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1147)

Configure a integração opcional do Comet.

Ambiente:
- **COMET_MODE** (`str`, *opcional*, padrão `get_or_create`): Controla se deve criar e registrar em um novo experimento Comet ou anexar a um experimento existente. Aceita os seguintes valores:
  * `get_or_create`: Decide automaticamente com base em se `COMET_EXPERIMENT_KEY` está definido e se já existe um Experiment com essa chave.
  * `create`: Sempre crie um novo Experimento Comet.
  * `get`: Sempre tente anexar a um Experimento Comet existente. Exige que `COMET_EXPERIMENT_KEY` esteja definido.
- **COMET_START_ONLINE** (`bool`, *opcional*): Se deve criar um Experimento online ou offline.
- **COMET_PROJECT_NAME** (`str`, *opcional*): Nome do projeto Comet para experimentos.
- **COMET_LOG_ASSETS** (`str`, *opcional*, padrão `TRUE`): Se os ativos de treinamento (checkpoints, etc.) devem ser registrados no Comet. Pode ser `TRUE` ou `FALSE`.

Para uma lista de itens configuráveis no ambiente, consulte [aqui](https://www.comet.com/docs/v2/guides/experiment-management/configure-sdk/#explore-comet-configuration-options).

#### transformers.DefaultFlowCallback[[transformers.DefaultFlowCallback]]

```python
transformers.DefaultFlowCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L563)

Uma [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que gerencia o fluxo padrão do loop de treinamento para logs, avaliação e checkpoints.

#### transformers.PrinterCallback[[transformers.PrinterCallback]]

```python
transformers.PrinterCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L698)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) simples que apenas imprime os logs.

#### transformers.ProgressCallback[[transformers.ProgressCallback]]

```python
transformers.ProgressCallback(max_str_len: int = 100)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L624)

Uma [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que exibe o progresso do treinamento ou da avaliação. Você pode modificar `max_str_len` para controlar o comprimento máximo das strings ao registrar logs.

#### transformers.EarlyStoppingCallback[[transformers.EarlyStoppingCallback]]

```python
transformers.EarlyStoppingCallback(early_stopping_patience: int = 1, early_stopping_threshold: float | None = 0.0)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L711)

**Parâmetros:**

early_stopping_patience (`int`) : Use com `metric_for_best_model` para interromper o treinamento quando a métrica especifica piorar por `early_stopping_patience` chamadas de avaliação.

early_stopping_threshold(`float`, *opcional*) : Use com TrainingArguments `metric_for_best_model` e `early_stopping_patience` para indicar em quanto a métrica especificada deve melhorar para satisfazer as condições de parada antecipada. `

Uma [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que trata do encerramento antecipado.

Este callback depende da funcionalidade do argumento *load_best_model_at_end* de [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) para definir best_metric em [TrainerState](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerState). Observe que, se o argumento *save_steps* de [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) for diferente de *eval_steps*, o early stopping não ocorrerá até o próximo passo de salvamento.

#### transformers.integrations.TensorBoardCallback[[transformers.integrations.TensorBoardCallback]]

```python
transformers.integrations.TensorBoardCallback(tb_writer = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L577)

**Parâmetros:**

tb_writer (`SummaryWriter`, *opcional*) : O writer a ser utilizado. Será instanciado um caso não esteja definido.

Uma [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que envia os logs para o [TensorBoard](https://www.tensorflow.org/tensorboard).

Ambiente:
- **TENSORBOARD_LOGGING_DIR** (`str`, *opcional*, padrão `None`): O diretório de log para registrar os resultados. O valor padrão é os.path.join(args.output_dir, default_logdir())

#### transformers.integrations.TrackioCallback[[transformers.integrations.TrackioCallback]]

```python
transformers.integrations.TrackioCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L935)

Uma [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que registra métricas no Trackio.

#### setup[[transformers.integrations.TrackioCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L969)

Configure a integração opcional com o Trackio.

Para personalizar a configuração, você também pode definir `project`, `trackio_space_id`, `trackio_bucket_id`, `trackio_static_space_id` e `hub_private_repo` em [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments).

#### transformers.integrations.WandbCallback[[transformers.integrations.WandbCallback]]

```python
transformers.integrations.WandbCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L695)

Uma [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que registra métricas, mídia e checkpoints do modelo no [Weight and Biases](https://www.wandb.com/).

#### setup[[transformers.integrations.WandbCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L711)

Configure a integração opcional com Weights & Biases (*wandb*).

É possível criar uma subclasse e sobrescrever este método para personalizar a configuração, se necessário. Encontre mais informações [aqui](https://docs.wandb.ai/guides/integrations/huggingface). Você também pode sobrescrever as seguintes variáveis de ambiente:

Ambiente:
- **WANDB_LOG_MODEL** (`str`, *opcional*, padrão `"false"`): se deve registrar o modelo e os checkpoints durante o treinamento. Pode ser `"end"`, `"checkpoint"` ou `"false"`. Se definido como `"end"`, o modelo será enviado ao final do treinamento. Se definido como `"checkpoint"`, o checkpoint será enviado a cada `args.save_steps` . Se definido como `"false"`, o modelo não será enviado. Use junto com `load_best_model_at_end()` para enviar o melhor modelo.
- **WANDB_WATCH** (`str`, *opcional*, padrão `"false"`): pode ser `"gradients"`, `"all"`, `"parameters"` ou `"false"`. Defina como `"all"` para registrar gradientes e parâmetros.
- **WANDB_PROJECT** (`str`, *opcional*, padrão `"huggingface"`): Defina este valor como uma string personalizada para armazenar os resultados em um projeto diferente.

#### transformers.integrations.MLflowCallback[[transformers.integrations.MLflowCallback]]

```python
transformers.integrations.MLflowCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1286)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que envia os logs para o [MLflow](https://www.mlflow.org/). Pode ser desativado definindo a variável de ambiente `DISABLE_MLFLOW_INTEGRATION = TRUE`.

#### setup[[transformers.integrations.MLflowCallback.setup]]

```python
setup(args, state, model)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1305)

Configure a integração opcional com o MLflow.

Ambiente:
- **HF_MLFLOW_LOG_ARTIFACTS** (`str`, *opcional*): Se deve usar a funcionalidade `.log_artifact()` do MLflow para registrar artefatos. Isso só faz sentido se o registro for feito em um servidor remoto, por exemplo, s3 ou GCS. Se definido como `True` ou *1*, cada checkpoint salvo em cada gravação no `output_dir` do [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) será copiado para o armazenamento de artefatos local ou remoto. Usá-lo sem um armazenamento remoto apenas copiará os arquivos para a localização dos seus artefatos.
- **MLFLOW_TRACKING_URI** (`str`, *opcional*): Se deseja armazenar as execuções em um caminho específico ou em um servidor remoto. Não definido por padrão, o que ignora completamente a configuração da URI de rastreamento.
- **MLFLOW_EXPERIMENT_NAME** (`str`, *opcional*, padrão `None`): Indica se deve ser usado um experiment_name do MLflow sob o qual iniciar a execução. O padrão é `None`, o que aponta para o experimento `Default` no MLflow. Caso contrário, é um nome sensível a maiúsculas e minúsculas do experimento a ser ativado. Se um experimento com esse nome não existir, um novo experimento com esse nome será criado.
- **MLFLOW_TAGS** (`str`, *opcional*): Uma string com o despejo de um dicionário de pares chave/valor a ser adicionada à execução do MLflow como tags. Exemplo: `os.environ['MLFLOW_TAGS']='{"release.candidate": "RC1", "release.version": "2.2.0"}'`.
- **MLFLOW_NESTED_RUN** (`str`, *opcional*): Se deve usar execuções aninhadas do MLflow. Se definido como `True` ou *1*, será criada uma execução aninhada dentro da execução atual.
- **MLFLOW_RUN_ID** (`str`, *opcional*): Permite reanexar a uma execução existente, o que pode ser útil ao retomar o treinamento a partir de um checkpoint. Quando a variável de ambiente `MLFLOW_RUN_ID` está definida, `start_run` tenta retomar uma execução com o ID de execução especificado e os outros parâmetros são ignorados.
- **MLFLOW_FLATTEN_PARAMS** (`str`, *opcional*, padrão `False`): Se deve achatar o dicionário de parâmetros antes de registrar.
- **MLFLOW_MAX_LOG_PARAMS** (`int`, *opcional*): Define o número máximo de parâmetros a serem registrados na execução.

#### transformers.integrations.AzureMLCallback[[transformers.integrations.AzureMLCallback]]

```python
transformers.integrations.AzureMLCallback(azureml_run = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1263)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que envia os logs para o [AzureML](https://pypi.org/project/azureml-sdk/).

#### transformers.integrations.CodeCarbonCallback[[transformers.integrations.CodeCarbonCallback]]

```python
transformers.integrations.CodeCarbonCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1809)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que rastreia a emissão de CO2 do treinamento.

#### transformers.integrations.ClearMLCallback[[transformers.integrations.ClearMLCallback]]

```python
transformers.integrations.ClearMLCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1843)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que envia os logs para o [ClearML](https://clear.ml/).

Ambiente:
- **CLEARML_PROJECT** (`str`, *opcional*, padrão `HuggingFace Transformers`): nome do projeto ClearML.
- **CLEARML_TASK** (`str`, *opcional*, padrão `Trainer`): Nome da tarefa do ClearML.
- **CLEARML_LOG_MODEL** (`bool`, *opcional*, padrão `False`): Se os modelos devem ser registrados como artefatos durante o treinamento.

#### transformers.integrations.DagsHubCallback[[transformers.integrations.DagsHubCallback]]

```python
transformers.integrations.DagsHubCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1467)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que registra logs no [DagsHub](https://dagshub.com/). Estende `MLflowCallback`

#### setup[[transformers.integrations.DagsHubCallback.setup]]

```python
setup(*args, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1481)

Configure a integração de Logging do DagsHub.

Ambiente:
- **HF_DAGSHUB_LOG_ARTIFACTS** (`str`, *opcional*): Se os artefatos de dados e modelos do experimento devem ser salvos. O valor padrão é `False`.

#### transformers.integrations.FlyteCallback[[transformers.integrations.FlyteCallback]]

```python
transformers.integrations.FlyteCallback(save_log_history: bool = True, sync_checkpoints: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2094)

**Parâmetros:**

save_log_history (`bool`, *opcional*, padrão `True`) : Quando definido como True, os logs de treinamento são salvos como um Flyte Deck.

sync_checkpoints (`bool`, *opcional*, padrão `True`) : Quando definido como True, os checkpoints são sincronizados com o Flyte e podem ser usados para retomar o treinamento em caso de interrupção.

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que envia os logs para o [Flyte](https://flyte.org/). OBSERVAÇÃO: este callback só funciona dentro de uma tarefa do Flyte.

Exemplo:

```python
# Note: This example skips over some setup steps for brevity.
from flytekit import current_context, task

@task
def train_hf_transformer():
    cp = current_context().checkpoint
    trainer = Trainer(..., callbacks=[FlyteCallback()])
    output = trainer.train(resume_from_checkpoint=cp.restore())
```

#### transformers.integrations.KubeflowCallback[[transformers.integrations.KubeflowCallback]]

```python
transformers.integrations.KubeflowCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2436)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que relata o progresso do treinamento para o [Kubeflow Trainer](https://github.com/kubeflow/trainer).

Este callback é registrado automaticamente durante o treinamento dentro de um Kubeflow TrainJob com o feature gate `TrainJobRuntimeStatus` habilitado. O controlador do Kubeflow injeta as variáveis de ambiente necessárias no pod de treinamento.

**Variáveis de ambiente (injetadas pelo controlador):**

- `KUBEFLOW_TRAINER_SERVER_URL`: endpoint HTTPS para atualizações de status
- `KUBEFLOW_TRAINER_SERVER_CA_CERT`: Caminho para o certificado CA para verificação TLS
- `KUBEFLOW_TRAINER_SERVER_TOKEN`: Caminho para o token da conta de serviço para autenticação

**Informações reportadas:**

- Porcentagem de progresso (0-100%)
- Tempo restante estimado (segundos)
- Métricas de treinamento (loss, learning_rate, etc.)

**Recursos:**

- Limitação automática (máximo de 1 atualização a cada 5 segundos) para evitar sobrecarregar o controlador
- Cache de tokens (5 minutos) para minimizar a E/S de arquivos
- Apenas o rank 0 relata o progresso no treinamento distribuído
- Falhas silenciosas - problemas de rede não interromperão o treinamento

Pode ser desativado definindo a variável de ambiente `DISABLE_KUBEFLOW_INTEGRATION=TRUE`.

#### transformers.integrations.DVCLiveCallback[[transformers.integrations.DVCLiveCallback]]

```python
transformers.integrations.DVCLiveCallback(live: typing.Any | None = None, log_model: typing.Union[typing.Literal['all'], bool, NoneType] = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2157)

**Parâmetros:**

live (`dvclive.Live`, *opcional*, padrão `None`) : Instância Live opcional. Se for None, uma nova instância será criada usando **kwargs.

log_model (Union[Literal["all"], bool], *opcional*, padrão `None`) : Se deve usar `dvclive.Live.log_artifact()` para registrar checkpoints criados pelo [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer). Se definido como `True`, o checkpoint final é registrado ao final do treinamento. Se definido como `"all"`, o `output_dir` inteiro do [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) é registrado a cada checkpoint.

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que envia os logs para o [DVCLive](https://www.dvc.org/doc/dvclive).

Use as variáveis de ambiente abaixo em `setup` para configurar a integração. Para personalizar esse callback além das variáveis de ambiente, veja [aqui](https://dvc.org/doc/dvclive/ml-frameworks/huggingface).

#### setup[[transformers.integrations.DVCLiveCallback.setup]]

```python
setup(args, state, model)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2198)

Configure a integração opcional com o DVCLive. Para personalizar esse callback além das variáveis de ambiente abaixo, consulte [aqui](https://dvc.org/doc/dvclive/ml-frameworks/huggingface).

Ambiente:
- **HF_DVCLIVE_LOG_MODEL** (`str`, *opcional*): se deve usar `dvclive.Live.log_artifact()` para registrar os checkpoints criados pelo [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer). Se definido como `True` ou *1*, o checkpoint final é registrado ao final do treinamento. Se definido como `all`, todo o `output_dir` do [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) é registrado a cada checkpoint.

#### transformers.integrations.SwanLabCallback[[transformers.integrations.SwanLabCallback]]

```python
transformers.integrations.SwanLabCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2262)

Um [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) que registra métricas, mídia e checkpoints do modelo no [SwanLab](https://swanlab.cn/).

#### setup[[transformers.integrations.SwanLabCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2276)

Configure a integração opcional com o SwanLab (*swanlab*).

É possível criar uma subclasse e sobrescrever este método para personalizar a configuração, se necessário. Encontre mais informações [aqui](https://docs.swanlab.cn/guide_cloud/integration/integration-huggingface-transformers.html).

Você também pode sobrescrever as seguintes variáveis de ambiente. Encontre mais informações sobre variáveis de ambiente [aqui](https://docs.swanlab.cn/en/api/environment-variable.html#environment-variables)

Ambiente:
- **SWANLAB_API_KEY** (`str`, *opcional*, padrão `None`): Chave de API da nuvem. Durante o login, esta variável de ambiente é verificada primeiro. Se ela não existir, o sistema verifica se o usuário já está conectado. Caso contrário, o processo de login é iniciado.

  - Se uma string for passada para a interface de login, essa variável de ambiente será ignorada.
  - Se o usuário já estiver conectado, esta variável de ambiente tem precedência sobre as informações de login armazenadas localmente.

- **SWANLAB_PROJECT** (`str`, *opcional*, padrão `None`): Defina este parâmetro como uma string personalizada para armazenar os resultados em um projeto diferente. Se não for especificado, será utilizado o nome do diretório de trabalho atual.

- **SWANLAB_LOG_DIR** (`str`, *opcional*, padrão `swanlog`): Esta variável de ambiente especifica o caminho de armazenamento para os arquivos de log ao executar no modo local. Por padrão, os logs são salvos em uma pasta chamada swanlog no diretório de trabalho.

- **SWANLAB_MODE** (`Literal["local", "cloud", "disabled"]`, *opcional*, padrão `cloud`): modo de parsing do SwanLab, que envolve callbacks registrados pelo operador. Atualmente, existem três modos: local, cloud e disabled. Observação: sensível a maiúsculas e minúsculas. Encontre mais informações [aqui](https://docs.swanlab.cn/en/api/py-init.html#swanlab-init)

- **SWANLAB_LOG_MODEL** (`str`, *opcional*, padrão `None`): o SwanLab ainda não suporta a funcionalidade de modo de salvamento. Essa funcionalidade estará disponível em uma versão futura

- **SWANLAB_WEB_HOST** (`str`, *opcional*, padrão `None`): Endereço web para o ambiente em nuvem do SwanLab na versão privada (que é gratuita)

- **SWANLAB_API_HOST** (`str`, *opcional*, padrão `None`): endereço da API para o ambiente em nuvem do SwanLab na versão privada (que é gratuita)

- **SWANLAB_RUN_ID** (`str`, *opcional*, padrão `None`): ID do experimento para retomar uma execução anterior. Use junto com `SWANLAB_RESUME` para continuar um experimento existente.

- **SWANLAB_RESUME** (`str`, *opcional*, padrão `None`): Modo de retomada (`"must"`, `"allow"`, `"never"`). O padrão é `"allow"` quando `resume_from_checkpoint` é usado.

## TrainerCallback[[transformers.TrainerCallback]]

#### transformers.TrainerCallback[[transformers.TrainerCallback]]

```python
transformers.TrainerCallback()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L295)

**Parâmetros:**

args ([TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments)) : Os argumentos de treinamento usados para instanciar o [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer).

state ([TrainerState](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerState)) : O estado atual do [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer).

control ([TrainerControl](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerControl)) : O objeto que é retornado para o [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer) e pode ser usado para tomar algumas decisões.

model ([PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel) ou `torch.nn.Module`) : O modelo que está sendo treinado.

processing_class ([`PreTrainedTokenizer` ou `BaseImageProcessor` ou `ProcessorMixin` ou `FeatureExtractionMixin`]) : A classe de processamento usada para codificar os dados. Pode ser um tokenizer, um processor, um image processor ou um feature extractor.

optimizer (`torch.optim.Optimizer`) : O otimizador usado para as etapas de treinamento.

lr_scheduler (`torch.optim.lr_scheduler.LambdaLR`) : O scheduler usado para definir a taxa de aprendizado.

train_dataloader (`torch.utils.data.DataLoader`, *opcional*) : O dataloader atual usado para o treinamento.

eval_dataloader (`torch.utils.data.DataLoader`, *opcional*) : O dataloader atual usado para avaliação.

metrics (`dict[str, float]`) : As métricas calculadas pela última fase de avaliação. Elas só estão acessíveis no evento `on_evaluate`.

logs  (`dict[str, float]`) : Os valores a serem registrados.  Esses valores só estão acessíveis no evento `on_log`.

Uma classe para objetos que inspecionam o estado do loop de treinamento em determinados eventos e tomam algumas decisões. Em cada um desses eventos, os seguintes argumentos estão disponíveis:

O objeto `control` é o único que pode ser alterado pelo callback, caso em que o evento que o modifica deve retornar a versão modificada.

Os argumentos `args`, `state` e `control` são posicionais para todos os eventos; todos os outros estão agrupados em `kwargs`. Você pode desempacotar os que precisa na assinatura do evento usando-os. Como exemplo, veja o código do simples [PrinterCallback](/docs/transformers/main/pt/main_classes/callback#transformers.PrinterCallback).

Exemplo:

```python
class PrinterCallback(TrainerCallback):
    def on_log(self, args, state, control, logs=None, **kwargs):
        _ = logs.pop("total_flos", None)
        if state.is_local_process_zero:
            print(logs)
```

#### on_epoch_begin[[transformers.TrainerCallback.on_epoch_begin]]

```python
on_epoch_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L361)

Evento chamado no início de uma época.

#### on_epoch_end[[transformers.TrainerCallback.on_epoch_end]]

```python
on_epoch_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L366)

Evento chamado no final de uma época.

#### on_evaluate[[transformers.TrainerCallback.on_evaluate]]

```python
on_evaluate(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L398)

Evento chamado após uma fase de avaliação.

#### on_init_end[[transformers.TrainerCallback.on_init_end]]

```python
on_init_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L346)

Evento chamado no final da inicialização do [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer).

#### on_log[[transformers.TrainerCallback.on_log]]

```python
on_log(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L413)

Evento chamado após o registro dos últimos logs.

#### on_optimizer_step[[transformers.TrainerCallback.on_optimizer_step]]

```python
on_optimizer_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L382)

Evento chamado após o passo do otimizador, mas antes que os gradientes sejam zerados. Útil para monitorar gradientes.

#### on_pre_optimizer_step[[transformers.TrainerCallback.on_pre_optimizer_step]]

```python
on_pre_optimizer_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L377)

Evento chamado antes da etapa do otimizador, mas após o recorte de gradientes. Útil para monitorar gradientes.

#### on_predict[[transformers.TrainerCallback.on_predict]]

```python
on_predict(args: TrainingArguments, state: TrainerState, control: TrainerControl, metrics, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L403)

Evento chamado após uma previsão bem-sucedida.

#### on_prediction_step[[transformers.TrainerCallback.on_prediction_step]]

```python
on_prediction_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L418)

Evento chamado após uma etapa de previsão.

#### on_push_begin[[transformers.TrainerCallback.on_push_begin]]

```python
on_push_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L423)

Evento chamado antes de enviar o modelo para o hub, no início de Trainer.push_to_hub e Trainer._push_from_checkpoint.

#### on_save[[transformers.TrainerCallback.on_save]]

```python
on_save(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L408)

Evento chamado após o salvamento de um checkpoint.

#### on_step_begin[[transformers.TrainerCallback.on_step_begin]]

```python
on_step_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L371)

Evento chamado no início de uma etapa de treinamento. Se estiver usando acúmulo de gradiente, uma etapa de treinamento pode envolver várias entradas.

#### on_step_end[[transformers.TrainerCallback.on_step_end]]

```python
on_step_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L392)

Evento chamado no final de uma etapa de treinamento. Se estiver usando acúmulo de gradiente, uma etapa de treinamento pode envolver várias entradas.

#### on_substep_end[[transformers.TrainerCallback.on_substep_end]]

```python
on_substep_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L387)

Evento chamado no final de um subpasso durante a acumulação de gradientes.

#### on_train_begin[[transformers.TrainerCallback.on_train_begin]]

```python
on_train_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L351)

Evento chamado no início do treinamento.

#### on_train_end[[transformers.TrainerCallback.on_train_end]]

```python
on_train_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L356)

Evento chamado ao final do treinamento.

Aqui está um exemplo de como registrar um callback personalizado com o [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer) do PyTorch:

```python
class MyCallback(TrainerCallback):
    "A callback that prints a message at the beginning of training"

    def on_train_begin(self, args, state, control, **kwargs):
        print("Starting training")

trainer = Trainer(
    model,
    args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    callbacks=[MyCallback],  # We can either pass the callback class this way or an instance of it (MyCallback())
)
```

Outra forma de registrar um callback é chamar `trainer.add_callback()` da seguinte maneira:

```python
trainer = Trainer(...)
trainer.add_callback(MyCallback)
# Alternatively, we can pass an instance of the callback class
trainer.add_callback(MyCallback())
```

## TrainerState[[transformers.TrainerState]]

#### transformers.TrainerState[[transformers.TrainerState]]

```python
transformers.TrainerState(epoch: float = 0, global_step: int = 0, max_steps: int = 0, logging_steps: int = 500, eval_steps: int = 500, save_steps: int = 500, train_batch_size: int | None = None, num_train_epochs: int = 0, num_input_tokens_seen: int = 0, total_flos: float = 0, log_history: list = None, best_metric: float | None = None, best_global_step: int | None = None, best_model_checkpoint: str | None = None, is_local_process_zero: bool = True, is_world_process_zero: bool = True, is_hyper_param_search: bool = False, trial_name: str | None = None, trial_params: dict[str, str | float | int | bool] | None = None, stateful_callbacks: list['TrainerCallback'] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L35)

**Parâmetros:**

epoch (`float`, *opcional*) : Definido apenas durante o treinamento, representa a época em que o treinamento está (a parte decimal sendo a porcentagem da época atual concluída).

global_step (`int`, *opcional*, padrão 0) : Durante o treinamento, representa o número de etapas de atualização concluídas.

max_steps (`int`, *opcional*, padrão 0) : O número de etapas de atualização a serem realizadas durante o treinamento atual.

logging_steps (`int`, *opcional*, padrão 500) : Registra a cada X etapas de atualização

eval_steps (`int`, *opcional*) : Executa uma avaliação a cada X etapas.

save_steps (`int`, *opcional*, padrão 500) : Salva um checkpoint a cada X etapas de atualização.

train_batch_size (`int`, *opcional*) : O tamanho do lote para o dataloader de treinamento. Necessário apenas quando `auto_find_batch_size` foi usado.

num_input_tokens_seen (`int`, *opcional*, padrão 0) : Ao rastrear os tokens de entrada, o número de tokens vistos durante o treinamento (número de tokens de entrada, não o número de tokens de previsão).

total_flos (`float`, *opcional*, padrão 0) : O número total de operações de ponto flutuante realizadas pelo modelo desde o início do treinamento (armazenado como floats para evitar estouro de capacidade).

log_history (`list[dict[str, float]]`, *opcional*) : A lista de registros feitos desde o início do treinamento.

best_metric (`float`, *opcional*) : Ao rastrear o melhor modelo, o valor da melhor métrica encontrada até o momento.

best_global_step (`int`, *opcional*) : Ao rastrear o melhor modelo, a etapa em que a melhor métrica foi encontrada. Usado para definir `best_model_checkpoint`.

best_model_checkpoint (`str`, *opcional*) : Ao rastrear o melhor modelo, o valor do nome do checkpoint do melhor modelo encontrado até o momento.

is_local_process_zero (`bool`, *opcional*, padrão `True`) : Indica se este processo é o processo principal local (por exemplo, em uma única máquina, caso o treinamento seja distribuído entre várias máquinas).

is_world_process_zero (`bool`, *opcional*, padrão `True`) : Indica se este processo é o processo principal global (quando o treinamento é distribuído em várias máquinas, isso será `True` apenas para um processo).

is_hyper_param_search (`bool`, *opcional*, padrão `False`) : Indica se estamos em um processo de busca de hiperparâmetros usando Trainer.hyperparameter_search. Isso afetará a forma como os dados serão registrados no TensorBoard.

stateful_callbacks (`list[StatefulTrainerCallback]`, *opcional*) : Callbacks anexados ao `Trainer` que devem ter seus estados salvos ou restaurados. Os callbacks relevantes devem implementar uma função `state` e uma função `from_state`.

Uma classe que contém o estado interno do [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer), que será salvo junto com o modelo e o otimizador durante o checkpointing e passado para o [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback).

Em toda esta classe, um passo deve ser entendido como um passo de atualização. Ao usar acúmulo de gradiente, um passo de atualização pode exigir várias passadas de frente e de trás: se você usar `gradient_accumulation_steps=n`, então um passo de atualização exige percorrer *n* lotes.

#### compute_steps[[transformers.TrainerState.compute_steps]]

```python
compute_steps(args, max_steps)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L156)

Calcula e armazena o valor absoluto para as etapas de registro, avaliação e salvamento, com base em se ele era uma proporção ou não.

#### init_training_references[[transformers.TrainerState.init_training_references]]

```python
init_training_references(trainer, max_steps, num_train_epochs, trial)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L169)

Armazena as referências iniciais de treinamento necessárias em `self`

#### load_from_json[[transformers.TrainerState.load_from_json]]

```python
load_from_json(json_path: str)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L149)

Crie uma instância a partir do conteúdo de `json_path`.

#### save_to_json[[transformers.TrainerState.save_to_json]]

```python
save_to_json(json_path: str)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L143)

Salve o conteúdo desta instância em formato JSON dentro de `json_path`.

## TrainerControl[[transformers.TrainerControl]]

#### transformers.TrainerControl[[transformers.TrainerControl]]

```python
transformers.TrainerControl(should_training_stop: bool = False, should_epoch_stop: bool = False, should_save: bool = False, should_evaluate: bool = False, should_log: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L234)

**Parâmetros:**

should_training_stop (`bool`, *opcional*, padrão `False`) : Indica se o treinamento deve ser interrompido. Se `True`, esta variável não será redefinida para `False`. O treinamento simplesmente será interrompido.

should_epoch_stop (`bool`, *opcional*, padrão `False`) : Indica se a epoch atual deve ser interrompida. Se `True`, esta variável será redefinida para `False` no início da próxima epoch.

should_save (`bool`, *opcional*, padrão `False`) : Indica se o modelo deve ser salvo nesta etapa. Se `True`, esta variável será redefinida para `False` no início da próxima etapa.

should_evaluate (`bool`, *opcional*, padrão `False`) : Indica se o modelo deve ser avaliado nesta etapa. Se `True`, esta variável será redefinida para `False` no início da próxima etapa.

should_log (`bool`, *opcional*, padrão `False`) : Indica se os logs devem ser reportados nesta etapa. Se `True`, esta variável será redefinida para `False` no início da próxima etapa.

Uma classe que gerencia o fluxo de controle do [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer). Esta classe é usada pelo [TrainerCallback](/docs/transformers/main/pt/main_classes/callback#transformers.TrainerCallback) para ativar alguns interruptores no loop de treinamento.