Hugging Face's logo

Transformers documentation

回调

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

回调

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

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

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

实现回调的主要类是 TrainerCallback。它会获取用于实例化 Trainer 的 TrainingArguments，可以通过 TrainerState 访问该 Trainer 的内部状态，并可以通过 TrainerControl 对训练循环执行某些操作。

可用回调

以下是库中可用的 TrainerCallback 列表：

class transformers.integrations.CometCallback

< >

( )

一个将日志发送到 Comet ML 的 TrainerCallback。

设置

< >

( argsstatemodel )

设置可选的 Comet 集成。

环境：

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

有关环境中可配置项的详细信息，请参阅此处。

class transformers.DefaultFlowCallback

< >

( )

一个用于处理训练循环中日志、评估和检查点默认流程的 TrainerCallback。

class transformers.PrinterCallback

< >

( )

一个仅用于打印日志的裸 TrainerCallback。

class transformers.ProgressCallback

< >

( max_str_len: int = 100 )

一个用于显示训练或评估进度的 TrainerCallback。 你可以通过修改 max_str_len 来控制记录日志时字符串的截断长度。

class transformers.EarlyStoppingCallback

< >

( early_stopping_patience: int = 1early_stopping_threshold: float | None = 0.0 )

参数

  • early_stopping_patience (int) — 与 metric_for_best_model 配合使用，当指定指标在连续 early_stopping_patience 次评估中变差时停止训练。
  • early_stopping_threshold(float, 可选) — 与 TrainingArguments 中的 metric_for_best_model 和 early_stopping_patience 配合使用，用于指定指标需要改善多少才能满足早停条件。`

用于处理早停的 TrainerCallback。

此回调依赖于 TrainingArguments 参数 load_best_model_at_end 的功能，以在 TrainerState 中设置 best_metric。请注意，如果 TrainingArguments 参数 save_steps 与 eval_steps 不同，则早停不会发生，直到下一个保存步骤。

class transformers.integrations.TensorBoardCallback

< >

( tb_writer = None )

参数

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

一个将日志发送到 TensorBoard 的 TrainerCallback。

环境：

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

class transformers.integrations.TrackioCallback

< >

( )

一个用于将指标记录到 Trackio 的 TrainerCallback。

设置

< >

( argsstatemodel**kwargs )

设置可选的 Trackio 集成。

要自定义设置，您还可以在 TrainingArguments 中设置 project、trackio_space_id、trackio_bucket_id、trackio_static_space_id 和 hub_private_repo。

class transformers.integrations.WandbCallback

< >

( )

一个用于将指标、媒体和模型检查点记录到 Weight and Biases 的 TrainerCallback。

设置

< >

( argsstatemodel**kwargs )

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

可以通过子类化并覆盖此方法来自定义设置（如有需要）。更多信息请参见此处。您还可以覆盖以下环境变量：

环境：

  • 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")： 将其设置为自定义字符串，可将结果存储到不同的项目中。

class transformers.integrations.MLflowCallback

< >

( )

一个将日志发送到 MLflow 的 TrainerCallback。可通过设置环境变量 DISABLE_MLFLOW_INTEGRATION = TRUE 来禁用。

设置

< >

( argsstatemodel )

设置可选的 MLflow 集成。

环境：

  • HF_MLFLOW_LOG_ARTIFACTS (str, 可选)： 是否使用 MLflow 的 .log_artifact() 功能来记录工件。仅在向日志记录到远程服务器（例如 s3 或 GCS）时才有意义。如果设置为 True 或 1，则会将 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，可选）： 设置要记录到运行中的最大参数数量。

class transformers.integrations.AzureMLCallback

< >

( azureml_run = None )

一个将日志发送到 AzureML 的 TrainerCallback。

class transformers.integrations.CodeCarbonCallback

< >

( )

一个用于跟踪训练过程中 CO2 排放量的 TrainerCallback。

class transformers.integrations.ClearMLCallback

< >

( )

一个将日志发送到 ClearML 的 TrainerCallback。

环境：

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

class transformers.integrations.DagsHubCallback

< >

( )

一个用于向 DagsHub 记录日志的 TrainerCallback。继承自 MLflowCallback

设置

< >

( *args**kwargs )

设置 DagsHub 的日志记录集成。

环境：

  • HF_DAGSHUB_LOG_ARTIFACTS (str, 可选)： 是否保存实验的数据和模型工件。默认为 False。

class transformers.integrations.FlyteCallback

< >

( save_log_history: bool = Truesync_checkpoints: bool = True )

参数

  • save_log_history（bool，可选，默认为 True）— 当设置为 True 时，训练日志将作为 Flyte Deck 保存。
  • sync_checkpoints (bool，可选，默认为 True) — 当设置为 True 时，检查点会与 Flyte 同步，并可在训练中断时用于恢复训练。

一个将日志发送到 Flyte 的 TrainerCallback。 注意：此回调仅在 Flyte 任务中有效。

示例：

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

class transformers.integrations.KubeflowCallback

< >

( )

一个用于向 Kubeflow Trainer 报告训练进度的 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 来禁用。

class transformers.integrations.DVCLiveCallback

< >

( live: typing.Any | None = Nonelog_model: typing.Union[typing.Literal['all'], bool, NoneType] = None**kwargs )

参数

  • live (dvclive.Live，可选，默认为 None) — 可选的 Live 实例。如果为 None，将使用 **kwargs 创建一个新的实例。
  • log_model (Union[Literal[“all”], bool], 可选，默认为 None) — 是否使用 dvclive.Live.log_artifact() 来记录由 Trainer 创建的检查点。如果设置为 True， 则在训练结束时记录最终检查点。如果设置为 "all"，则在每个检查点处记录整个 TrainingArguments 的 output_dir。

一个将日志发送到 DVCLive 的 TrainerCallback。

在 setup 中使用以下环境变量来配置集成。若要在此类环境变量之外进一步自定义该回调，请参阅 此处。

设置

< >

( argsstatemodel )

设置可选的 DVCLive 集成。若要自定义此回调（超出以下环境变量），请参阅 此处。

环境：

  • HF_DVCLIVE_LOG_MODEL (str, 可选)： 是否使用 dvclive.Live.log_artifact() 来记录由 Trainer 创建的检查点。如果设置为 True 或 1，则在训练结束时记录最终检查点。如果设置为 all，则在每个检查点处记录整个 TrainingArguments 的 output_dir。

class transformers.integrations.SwanLabCallback

< >

( )

一个用于将指标、媒体和模型检查点记录到 SwanLab 的 TrainerCallback。

设置

< >

( argsstatemodel**kwargs )

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

可以通过子类化并覆盖此方法来自定义设置（如需要）。更多信息请参见此处。

您也可以覆盖以下环境变量。有关环境变量的更多信息，请参见此处

环境：

  • 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。注意：区分大小写。更多信息请参见 此处

  • 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

class transformers.TrainerCallback

< >

( )

参数

  • args (TrainingArguments) — 用于实例化 Trainer 的训练参数。
  • state (TrainerState) — Trainer 的当前状态。
  • control (TrainerControl) — 返回给 Trainer 的对象，可用于做出某些决策。
  • model (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 的代码。

示例：

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

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

在 epoch 开始时调用的事件。

on_epoch_end

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

在 epoch 结束时调用的事件。

on_evaluate

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_init_end

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

在 Trainer 初始化结束时调用的事件。

on_log

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_optimizer_step

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_pre_optimizer_step

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_predict

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControlmetrics**kwargs )

成功预测后调用的事件。

on_prediction_step

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_push_begin

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_save

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_step_begin

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_step_end

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_substep_end

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_train_begin

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

on_train_end

< >

( args: TrainingArgumentsstate: TrainerStatecontrol: TrainerControl**kwargs )

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

以下是使用 PyTorch Trainer 注册自定义回调的示例：

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

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

TrainerState

类 transformers.TrainerState

< >

( epoch: float = 0global_step: int = 0max_steps: int = 0logging_steps: int = 500eval_steps: int = 500save_steps: int = 500train_batch_size: int | None = Nonenum_train_epochs: int = 0num_input_tokens_seen: int = 0total_flos: float = 0log_history: list = Nonebest_metric: float | None = Nonebest_global_step: int | None = Nonebest_model_checkpoint: str | None = Noneis_local_process_zero: bool = Trueis_world_process_zero: bool = Trueis_hyper_param_search: bool = Falsetrial_name: str | None = Nonetrial_params: dict[str, str | float | int | bool] | None = Nonestateful_callbacks: list['TrainerCallback'] | None = None )

参数

  • epoch (float, 可选) — 仅在训练期间设置，表示当前所处的训练轮次（小数部分表示当前轮次已完成的百分比）。
  • 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 内部状态的类，该状态会在创建检查点时与模型和优化器一起保存，并传递给 TrainerCallback。

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

compute_steps

< >

( argsmax_steps )

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

init_training_references

< >

( trainermax_stepsnum_train_epochstrial )

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

load_from_json

< >

( json_path: str )

从 json_path 的内容创建实例。

save_to_json

< >

( json_path: str )

以 JSON 格式将此实例的内容保存到 json_path 中。

TrainerControl

class transformers.TrainerControl

< >

( should_training_stop: bool = Falseshould_epoch_stop: bool = Falseshould_save: bool = Falseshould_evaluate: bool = Falseshould_log: bool = False )

参数

  • 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 控制流的类。该类由 TrainerCallback 使用，以在训练循环中激活某些开关。

Update on GitHub

←骨干网络 配置→