# 回调

回调（Callbacks）是用于自定义 PyTorch [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 中训练循环行为的对象。它们可以检查训练循环的状态（例如用于进度报告、在 TensorBoard 或其他 ML 平台上记录日志……），并据此做出决策（例如提前停止训练）。

回调是“只读”的代码片段，除了它们返回的 [TrainerControl](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerControl) 对象外，它们无法更改训练循环中的任何内容。对于需要修改训练循环的自定义需求，您应该对 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 进行子类化并覆盖所需的方法（示例请参见 [trainer](trainer)）。

默认情况下，`TrainingArguments.report_to` 被设置为 `"none"`。

实现回调的主要类是 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。它会获取用于实例化 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 的 [TrainingArguments](/docs/transformers/main/zh/main_classes/trainer#transformers.TrainingArguments)，可以通过 [TrainerState](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerState) 访问该 Trainer 的内部状态，并可以通过 [TrainerControl](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerControl) 对训练循环执行某些操作。

## 可用回调[[transformers.integrations.CometCallback]]

以下是库中可用的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback) 列表：

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

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

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

一个将日志发送到 [Comet ML](https://www.comet.com/site/) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

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

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

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

设置可选的 Comet 集成。

环境：
- **COMET_MODE**（`str`，*可选*，默认为 `get_or_create`）：控制是创建并记录到新的 Comet 实验，还是追加到现有实验。它接受以下值：
  * `get_or_create`：根据 `COMET_EXPERIMENT_KEY` 是否已设置，以及是否已存在具有该 key 的 Experiment，自动决定行为。
  * `create`：始终创建一个新的 Comet Experiment。
  * `get`：始终尝试追加到现有的 Comet 实验。需要设置 `COMET_EXPERIMENT_KEY`。
- **COMET_START_ONLINE**（`bool`，*可选*）：是否创建在线或离线 Experiment。
- **COMET_PROJECT_NAME**（`str`，*可选*）：用于实验的 Comet 项目名称。
- **COMET_LOG_ASSETS**（`str`，*可选*，默认为 `TRUE`）：是否将训练资产（检查点等）记录到 Comet。可以设置为 `TRUE` 或 `FALSE`。

有关环境中可配置项的详细信息，请参阅[此处](https://www.comet.com/docs/v2/guides/experiment-management/configure-sdk/#explore-comet-configuration-options)。

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

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

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

一个用于处理训练循环中日志、评估和检查点默认流程的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

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

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

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

一个仅用于打印日志的裸 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

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

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

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

一个用于显示训练或评估进度的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。您可以修改 `max_str_len` 以控制在记录日志时字符串被截断的长度。

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

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

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

**参数：**

early_stopping_patience (`int`) : 与 `metric_for_best_model` 配合使用，当指定指标在连续 `early_stopping_patience` 次评估调用中变差时停止训练。

early_stopping_threshold(`float`, *可选*) : 与 TrainingArguments 中的 `metric_for_best_model` 和 `early_stopping_patience` 配合使用，用于指定指标需要改善多少才能满足早停条件。

用于处理早停的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

此回调依赖于 [TrainingArguments](/docs/transformers/main/zh/main_classes/trainer#transformers.TrainingArguments) 参数 *load_best_model_at_end* 的功能，以在 [TrainerState](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerState) 中设置 best_metric。请注意，如果 [TrainingArguments](/docs/transformers/main/zh/main_classes/trainer#transformers.TrainingArguments) 参数 *save_steps* 与 *eval_steps* 不同，则早停机制不会在下一个保存步骤之前触发。

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

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

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

**参数：**

tb_writer (`SummaryWriter`，*可选*)：要使用的写入器。如果未设置，将实例化一个。

一个将日志发送到 [TensorBoard](https://www.tensorflow.org/tensorboard) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

环境：
- **TENSORBOARD_LOGGING_DIR** (`str`，*可选*，默认为 `None`)：用于记录结果的日志目录。默认值为 os.path.join(args.output_dir, default_logdir())

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

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

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

一个用于将指标记录到 Trackio 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

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

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

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

设置可选的 Trackio 集成。

要自定义设置，您还可以在 [TrainingArguments](/docs/transformers/main/zh/main_classes/trainer#transformers.TrainingArguments) 中设置 `project`、`trackio_space_id`、`trackio_bucket_id`、`trackio_static_space_id` 和 `hub_private_repo`。

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

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

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

一个用于将指标、媒体和模型检查点记录到 [Weight and Biases](https://www.wandb.com/) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

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

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

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

设置可选的 Weights & Biases（*wandb*）集成。

可以通过子类化并覆盖此方法来自定义设置（如需要）。更多信息请参见[此处](https://docs.wandb.ai/guides/integrations/huggingface)。您还可以覆盖以下环境变量：

环境：
- **WANDB_LOG_MODEL** (`str`，*可选*，默认为 `"false"`)：是否在训练期间记录模型和检查点。可取值为 `"end"`、`"checkpoint"` 或 `"false"`。如果设置为 `"end"`，将在训练结束时上传模型。如果设置为 `"checkpoint"`，则每 `args.save_steps` 步上传一次检查点。如果设置为 `"false"`，则不会上传模型。可与 `load_best_model_at_end()` 配合使用，以上传最佳模型。
- **WANDB_WATCH**（`str`，*可选*，默认为 `"false"`）：可取值为 `"gradients"`、`"all"`、`"parameters"` 或 `"false"`。设置为 `"all"` 以记录梯度和参数。
- **WANDB_PROJECT**（`str`，*可选*，默认为 `"huggingface"`）：将其设置为自定义字符串，可将结果存储到其他项目中。

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

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

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

一个用于将日志发送到 [MLflow](https://www.mlflow.org/) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。可以通过设置环境变量 `DISABLE_MLFLOW_INTEGRATION = TRUE` 来禁用。

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

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

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

设置可选的 MLflow 集成。

环境：
- **HF_MLFLOW_LOG_ARTIFACTS** (`str`, *可选*)：是否使用 MLflow 的 `.log_artifact()` 功能来记录工件。仅在向日志记录到远程服务器（例如 s3 或 GCS）时才有意义。如果设置为 `True` 或 *1*，则会将 [TrainingArguments](/docs/transformers/main/zh/main_classes/trainer#transformers.TrainingArguments) 的 `output_dir` 中每次保存的每个检查点复制到本地或远程工件存储中。在没有远程存储的情况下使用此功能，只会将文件复制到你的工件位置。
- **MLFLOW_TRACKING_URI**（`str`，*可选*）：是否将运行记录存储在特定路径或远程服务器上。默认未设置，即完全跳过设置跟踪 URI。
- **MLFLOW_EXPERIMENT_NAME** (`str`，*可选*，默认为 `None`)：是否使用 MLflow 的 experiment_name 来启动运行。默认为 `None`，将指向 MLflow 中的 `Default` 实验。否则，它是待激活实验的区分大小写的名称。如果不存在具有此名称的实验，则会创建一个具有该名称的新实验。
- **MLFLOW_TAGS**（`str`，*可选*）：一个键值对字典的字符串转储，将作为标签添加到 MLflow 运行中。示例：`os.environ['MLFLOW_TAGS']='{"release.candidate": "RC1", "release.version": "2.2.0"}'`。
- **MLFLOW_NESTED_RUN** (`str`, *可选*)：是否使用 MLflow 嵌套运行。如果设置为 `True` 或 *1*，将在当前运行内创建一个嵌套运行。
- **MLFLOW_RUN_ID**（`str`，*可选*）：允许重新附加到现有的 run，这在从检查点恢复训练时非常有用。当设置了 `MLFLOW_RUN_ID` 环境变量时，`start_run` 会尝试恢复具有指定 run ID 的 run，其他参数将被忽略。
- **MLFLOW_FLATTEN_PARAMS** (`str`，*可选*，默认为 `False`)：是否在记录之前展平参数字典。
- **MLFLOW_MAX_LOG_PARAMS**（`int`，*可选*）：设置要记录到运行中的最大参数数量。

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

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

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

一个将日志发送到 [AzureML](https://pypi.org/project/azureml-sdk/) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

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

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

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

一个用于跟踪训练过程中 CO2 排放量的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

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

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

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

一个将日志发送到 [ClearML](https://clear.ml/) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

环境：
- **CLEARML_PROJECT** (`str`，*可选*，默认为 `HuggingFace Transformers`)：ClearML 项目名称。
- **CLEARML_TASK** (`str`，*可选*，默认为 `Trainer`)：ClearML 任务名称。
- **CLEARML_LOG_MODEL**（`bool`，*可选*，默认为 `False`）：是否在训练过程中将模型作为工件进行记录。

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

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

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

一个用于向 [DagsHub](https://dagshub.com/) 记录日志的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。继承自 `MLflowCallback`

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

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

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

设置 DagsHub 的日志记录集成。

环境：
- **HF_DAGSHUB_LOG_ARTIFACTS**（`str`，*可选*）：是否保存实验的数据和模型工件。默认为 `False`。

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

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

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

**参数：**

save_log_history (`bool`，*可选*，默认为 `True`)：当设置为 True 时，训练日志将保存为 Flyte Deck。

sync_checkpoints (`bool`，*可选*，默认为 `True`)：当设置为 True 时，检查点会与 Flyte 同步，并可在训练中断时用于恢复训练。

一个将日志发送到 [Flyte](https://flyte.org/) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。注意：此回调仅在 Flyte 任务中有效。

示例：

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

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

一个用于向 [Kubeflow Trainer](https://github.com/kubeflow/trainer) 报告训练进度的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

当在启用了 `TrainJobRuntimeStatus` 功能门控的 Kubeflow TrainJob 中进行训练时，此回调会自动注册。Kubeflow 控制器会将所需的环境变量注入到训练 Pod 中。

**环境变量（由控制器注入）：**

- `KUBEFLOW_TRAINER_SERVER_URL`：用于状态更新的 HTTPS 端点
- `KUBEFLOW_TRAINER_SERVER_CA_CERT`：用于 TLS 验证的 CA 证书路径
- `KUBEFLOW_TRAINER_SERVER_TOKEN`：用于身份验证的服务账户令牌路径

**报告的信息：**

- 进度百分比（0-100%）
- 预计剩余时间（秒）
- 训练指标（loss、learning_rate 等）

**功能：**

- 自动限流（每 5 秒最多更新 1 次），以避免控制器过载
- Token 缓存（5 分钟）以最小化文件 I/O
- 在分布式训练中，仅 rank 0 报告进度
- 静默失败 - 网络问题不会中断训练

可通过设置环境变量 `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)
```

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

**参数：**

live (`dvclive.Live`，*可选*，默认为 `None`)：可选的 Live 实例。如果为 None，将使用 **kwargs 创建一个新的实例。

log_model (Union[Literal["all"], bool], *可选*，默认为 `None`) : 是否使用 `dvclive.Live.log_artifact()` 来记录由 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 创建的检查点。如果设置为 `True`，则在训练结束时记录最终检查点。如果设置为 `"all"`，则在每个检查点处记录整个 [TrainingArguments](/docs/transformers/main/zh/main_classes/trainer#transformers.TrainingArguments) 的 `output_dir`。

一个将日志发送到 [DVCLive](https://www.dvc.org/doc/dvclive) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

在 `setup` 中使用以下环境变量来配置集成。若要在此类环境变量之外进一步自定义此回调，请参阅 [此处](https://dvc.org/doc/dvclive/ml-frameworks/huggingface)。

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

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

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

设置可选的 DVCLive 集成。若要自定义此回调（超出以下环境变量），请参阅 [此处](https://dvc.org/doc/dvclive/ml-frameworks/huggingface)。

环境：
- **HF_DVCLIVE_LOG_MODEL** (`str`, *可选*)：是否使用 `dvclive.Live.log_artifact()` 来记录由 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 创建的检查点。如果设置为 `True` 或 *1*，则会在训练结束时记录最终检查点。如果设置为 `all`，则会在每个检查点处记录整个 [TrainingArguments](/docs/transformers/main/zh/main_classes/trainer#transformers.TrainingArguments) 的 `output_dir`。

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

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

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

一个用于将指标、媒体和模型检查点记录到 [SwanLab](https://swanlab.cn/) 的 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

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

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

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

配置可选的 SwanLab (*swanlab*) 集成。

可以通过子类化并覆盖此方法来自定义设置（如需要）。更多信息请参见[此处](https://docs.swanlab.cn/guide_cloud/integration/integration-huggingface-transformers.html)。

您还可以覆盖以下环境变量。有关环境变量的更多信息，请参见[此处](https://docs.swanlab.cn/en/api/environment-variable.html#environment-variables)

环境：
- **SWANLAB_API_KEY**（`str`，*可选*，默认为 `None`）：云端 API Key。登录时，系统会首先检查此环境变量。如果该变量不存在，系统会检查用户是否已登录。如果未登录，则启动登录流程。

  - 如果向登录接口传递了字符串，则此环境变量将被忽略。
  - 如果用户已登录，此环境变量将优先于本地存储的登录信息。

- **SWANLAB_PROJECT**（`str`，*可选*，默认为 `None`）：将其设置为自定义字符串，可将结果存储到不同的项目中。如果未指定，则使用当前运行目录的名称。

- **SWANLAB_LOG_DIR**（`str`，*可选*，默认为 `swanlog`）：此环境变量用于指定在本地模式下运行时日志文件的存储路径。默认情况下，日志会保存在工作目录下名为 swanlog 的文件夹中。

- **SWANLAB_MODE**（`Literal["local", "cloud", "disabled"]`，*可选*，默认为 `cloud`）：SwanLab 的解析模式，涉及由操作员注册的回调。目前共有三种模式：local、cloud 和 disabled。注意：区分大小写。更多信息请参见[此处](https://docs.swanlab.cn/en/api/py-init.html#swanlab-init)

- **SWANLAB_LOG_MODEL** (`str`，*可选*，默认为 `None`)：SwanLab 目前不支持保存模式功能。此功能将在未来的版本中提供

- **SWANLAB_WEB_HOST** (`str`，*可选*，默认为 `None`)：私有版 SwanLab 云环境的 Web 地址（免费）

- **SWANLAB_API_HOST**（`str`，*可选*，默认为 `None`）：私有版 SwanLab 云环境的 API 地址（免费）

- **SWANLAB_RUN_ID**（`str`，*可选*，默认为 `None`）：用于恢复先前运行的实验 ID。与 `SWANLAB_RESUME` 配合使用，以继续现有的实验。

- **SWANLAB_RESUME**（`str`，*可选*，默认为 `None`）：恢复模式（`"must"`、`"allow"`、`"never"`）。当使用 `resume_from_checkpoint` 时，默认为 `"allow"`。

## TrainerCallback[[transformers.TrainerCallback]]

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

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

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

**参数：**

args ([TrainingArguments](/docs/transformers/main/zh/main_classes/trainer#transformers.TrainingArguments))：用于实例化 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 的训练参数。

state ([TrainerState](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerState))：[Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 的当前状态。

control ([TrainerControl](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerControl))：返回给 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 的对象，可用于做出某些决策。

model （[PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel) 或 `torch.nn.Module`）：正在训练的模型。

processing_class ([`PreTrainedTokenizer` 或 `BaseImageProcessor` 或 `ProcessorMixin` 或 `FeatureExtractionMixin`])：用于对数据进行编码的处理类。可以是分词器、处理器、图像处理器或特征提取器。

optimizer (`torch.optim.Optimizer`)：用于训练步骤的优化器。

lr_scheduler (`torch.optim.lr_scheduler.LambdaLR`)：用于设置学习率的调度器。

train_dataloader (`torch.utils.data.DataLoader`，*可选*)：当前用于训练的 dataloader。

eval_dataloader (`torch.utils.data.DataLoader`，*可选*)：当前用于评估的数据加载器。

metrics (`dict[str, float]`) : 由最后一次评估阶段计算得出的指标。 这些指标仅在事件 `on_evaluate` 中可访问。

logs  (`dict[str, float]`) : 要记录的值。 这些值仅在事件 `on_log` 中可访问。

用于在训练循环的某些事件处检查状态并做出决策的对象的类。在每个此类事件中，以下参数可用：

`control` 对象是唯一可以被回调修改的对象，在这种情况下，修改它的回调应返回修改后的版本。

参数 `args`、`state` 和 `control` 是所有事件的按位置传递的参数，其余参数都包含在 `kwargs` 中。你可以在事件的签名中解包所需的参数。示例请参见简单的 [PrinterCallback](/docs/transformers/main/zh/main_classes/callback#transformers.PrinterCallback) 代码。

示例：

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

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

在 epoch 开始时调用的事件。

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

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

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

在 epoch 结束时调用的事件。

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

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

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

在评估阶段之后调用的事件。

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

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

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

在 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 初始化结束时调用的事件。

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

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

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

在记录完最后一条日志后触发的事件。

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

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

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

在优化器步骤之后、梯度清零之前调用的事件。适用于监控梯度。

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

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

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

在梯度裁剪之后、优化器步骤之前调用的事件。适用于监控梯度。

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

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

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

成功预测后调用的事件。

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

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

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

在预测步骤之后调用的事件。

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

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

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

Event called before pushing the model to the hub, at the beginning of Trainer.push_to_hub and Trainer._push_from_checkpoint.

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

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

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

在检查点保存后调用的事件。

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

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

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

在训练步骤开始时调用的事件。如果使用梯度累积，一个训练步骤可能需要处理多个输入。

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

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

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

在训练步骤结束时调用的事件。如果使用梯度累积，一个训练步骤可能需要处理多个输入。

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

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

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

在梯度累积期间，子步骤结束时调用的事件。

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

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

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

在训练开始时调用的事件。

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

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

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

在训练结束时调用的事件。

以下是使用 PyTorch [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 注册自定义回调的示例：

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

注册回调的另一种方式是按如下方式调用 `trainer.add_callback()`：

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

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

**参数：**

epoch (`float`, *可选*) : 仅在训练期间设置，表示当前训练所处的 epoch（小数部分表示当前 epoch 的完成百分比）。

global_step (`int`，*可选*，默认值为 0)：在训练过程中，表示已完成的更新步数。

max_steps (`int`，*可选*，默认为 0)：当前训练期间要执行的更新步数。

logging_steps (`int`，*可选*，默认为 500)：每 X 个更新步骤记录一次日志

eval_steps (`int`, *可选*) : 每隔 X 步运行一次评估。

save_steps (`int`，*可选*，默认为 500)：每 X 个更新步骤保存一次检查点。

train_batch_size (`int`, *可选*) : 训练数据加载器的批大小。仅在已使用 `auto_find_batch_size` 时需要。

num_input_tokens_seen (`int`，*可选*，默认为 0)：在跟踪输入 token 时，训练过程中已看到的 token 数量（指输入 token 的数量，而非预测 token 的数量）。

total_flos (`float`，*可选*，默认值为 0)：模型自训练开始以来执行的浮点运算总次数（以浮点数形式存储，以避免溢出）。

log_history (`list[dict[str, float]]`，*可选*)：自训练开始以来生成的日志列表。

best_metric (`float`, *可选*) : 在跟踪最佳模型时，迄今为止遇到的最佳指标值。

best_global_step (`int`，*可选*)：在跟踪最佳模型时，记录遇到最佳指标时的步数。用于设置 `best_model_checkpoint`。

best_model_checkpoint (`str`, *可选*) : 在跟踪最佳模型时，迄今为止遇到的最佳模型检查点的名称值。

is_local_process_zero (`bool`，*可选*，默认为 `True`)：此进程是否为本地（例如，在多台机器上以分布式方式训练时，指单台机器上的）主进程。

is_world_process_zero (`bool`，*可选*，默认为 `True`)：此进程是否为全局主进程（在多台机器上进行分布式训练时，仅有一个进程为 `True`）。

is_hyper_param_search (`bool`，*可选*，默认为 `False`)：是否正在使用 Trainer.hyperparameter_search 进行超参数搜索。这将影响数据在 TensorBoard 中的记录方式。

stateful_callbacks (`list[StatefulTrainerCallback]`，*可选*)：附加到 `Trainer` 上、其状态需要被保存或恢复的回调。相关的回调应实现 `state` 和 `from_state` 函数。

一个包含 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 内部状态的类，该状态会在检查点保存时与模型和优化器一起保存，并传递给 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback)。

在本类中，一个步骤应被理解为一个更新步骤。在使用梯度累积时，一个更新步骤可能需要多次前向和反向传播：如果你使用 `gradient_accumulation_steps=n`，那么一个更新步骤需要遍历 *n* 个批次。

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

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

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

根据该值是比例还是绝对值，计算并存储用于记录、评估和保存步骤的绝对值。

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

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

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

在 `self` 中存储训练所需的初始引用

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

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

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

从 `json_path` 的内容创建实例。

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

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

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

以 JSON 格式将此实例的内容保存到 `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)
```

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

**参数：**

should_training_stop (`bool`，*可选*，默认为 `False`)：是否应中断训练。如果为 `True`，该变量将不会被重置为 `False`。训练将直接停止。

should_epoch_stop (`bool`，*可选*，默认为 `False`)：是否应中断当前 epoch。如果为 `True`，该变量将在下一个 epoch 开始时重置为 `False`。

should_save (`bool`，*可选*，默认为 `False`)：是否应在当前步骤保存模型。如果为 `True`，该变量将在下一步开始时重置为 `False`。

should_evaluate (`bool`，*可选*，默认为 `False`)：是否应在当前步骤对模型进行评估。如果为 `True`，该变量将在下一步开始时重置为 `False`。

should_log (`bool`，*可选*，默认为 `False`)：是否应在当前步骤报告日志。如果为 `True`，该变量将在下一步开始时重置为 `False`。

一个用于处理 [Trainer](/docs/transformers/main/zh/main_classes/trainer#transformers.Trainer) 控制流的类。该类由 [TrainerCallback](/docs/transformers/main/zh/main_classes/callback#transformers.TrainerCallback) 使用，以在训练循环中激活某些开关。