Transformers 4.37 中文文档（十四）（1）

原文：huggingface.co/docs/transformers

骨干

原文链接：huggingface.co/docs/transformers/v4.37.2/en/main_classes/backbones

骨干是用于计算机视觉任务的特征提取模型。可以通过两种方式之一将模型用作骨干：

• 使用预训练模型初始化AutoBackbone类，
  
• 初始化支持的骨干配置并将其传递给模型架构。
  

使用 AutoBackbone

您可以使用AutoBackbone类初始化一个模型作为骨干，并获取任何阶段的特征图。您可以定义out_indices来指示您想要从哪些层获取特征图。如果您知道层的名称，也可以使用out_features。您可以互换使用它们。如果同时使用out_indices和out_features，请确保它们是一致的。不传递任何特征图参数将使骨干产生最后一层的特征图。为了可视化各个阶段的外观，让我们以 Swin 模型为例。每个阶段负责特征提取，输出特征图。

第一阶段的特征图如下所示。

让我们通过一个示例来看看。请注意，out_indices=(0,)会导致产生模型的 stem。Stem 指的是第一个特征提取阶段之前的阶段。在上图中，它指的是 patch 分区。我们希望从 stem、第一阶段和第二阶段获取特征图。

>>> from transformers import AutoImageProcessor, AutoBackbone
>>> import torch
>>> from PIL import Image
>>> import requests
>>> processor = AutoImageProcessor.from_pretrained("microsoft/swin-tiny-patch4-window7-224")
>>> model = AutoBackbone.from_pretrained("microsoft/swin-tiny-patch4-window7-224", out_indices=(0,1,2))
>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> image = Image.open(requests.get(url, stream=True).raw)
>>> inputs = processor(image, return_tensors="pt")
>>> outputs = model(**inputs)
>>> feature_maps = outputs.feature_maps

feature_maps对象现在有三个特征图，每个都可以像下面这样访问。假设我们想要获取 stem 的特征图。

>>> list(feature_maps[0].shape)
[1, 96, 56, 56]

我们可以像下面这样获取第一阶段和第二阶段的特征图。

>>> list(feature_maps[1].shape)
[1, 96, 56, 56]
>>> list(feature_maps[2].shape)
[1, 192, 28, 28]

初始化骨干配置

在计算机视觉中，模型由骨干、neck 和头部组成。骨干提取特征，neck 转换骨干的输出，头部用于主要任务（例如目标检测）。您可以通过将模型配置传递给backbone_config来使用模型骨干初始化 neck 和头部。例如，您可以看到如何使用 ResNet 骨干初始化带有实例分割头部的 MaskFormer 模型。

from transformers import MaskFormerConfig, MaskFormerForInstanceSegmentation, ResNetConfig
backbone_config = ResNetConfig.from_pretrained("microsoft/resnet-50")
config = MaskFormerConfig(backbone_config=backbone_config)
model = MaskFormerForInstanceSegmentation(config)

您还可以使用随机权重初始化骨干，以初始化模型的 neck。

backbone_config = ResNetConfig()
config = MaskFormerConfig(backbone_config=backbone_config)
model = MaskFormerForInstanceSegmentation(config)

通过TimmBackbone和TimmBackboneConfig，transformers 还支持timm模型。

from transformers import TimmBackboneConfig, TimmBackbone
backbone_config = TimmBackboneConfig("resnet50")
model = TimmBackbone(config=backbone_config)

回调函数

原始文本：huggingface.co/docs/transformers/v4.37.2/en/main_classes/callback

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

回调函数是“只读”代码片段，除了它们返回的 TrainerControl 对象外，它们不能更改训练循环中的任何内容。对于需要更改训练循环的自定义内容，您应该子类化 Trainer 并覆盖您需要的方法（请参阅 trainer 以获取示例）。

默认情况下，TrainingArguments.report_to设置为"all"，因此 Trainer 将使用以下回调函数。

• DefaultFlowCallback 处理日志记录、保存和评估的默认行为。
  
• 使用 PrinterCallback 或 ProgressCallback 显示进度并打印日志（如果通过 TrainingArguments 停用 tqdm，则使用第一个，否则使用第二个）。
  
• 如果 tensorboard 可访问（通过 PyTorch >= 1.4 或 tensorboardX），则使用 TensorBoardCallback。
  
• 如果安装了wandb，则使用 WandbCallback。
  
• 如果安装了comet_ml，则使用 CometCallback。
  
• 如果安装了mlflow，则使用 MLflowCallback。
  
• 如果安装了neptune，则使用 NeptuneCallback。
  
• 如果安装了azureml-sdk，则使用 AzureMLCallback。
  
• 如果安装了codecarbon，则使用 CodeCarbonCallback。
  
• 如果安装了clearml，则使用 ClearMLCallback。
  
• 如果安装了dagshub，则使用 DagsHubCallback。
  
• 如果安装了flyte，则使用 FlyteCallback。
  
• 如果安装了dvclive，则使用 DVCLiveCallback。
  

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

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

可用的回调

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

class transformers.integrations.CometCallback

< source >

( )

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

setup

< source >

( args state model )

设置可选的 Comet.ml 集成。

环境：

• COMET_MODE (str, 可选，默认为ONLINE): 是否创建在线、离线实验或禁用 Comet 日志记录。可以是OFFLINE、ONLINE或DISABLED。
  
• COMET_PROJECT_NAME (str, 可选): 用于实验的 Comet 项目名称。
  
• COMET_OFFLINE_DIRECTORY (str, 可选): 在COMET_MODE为OFFLINE时用于保存离线实验的文件夹。
  
• COMET_LOG_ASSETS (str, 可选，默认为TRUE): 是否将训练资产（tf 事件日志、检查点等）记录到 Comet。可以是TRUE或FALSE。
  

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

class transformers.DefaultFlowCallback

< source >

( )

处理训练循环的默认流程，包括日志、评估和检查点的 TrainerCallback。

class transformers.PrinterCallback

< source >

( )

一个简单的 TrainerCallback，只打印日志。

class transformers.ProgressCallback

< source >

( )

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

class transformers.EarlyStoppingCallback

< source >

( 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不同，则直到下一个保存步骤才会发生早停。

class transformers.integrations.TensorBoardCallback

<来源>

( tb_writer = None )

参数

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

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

class transformers.integrations.WandbCallback

<来源>

( )

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

setup

<来源>

( 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以禁用。
  

class transformers.integrations.MLflowCallback

<来源>

( )

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

setup

<来源>

( args state model )

设置可选的 MLflow 集成。

环境：

• HF_MLFLOW_LOG_ARTIFACTS（str，可选）：是否使用 MLflow 的.log_artifact()功能来记录工件。只有在将日志记录到远程服务器（例如 s3 或 GCS）时才有意义。如果设置为True或1，将在每次在 TrainingArguments 的output_dir中保存时将每个保存的检查点复制到本地或远程工件存储。在没有远程存储的情况下使用它将只是将文件复制到您的工件位置。
  
• MLFLOW_EXPERIMENT_NAME (str, 可选, 默认为None)：是否使用 MLflow 实验名称来启动运行。默认为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)：是否在记录之前展平参数字典。
  

class transformers.integrations.AzureMLCallback

<来源>

( azureml_run = None )

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

class transformers.integrations.CodeCarbonCallback

<来源>

( )

一个 TrainerCallback，用于跟踪训练的 CO2 排放量。

class 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 项目的名称，格式为“workspace-name/project-name”。您可以在 Neptune 中的项目设置 -> 属性中找到并复制名称。如果为 None（默认），则使用NEPTUNE_PROJECT环境变量的值。
  
• name (str, 可选) — 运行的自定义名称。
  
• base_namespace (str, 可选, 默认为“finetuning”) — 在 Neptune 运行中，将包含回调记录的所有元数据的根命名空间。
  
• log_parameters (bool, 可选, 默认为True) — 如果为 True，则记录 Trainer 提供的所有参数和模型参数。
  
• log_checkpoints (str, 可选) — 如果为“same”，则在 Trainer 保存检查点时上传检查点。如果为“last”，则仅上传最近保存的检查点。如果为“best”，则上传最佳检查点（在 Trainer 保存的检查点中选择）。如果为None，则不上传检查点。
  
• run (Run, 可选) — 如果要继续记录到现有运行中，请传递一个 Neptune 运行对象。在文档中了解更多关于恢复运行的信息。
  
• **neptune_run_kwargs (可选) — 传递给neptune.init_run()函数的其他关键字参数，当创建新运行时。
  

将日志发送到Neptune的 TrainerCallback。

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

class transformers.integrations.ClearMLCallback

< source >

( )

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

环境：

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

class transformers.integrations.DagsHubCallback

< source >

( )

一个将日志记录到DagsHub的 TrainerCallback。扩展MLflowCallback

setup

< source >

( *args **kwargs )

设置 DagsHub 的日志记录集成。

环境：

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

class transformers.integrations.FlyteCallback

< source >

( save_log_history: bool = True sync_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.DVCLiveCallback

< source >

( live: Optional = None log_model: Union = 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中使用下面的环境变量来配置集成。要在这些环境变量之外自定义此回调，请参阅此处。

setup

< source >

( args state model )

设置可选的 DVCLive 集成。要在环境变量之外自定义此回调，请参阅此处。

环境：

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

TrainerCallback

class transformers.TrainerCallback

< source >

( )

参数

• 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, optional) — 用于训练的当前数据加载器。
  
• eval_dataloader (torch.utils.data.DataLoader, optional) — 用于训练的当前数据加载器。
  
• metrics (Dict[str, float]) — 上次评估阶段计算的指标。
  这些只能在事件on_evaluate中访问。
  
• logs (Dict[str, float]) — 要记录的值。
  这些只能在事件on_log中访问。
  

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

control对象是唯一可以被回调函数更改的对象，如果更改了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

< source >

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

在一个 epoch 开始时调用的事件。

on_epoch_end

< source >

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

在一个 epoch 结束时调用的事件。

on_evaluate

< source >

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

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

on_init_end

< source >

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

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

on_log

< source >

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

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

on_predict

< source >

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

在成功预测后调用的事件。

on_prediction_step

< source >

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

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

on_save

< source >

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

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

on_step_begin

< source >

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

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

on_step_end

< source >

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

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

on_substep_end

< source >

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

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

on_train_begin

< source >

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

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

on_train_end

< source >

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

Transformers 4.37 中文文档（十四）（2）https://developer.aliyun.com/article/1564956