Hugging Face 的 logo

Transformers 文档

回调函数

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

回调

回调是可以在 PyTorch 训练器 中自定义训练循环行为的对象（此功能尚未在 TensorFlow 中实现），可以检查训练循环状态（用于进度报告、在 TensorBoard 或其他机器学习平台上记录...）并做出决策（例如提前停止）。

回调是“只读”代码段，除了它们返回的 训练器控制 对象外，它们无法更改训练循环中的任何内容。对于需要更改训练循环的自定义，您应该继承 训练器 并覆盖您需要的方法（请参阅 训练器 获取示例）。

默认情况下，TrainingArguments.report_to 设置为 "all"，因此 训练器 将使用以下回调。

如果安装了某个软件包，但您不希望使用附带的集成，您可以将 TrainingArguments.report_to 更改为仅包含您想要使用的集成的列表（例如 ["azure_ml", "wandb"]）。

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

可用回调

以下是库中可用的 TrainerCallback 列表

类 transformers.integrations.CometCallback

< >

( )

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

设置

< >

( args state model )

设置可选的 Comet 集成。

环境

  • COMET_MODE (str, 可选, 默认为 get_or_create): 控制是创建并记录到新的 Comet 实验还是追加到现有的实验。它接受以下值
    • get_or_create: 根据是否设置了 COMET_EXPERIMENT_KEY 以及是否存在具有该密钥的实验自动决定。
    • create: 始终创建新的 Comet 实验。
    • get: 始终尝试追加到现有的 Comet 实验。需要设置 COMET_EXPERIMENT_KEY。
    • ONLINE: 已弃用，用于创建在线实验。请改用 COMET_START_ONLINE=1。
    • OFFLINE: 已弃用，用于创建离线实验。请改用 COMET_START_ONLINE=0。
    • DISABLED: 已弃用，用于禁用 Comet 日志记录。请使用 --report_to 标志来控制用于记录结果的集成。
  • COMET_PROJECT_NAME (str, 可选): 实验的 Comet 项目名称。
  • COMET_LOG_ASSETS (str, 可选, 默认为 TRUE): 是否将训练资产（tf 事件日志、检查点等）记录到 Comet。可以是 TRUE 或 FALSE。

有关环境中许多可配置项的信息，请参见 此处。

类 transformers.DefaultFlowCallback

< >

( )

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

类 transformers.PrinterCallback

< >

( )

一个只打印日志的 TrainerCallback。

类 transformers.ProgressCallback

< >

( )

一个用于显示训练或评估进度的 TrainerCallback。

类 transformers.EarlyStoppingCallback

< >

( early_stopping_patience: int = 1 early_stopping_threshold: Optional = 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 不同，则提前停止将不会发生，直到下一个保存步骤。

类 transformers.integrations.TensorBoardCallback

< >

( tb_writer = None )

参数

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

一个 TrainerCallback，它将日志发送到 TensorBoard。

类 transformers.integrations.WandbCallback

< >

( )

一个 TrainerCallback，它将指标、媒体、模型检查点记录到 Weight and Biases。

设置

< >

( args state model **kwargs )

设置可选的 Weights & Biases (wandb) 集成。

可以根据需要子类化并覆盖此方法以自定义设置。在此处 了解更多信息。您还可以覆盖以下环境变量

环境

  • WANDB_LOG_MODEL (str, 可选, 默认为 "false"): 是否在训练期间记录模型和检查点。可以是 "end"、"checkpoint" 或 "false"。如果设置为 "end"，模型将在训练结束时上传。如果设置为 "checkpoint"，检查点将每 args.save_steps 上传一次。如果设置为 "false"，则不会上传模型。与 load_best_model_at_end() 一起使用以上传最佳模型。

    在 5.0 中弃用

    在 🤗 Transformers 版本 5 中，将 WANDB_LOG_MODEL 设置为 bool 将被弃用。

  • WANDB_WATCH (str, 可选 默认为 "false"): 可以是 "gradients"、"all"、"parameters" 或 "false"。设置为 "all" 以记录梯度和参数。

  • WANDB_PROJECT (str, 可选, 默认为 "huggingface"): 将此设置为自定义字符串以将结果存储在不同的项目中。

  • WANDB_DISABLED (bool, 可选, 默认为 False): 是否完全禁用 wandb。设置 WANDB_DISABLED=true 以禁用。

类 transformers.integrations.MLflowCallback

< >

( )

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

设置

< >

( args state model )

设置可选的 MLflow 集成。

环境

  • HF_MLFLOW_LOG_ARTIFACTS (str, 可选): 是否使用 MLflow .log_artifact() 功能来记录 artifacts。这只有在记录到远程服务器（例如 s3 或 GCS）时才有意义。如果设置为 True 或 1，则会在每次保存时将 TrainingArguments 的 output_dir 中保存的每个检查点复制到本地或远程 artifact 存储。在没有远程存储的情况下使用它只会将文件复制到您的 artifact 位置。
  • 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, 可选): 允许重新附加到现有运行，这在从检查点恢复训练时很有用。当设置了 MLFLOW_RUN_ID 环境变量时，start_run 会尝试使用指定的运行 ID 恢复运行，并忽略其他参数。
  • MLFLOW_FLATTEN_PARAMS (str, 可选, 默认为 False): 是否在记录之前展平参数字典。

类 transformers.integrations.AzureMLCallback

< >

( azureml_run = None )

一个 TrainerCallback，用于将日志发送到 AzureML。

类 transformers.integrations.CodeCarbonCallback

< >

( )

一个 TrainerCallback，用于跟踪训练的二氧化碳排放量。

类 transformers.integrations.NeptuneCallback

< >

( api_token: Optional = None project: Optional = None name: Optional = None base_namespace: str = 'finetuning' run = None log_parameters: bool = True log_checkpoints: Optional = None **neptune_run_kwargs )

参数

  • api_token (str, 可选) — 注册后获得的 Neptune API 令牌。如果您已将令牌保存到 NEPTUNE_API_TOKEN 环境变量（强烈建议），则可以省略此参数。请参阅文档中的完整设置说明。
  • project (str, 可选) — 现有 Neptune 项目的名称，格式为“工作区名称/项目名称”。您可以在 Neptune 中从项目设置 -> 属性中找到并复制名称。如果为 None（默认值），则使用 NEPTUNE_PROJECT 环境变量的值。
  • name (str, 可选) — 运行的自定义名称。
  • base_namespace (str, 可选, 默认为“finetuning”) — 在 Neptune 运行中，将包含回调记录的所有元数据的根命名空间。
  • log_parameters (bool, 可选, 默认为 True) — 如果为 True，则记录 Trainer 提供的所有 Trainer 参数和模型参数。
  • log_checkpoints (str, 可选) — 如果为“same”，则在 Trainer 保存检查点时上传检查点。如果为“last”，则仅上传最近保存的检查点。如果为“best”，则上传最佳检查点（在 Trainer 保存的检查点中）。如果为 None，则不上传检查点。
  • run (Run, 可选) — 如果您想继续记录到现有运行，请传递 Neptune 运行对象。在文档中阅读有关恢复运行的更多信息。
  • **neptune_run_kwargs (可选) — 创建新运行时要直接传递给 neptune.init_run() 函数的额外关键字参数。

将日志发送到 Neptune 的 TrainerCallback。

有关说明和示例，请参阅 Neptune 文档中的 Transformers 集成指南。

类 transformers.integrations.ClearMLCallback

< >

( )

将日志发送到 ClearML 的 TrainerCallback。

环境

  • CLEARML_PROJECT (str, 可选, 默认为 HuggingFace Transformers): ClearML 项目名称。
  • CLEARML_TASK (str, 可选, 默认为 Trainer): ClearML 任务名称。
  • CLEARML_LOG_MODEL (bool, 可选, 默认为 False): 是否在训练期间将模型记录为工件。

类 transformers.integrations.DagsHubCallback

< >

( )

记录到 DagsHub 的 TrainerCallback。 扩展 MLflowCallback

设置

< >

( *args **kwargs )

设置 DagsHub 的日志记录集成。

环境

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

类 transformers.integrations.FlyteCallback

< >

( save_log_history: bool = True sync_checkpoints: bool = True )

参数

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

一个 TrainerCallback，将日志发送到 Flyte。注意：此回调仅在 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())

类 transformers.integrations.DVCLiveCallback

< >

( live: 可选 = 无 log_model: 联合 = 无 **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。

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

在 setup 中使用以下环境变量来配置集成。要对此回调进行超出这些环境变量的自定义，请参见 此处。

设置

< >

( args state model )

设置可选的 DVCLive 集成。要对此回调进行超出以下环境变量的自定义，请参见 此处。

环境

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

TrainerCallback

类 transformers.TrainerCallback

< >

( )

参数

  • args (TrainingArguments) — 用于实例化 Trainer 的训练参数。
  • state (TrainerState) — Trainer 的当前状态。
  • control (TrainerControl) — 返回给 Trainer 的对象，可用于做出一些决策。
  • model (PreTrainedModel 或 torch.nn.Module) — 正在训练的模型。
  • tokenizer (PreTrainedTokenizer) — 用于编码数据的分词器。
  • optimizer (torch.optim.Optimizer) — 用于训练步骤的优化器。
  • lr_scheduler (torch.optim.lr_scheduler.LambdaLR) — 用于设置学习率的调度器。
  • train_dataloader (torch.utils.data.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: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

在 epoch 开始时调用的事件。

on_epoch_end

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

在 epoch 结束时调用的事件。

on_evaluate

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_init_end

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_log

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

在记录最后日志后调用的事件。

on_optimizer_step

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_pre_optimizer_step

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_predict

< >

( args: TrainingArguments state: TrainerState control: TrainerControl metrics **kwargs )

成功预测后调用的事件。

on_prediction_step

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_save

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_step_begin

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_step_end

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_substep_end

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_train_begin

< >

( args: TrainingArguments state: TrainerState control: TrainerControl **kwargs )

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

on_train_end

< >

( args: TrainingArguments state: TrainerState control: 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: Optional = None 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 num_train_epochs: int = 0 num_input_tokens_seen: int = 0 total_flos: float = 0 log_history: List = None best_metric: Optional = None best_model_checkpoint: Optional = None is_local_process_zero: bool = True is_world_process_zero: bool = True is_hyper_param_search: bool = False trial_name: str = None trial_params: Dict = None stateful_callbacks: List = 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) — 训练期间看到的标记数量（输入标记的数量，而不是预测标记的数量）。
  • total_flos (float, 可选, 默认为 0) — 自训练开始以来模型完成的浮点运算总数（存储为浮点数以避免溢出）。
  • log_history (List[Dict[str, float]], 可选) — 自训练开始以来完成的日志列表。
  • best_metric (float, 可选) — 跟踪最佳模型时，到目前为止遇到的最佳指标的值。
  • 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 个批次。

从 JSON 加载

< >

( json_path: str )

从 json_path 的内容创建一个实例。

保存到 JSON

< >

( json_path: str )

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

TrainerControl

类 transformers.TrainerControl

< >

( should_training_stop: bool = False should_epoch_stop: bool = False should_save: bool = False should_evaluate: bool = False should_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 使用，以在训练循环中激活一些开关。

< > 在 GitHub 上更新

←骨干网络 配置→