训练师

SentenceTransformerTrainer

class sentence_transformers.trainer.SentenceTransformerTrainer(model: SentenceTransformer | None = None, args: SentenceTransformerTrainingArguments = None, train_dataset: Dataset | DatasetDict | IterableDataset | dict[str, Dataset] | None = None, eval_dataset: Dataset | DatasetDict | IterableDataset | dict[str, Dataset] | None = None, loss: nn.Module | dict[str, nn.Module] | Callable[[SentenceTransformer], torch.nn.Module] | dict[str, Callable[[SentenceTransformer], torch.nn.Module]] | None = None, evaluator: SentenceEvaluator | list[SentenceEvaluator] | None = None, data_collator: DataCollator | None = None, tokenizer: PreTrainedTokenizerBase | Callable | None = None, model_init: Callable[[], SentenceTransformer] | None = None, compute_metrics: Callable[[EvalPrediction], dict] | None = None, callbacks: list[TrainerCallback] | None = None, optimizers: tuple[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR] = (None, None), preprocess_logits_for_metrics: Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = None)

SentenceTransformerTrainer 是一个简单但功能齐全的基于 PyTorch 的训练和评估循环，基于 🤗 Transformers :class:~transformers.Trainer。

此训练器集成了对各种 :class:transformers.TrainerCallback 子类的支持，例如：

• :class:~transformers.integrations.WandbCallback 用于在安装了 wandb 的情况下自动记录训练指标到 W&B。

• :class:~transformers.integrations.TensorBoardCallback 用于在 tensorboard 可访问时将训练指标记录到 TensorBoard。

• :class:~transformers.integrations.CodeCarbonCallback 用于在安装了 codecarbon 的情况下，跟踪模型训练期间的碳排放。

  • 注意：这些碳排放将被包含在你自动生成的模型卡片中。

有关集成回调以及如何编写自己的回调的更多信息，请参阅 Transformers 的 Callbacks <https://huggingface.co/docs/transformers/main/en/main_classes/callback>_ 文档。

参数:

• model (SentenceTransformer, optional) -- 用于训练、评估或预测的模型。如果未提供，则必须传递 model_init。

• args (SentenceTransformerTrainingArguments, optional) -- 用于调整训练的参数。如果没有提供，将默认使用 :class:~sentence_transformers.training_args.SentenceTransformerTrainingArguments 的基本实例，并将 output_dir 设置为当前目录中名为 tmp_trainer 的目录。

• train_dataset (Union[datasets.Dataset, datasets.DatasetDict, datasets.IterableDataset, Dict[str, datasets.Dataset]], optional) -- 用于训练的数据集。必须具有损失函数接受的格式，请参见 训练概述 > 数据集格式 <../../../docs/sentence_transformer/training_overview.html#dataset-format>_。

• eval_dataset (Union[datasets.Dataset, datasets.DatasetDict, datasets.IterableDataset, Dict[str, datasets.Dataset]], optional) -- 用于评估的数据集。必须具有损失函数接受的格式，参见 训练概览 > 数据集格式 <../../../docs/sentence_transformer/training_overview.html#dataset-format>_。

• loss (Optional[Union[torch.nn.Module, Dict[str, torch.nn.Module], Callable[[SentenceTransformer], torch.nn.Module], Dict[str, Callable[[SentenceTransformer]]]], optional) -- 用于训练的损失函数。可以是损失类实例、将数据集名称映射到损失类实例的字典、给定模型返回损失类实例的函数，或者是将数据集名称映射到给定模型返回损失类实例的函数的字典。实际上，后两者主要用于超参数优化。如果没有提供 loss，将默认使用 :class:~sentence_transformers.losses.CoSENTLoss。

• evaluator (Union[SentenceEvaluator, List[SentenceEvaluator]], optional) -- 用于训练期间有用评估指标的评估器实例。你可以使用 evaluator 有或没有 eval_dataset，反之亦然。通常，evaluator 返回的指标比从 eval_dataset 返回的损失值更有用。评估器列表将被包装在 :class:~sentence_transformers.evaluation.SequentialEvaluator 中，以顺序运行它们。

• callbacks (List of [transformers.TrainerCallback], optional) -- 用于自定义训练循环的回调列表。将这些回调添加到此处详细说明的默认回调列表中。如果你想移除默认回调之一，请使用[Trainer.remove_callback]方法。

• optimizers (Tuple[:class:`torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR]`, optional, defaults to (None, None)) -- 包含要使用的优化器和调度器的元组。默认情况下，将在模型上使用 :class:torch.optim.AdamW 的实例，并由 args 控制的 :func:transformers.get_linear_schedule_with_warmup 提供的调度器。

重要属性：

• 模型 -- 始终指向核心模型。如果使用的是 transformers 模型，它将是 [PreTrainedModel] 的子类。

• model_wrapped -- 始终指向最外层的模型，以防一个或多个其他模块包装了原始模型。这是应该用于前向传递的模型。例如，在 DeepSpeed 下，内部模型被包装在 DeepSpeed 中，然后再次被包装在 torch.nn.DistributedDataParallel 中。如果内部模型尚未被包装，则 self.model_wrapped 与 self.model 相同。

• is_model_parallel -- 模型是否已切换到模型并行模式（与数据并行不同，这意味着模型的某些层被分割在不同的GPU上）。

• place_model_on_device -- 是否自动将模型放置在设备上 - 如果使用了模型并行或deepspeed，或者如果默认的 TrainingArguments.place_model_on_device 被覆盖为返回 False，则将设置为 False。

• is_in_train -- 模型当前是否正在运行 train（例如，当在 train 状态下调用 evaluate 时）

add_callback(callback)

向当前的 [~transformers.TrainerCallback] 列表中添加一个回调。

参数:

callback (type or [~transformers.TrainerCallback]) -- 一个 [~transformers.TrainerCallback] 类或 [~transformers.TrainerCallback] 的实例。在第一种情况下，将实例化该类的成员。

compute_loss(model: SentenceTransformer, inputs: dict[str, torch.Tensor | Any], return_outputs: bool = False) → torch.Tensor | tuple[torch.Tensor, dict[str, Any]]

计算 SentenceTransformer 模型的损失。

它使用 self.loss 来计算损失，这可以是一个单一的损失函数或一个包含不同数据集损失函数的字典。如果损失是一个字典，则期望在输入中传递数据集名称，键为 "dataset_name"。这是在 add_dataset_name_column 方法中自动完成的。请注意，即使 return_outputs = True，输出也将为空，因为 SentenceTransformers 损失不返回输出。

参数:

• model (SentenceTransformer) -- SentenceTransformer 模型。

• inputs (Dict[str, Union[torch.Tensor, Any]]) -- 模型的输入数据。

• return_outputs (bool, optional) -- 是否返回输出以及损失。默认为 False。

返回:

计算的损失。如果 return_outputs 为 True，则返回损失和输出的元组。否则，仅返回损失。

返回类型:

Union[torch.Tensor, Tuple[torch.Tensor, Dict[str, Any]]]

create_model_card(language: str | None = None, license: str | None = None, tags: str | list[str] | None = None, model_name: str | None = None, finetuned_from: str | None = None, tasks: str | list[str] | None = None, dataset_tags: str | list[str] | None = None, dataset: str | list[str] | None = None, dataset_args: str | list[str] | None = None, **kwargs) → None

使用 Trainer 可用的信息创建一个模型卡的草稿。

参数:

• language (str, optional) -- 模型的语言（如果适用）

• license (str, optional) -- 模型的许可证。如果提供给 Trainer 的原始模型来自 Hub 上的仓库，则默认使用预训练模型的许可证。

• tags (str or List[str], optional) -- 模型卡片元数据中应包含的一些标签。

• model_name (str, optional) -- 模型的名称。

• finetuned_from (str, optional) -- 用于微调此模型的模型名称（如果适用）。将默认为提供给 Trainer 的原始模型的仓库名称（如果它来自 Hub）。

• tasks (str or List[str], optional) -- 一个或多个任务标识符，将包含在模型卡的元数据中。

• dataset_tags (str or List[str], optional) -- 一个或多个数据集标签，包含在模型卡的元数据中。

• dataset (str or List[str], optional) -- 一个或多个数据集标识符，将包含在模型卡的元数据中。

• dataset_args (str or List[str], optional) -- 一个或多个数据集参数，将被包含在模型卡的元数据中。

create_optimizer()

设置优化器。

我们提供了一个合理的默认设置，效果良好。如果你想使用其他设置，可以通过 optimizers 在 Trainer 的初始化中传递一个元组，或者在子类中继承并重写此方法。

create_optimizer_and_scheduler(num_training_steps: int)

设置优化器和学习率调度器。

我们提供了一个合理的工作良好的默认设置。如果你想使用其他的东西，你可以通过 optimizers 在 Trainer 的初始化中传递一个元组，或者在子类中子类化并覆盖这个方法（或 create_optimizer 和/或 create_scheduler）。

create_scheduler(num_training_steps: int, optimizer: Optimizer | None = None)

设置调度器。训练器的优化器必须在此方法调用之前设置，或者作为参数传递。

参数:

num_training_steps (int) -- 要执行的训练步骤数。

evaluate(eval_dataset: Dataset | dict[str, Dataset] | None = None, ignore_keys: list[str] | None = None, metric_key_prefix: str = 'eval') → dict[str, float]

运行评估并返回指标。

调用脚本将负责提供计算指标的方法，因为这些指标是任务相关的（将其传递给初始化 compute_metrics 参数）。

您还可以子类化并重写此方法以注入自定义行为。

参数:

• eval_dataset (Union[Dataset, Dict[str, Dataset]), optional) -- 如果你想覆盖 self.eval_dataset，请传递一个数据集。如果它是一个 [~datasets.Dataset]，model.forward() 方法不接受的列会自动被移除。如果它是一个字典，它将在每个数据集上进行评估，并将字典键添加到指标名称前。数据集必须实现 __len__ 方法。 如果你传递一个以数据集名称为键、数据集为值的字典，evaluate 将在每个数据集上运行单独的评估。这对于监控训练如何影响其他数据集或简单地获得更细粒度的评估非常有用。当与 load_best_model_at_end 一起使用时，确保 metric_for_best_model 引用了其中一个数据集。例如，如果你传入 {"data1": data1, "data2": data2} 用于两个数据集 data1 和 data2，你可以指定 metric_for_best_model="eval_data1_loss" 以使用 data1 上的损失，或指定 metric_for_best_model="eval_data2_loss" 以使用 data2 上的损失。

• ignore_keys (List[str], optional) -- 在收集预测时，模型输出中应忽略的键列表（如果它是字典）。

• metric_key_prefix (str, optional, defaults to "eval") -- 一个可选的前缀，用作指标键的前缀。例如，如果前缀是“eval”（默认），指标“bleu”将被命名为“eval_bleu”。

返回:

一个包含评估损失和从预测中计算出的潜在指标的字典。该字典还包含从训练状态中获取的轮次数。

get_batch_sampler(dataset: Dataset, batch_size: int, drop_last: bool, valid_label_columns: list[str] | None = None, generator: torch.Generator | None = None) → BatchSampler | None

根据 self.args 中的 batch_sampler 参数返回适当的批量采样器。此批量采样器类支持 __len__ 和 __iter__ 方法，并作为 batch_sampler 用于创建 :class:torch.utils.data.DataLoader。

备注

重写此方法以提供自定义的批量采样器。

参数:

• dataset (Dataset) -- 要从中采样的数据集。

• batch_size (int) -- 每个批次的样本数量。

• drop_last (bool) -- 如果为 True，当数据集大小不能被批次大小整除时，丢弃最后一个不完整的批次。

• valid_label_columns (List[str]) -- 要检查标签的列名列表。数据集中找到的第一个 valid_label_columns 中的列名将被用作标签列。

• generator (torch.Generator, optional) -- 用于打乱索引的可选随机数生成器。

get_eval_dataloader(eval_dataset: Dataset | None = None) → DataLoader

返回评估 [~torch.utils.data.DataLoader]。

如果你想注入一些自定义行为，可以子类化并重写此方法。

参数:

eval_dataset (torch.utils.data.Dataset, optional) -- 如果提供，将覆盖 self.eval_dataset。如果它是一个 [~datasets.Dataset]，model.forward() 方法不接受的列将被自动移除。它必须实现 __len__。

get_learning_rates()

从 self.optimizer 返回每个参数的学习率。

get_multi_dataset_batch_sampler(dataset: ConcatDataset, batch_samplers: list[BatchSampler], generator: Generator | None = None, seed: int | None = 0) → BatchSampler

根据 self.args 中的 multi_dataset_batch_sampler 参数返回适当的多数据集批次采样器。该批次采样器类支持 __len__ 和 __iter__ 方法，并作为 batch_sampler 用于创建 :class:torch.utils.data.DataLoader。

备注

重写此方法以提供自定义的多数据集批次采样器。

参数:

• dataset (ConcatDataset) -- 所有数据集的连接。

• batch_samplers (List[BatchSampler]) -- 连接数据集中每个数据集的批量采样器列表。

• generator (torch.Generator, optional) -- 用于打乱索引的可选随机数生成器。

• seed (int, optional) -- 随机数生成器的可选种子

get_num_trainable_parameters()

获取可训练参数的数量。

get_optimizer_group(param: str | Parameter | None = None)

如果给定参数，则返回该参数的优化器组，否则返回所有参数的优化器组。

参数:

param (str or torch.nn.parameter.Parameter, optional) -- 需要返回的优化器组的参数。

get_test_dataloader(test_dataset: Dataset) → DataLoader

返回训练的 [~torch.utils.data.DataLoader]。

如果你想注入一些自定义行为，可以子类化并重写此方法。

参数:

test_dataset (torch.utils.data.Dataset, optional) -- 要使用的测试数据集。如果它是一个 [~datasets.Dataset]，则 model.forward() 方法不接受的列会自动移除。它必须实现 __len__。

get_train_dataloader() → DataLoader

返回训练的 [~torch.utils.data.DataLoader]。

如果 train_dataset 没有实现 __len__，将不使用采样器；否则，将使用随机采样器（如果需要，适应分布式训练）。

如果你想注入一些自定义行为，可以子类化并重写此方法。

hyperparameter_search(hp_space: Callable[[optuna.Trial], Dict[str, float]] | None = None, compute_objective: Callable[[Dict[str, float]], float] | None = None, n_trials: int = 20, direction: str | List[str] = 'minimize', backend: str | HPSearchBackend | None = None, hp_name: Callable[[optuna.Trial], str] | None = None, **kwargs) → BestRun | List[BestRun]

使用 optuna 或 Ray Tune 或 SigOpt 启动超参数搜索。优化的数量由 compute_objective 决定，默认情况下，当未提供指标时，该函数返回评估损失，否则返回所有指标的总和。

<Tip warning={true}>

要使用此方法，您需要在初始化 [Trainer] 时提供 model_init：我们需要在每次新运行时重新初始化模型。这与 optimizers 参数不兼容，因此您需要子类化 [Trainer] 并覆盖方法 [~Trainer.create_optimizer_and_scheduler] 以使用自定义优化器/调度器。

</Tip>

参数:

• hp_space (Callable[["optuna.Trial"], Dict[str, float]], optional) -- 定义超参数搜索空间的函数。将默认使用 [~trainer_utils.default_hp_space_optuna] 或 [~trainer_utils.default_hp_space_ray] 或 [~trainer_utils.default_hp_space_sigopt]，具体取决于您的后端。

• compute_objective (Callable[[Dict[str, float]], float], optional) -- 一个函数，用于从 evaluate 方法返回的指标中计算要最小化或最大化的目标。默认使用 [~trainer_utils.default_compute_objective]。

• n_trials (int, optional, defaults to 100) -- 测试的试运行次数。

• direction (str or List[str], optional, defaults to "minimize") -- 如果是单目标优化，方向是 str，可以是 "minimize" 或 "maximize"，在优化验证损失时应选择 "minimize"，在优化一个或多个指标时应选择 "maximize"。如果是多目标优化，方向是 List[str]，可以是 "minimize" 和 "maximize" 的列表，在优化验证损失时应选择 "minimize"，在优化一个或多个指标时应选择 "maximize"。

• backend (str or [~training_utils.HPSearchBackend], optional) -- 用于超参数搜索的后端。默认将使用 optuna 或 Ray Tune 或 SigOpt，取决于哪个已安装。如果全部都已安装，将默认使用 optuna。

• hp_name (Callable[["optuna.Trial"], str]], optional) -- 定义试验/运行名称的函数。默认为 None。

• kwargs (Dict[str, Any], optional) -- 传递给 optuna.create_study 或 ray.tune.run 的其他关键字参数。更多信息请参见：

返回:

关于多目标优化的最佳运行或最佳运行的所有信息。实验摘要可以在 Ray 后端的 run_summary 属性中找到。

返回类型:

[trainer_utils.BestRun 或 List[trainer_utils.BestRun]]

is_local_process_zero() → bool

这个过程是否是本地（例如，如果在一个分布式环境中在多台机器上训练，则在一台机器上）主进程。

is_world_process_zero() → bool

无论此进程是否是全局主进程（在多台机器上以分布式方式训练时，这仅对一个进程为 True）。

log(logs: Dict[str, float]) → None

在观察训练的各种对象上记录 logs。

子类化并重写此方法以注入自定义行为。

参数:

logs (Dict[str, float]) -- 要记录的值。

pop_callback(callback)

从当前的 [~transformers.TrainerCallback] 列表中移除一个回调并返回它。

如果找不到回调函数，返回 None （并且不会引发错误）。

参数:

callback (type or [~transformers.TrainerCallback]) -- 一个 [~transformers.TrainerCallback] 类或 [~transformers.TrainerCallback] 的实例。在第一种情况下，将从回调列表中弹出该类的第一个成员。

返回:

如果找到，回调将被移除。

返回类型:

[~transformers.TrainerCallback]

propagate_args_to_deepspeed(auto_find_batch_size=False)

根据 Trainer 参数设置 deepspeed 插件中的值

push_to_hub(commit_message: str | None = 'End of training', blocking: bool = True, token: str | None = None, revision: str | None = None, **kwargs) → str

将 self.model 和 self.tokenizer 上传到仓库 self.args.hub_model_id 的 🤗 模型中心。

参数:

• commit_message (str, optional, defaults to "End of training") -- 推送时提交的消息。

• blocking (bool, optional, defaults to True) -- 函数是否应在 git push 完成后才返回。

• token (str, optional, defaults to None) -- 具有写权限的令牌，用于覆盖训练器的原始参数。

• revision (str, optional) -- 要提交的 git 修订版本。默认为“main”分支的头部。

• kwargs (Dict[str, Any], optional) -- 传递给 [~Trainer.create_model_card] 的其他关键字参数。

返回:

如果 blocking=False，则为推送模型的仓库的URL；如果 blocking=True，则为跟踪提交进度的 Future 对象。

remove_callback(callback)

从当前的 [~transformers.TrainerCallback] 列表中移除一个回调。

参数:

callback (type or [~transformers.TrainerCallback]) -- 一个 [~transformers.TrainerCallback] 类或 [~transformers.TrainerCallback] 的实例。在第一种情况下，将移除回调列表中找到的该类的第一个成员。

save_model(output_dir: str | None = None, _internal_call: bool = False)

将保存模型，因此您可以使用 from_pretrained() 重新加载它。

仅从主进程保存。

train(resume_from_checkpoint: str | bool | None = None, trial: optuna.Trial | Dict[str, Any] = None, ignore_keys_for_eval: List[str] | None = None, **kwargs)

主要训练入口点。

参数:

• resume_from_checkpoint (str or bool, optional) -- 如果是 str，则为本地路径，指向一个由 [Trainer] 的先前实例保存的检查点。如果是 bool 并且等于 True，则加载 args.output_dir 中由 [Trainer] 的先前实例保存的最后一个检查点。如果存在，训练将从这里加载的模型/优化器/调度器状态中恢复。

• trial (optuna.Trial or Dict[str, Any], optional) -- 试运行或超参数搜索的超参数字典。

• ignore_keys_for_eval (List[str], optional) -- 在训练期间收集预测以进行评估时，应忽略的模型输出中的键列表（如果它是字典）。

• kwargs (Dict[str, Any], optional) -- 用于隐藏已弃用参数的其他关键字参数