Hugging Face's logo

Transformers documentation

Trainer

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Trainer

Trainer 类为 PyTorch 提供了功能完备的训练 API，支持在多 GPU/TPU 上进行分布式训练，支持 NVIDIA GPU、AMD GPU 的混合精度，以及 PyTorch 的 torch.amp。Trainer 与 TrainingArguments 类紧密配合，后者提供了丰富的选项来自定义模型的训练方式。这两个类共同构成了完整的训练 API。

Seq2SeqTrainer 和 Seq2SeqTrainingArguments 分别继承自 Trainer 和 TrainingArguments 类，并针对摘要或翻译等序列到序列任务的模型训练进行了适配。

Trainer 类针对 🤗 Transformers 模型进行了优化，与其他模型配合使用时可能会出现一些意外的行为。如果您要将其用于自己的模型，请确保：

  • 您的模型始终返回元组或 ModelOutput 的子类
  • 如果您的模型在提供了 labels 参数时能够计算损失，并且该损失作为元组的第一个元素返回（如果您的模型返回元组）
  • 您的模型可以接受多个标签参数（在 TrainingArguments 中使用 label_names 来向 Trainer 指定它们的名称），但其中任何参数都不能命名为 "label"

Trainer

class transformers.Trainer

< >

( model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, NoneType] = Noneargs: transformers.training_args.TrainingArguments | None = Nonedata_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = Nonetrain_dataset: Dataset | IterableDataset | datasets.Dataset | None = Noneeval_dataset: Dataset | dict[str, Dataset] | datasets.Dataset | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.image_processing_utils.BaseImageProcessor | transformers.feature_extraction_utils.FeatureExtractionMixin | transformers.processing_utils.ProcessorMixin | None = Nonemodel_init: collections.abc.Callable[..., transformers.modeling_utils.PreTrainedModel] | None = Nonecompute_loss_func: collections.abc.Callable | None = Nonecompute_metrics: collections.abc.Callable[[transformers.trainer_utils.EvalPrediction], dict] | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)optimizer_cls_and_kwargs: tuple[type[torch.optim.Optimizer], dict[str, typing.Any]] | None = Nonepreprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = None )

参数

  • model (PreTrainedModel 或 torch.nn.Module, 可选) — 要训练、评估或用于预测的模型。如果未提供，则必须传入 model_init 。

    Trainer 针对库提供的 PreTrainedModel 进行了优化。只要您自定义的 torch.nn.Module 模型与 🤗 Transformers 模型的工作方式一致，就可以继续使用它们。

  • args (TrainingArguments，可选) — 用于调整训练的参数。如果未提供，将默认为 TrainingArguments 的一个基本实例，其中 output_dir 设置为当前目录下名为 tmp_trainer 的目录。
  • data_collator (DataCollator, 可选) — 用于将 train_dataset 或 eval_dataset 的元素列表组合成一个批次的函数。如果未提供 processing_class，则默认为 default_data_collator()；否则，如果 processing_class 是 feature extractor 或 tokenizer，则默认为 DataCollatorWithPadding 的实例。
  • train_dataset (torch.utils.data.Dataset | torch.utils.data.IterableDataset | datasets.Dataset, 可选) — 用于训练的数据集。如果它是 Dataset, ，则 model.forward() 方法不接受的列会被自动移除。请注意，如果它是一个带有随机化的 torch.utils.data.IterableDataset，且您正在以分布式方式训练，那么您的可迭代数据集应使用一个内部属性生成器（该生成器必须是 torch.Generator，用于随机化，且必须在所有进程上保持一致，Trainer 将在每个 epoch 开始时手动设置该生成器的种子），或者实现一个 set_epoch() 方法，在内部设置所用随机数生成器的种子。如果数据集未实现 __len__（例如流式 IterableDataset），则必须设置 max_steps，因为无法推断出训练步数的总数。

    请注意，如果它是一个带有一定随机性的 torch.utils.data.IterableDataset，并且您正在以分布式方式训练，那么您的可迭代数据集应使用一个内部属性 generator（该属性是一个用于随机化的 torch.Generator，且必须在所有进程上保持一致，Trainer 会在每个 epoch 开始时手动设置该 generator 的种子），或者提供一个 set_epoch() 方法，在内部设置所使用的随机数生成器的种子。

    如果数据集未实现 __len__（例如流式 IterableDataset），则必须设置 max_steps，因为无法推断出训练步数的总数。

  • eval_dataset (torch.utils.data.Dataset | dict[str, torch.utils.data.Dataset] | datasets.Dataset, 可选) — 用于评估的数据集。如果它是 Dataset，则 model.forward() 方法不接受的列会被自动移除。如果它是一个字典，则会在每个数据集上进行评估，并将字典键作为前缀添加到指标名称中。
  • processing_class（PreTrainedTokenizerBase 或 BaseImageProcessor 或 FeatureExtractionMixin 或 ProcessorMixin，可选）— 用于处理数据的处理类。如果提供，将自动用于处理模型的输入，并随模型一起保存，以便更容易地重新运行中断的训练或复用微调后的模型。
  • model_init (Callable[[], PreTrainedModel], 可选) — 用于实例化待使用模型的函数。如果提供该函数，每次调用 train() 都将基于此函数提供的新模型实例开始训练。

    该函数可以没有参数，也可以包含一个参数，即 optuna/Ray Tune 的 trial 对象，以便根据超参数（例如层数、内部层大小、dropout 概率等）选择不同的架构。

  • compute_loss_func (Callable, 可选) — 一个函数，接收原始模型输出、标签以及整个累积批次中的样本数量（batch_size * gradient_accumulation_steps），并返回损失值。例如，参见 Trainer 使用的默认 损失函数。
  • compute_metrics (Callable[[EvalPrediction], Dict], 可选) — 用于在评估时计算指标的函数。必须接受一个 EvalPrediction 并返回一个从字符串到指标值的字典。注意 当传入的 TrainingArgs 中 batch_eval_metrics 设置为 True 时，您的 compute_metrics 函数必须接受一个布尔类型的 compute_result 参数。这将在最后一个评估批次之后触发，以指示该函数需要计算并返回全局汇总统计信息，而不是累积批次级别的统计信息
  • callbacks (的列表 TrainerCallback, ，可选) — 用于自定义训练循环的回调列表。这些回调将被添加到 此处详述的默认回调列表中。如需移除某个默认回调，请使用 Trainer.remove_callback() 方法。.

    如果要移除其中一个默认使用的回调，请使用 Trainer.remove_callback() 方法。

  • optimizers (tuple[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR]，可选，默认为 (None, None)) — 一个包含要使用的优化器和调度器的元组。默认情况下，将在您的模型上使用 AdamW 的实例，并使用由 args 控制的、通过 get_linear_schedule_with_warmup() 给出的调度器。
  • optimizer_cls_and_kwargs (tuple[Type[torch.optim.Optimizer], dict[str, Any]], 可选) — 一个元组，包含要使用的优化器类和关键字参数。 覆盖 optim 和 optim_args 中的 args. 与 optimizers 参数不兼容。

    与 optimizers 不同，此参数可避免在初始化 Trainer 之前将模型参数放置到正确设备上。

  • preprocess_logits_for_metrics (Callable[[torch.Tensor, torch.Tensor], torch.Tensor], 可选) — 一个函数，用于在每次评估步骤缓存 logits 之前对其进行预处理。该函数必须接收两个张量（logits 和 labels），并返回处理后的 logits。此函数所做的修改将反映在传递给 compute_metrics.

    请注意，如果数据集没有标签，则标签（第二个参数）将为 None。

Trainer 是一个简单但功能完备的 PyTorch 训练和评估循环，专为 🤗 Transformers 进行了优化。

重要属性：

  • model — 始终指向核心模型。如果使用 transformers 模型，它将是 PreTrainedModel 的子类。
  • model_wrapped — 始终指向最外层的模型，以防一个或多个其他模块对原始模型进行了包装。这是用于前向传播的模型。例如，在 DeepSpeed 下，内部模型先被 DeepSpeed 包装，然后又被 torch.nn.DistributedDataParallel 包装。如果内部模型未被包装，则 self.model_wrapped 与 self.model 相同。
  • is_model_parallel — 模型是否已切换到模型并行模式（与数据并行不同，这意味着模型的部分层被拆分到不同的 GPU 上）。
  • place_model_on_device — 是否自动将模型放置到设备上。除非启用了模型并行、DeepSpeed、FSDP、完整的 fp16/bf16 评估或 SageMaker MP，否则默认为 True。可以通过子类化 TrainingArguments 并重写 place_model_on_device 属性来覆盖此设置。
  • is_in_train — 模型当前是否正在运行 train（例如，在 train 期间调用 evaluate 时）
  • loss_is_scaled_for_ga — compute_loss 返回的损失是否已针对梯度累积进行缩放。True：training_step 直接使用该值。False：training_step 会将其除以梯度累积步数。None（默认值）：当损失已通过 num_items_in_batch 进行归一化时，即当模型接受损失关键字参数或传入了 compute_loss_func 时，该损失被视为已缩放。自行计算损失的子类应设置此参数。

add_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback )

参数

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

将回调添加到当前的 TrainerCallback 列表中。

autocast_smart_context_manager

< >

( cache_enabled: bool | None = True )

一个辅助包装器，用于根据具体情况创建适用于 autocast 的上下文管理器，并向其传入所需的参数。我们依赖 accelerate 来实现 autocast，因此此处不做任何处理。

call_model_init

< >

( trial: optuna.Trial | dict[str, Any] | None = None )

调用 model_init 以获取一个新的模型实例，可选择性地基于超参数试验进行条件化。

compute_loss

< >

( model: Moduleinputs: dict[str, typing.Union[torch.Tensor, typing.Any]]return_outputs: bool = Falsenum_items_in_batch: typing.Union[int, torch.Tensor, NoneType] = None )

参数

  • model (nn.Module) — 用于计算损失的模型。
  • inputs (dict[str, torch.Tensor | Any]) — 模型的输入数据。
  • return_outputs (bool，可选，默认为 False) — 是否同时返回模型输出和损失。
  • num_items_in_batch (Optional[torch.Tensor], 可选) — 批次中的样本数量。如果未传入，则使用默认的批次大小归约逻辑来计算损失。

Trainer 计算损失的方式。默认情况下，所有模型都在第一个元素中返回损失。

通过子类化并重写来自定义行为。如果您自行计算损失，请设置 loss_is_scaled_for_ga 以说明该损失是否已针对梯度累积进行了缩放：如果它是每个批次的平均值，则设为 False（Trainer 随后会将其除以梯度累积步数）；如果您已经对整个累积批次进行了归一化，则设为 True。

compute_loss_context_manager

< >

( )

一个用于将多个上下文管理器组合在一起的辅助包装器。

create_accelerator_and_postprocess

< >

( )

创建 accelerator 并执行创建后的设置（FSDP、DeepSpeed 等）。

create_model_card

< >

( language: str | None = Nonelicense: str | None = Nonetags: str | list[str] | None = Nonemodel_name: str | None = Nonefinetuned_from: str | None = Nonetasks: str | list[str] | None = Nonedataset_tags: str | list[str] | None = Nonedataset: str | list[str] | None = Nonedataset_args: str | list[str] | None = None )

参数

  • language (str, 可选) — 模型的语言（如适用）
  • license (str, 可选) — 模型的许可证。如果提供给 Trainer 的原始模型来自 Hub 上的仓库，则默认使用所用预训练模型的许可证。
  • tags（str 或 list[str]，可选）— 要包含在模型卡片元数据中的一些标签。
  • model_name (str, 可选) — 模型的名称。
  • finetuned_from (str, 可选) — 用于微调此模型的模型名称（如适用）。如果原始模型来自 Hub，则默认使用传递给 Trainer 的原始模型仓库名称。
  • tasks（str 或 list[str]，可选）— 一个或多个任务标识符，将包含在模型卡片的元数据中。
  • dataset_tags (str 或 list[str]，可选) — 一个或多个数据集标签，将包含在模型卡片的元数据中。
  • dataset (str 或 list[str]，可选) — 一个或多个数据集标识符，将包含在模型卡片的元数据中。
  • dataset_args (str 或 list[str]，可选) — 一个或多个数据集参数，将包含在模型卡片的元数据中。

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

create_optimizer

< >

( model = None ) → torch.optim.Optimizer

返回值

torch.optim.Optimizer

优化器实例。

设置优化器。

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

create_optimizer_and_scheduler

< >

( num_training_steps: int )

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

我们提供了一个效果良好的合理默认值。如果您想使用其他配置，可以通过 optimizers 在 Trainer 的初始化中传入一个元组，或者在子类中重写此方法（或 create_optimizer 和/或 create_scheduler）。

create_scheduler

< >

( num_training_steps: intoptimizer: typing.Optional[torch.optim.Optimizer] = None ) → torch.optim.lr_scheduler.LRScheduler

参数

  • num_training_steps (int) — 要执行的训练步数。

返回值

torch.optim.lr_scheduler.LRScheduler

学习率调度器实例。

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

结束

< >

( )

完成跟踪器并销毁分布式进程组。

请在脚本的最末尾、所有需要其他进程的操作完成之后调用一次此函数：train()、evaluate()、predict()、save_model() 和 push_to_hub() 都会在进程之间进行通信，一旦进程组被销毁，它们就会失败。

示例：

trainer.train()
trainer.evaluate()
trainer.push_to_hub()
trainer.end()

evaluate

< >

( eval_dataset: typing.Union[torch.utils.data.Dataset, dict[str, torch.utils.data.Dataset], NoneType] = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval' )

参数

  • eval_dataset (Dataset | dict[str, Dataset], 可选) — 如需覆盖 self.eval_dataset. ，且其为 Dataset, ，则 model.forward() 方法不接受的列会被自动移除。如果传入的是字典，则会在每个数据集上进行评估，并在指标名称前添加字典键作为前缀。

    如果传入一个以数据集名称为键、以数据集为值的字典，evaluate 将对每个数据集分别运行评估。这有助于监控训练对其他数据集的影响，或者获得更细粒度的评估结果。 与 load_best_model_at_end 一起使用时，请确保 metric_for_best_model 恰好引用其中一个数据集。例如，如果为两个数据集 data1 和 data2 传入 {"data1": data1, "data2": data2}，可以指定 metric_for_best_model="eval_data1_loss" 来使用 data1 上的损失，或指定 metric_for_best_model="eval_data2_loss" 来使用 data2 上的损失。

  • ignore_keys (list[str], 可选) — 如果模型输出为字典，则指定在收集预测结果时应忽略的键列表。
  • metric_key_prefix (str, 可选，默认为 "eval") — 用作指标键前缀的可选前缀。例如，如果前缀为 “eval”（默认值），则指标 “bleu” 将被命名为 “eval_bleu”。

运行评估并返回指标。

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

您也可以通过子类化并覆盖此方法来注入自定义行为。

evaluation_loop

< >

( dataloader: DataLoaderdescription: strprediction_loss_only: bool | None = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval' )

预测/评估循环，由 Trainer.evaluate() 和 Trainer.predict() 共用。

无论是否提供标签均可使用。

floating_point_ops

< >

( inputs: dict[str, typing.Union[torch.Tensor, typing.Any]] ) → int

参数

  • inputs (dict[str, torch.Tensor | Any]) — 模型的输入和目标。

返回值

int

浮点运算次数。

对于继承自 PreTrainedModel 的模型，使用该方法计算每次反向传播 + 前向传播的浮点运算次数。如果使用其他模型，则需要在模型中实现此类方法，或者进行子类化并覆盖此方法。

get_batch_samples

< >

( epoch_iterator: Iteratornum_batches: intdevice: device )

从 epoch 迭代器中收集指定数量的批次，并可选择统计批次中的样本数量，以便正确缩放损失。

get_cp_size

< >

( )

获取上下文并行大小

get_decay_parameter_names

< >

( model: Module )

获取将应用权重衰减的所有参数名称。

此函数通过两种方式过滤参数：

  1. 按层类型（ALL_LAYERNORM_LAYERS 中指定的层实例）
  2. 通过参数名称模式（包含 ‘bias’，或 ‘norm’ 的变体）

get_eval_dataloader

< >

( eval_dataset: typing.Union[str, torch.utils.data.Dataset, NoneType] = None )

参数

  • eval_dataset (str 或 torch.utils.data.Dataset，可选) — 如果为 str，则将使用 self.eval_dataset[eval_dataset] 作为评估数据集。如果为 Dataset，则会覆盖 self.eval_dataset。如果它是 Dataset，则 model.forward() 方法不接受的列会被自动移除。

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

如果您希望注入一些自定义行为，请子类化并覆盖此方法。

get_learning_rates

< >

( )

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

get_num_trainable_parameters

< >

( )

获取可训练参数的数量。

get_optimizer_cls_and_kwargs

< >

( args: TrainingArgumentsmodel: transformers.modeling_utils.PreTrainedModel | None = None )

参数

  • args (transformers.training_args.TrainingArguments) — 本次训练会话的训练参数。
  • model (PreTrainedModel，可选) — 正在训练的模型。某些优化器（GaLore、Apollo、LOMO）需要此参数。

根据训练参数返回优化器类和优化器参数。

get_optimizer_group

< >

( param: typing.Union[str, torch.nn.parameter.Parameter, NoneType] = None )

参数

  • param (str 或 torch.nn.parameter.Parameter，可选) — 需要返回其优化器组的参数。

如果提供了参数，则返回该参数的优化器组；否则，返回所有参数的优化器组。

get_sp_size

< >

( )

获取序列并行大小

get_test_dataloader

< >

( test_dataset: Dataset )

参数

  • test_dataset (torch.utils.data.Dataset, 可选) — 要使用的测试数据集。如果它是 Dataset，则 model.forward() 方法不接受的列会被自动移除。

返回测试~torch.utils.data.DataLoader。

如果您希望注入一些自定义行为，请子类化并覆盖此方法。

get_total_train_batch_size

< >

( args: TrainingArguments )

计算总批大小（micro_batch grad_accum dp_world_size）。

涵盖所有并行维度：TP、CP 和 SP。

公式：dp_world_size = world_size // (tp_size cp_size sp_size)

其中：

  • TP（张量并行）：将模型层拆分到多个 GPU 上
  • CP（上下文并行）：使用 Ring Attention（FSDP2）对序列进行切分
  • SP（序列并行）：使用 ALST/Ulysses（DeepSpeed）对序列进行拆分

所有维度相互独立且相乘：world_size = dp_size tp_size cp_size * sp_size

get_tp_size

< >

( )

从模型或 DeepSpeed 配置中获取张量并行大小。

get_train_dataloader

< >

( )

返回训练~torch.utils.data.DataLoader。

如果 train_dataset 未实现 __len__，则不使用任何采样器；否则使用随机采样器（如有必要，会针对分布式训练进行适配）。

如果您希望注入一些自定义行为，请子类化并覆盖此方法。

超参数搜索

< >

( hp_space: collections.abc.Callable[['optuna.Trial'], dict[str, float]] | None = Nonecompute_objective: collections.abc.Callable[[dict[str, float]], float] | None = Nonen_trials: int = 20direction: str | list[str] = 'minimize'backend: str | transformers.trainer_utils.HPSearchBackend | None = Nonehp_name: collections.abc.Callable[['optuna.Trial'], str] | None = None**kwargs ) → [trainer_utils.BestRun or list[trainer_utils.BestRun]]

参数

  • hp_space (Callable[["optuna.Trial"], dict[str, float]]，可选) — 定义超参数搜索空间的一个函数。将根据您的后端，默认为 default_hp_space_optuna() 或 default_hp_space_ray()。
  • compute_objective (Callable[[dict[str, float]], float]，可选) — 一个函数，用于根据 evaluate 方法返回的指标计算需要最小化或最大化的目标值。默认使用 default_compute_objective()。
  • n_trials (int，可选，默认为 100) — 用于测试的试验运行次数。
  • direction (str 或 list[str]，可选，默认为 "minimize") — 如果是单目标优化，str 类型的 direction 可以是 "minimize" 或 "maximize"。在优化验证损失时，应选择 "minimize"；在优化一个或多个指标时，应选择 "maximize"。如果是多目标优化，list[str] 类型的 direction 可以是 "minimize" 和 "maximize" 的列表。在优化验证损失时，应选择 "minimize"；在优化一个或多个指标时，应选择 "maximize"。
  • backend (str 或 ~training_utils.HPSearchBackend，可选) — 用于超参数搜索的后端。默认使用 optuna 或 Ray Tune，具体取决于已安装的是哪一个。如果两者均已安装，则默认使用 optuna。
  • hp_name (Callable[["optuna.Trial"], str]], 可选) — 用于定义试验/运行名称的函数。默认值为 None。
  • kwargs (dict[str, Any], 可选) — 传递给各后端的额外关键字参数：

返回值

[trainer_utils.BestRun 或 list[trainer_utils.BestRun]]

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

使用 optuna 或 Ray Tune 启动超参数搜索。优化目标由 compute_objective 决定，其默认行为为：在未提供评估指标时，返回评估损失；否则返回所有指标的总和。

To use this method, you need to have provided a model_init when initializing your Trainer: we need to reinitialize the model at each new run. This is incompatible with the optimizers argument, so you need to subclass Trainer and override the method create_optimizer_and_scheduler() for custom optimizer/scheduler.

init_hf_repo

< >

( token: str | None = Noneprivate: bool | None = None )

参数

  • token (str, 可选) — 具有写入权限的 Token。默认为 self.args.hub_token。
  • private (bool，可选) — 创建仓库时是否将其设为私有。默认值为 self.args.hub_private_repo。如果仓库已存在，则此参数无效。

在 self.args.hub_model_id 中初始化一个 git 仓库。

is_local_process_zero

< >

( )

此过程是否为本地（例如，在多台机器上以分布式方式训练时，其中一台机器上的）主进程。

is_world_process_zero

< >

( )

此过程是否为全局主进程（在多台机器上进行分布式训练时，仅有一个进程为 True）。

日志

< >

( logs: dict[str, float]start_time: float | None = None )

参数

  • logs (dict[str, float]) — 要记录的值。
  • start_time (Optional[float]) — 训练的起始时间。

在监控训练的各种对象上记录 logs。

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

log_metrics

< >

( splitmetrics )

参数

  • split (str) — 模式/拆分名称：train、eval 或 test 之一
  • metrics (dict[str, float]) — 从 train/evaluate/predict 返回的指标：metrics 字典

以特殊格式记录指标。

在分布式环境中，此操作仅由 rank 为 0 的进程执行。

内存报告说明：

要获取内存使用报告，您需要安装 psutil。您可以通过 pip install psutil 来安装。

现在，当运行此方法时，您将看到一份报告，其中包含：

init_mem_cpu_alloc_delta   =     1301MB
init_mem_cpu_peaked_delta  =      154MB
init_mem_gpu_alloc_delta   =      230MB
init_mem_gpu_peaked_delta  =        0MB
train_mem_cpu_alloc_delta  =     1345MB
train_mem_cpu_peaked_delta =        0MB
train_mem_gpu_alloc_delta  =      693MB
train_mem_gpu_peaked_delta =        7MB

了解报告：

  • 第一个片段，例如 train__，表示这些指标所属的阶段。以 init_ 开头的报告会被添加到第一个执行的阶段中。因此，如果只运行了评估，__init__ 的内存使用情况将与 eval_ 指标一起报告。
  • 第三段是 cpu 或 gpu，用于指示该指标是通用内存还是 gpu0 内存。
  • *_alloc_delta - 是阶段结束与开始之间已用/已分配内存计数器的差值 - 如果函数释放的内存多于其分配的内存，该值可能为负数。
  • *_peaked_delta - 指已消耗随后又释放的额外内存 - 相对于当前已分配内存计数器 - 其值永不为负。查看任意阶段的指标时，将 alloc_delta + peaked_delta 相加，即可得知完成该阶段所需的内存量。

报告仅在 rank 0 的进程以及 gpu 0（如果存在 gpu）上执行。通常这已经足够了，因为主进程承担了大部分工作，但如果使用了模型并行，情况可能并非如此，因为其他 GPU 可能使用不同数量的 gpu 内存。在 DataParallel 下情况也各不相同，因为 gpu0 需要存储所有参与 GPU 的梯度和优化器状态，因此它所需的内存可能远多于其他 GPU。未来这些报告可能会进一步演进，以同时测量这些指标。

CPU RAM 指标衡量的是 RSS（常驻集大小），它既包含进程独占的内存，也包含与其他进程共享的内存。需要注意的是，该指标不包含已交换到磁盘的内存，因此报告结果可能不够精确。

CPU 峰值内存通过采样线程进行测量。由于 Python 的 GIL 机制，如果该线程在内存使用达到最高值时未能获得执行机会，可能会遗漏部分峰值内存。因此，此报告的数值可能低于实际值。使用 tracemalloc 可以报告精确的峰值内存，但它不会报告 Python 之外的内存分配。因此，如果某些 C++ CUDA 扩展分配了自身的内存，这些内存将不会被报告。所以，我们放弃了该方法，转而采用内存采样方式，即读取当前进程的内存使用情况。

GPU 分配内存和峰值内存的报告是通过 torch.cuda.memory_allocated() 和 torch.cuda.max_memory_allocated() 完成的。该指标仅报告 PyTorch 特定分配的“增量”，因为 torch.cuda 内存管理系统不会跟踪在 PyTorch 之外分配的内存。例如，第一个 CUDA 调用通常会加载 CUDA 内核，这可能占用 0.5 到 2GB 的 GPU 内存。

请注意，此跟踪器不会统计 Trainer 的 __init__、train、evaluate 和 predict 调用之外的内存分配。

由于 evaluation 调用可能发生在 train 期间，我们无法处理嵌套调用，因为 torch.cuda.max_memory_allocated 是一个单一计数器，如果它被嵌套的 eval 调用重置，train 的跟踪器将报告错误的信息。如果这个 pytorch issue 得到解决，就可以将该类改为可重入。在此之前，我们只会跟踪 train、evaluate 和 predict 方法的最外层。这意味着，如果在 train 期间调用了 eval，将由后者（即 train）来统计其自身的内存使用量以及前者的内存使用量。

这也意味着，如果与 Trainer 一起使用的任何其他工具调用了 torch.cuda.reset_peak_memory_stats，GPU 峰值内存统计信息可能会失效。此外，Trainer 会干扰那些依赖自行调用 torch.cuda.reset_peak_memory_stats 的工具的正常运行。

为了获得最佳性能，您可能需要考虑在生产运行中关闭内存分析。

metrics_format

< >

( metrics: dict[str, float] ) → metrics (dict[str, float])

参数

  • metrics (dict[str, float]) — 从 train/evaluate/predict 返回的指标

返回值

metrics（dict[str, float]）

重新格式化后的指标

将 Trainer 指标值重新格式化为人类可读的格式。

num_examples

< >

( dataloader: DataLoader )

用于通过访问其数据集来获取 ~torch.utils.data.DataLoader 中样本数量的辅助函数。当 dataloader.dataset 不存在或没有长度时，会尽可能地进行估算

pop_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback ) → TrainerCallback

参数

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

返回值

TrainerCallback

如果找到，则移除该回调。

从当前的 TrainerCallback 列表中移除一个回调并返回它。

如果未找到该回调，则返回 None（不会引发错误）。

predict

< >

( test_dataset: Datasetignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'test' )

参数

  • test_dataset (Dataset) — 用于执行预测的数据集。如果它是 datasets.Dataset，则 model.forward() 方法不接受的列会被自动移除。
  • ignore_keys (list[str], 可选) — 如果模型输出为字典，则指定在收集预测结果时应忽略的键列表。
  • metric_key_prefix (str, 可选，默认为 "test") — 用作指标键前缀的可选前缀。例如，如果前缀为 “test”（默认值），则指标 “bleu” 将被命名为 “test_bleu”。

运行预测并返回预测结果及潜在指标。

根据数据集和您的使用场景，测试数据集中可能包含标签。在这种情况下，该方法还会返回指标，类似于 evaluate() 中的情况。

如果你的预测或标签具有不同的序列长度（例如，由于你在执行动态填充的标记分类任务），预测结果将在右侧进行填充，以便能够拼接为一个数组。填充索引为 -100。

返回：NamedTuple 一个包含以下键的命名元组：

  • predictions (np.ndarray): 在 test_dataset 上的预测结果。
  • label_ids (np.ndarray，可选)：标签（如果数据集中包含标签）。
  • metrics (dict[str, float]，可选)：指标字典（如果数据集包含标签）。

prediction_step

< >

( model: Moduleinputs: dict[str, typing.Union[torch.Tensor, typing.Any]]prediction_loss_only: boolignore_keys: list[str] | None = None ) → tuple[Optional[torch.Tensor], Optional[torch.Tensor], Optional[torch.Tensor]]

参数

  • model (nn.Module) — 要评估的模型。
  • inputs (dict[str, torch.Tensor | Any]) — 模型的输入和目标。

    该字典在传入模型之前会被解包。大多数模型期望目标数据位于参数 labels 下。请查阅模型的文档以了解所有受支持的参数。

  • prediction_loss_only (bool) — 是否仅返回损失值。
  • ignore_keys (list[str], 可选) — 如果模型输出为字典，则指定在收集预测结果时应忽略的键列表。

返回值

tuple[Optional[torch.Tensor], Optional[torch.Tensor], Optional[torch.Tensor]]

一个元组，包含损失值、logits 和标签（每一项均为可选）。

使用 inputs 对 model 执行评估步骤。

通过子类化并重写来注入自定义行为。

push_to_hub

< >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )

参数

  • commit_message (str，可选，默认为 "End of training") — 推送时提交的提交信息。
  • blocking (bool，可选，默认为 True) — 是否仅在 git push 完成后才返回。
  • token (str，可选，默认为 None) — 具有写入权限的 Token，用于覆盖 Trainer 的原始参数。
  • revision (str, 可选) — 要从中提交内容的 git 修订版本。默认值为 “main” 分支的头部。
  • private (bool，可选) — 创建仓库时是否将其设为私有。默认值为 args.hub_private_repo。如果仓库已存在，则此参数无效。
  • kwargs (dict[str, Any]，可选) — 传递给 create_model_card() 的额外关键字参数。

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

remove_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback )

参数

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

从当前的 TrainerCallback 列表中移除一个回调。

save_metrics

< >

( splitmetricscombined = True )

参数

  • split (str) — 模式/拆分名称：train、eval、test、all 之一
  • metrics (dict[str, float]) — 从 train/evaluate/predict 返回的指标
  • combined（bool，可选，默认为 True）— 通过用本次调用的指标更新 all_results.json 来创建合并后的指标

将该 split 的指标保存到一个 json 文件中，例如 train_results.json。

在分布式环境中，此操作仅由 rank 为 0 的进程执行。

要了解这些指标，请阅读 log_metrics() 的文档字符串。唯一的区别是，当前方法保存的是未经格式化的原始数值。

save_model

< >

( output_dir: str | None = None_internal_call: bool = False )

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

仅从主进程保存。

save_state

< >

( )

保存 Trainer 状态，因为 Trainer.save_model 仅保存与模型关联的 tokenizer。

在分布式环境中，此操作仅由 rank 为 0 的进程执行。

set_initial_training_values

< >

( args: TrainingArgumentsdataloader: DataLoader )

计算并返回以下值：

  • num_train_epochs
  • num_update_steps_per_epoch
  • num_examples
  • num_train_samples
  • total_train_batch_size
  • steps_in_epoch（每个 epoch 的总批次数）
  • max_steps

store_flos

< >

( )

存储模型中使用的浮点运算次数。

训练

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → TrainOutput

参数

  • resume_from_checkpoint (str 或 bool，可选) — 如果为 str，则为之前 Trainer 实例保存的检查点的本地路径。如果为 bool 且等于 True，则加载之前 Trainer 实例保存在 args.output_dir 中的最后一个检查点。如果存在，训练将从此处加载的模型/优化器/调度器状态中恢复。
  • trial (optuna.Trial 或 dict[str, Any]，可选) — 用于超参数搜索的试验运行或超参数字典。
  • ignore_keys_for_eval (list[str]，可选) — 在训练过程中收集预测结果以进行评估时，应忽略的模型输出（如果输出是字典）中的键列表。

返回值

TrainOutput

包含全局步数、训练损失和指标的 Object。

主要训练入口。

training_step

< >

( model: Moduleinputs: dict[str, typing.Union[torch.Tensor, typing.Any]]num_items_in_batch: typing.Union[int, torch.Tensor, NoneType] = None ) → torch.Tensor

参数

  • model (nn.Module) — 要训练的模型。
  • inputs (dict[str, torch.Tensor | Any]) — 模型的输入和目标。

    该字典在传入模型之前会被解包。大多数模型期望目标数据位于参数 labels 下。请查阅模型的文档以了解所有受支持的参数。

返回值

torch.Tensor

该批次上的训练损失张量。

对一批输入执行一次训练步骤。

通过子类化并重写来注入自定义行为。

Seq2SeqTrainer

类 transformers.Seq2SeqTrainer

< >

( model: typing.Union[ForwardRef('PreTrainedModel'), torch.nn.Module, NoneType] = Noneargs: typing.Optional[ForwardRef('TrainingArguments')] = Nonedata_collator: typing.Optional[ForwardRef('DataCollator')] = Nonetrain_dataset: typing.Union[torch.utils.data.Dataset, ForwardRef('IterableDataset'), ForwardRef('datasets.Dataset'), NoneType] = Noneeval_dataset: typing.Union[torch.utils.data.Dataset, dict[str, torch.utils.data.Dataset], NoneType] = Noneprocessing_class: typing.Union[ForwardRef('PreTrainedTokenizerBase'), ForwardRef('BaseImageProcessor'), ForwardRef('FeatureExtractionMixin'), ForwardRef('ProcessorMixin'), NoneType] = Nonemodel_init: collections.abc.Callable[[], 'PreTrainedModel'] | None = Nonecompute_loss_func: collections.abc.Callable | None = Nonecompute_metrics: collections.abc.Callable[['EvalPrediction'], dict] | None = Nonecallbacks: list['TrainerCallback'] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)preprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = None )

evaluate

< >

( eval_dataset: typing.Optional[torch.utils.data.Dataset] = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval'**gen_kwargs )

参数

  • eval_dataset (Dataset，可选) — 如需覆盖 self.eval_dataset，请传入一个数据集。如果它是 Dataset，model.forward() 方法不接受的列会被自动移除。它必须实现 __len__ 方法。
  • ignore_keys (list[str], 可选) — 如果模型输出为字典，则指定在收集预测结果时应忽略的键列表。
  • metric_key_prefix (str，可选，默认为 "eval") — 用作指标键前缀的可选前缀。例如，如果前缀为 "eval"（默认值），则指标 “bleu” 将被命名为 “eval_bleu”。
  • max_length (int, 可选) — 使用 generate 方法进行预测时，目标序列的最大长度。
  • num_beams (int, 可选) — 使用 generate 方法进行预测时，beam search 所使用的 beam 数量。1 表示不使用 beam search。
  • gen_kwargs — generate 的额外关键字参数。

运行评估并返回指标。

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

您也可以通过子类化并覆盖此方法来注入自定义行为。

predict

< >

( test_dataset: Datasetignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'test'**gen_kwargs )

参数

  • test_dataset (Dataset) — 用于运行预测的 Dataset。如果它是 Dataset，则 model.forward() 方法不接受的列会被自动移除。必须实现 __len__ 方法
  • ignore_keys (list[str], 可选) — 如果模型输出为字典，则指定在收集预测结果时应忽略的键列表。
  • metric_key_prefix (str，可选，默认为 "eval") — 用作指标键前缀的可选前缀。例如，如果前缀为 "eval"（默认值），则指标 “bleu” 将被命名为 “eval_bleu”。
  • max_length (int, 可选) — 使用 generate 方法进行预测时，目标序列的最大长度。
  • num_beams (int, 可选) — 使用 generate 方法进行预测时，beam search 所使用的 beam 数量。1 表示不使用 beam search。
  • gen_kwargs — generate 的额外关键字参数。

运行预测并返回预测结果及潜在指标。

根据数据集和您的使用场景，测试数据集中可能包含标签。在这种情况下，该方法还会返回指标，类似于 evaluate() 中的情况。

如果您的预测或标签具有不同的序列长度（例如，由于您在执行动态填充的标记分类任务），预测结果将在右侧进行填充，以便能够拼接为一个数组。填充索引为 -100。

返回：NamedTuple 一个包含以下键的命名元组：

  • predictions (np.ndarray): 在 test_dataset 上的预测结果。
  • label_ids (np.ndarray，可选)：标签（如果数据集中包含标签）。
  • metrics (dict[str, float]，可选)：指标字典（如果数据集包含标签）。

TrainingArguments

类 transformers.TrainingArguments

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 5e-05lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool = Falsefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool | None = Nonegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 500logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Falserestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: typing.Any | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Truelabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1 )

参数

  • output_dir (str，可选，默认为 "trainer_output") — 模型预测结果和检查点将写入的输出目录。

训练时长与批大小

  • per_device_train_batch_size (int，可选，默认值为 8) — 每个设备的批大小。全局批大小的计算方式为： 在多 GPU 或分布式环境中，per_device_train_batch_size * number_of_devices。
  • num_train_epochs(float, 可选，默认值为 3.0) — 要执行的训练轮数总数（如果不是整数，则在停止训练前执行最后一个轮次的相应小数部分）。
  • max_steps (int，可选，默认为 -1) — 覆盖 num_train_epochs。如果设置为正数，则指定要执行的训练总步数。 对于有限数据集，训练会反复遍历数据集（如果所有数据已用尽），直到达到 max_steps。当训练数据集未实现 __len__（例如流式数据集）时，必须将其设置为正值，因为此时无法推断总步数，且需要该值来限定训练循环并配置学习率调度器。

学习率与调度器

  • learning_rate (float，可选，默认值为 5e-5) — 优化器的初始学习率。当使用带有预热（warmup）的调度器时，这通常是峰值学习率。
  • lr_scheduler_type (str 或 SchedulerType, 可选, 默认为 "linear") — 要使用的学习率调度器类型。请参阅 SchedulerType 以查看所有可能的值。常见选择：
  • lr_scheduler_kwargs (dict 或 str，可选，默认为 None) — lr_scheduler 的额外参数。有关可能的取值，请参阅各调度器的文档。
  • warmup_steps (int 或 float, 可选, ，默认为 0）— 从 0 线性预热到 learning_rate. 的步数。预热有助于在训练初期稳定训练过程。可以是：
    • 一个整数：预热步数的精确值
    • 范围在 [0, 1) 内的浮点数：解释为总训练步数的比例

优化器

  • optim (str 或 training_args.OptimizerNames, 可选, 默认为 "adamw_torch" (适用于 torch>=2.8 "adamw_torch_fused")) — 要使用的优化器。常用选项：
    • "adamw_torch"：PyTorch 的 AdamW（推荐的默认值）
    • "adamw_torch_fused"：融合 AdamW 内核
    • "adamw_hf"：HuggingFace 的 AdamW 实现
    • "sgd"：带动量的随机梯度下降
    • "adafactor"：适用于大型模型的内存高效优化器
    • "adamw_8bit"：8 位 AdamW（需要 bitsandbytes） 完整列表请参见 OptimizerNames。
  • optim_args (str, 可选) — 传递给优化器（如 AnyPrecisionAdamW、AdEMAMix 和 GaLore）的可选参数。
  • weight_decay (float, 可选，默认为 0) — 优化器应用的权重衰减系数（而非损失函数）。通过惩罚较大的权重来添加 L2 正则化，以防止过拟合。自动排除 bias 和 LayerNorm 参数。典型值：0.01（标准）、0.1（更强的正则化）、0.0（无正则化）。
  • adam_beta1 (float, 可选，默认为 0.9) — 基于 Adam 的优化器中一阶矩估计（动量）的指数衰减率。控制保留多少梯度历史。
  • adam_beta2 (float, 可选，默认值为 0.999) — 基于 Adam 的优化器中二阶矩估计（方差）的指数衰减率。用于控制自适应学习率的缩放。
  • adam_epsilon (float，可选，默认值为 1e-8) — 基于 Adam 的优化器中用于数值稳定性的 Epsilon 值。可防止更新规则分母中出现除以零的情况。
  • optim_target_modules (Union[str, list[str]], 可选) — 要优化的目标模块，即您希望进行训练的模块名称。 目前用于 GaLore 算法 和 APOLLO 算法。 有关更多详细信息，请参阅 GaLore 实现 和 APOLLO 实现。 请确保传入有效的 GaLore 或 APOLLO 优化器，例如：“apollo_adamw”、“galore_adamw”、“galore_adamw_8bit”、“galore_adafactor”，并确保目标模块仅为 nn.Linear 模块。

正则化与训练稳定性

  • gradient_accumulation_steps (int, 可选, ，默认值为 1）— 在执行反向传播/更新之前累积梯度的更新步数。 可在不增加额外内存的情况下模拟更大的批大小。有效批大小 = per_device_train_batch_size × num_devices × gradient_accumulation_steps.

    在使用梯度累积时，一个“step”被计为一次带有反向传播的 step。因此，日志记录、评估和保存将每 gradient_accumulation_steps × xxx_step 个训练样本发生一次。

  • average_tokens_across_devices (bool，可选，默认为 True) — 是否跨设备对 token 取平均值。如果启用，将使用 all_reduce 来同步 num_tokens_in_batch，以实现精确的损失计算。参考： https://github.com/huggingface/transformers/issues/34242
  • max_grad_norm (float，可选，默认值为 1.0) — 用于梯度裁剪的最大梯度范数。在反向传播之后、优化器更新之前应用。当梯度的全局范数超过此阈值时，通过缩小梯度来防止梯度爆炸。设置为 0 可禁用裁剪。典型取值：1.0（标准）、0.5（更保守）、5.0（更宽松）。
  • label_smoothing_factor (float，可选，默认为 0.0) — 标签平滑系数，用于防止模型过度自信。它将硬性的 0/1 目标替换为软目标：0 变为 ε/num_labels，1 变为 1 - ε + ε/num_labels，其中 ε = label_smoothing_factor。设为 0 表示不进行平滑。典型取值范围：0.0 到 0.1。

混合精度训练

  • bf16 (bool，可选，默认为 False) — 启用 bfloat16 (BF16) 混合精度训练 通常优先于 FP16，因为具有更好的数值稳定性，且无需进行损失缩放。
  • fp16 (bool，可选，默认为 False) — 启用 float16 (FP16) 混合精度训练。 如果硬件支持，建议改用 BF16。
  • bf16_full_eval (bool，可选，默认为 False) — 在评估时使用完整的 BF16 精度（而不仅仅是混合精度）。速度更快且节省内存，但可能会略微影响指标数值。仅在评估阶段生效。
  • fp16_full_eval (bool，可选，默认为 False) — 在评估时使用完整的 FP16 精度（而不仅仅是混合精度）。速度更快且节省内存，但可能会略微影响指标值。仅在评估阶段生效。
  • tf32 (bool, 可选) — 在 Ampere 及更新架构的 GPU 上启用 TensorFloat-32 (TF32) 模式。TF32 在矩阵乘法中使用 19 位精度（而非 FP32 的 23 位），在精度损失可忽略不计的情况下，可提供最高 8 倍的加速。默认值取决于 PyTorch 版本。请参阅 TF32 文档。

激活检查点

  • activation_checkpointing (bool，可选，默认为 False) — 启用激活检查点，以计算换取内存。通过在正向传播期间清除激活值并在反向传播期间重新计算它们来降低内存使用量。代价是训练速度降低约 20%，但可支持训练更大的模型或更大的批处理大小。
  • activation_checkpointing_kwargs (dict, 可选，默认为 None) — 传递给 activation_checkpointing_enable() 的关键字参数。every_n_layers 仅对每 n 个解码器层执行一次检查点，而不是对所有层执行；1 是通常的全有或全无行为，较大的值会释放一些内存以换取速度。offload 将保存的激活值存储在固定的主机内存中，这会释放 layers x sequence x hidden 字节的设备内存，但会使步骤变慢。其他任何键都会转发给 torch.utils.checkpoint.checkpoint。
  • gradient_checkpointing (bool，可选) — activation_checkpointing 的已弃用别名，将在 v6 中移除。
  • gradient_checkpointing_kwargs (dict, 可选) — activation_checkpointing_kwargs 的已弃用别名，将在 v6 中移除。

编译

  • torch_compile（bool，可选，默认为 False）— 使用 PyTorch 2.0 的 torch.compile() 编译模型以加快训练速度。无需修改代码即可提供 20-50% 的速度提升。除非指定了 torch_compile_backend 或 torch_compile_mode，否则使用默认编译设置。
  • torch_compile_backend (str, 可选) — torch.compile() 的后端。如果设置，将自动启用 torch_compile。选项包括 "inductor"（默认值）、"aot_eager"、"cudagraphs"。后端因 PyTorch 版本而异 - 请参阅 PyTorch 文档了解可用选项。
  • torch_compile_mode (str, 可选) — torch.compile() 的编译模式。如果设置，将自动启用 torch_compile。 选项："default"、"reduce-overhead"（最小化 Python 开销）、"max-autotune" （激进优化，编译时间更长）。

内核

  • use_liger_kernel (bool，可选，默认为 False) — 启用 Liger Kernel 优化。可将多 GPU 吞吐量提升约 20%，并将内存占用降低约 60%。兼容 Flash Attention、FSDP 和 DeepSpeed。目前支持 Llama、Mistral、Mixtral 和 Gemma 模型。
  • liger_kernel_config (Optional[dict], 可选) — Liger Kernel 的配置。作为 kwargs 传递给 _apply_liger_kernel_to_instance()。 选项通常包括："rope"、"swiglu"、"cross_entropy"、 "fused_linear_cross_entropy"、"rms_norm"。如果为 None，则使用默认配置。

其他优化

  • use_cache（bool，可选，默认为 False）— 是否启用模型的缓存。在训练过程中，通常不需要启用此功能，除非使用某些依赖 past_key_values 的 PEFT 方法。
  • neftune_noise_alpha (Optional[float]) — 如果不为 None，将启用 NEFTune 噪声嵌入。这可以显著提升指令微调的模型性能。请参阅原始论文和原始代码。支持 Transformers 的 PreTrainedModel，也支持来自 peft 的 PeftModel。原始论文中使用的值范围为 [5.0, 15.0]。
  • torch_empty_cache_steps (int, 可选) — 在调用 torch.<device>.empty_cache() 之前等待的步数。如果未设置或设置为 None，则不会清空缓存。 这可以通过降低峰值 VRAM 使用量来帮助避免 CUDA 内存不足错误，但代价是性能大约降低 10%。
  • auto_find_batch_size（bool，可选，默认为 False）— 是否通过指数衰减自动寻找能够放入内存的训练 batch size，以避免 CUDA Out-of-Memory 错误。评估 batch size 不会进行调整。

训练日志与监控

  • logging_strategy (str 或 IntervalStrategy, 可选, 默认为 "steps") — 训练期间采用的日志记录策略。可能的取值如下：
    • "no"：训练期间不执行任何日志记录。
    • "epoch"：日志记录在每个 epoch 结束时进行。
    • "steps"：每 logging_steps 步记录一次日志。
  • logging_steps（int 或 float，可选，默认值为 500）— 当 logging_strategy="steps" 时，两次日志记录之间的更新步数。应为整数或 [0,1) 范围内的浮点数。如果小于 1，将被解释为总训练步数的比例。
  • logging_first_step (bool，可选，默认为 False) — 是否记录第一个 global_step。
  • log_on_each_node (bool，可选，默认为 True) — 在多节点分布式训练中，是否在每个节点上都使用 log_level 记录日志，还是仅在主节点上记录。
  • logging_nan_inf_filter (bool，可选，默认为 True) — 在记录日志时过滤掉 NaN 和 Inf 损失。如果为 True，则用近期有效损失的均值替换训练损失中的 NaN/Inf，并在评估损失中排除包含 NaN/Inf 的批次（例如没有标签 token 的批次）。不影响梯度计算，仅影响日志记录。
  • include_num_input_tokens_seen (Optional[Union[str, bool]]，可选，默认为 “no”) — 是否跟踪已看到的输入 token 数量。必须是 [“all”, “non_padding”, “no”] 之一，或者是一个映射到 “all” 或 “no” 的布尔值。 在分布式训练中可能会更慢，因为必须调用 gather 操作。

日志记录

  • log_level (str，可选，默认为 passive) — 主进程的日志级别。可选值："debug"、"info"、"warning"、"error"、 "critical" 或 "passive"（不更改当前 Transformers 的日志级别， 其默认值为 "warning"）
  • log_level_replica (str，可选，默认为 "warning") — 分布式训练中副本进程的日志级别。选项与 log_level 相同。
  • disable_tqdm (bool，可选) — 禁用 tqdm 进度条。如果 log_level 为 warning 或更低，则默认为 True，否则为 False。

实验跟踪集成

  • report_to (str 或 list[str]，可选，默认为 "none") — 用于报告结果和日志的集成列表。支持的平台包括 "azure_ml"、 "clearml"、"codecarbon"、"comet_ml"、"dagshub"、"dvclive"、"flyte"、"mlflow"、"swanlab"、 "tensorboard"、"trackio" 和 "wandb"。使用 "all" 可报告到所有已安装的集成，使用 "none" 表示不使用任何集成。
  • run_name (str, 可选) — 用于描述该次运行。通常用于 trackio、wandb、mlflow、comet 和 swanlab 的日志记录。
  • project (str，可选，默认为 "huggingface") — 用于日志记录的项目名称。目前仅由 Trackio 使用。
  • trackio_space_id (str 或 None，可选，默认为 None) — 用于基于 Gradio 的 Space 进行实时 Trackio 日志记录的 Hugging Face Space ID。应为完整的 Space 名称，如 'username/reponame' 或 'orgname/reponame'，或仅为 'reponame'（Space 将创建在当前登录用户的命名空间中）。如果为 None，指标仅记录到 本地 目录（Hub 上没有 Space）。该 Gradio Space 对 Trackio Bucket 具有 读写 权限，这在训练 进行中 时正是您所需要的——例如在 恢复 部分运行或从多台机器 聚合日志 时。除非您设置 hub_private_repo=True 或您的组织默认创建私有 Space，否则该 Space 将是 公开 的。
  • trackio_bucket_id（str 或 None，可选，默认为 None）— Trackio 的可选 Hugging Face Bucket id。如果未设置，Trackio 会自动派生一个。与 Gradio Space（trackio_space_id）配合使用，并在部署静态 Space（trackio_static_space_id 不为 False）时生效。
  • trackio_static_space_id (str、False 或 None，可选，默认为 None) — 训练完成后用于创建静态 Space 的 Hugging Face Space ID。应为完整的 Space 名称，例如 'username/reponame' 或 'orgname/reponame'，或者仅为 'reponame'（该 Space 将创建在当前登录用户的命名空间中）。如果为 False，则不会创建静态 Space。如果为 None 且模型已推送到 Hub，则会使用默认名称创建一个静态 Space，并从模型卡片中链接到该 Space。除非您设置了 hub_private_repo=True 或您的组织默认创建私有 Space，否则该 Space 将是公开的。

评估

  • eval_strategy (str 或 IntervalStrategy, 可选, 默认为 "no") — 何时运行评估。选项：
    • "no"：训练期间不进行任何评估
    • "steps"：每 eval_steps 步执行一次评估
    • "epoch"：在每个 epoch 结束时进行评估
  • eval_steps（int 或 float，可选）— 如果 eval_strategy="steps"，则指定两次评估之间的更新步数。如果未设置，默认值与 logging_steps 相同。应为整数或 [0,1) 范围内的浮点数。如果小于 1，将被解释为总训练步数的比例。
  • eval_delay (float, 可选) — 根据 eval_strategy，在首次执行评估之前需要等待的 epoch 数或步数。
  • per_device_eval_batch_size (int，可选，默认为 8) — 评估时每个设备加速器核心/CPU 的批大小。
  • prediction_loss_only（bool，可选，默认为 False）— 在执行评估并生成预测时，仅返回损失值。
  • eval_on_start（bool，可选，默认为 False）— 是否在训练开始前执行一次评估步骤（健全性检查），以确保验证步骤能正确运行。
  • eval_do_concat_batches (bool，可选，默认为 True) — 是否递归地跨批次拼接输入/损失/标签/预测值。如果为 False，则改为将它们存储为列表，每个批次保持独立。
  • eval_use_gather_object (bool，可选，默认为 False) — 是否对所有设备上的嵌套列表/元组/字典中的对象执行递归 gather 操作。仅当用户返回的内容不仅仅是张量时才应启用此选项，且 PyTorch 明确不推荐这样做。 当标签结构非标准时（例如在计算机视觉任务中），此选项非常有用。
  • eval_accumulation_steps (int, 可选) — 在将结果移至 CPU 之前，用于累积输出张量的预测步数。如果未设置，则所有预测结果都将在设备加速器上累积，然后再移至 CPU（速度更快，但需要更多内存）。

指标计算

  • include_for_metrics (list[str], 可选, 默认为 []) — 在需要计算指标时，将额外数据包含在 compute_metrics 函数中。 可添加到 include_for_metrics 列表中的选项：
    • "inputs"：传递给模型的输入数据，用于计算依赖于输入的指标。
    • "loss"：在评估期间计算得出的损失值，用于计算依赖于损失的指标。
  • batch_eval_metrics (bool，可选，默认为 False) — 如果设置为 True，评估将在每个批次结束时调用 compute_metrics 来累积统计信息，而不是将所有评估 logits 保存在内存中。当设置为 True 时，必须传入一个 compute_metrics 函数，该函数接受一个布尔参数 compute_result；当传入 True 时，将基于你在评估集上累积的批次级统计信息，触发最终的全局汇总统计。

检查点与保存

  • save_only_model (bool，可选，默认为 False) — 仅保存模型权重，不保存优化器/调度器/RNG 状态。这会显著减小检查点的大小，但无法从该检查点恢复训练。当只需要使用训练好的模型进行推理，而不需要继续训练时，请使用此选项。 将此选项设置为 True 后，只能通过 from_pretrained 加载模型。
  • save_strategy (str 或 SaveStrategy, 可选, 默认为 "steps") — 训练期间采用的检查点保存策略。可能的取值如下：
    • "no"：训练过程中不会执行任何保存操作。
    • "epoch"：在每个 epoch 结束时执行保存。
    • "steps"：每 save_steps 步执行一次保存。
    • "best"：每当达到新的 best_metric 时执行保存。
  • save_steps（int 或 float，可选，默认值为 500）— 当 save_strategy="steps" 时，两次保存检查点之间的更新步数。应为整数或 [0,1) 范围内的浮点数。如果小于 1，将被解释为总训练步数的比例。
  • save_on_each_node (bool，可选，默认为 False) — 在进行多节点分布式训练时，是否在每个节点上保存模型和检查点，还是仅在主要节点上保存。 当不同节点使用相同的存储时，不应启用此选项，因为每个节点保存的文件将具有相同的名称。
  • save_total_limit (int, 可选) — 要保留的检查点最大数量。会删除 output_dir 中较旧的检查点。当 load_best_model_at_end=True 时，始终保留最佳检查点以及最近的检查点。例如，save_total_limit=5 会保留最近的 4 个检查点以及最佳检查点
  • enable_jit_checkpoint (bool，可选，默认为 False) — 在收到 SIGTERM 信号时启用即时（Just-In-Time）检查点，以便在可抢占工作负载上实现优雅终止。重要：请配置编排器的优雅关闭时间，以确保有足够的时间。对于 Kubernetes，请设置 terminationGracePeriodSeconds（默认的 30 秒通常不够）。对于 Slurm，请使用 --signal=TERM@<seconds>。所需的优雅关闭时间 ≥ 最长迭代时间 + 检查点保存时间。

Hugging Face Hub 集成

  • push_to_hub (bool，可选，默认为 False) — 是否在每次保存模型时将其推送到 Hub。如果启用此选项，output_dir 将启动一个与仓库（由 hub_model_id 确定）同步的 git 目录，并且每次触发保存时（取决于您的 save_strategy）都会推送内容。调用 save_model() 也会触发推送。
  • hub_token (str, 可选) — 用于将模型推送到 Hub 的令牌。默认使用通过 hf auth login 获取并存储在缓存文件夹中的令牌。
  • hub_private_repo (bool, 可选) — 是否将仓库设为私有。如果为 None（默认值），除非组织的默认设置为私有，否则仓库将是公开的。如果仓库已存在，则忽略此值。如果启用了部署到 Hugging Face Spaces 的 Trackio 报告，相同的逻辑将决定该 Space 是否为私有。
  • hub_model_id (str, 可选) — 要与本地 output_dir 保持同步的仓库名称。它可以是一个简单的模型 ID，在这种情况下，模型将推送到你的命名空间。否则，它应该是完整的仓库名称，例如 "user_name/model"，这允许你使用 "organization_name/model" 推送到你所属的组织。默认值为 user_name/output_dir_name，其中 output_dir_name 是 output_dir 的名称。
  • hub_strategy (str 或 HubStrategy, 可选, 默认为 "every_save") — 定义推送至 Hub 的内容和时机。选项：
    • "end"：仅在训练结束时推送
    • "every_save"：每次保存时推送（异步执行，以免阻塞训练）
    • "checkpoint"：与 "every_save" 类似，但会将最新的检查点推送到 "last-checkpoint" 子文件夹中，以便于恢复训练
    • "all_checkpoints"：推送所有出现的检查点
  • hub_always_push (bool，可选，默认为 False) — 除非此参数为 True，否则 Trainer 会在上一次推送尚未完成时跳过推送检查点。
  • hub_revision (str, 可选) — 推送到 Hub 时使用的版本。可以是分支名称、标签或提交哈希。

最佳模型跟踪

  • load_best_model_at_end (bool，可选，默认为 False) — 在训练结束时加载最佳检查点。需要设置 eval_strategy。 启用后，最佳检查点始终会被保存（参见 save_total_limit）。 当为 `True` 时，`save_strategy` 必须与 `eval_strategy` 匹配（除非 `save_strategy` 为 `"best"`），并且如果使用 `"steps"`， `save_steps` 必须是 `eval_steps` 的倍数。
  • metric_for_best_model (str, 可选) — 当 load_best_model_at_end=True 时，用于比较模型的指标。必须是评估返回的指标名称，可以带或不带 "eval_" 前缀。默认值为 "loss"。 如果设置了此项，除非名称以 "loss" 结尾，否则 greater_is_better 的默认值为 True。示例："accuracy"、"f1"、"eval_bleu"。
  • greater_is_better (bool，可选) — 是否指标值越高越好。默认值基于 metric_for_best_model： 如果指标名称不以 "loss" 结尾，则为 True，否则为 False。

恢复训练

  • ignore_data_skip (bool，可选，默认为 False) — 恢复训练时，跳过通过数据集快速前进以到达先前状态的操作。如果为 True，训练将从数据集的开头开始（恢复速度更快，但结果与中断前的训练不匹配）。如果为 False，则跳过已查看的数据（恢复速度较慢，但可精确继续）。
  • restore_callback_states_from_checkpoint (bool，可选，默认为 False) — 在恢复训练时从检查点恢复回调状态。如果为 True，且检查点中存在这些回调，则会覆盖传递给 Trainer 的回调。

可复现性

  • full_determinism (bool，可选，默认为 False) — 如果为 True，将调用 enable_full_determinism() 而非 set_seed()，以确保分布式训练中的结果可复现。重要提示：这会负面影响性能，因此仅建议在调试时使用。
  • seed (int，可选，默认为 42) — 将在训练开始时设置的随机种子。为了确保多次运行之间的可复现性，如果模型包含随机初始化的参数，请使用 ~Trainer.model_init 函数来实例化该模型。
  • data_seed (int, 可选) — 用于数据采样器的随机种子。如果未设置，数据采样的随机生成器将使用与 seed 相同的种子。这可用于确保数据采样的可复现性，且独立于模型种子。

硬件配置

  • use_cpu (bool，可选，默认为 False) — 是否使用 CPU。如果设置为 False，我们将使用可用的 torch 设备/后端。

Accelerate 配置

  • accelerator_config (str, dict, 或 AcceleratorConfig, 可选) — 内部 Accelerate 集成的配置。可以是： 指向 JSON 配置文件的路径："accelerator_config.json" 包含配置选项的字典 AcceleratorConfig 实例 主要选项：split_batches (bool, 默认为 False)：是否跨设备拆分批次。如果为 True，所有设备上的实际批次大小相同（总数必须能被 num_processes 整除）。如果为 False，每个设备获得指定的批次大小。dispatch_batches (bool)：如果为 True，仅主进程遍历 dataloader 并将批次分发到各设备。对于 IterableDataset 默认为 True，否则为 False。even_batches (bool, 默认为 True)：从数据集开头复制样本，以确保所有 worker 获得相等的批次大小。use_seedable_sampler (bool, 默认为 True)：使用完全可播种的随机采样器以实现可复现性。use_configured_state (bool, 默认为 False)：使用预初始化的 AcceleratorState/PartialState，而不是创建新的实例。这可能会导致超参数调优出现问题。
    • JSON 配置文件的路径："accelerator_config.json"
    • 包含配置选项的字典
    • AcceleratorConfig 实例 主要选项：
    • split_batches（bool，默认为 False）：是否将批次拆分到各个设备上。 如果为 True，则所有设备上的实际批次大小相同（总数必须能被 num_processes 整除）。如果为 False，则每个设备获得指定的批次大小。
    • dispatch_batches（bool）：如果为 True，则仅主进程遍历 dataloader 并将批次分发到各设备。对于 IterableDataset，默认值为 True，否则为 False。
    • even_batches（bool，默认为 True）：从数据集开头复制样本，以确保所有工作进程获得相同的批次大小。
    • use_seedable_sampler (bool，默认为 True)：使用完全可复现的随机采样器，以确保结果的可重复性。
    • use_configured_state (bool，默认为 False)：使用预先初始化的 AcceleratorState/PartialState，而不是创建新的实例。这可能会导致超参数调优出现问题。
  • parallelism_config (ParallelismConfig，可选) — 训练运行的并行配置。需要 Accelerate 1.10.1

Dataloader

  • dataloader_drop_last (bool，可选，默认为 False) — 是否丢弃最后一个不完整的批次（当数据集长度不能被批次大小整除时）。
  • dataloader_num_workers (int，可选，默认为 0) — 用于数据加载的子进程数量（仅适用于 PyTorch）。0 表示数据将在主进程中加载。
  • dataloader_pin_memory (bool，可选，默认为 True) — 是否要在数据加载器中固定内存。默认值为 True。
  • dataloader_persistent_workers (bool，可选，默认为 False) — 如果为 True，数据加载器在数据集被消费一次后不会关闭工作进程。 这可以保持工作进程中的 Dataset 实例处于活动状态。可能会加速训练，但会增加内存使用量。默认为 False。
  • dataloader_prefetch_factor (int, 可选) — 每个 worker 预先加载的批次数量。 2 表示所有 worker 总共会预取 2 * num_workers 个批次。
  • dataloader_multiprocessing_context (str, 可选) — 用于数据加载工作进程的多进程启动方法（"fork"、"spawn" 或 "forkserver"）。默认使用 PyTorch 的默认启动方法，但在 MPS 上且 dataloader_num_workers > 1 时，默认值为 "fork"。当从对象不支持 fork 的来源（例如通过 pyarrow 访问的 HDFS）进行流式读取时，请使用 "spawn"。在 "spawn" 模式下，任何自定义的 collate_fn 或数据集代码都必须在模块级别可导入（不能使用 lambda 函数或闭包）。
  • dataloader_in_order (bool，可选，默认为 True) — 如果为 True，数据加载器将按照 worker 被调度的顺序返回批次。将其设置为 False 可在批次就绪时立即返回，从而降低 IterableDataset 流式工作负载的尾部延迟。需要 PyTorch >= 2.6。
  • remove_unused_columns（bool，可选，默认为 True）—— 是否自动移除模型 forward 方法未使用的列。
  • label_names (list[str], 可选) — 输入字典中对应标签的键列表。 最终将默认为模型接受的参数名中包含“label”一词的列表， 但如果使用的模型是 XxxForQuestionAnswering 之一，则还会包含 ["start_positions", "end_positions"] 键。 仅当使用自定义标签名称，或模型的 forward 消耗多个标签张量（例如抽取式问答）时，才应指定 label_names。
  • train_sampling_strategy (str, 可选, 默认值为 "random") — 用于训练数据加载器的采样器。可选值如下：
    • "random"：使用 RandomSampler（默认）。
    • "sequential"：使用 SequentialSampler。
    • "group_by_length"：使用 LengthGroupedSampler 将长度大致相同的样本分组在一起（以减少填充，提高效率）。
    • "batch_rebalance"：使用 BatchRebalanceSampler 在每个有效批次内平衡各设备以及梯度累积步骤之间的填充 token 开销，与 "group_by_length" 相比，可减少填充浪费并降低峰值内存。目前仅支持数据并行训练（尚不支持张量并行）。

    注意：当使用 IterableDataset 时，此参数将被忽略。

  • length_column_name (str, 可选，默认为 "length") — 预计算长度的列名。如果该列存在，按长度分组时将使用这些值，而不是在训练启动时进行计算。除非 train_sampling_strategy 为 "group_by_length" 或 "batch_rebalance" 且数据集是 Dataset 的实例，否则此参数将被忽略。

DDP（DistributedDataParallel）

  • ddp_find_unused_parameters (bool, 可选) — 在使用分布式训练时，传递给 DistributedDataParallel 的 find_unused_parameters 标志的值。如果使用了梯度检查点，则默认为 False，否则为 True。
  • ddp_bucket_cap_mb (int，可选) — 在使用分布式训练时，传递给 DistributedDataParallel 的 bucket_cap_mb 标志的值。
  • ddp_broadcast_buffers (bool，可选) — 在使用分布式训练时，传递给 DistributedDataParallel 的 broadcast_buffers 标志的值。如果使用了梯度检查点，则默认为 False，否则为 True。
  • ddp_static_graph (bool, 可选) — 在使用分布式训练时，传递给 DistributedDataParallel 的 static_graph 标志的值。
  • ddp_backend (str, 可选) — 用于分布式训练的 backend。必须是 "nccl"、"mpi"、"xccl"、"gloo"、"hccl" 之一。
  • ddp_timeout (int，可选，默认值为 1800) — torch.distributed.init_process_group 调用的超时时间，用于在分布式运行中执行耗时操作时避免 GPU 套接字超时。有关更多信息，请参阅 PyTorch 文档。

FSDP（Fully Sharded Data Parallel）

  • fsdp (bool，可选，默认为 None) — 启用 PyTorch Fully Sharded Data Parallel (FSDP) 以进行分布式训练。传入 True 以启用 FSDP。
  • fsdp_config (str 或 dict, 可选) — 启用 fsdp 时的配置设置。传入 JSON 配置文件的路径，例如 fsdp_config.json, ，或已加载的 dict。

    支持的键：

    • version (int，可选，默认为 2)： 要使用的 FSDP 版本（2 表示 FSDP2，1 表示旧版 FSDP1）。
    • reshard_after_forward (bool, 可选, 默认为 True): 是否在前向传播后重新分片参数。将其设置为 False 可在前向传播和反向传播之间保持参数聚合状态，避免重新执行 all-gather 操作，但会占用更高的峰值内存。
    • cpu_offload (bool，可选，默认为 False)： 在参数和梯度未使用时将其卸载到 CPU，以节省 GPU 内存。
    • activation_checkpointing (bool, 可选, 默认为 False): 设置为 True 可在反向传播过程中通过重新计算激活值来减少内存占用。在使用 FSDP 时，建议优先使用此参数，而非 activation_checkpointing 训练参数，因为后者会在反向传播中引入冗余的 all-gather 操作。
    • cpu_ram_efficient_loading (bool, 可选，默认为 False)： 设置为 True 时，仅在第一个进程上加载预训练检查点。其他进程以空权重启动，并通过广播接收权重。
    • state_dict_type (str，可选，默认为 "FULL_STATE_DICT")： 检查点格式："FULL_STATE_DICT"（单个兼容 HF 的文件）或 "SHARDED_STATE_DICT"（每个 rank 一个文件，对大型模型更快）。
    • auto_wrap_policy (str, 可选，默认为 "TRANSFORMER_BASED_WRAP")： 要使用的自动包装策略。选择 "TRANSFORMER_BASED_WRAP"、"SIZE_BASED_WRAP" 或 "NO_WRAP"。
    • transformer_layer_cls_to_wrap (list[str], 可选)： 需要包装的 Transformer 层类名（区分大小写），例如 LlamaDecoderLayer。通常无需设置：包装策略会回退到模型的 _no_split_modules，该属性涵盖了大多数 transformers 模型。
    • min_num_params (int, 可选，默认为 0)： 用于基于大小的自动包装时，每个模块所需的最小参数量（与 auto_wrap_policy="SIZE_BASED_WRAP" 配合使用）。
    • xla (bool，可选，默认为 False)： 是否使用 PyTorch/XLA 完全分片数据并行训练。实验性功能。
    • xla_fsdp_settings (dict, 可选)： XLA FSDP 包装参数的字典。完整的选项列表，请参阅 XLA FSDP 源代码。
    • xla_fsdp_grad_ckpt (bool, 可选，默认为 False)： 设置为 True 以在每个嵌套的 XLA FSDP 包装层上使用梯度检查点。需要 xla=True 以及自动包装策略（min_num_params 或 transformer_layer_cls_to_wrap）。

DeepSpeed

  • deepspeed (str 或 dict, 可选) — 启用 DeepSpeed 集成。取值可以是：
    • DeepSpeed JSON 配置文件的路径："ds_config.json"
    • 已加载配置为字典

      如果使用 ZeRO 初始化，请在初始化 TrainingArguments 之后再实例化模型，否则 ZeRO 将不会生效。

调试与性能分析（实验性）

  • debug (str 或 DebugOption, 可选, 默认为 "") — 启用一个或多个调试功能。这是一个实验性功能。 可选选项包括：
    • “underflow_overflow”：检测模型输入/输出中的溢出，并报告导致该事件的最后几帧
    • “tpu_metrics_debug”：在 TPU 上打印调试指标
  • skip_memory_metrics (bool，可选，默认为 True) — 是否跳过将内存分析器报告添加到指标中。默认情况下会跳过此操作，因为它会降低训练和评估的速度。

外部脚本标志（Trainer 未使用）

  • do_train (bool，可选，默认为 False) — 是否执行训练。该参数不会被 Trainer 直接使用，而是供您的训练/评估脚本使用。
  • do_eval (bool, 可选) — 是否对验证集运行评估。如果 eval_strategy 不同于 "no"，则会被设置为 True。此参数不会被 Trainer 直接使用，而是供您的训练/评估脚本使用。
  • do_predict (bool，可选，默认为 False) — 是否对测试集运行预测。该参数不会被 Trainer 直接使用，而是供您的训练/评估脚本使用。
  • resume_from_checkpoint (str, 可选) — 指向包含模型有效检查点文件夹的路径。此参数不会被 Trainer 直接使用，而是供您的训练/评估脚本使用。

用于控制 Trainer 模型训练所有方面的配置类。 TrainingArguments 集中管理了训练所需的所有超参数、优化设置、日志记录偏好以及基础设施选择。

HfArgumentParser 可以将此类转换为 argparse 参数，从而可以在命令行中指定。

get_process_log_level

< >

( )

根据此进程是节点 0 的主进程、非 0 节点的主进程还是非主进程，返回要使用的日志级别。

对于主进程，除非被 log_level 参数覆盖，否则日志级别默认为已设置的日志级别（如果您未进行任何设置，则为 logging.WARNING）。

对于副本进程，除非通过 log_level_replica 参数进行覆盖，否则日志级别默认为 logging.WARNING。

主进程与副本进程设置之间的选择，是根据 should_log 的返回值来确定的。

get_warmup_steps

< >

( num_training_steps: int )

获取线性预热所使用的步数。

main_process_first

< >

( local = Truedesc = 'work' )

参数

  • local (bool，可选，默认为 True) — 如果为 True，则“first”指每个节点上 rank 为 0 的进程；如果为 False，则“first”指 rank 为 0 的节点上的进程。在具有共享文件系统的多节点环境中，您很可能希望使用 local=False，以便仅第一个节点的主进程执行处理。然而，如果文件系统未共享，则每个节点的主进程都需要执行处理，这是默认行为。
  • desc (str，可选，默认为 "work") — 用于调试日志的工作描述

一个用于 torch 分布式环境的上下文管理器，用于在主进程上执行某些操作，同时阻塞副本进程，并在操作完成后释放副本进程。

一种此类用途是 datasets 的 map 功能。为了高效运行，该功能应在主进程上执行一次，完成后会保存结果的缓存版本，随后副本会自动加载该缓存。

set_dataloader

< >

( train_batch_size: int = 8eval_batch_size: int = 8drop_last: bool = Falsenum_workers: int = 0pin_memory: bool = Truepersistent_workers: bool = Falseprefetch_factor: int | None = Nonemultiprocessing_context: str | None = Nonein_order: bool = Trueauto_find_batch_size: bool = Falseignore_data_skip: bool = Falsesampler_seed: int | None = None )

参数

  • drop_last (bool，可选，默认为 False) — 是否丢弃最后一个不完整的批次（当数据集长度不能被批次大小整除时）。
  • num_workers (int，可选，默认为 0) — 用于数据加载的子进程数量（仅适用于 PyTorch）。0 表示数据将在主进程中加载。
  • pin_memory (bool，可选，默认为 True) — 是否要在数据加载器中固定内存。默认值为 True。
  • persistent_workers (bool，可选，默认为 False) — 如果为 True，数据加载器在数据集被消费一次后不会关闭工作进程。这可以保持工作进程中的 Dataset 实例处于活动状态。可能会加快训练速度，但会增加内存使用量。默认值为 False。
  • prefetch_factor (int, 可选) — 每个 worker 预先加载的 batch 数量。 2 表示所有 worker 总共会预取 2 * num_workers 个 batch。
  • multiprocessing_context (str, 可选) — 用于数据加载工作进程的多进程启动方法（"fork"、"spawn" 或 "forkserver"）。默认使用 PyTorch 的默认启动方法。当从对象不支持 fork 的源（例如通过 pyarrow 访问的 HDFS）进行流式读取时，请使用 "spawn"。在 "spawn" 模式下，任何自定义的 collate_fn 或数据集代码都必须在模块级别可导入（不能使用 lambda 函数或闭包）。
  • in_order (bool，可选，默认为 True) — 如果为 True，数据加载器将按照 worker 被调度的顺序返回批次。将其设置为 False 可在批次就绪时立即返回，从而降低 IterableDataset 流式工作负载的尾部延迟。需要 PyTorch >= 2.6。
  • auto_find_batch_size (bool，可选，默认为 False) — 是否通过指数衰减自动寻找能够装入内存的 batch size，以避免 CUDA 内存不足错误。需要安装 accelerate（pip install accelerate）
  • ignore_data_skip (bool，可选，默认为 False) — 在恢复训练时，是否跳过相应的 epoch 和 batch，以使数据加载阶段与上一次训练保持一致。如果设置为 True，训练启动会更快（因为跳过步骤可能耗时较长），但结果将与被中断的训练不同。
  • sampler_seed (int, 可选) — 用于数据采样器的随机种子。如果未设置，数据采样的随机生成器将使用与 self.seed 相同的种子。这可用于确保数据采样的可复现性，且独立于模型种子。

一种将所有与数据加载器创建相关的参数归组在一起的方法。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_dataloader(train_batch_size=16, eval_batch_size=64)
>>> args.per_device_train_batch_size
16

set_evaluate

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'no'steps: int = 500batch_size: int = 8accumulation_steps: int | None = Nonedelay: float | None = Noneloss_only: bool = False )

参数

  • strategy (str 或 IntervalStrategy, ，可选, ，默认为 "no") — 训练期间采用的评估策略。可能的取值为：
    • "no"：训练期间不执行任何评估。
    • "steps"：每 steps 步执行一次评估（并记录日志）。
    • "epoch"：在每个 epoch 结束时进行评估。

    将 strategy 设置为不同于 "no" 的值会将 self.do_eval 设置为 True。

  • steps (int，可选，默认为 500) — 如果 strategy="steps"，则两次评估之间的更新步数。
  • batch_size (int 可选，默认为 8) — 用于评估的每个设备（GPU/TPU 核心/CPU…）的批大小。
  • accumulation_steps (int, 可选) — 在将结果移至 CPU 之前，用于累积输出张量的预测步数。 如果未设置，则所有预测结果都将在 GPU/TPU 上累积，然后再移至 CPU（速度更快，但需要更多内存）。
  • delay (float, 可选) — 根据 eval_strategy，在首次执行评估之前需要等待的 epoch 数或步数。
  • loss_only（bool，可选，默认为 False）— 忽略除损失以外的所有输出。

一种将所有与评估相关的参数重新分组的方法。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_evaluate(strategy="steps", steps=100)
>>> args.eval_steps
100

set_logging

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'steps'steps: int = 500report_to: str | list[str] = 'none'level: str = 'passive'first_step: bool = Falsenan_inf_filter: bool = Falseon_each_node: bool = Falsereplica_level: str = 'passive' )

参数

  • strategy (str 或 IntervalStrategy, 可选, 默认为 "steps") — 训练期间采用的日志记录策略。可能的取值如下：
    • "no"：训练期间不执行任何日志记录。
    • "epoch"：日志记录在每个 epoch 结束时进行。
    • "steps"：每 logging_steps 步记录一次日志。
  • steps (int，可选，默认为 500) — 当 strategy="steps" 时，两次日志记录之间的更新步数。
  • level (str，可选，默认为 "passive") — 主进程使用的 Logger 日志级别。可选值为字符串形式的日志级别："debug"、 "info"、"warning"、"error" 和 "critical"，此外还有一个 "passive" 级别，该级别不设置任何内容， 由应用程序自行设置日志级别。
  • report_to (str 或 list[str]，可选，默认为 "none") — 用于报告结果和日志的集成列表。支持的平台包括 "azure_ml"、 "clearml"、"codecarbon"、"comet_ml"、"dagshub"、"dvclive"、"flyte"、"mlflow"、 "swanlab"、"tensorboard"、"trackio" 和 "wandb"。使用 "all" 可报告到所有已安装的集成，使用 "none" 表示不使用任何集成。
  • first_step (bool，可选，默认为 False) — 是否记录并评估第一个 global_step。
  • nan_inf_filter (bool, 可选, 默认值为 True) — 是否过滤 nan 和 inf 损失值用于日志记录。如果设置为 True ，则每个步骤中为 nan 或 inf 的损失值将被过滤，并改用当前日志记录窗口的平均损失值。该参数仅影响损失值的日志记录，不会改变梯度的计算方式或模型参数的更新行为。

    nan_inf_filter 仅影响损失值的记录，不会改变梯度的计算方式或其在模型上的应用行为。

  • on_each_node (bool，可选，默认为 True) — 在多节点分布式训练中，是否在每个节点上都使用 log_level 记录日志，还是仅在主要节点上记录。
  • replica_level (str，可选，默认为 "passive") — 副本上使用的日志记录器日志级别。可选值与 log_level 相同

一种用于重新组织所有与日志记录相关的参数的方法。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_logging(strategy="steps", steps=100)
>>> args.logging_steps
100

set_lr_scheduler

< >

( name: str | transformers.trainer_utils.SchedulerType = 'linear'num_epochs: float = 3.0max_steps: int = -1warmup_steps: float = 0 )

参数

  • name (str 或 SchedulerType，可选，默认为 "linear") — 要使用的调度器类型。有关所有可能的值，请参阅 SchedulerType 的文档。
  • num_epochs(float, 可选，默认值为 3.0) — 要执行的训练总轮数（如果不是整数，则在停止训练前执行最后一轮的相应百分比部分）。
  • max_steps (int, 可选，默认为 -1) — 如果设置为正数，则指定要执行的训练总步数。该参数会覆盖 num_train_epochs。 对于有限数据集，如果所有数据均已用尽，训练将反复遍历数据集，直到达到 max_steps。当训练数据集未实现 __len__（例如流式数据集）时，必须将其设置为正值，因为此时无法推断总步数，而该值对于限定训练循环并配置学习率调度器是必需的。
  • warmup_steps (float，可选，默认为 0) — 用于从 0 到 learning_rate 进行线性预热（warmup）的步数。应为整数或 [0,1) 范围内的浮点数。 如果小于 1，则会被解释为用于从 0 到 learning_rate 进行线性预热的步数比例。

一种将所有与学习率调度器及其超参数相关的参数归为一组的方法。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_lr_scheduler(name="cosine", warmup_steps=0.05)
>>> args.warmup_steps
0.05

set_optimizer

< >

( name: str | transformers.training_args.OptimizerNames = 'adamw_torch'learning_rate: float = 5e-05weight_decay: float = 0beta1: float = 0.9beta2: float = 0.999epsilon: float = 1e-08args: str | None = None )

参数

  • name (str 或 training_args.OptimizerNames，可选，默认为 "adamw_torch") — 要使用的优化器："adamw_torch"、"adamw_torch_fused"、 "adamw_anyprecision" 或 "adafactor"。
  • learning_rate (float，可选，默认为 5e-5) — 初始学习率。
  • weight_decay (float, 可选，默认为 0) — 应用于除所有 bias 和 LayerNorm 权重之外的所有层的权重衰减（如果非零）。
  • beta1 (float, 可选，默认为 0.9) — adam 优化器或其变体的 beta1 超参数。
  • beta2 (float, 可选，默认为 0.999) — adam 优化器或其变体的 beta2 超参数。
  • epsilon (float, 可选，默认为 1e-8) — adam 优化器或其变体的 epsilon 超参数。
  • args (str, 可选) — 传递给 AnyPrecisionAdamW 的可选参数（仅在 optim="adamw_anyprecision" 时有用）。

一种用于重新组织所有与优化器及其超参数相关的参数的方法。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_optimizer(name="adamw_torch", beta1=0.8)
>>> args.optim
'adamw_torch'

set_push_to_hub

< >

( model_id: strstrategy: str | transformers.trainer_utils.HubStrategy = 'every_save'token: str | None = Noneprivate_repo: bool | None = Nonealways_push: bool = Falserevision: str | None = None )

参数

  • model_id (str) — 要与本地 output_dir 保持同步的仓库名称。它可以是一个简单的模型 ID，在这种情况下，模型将推送到您的命名空间。否则，它应该是完整的仓库名称，例如 "user_name/model"，这允许您使用 "organization_name/model" 推送到您所属的组织。
  • strategy (str 或 HubStrategy, 可选, 默认为 "every_save") — 定义推送到 Hub 的内容范围及推送时机。可能的取值如下：
    • "end"：当调用 save_model() 方法时，推送模型、其配置、处理类（例如 tokenizer，如果已传递给 Trainer）以及模型卡草稿。
    • "every_save"：每次保存模型时，推送模型、其配置、processing_class（例如 tokenizer，如果已传递给 Trainer）以及模型卡草稿。推送是异步执行的，以避免阻塞训练；如果保存非常频繁，只有在上一次推送完成后才会尝试新的推送。训练结束时，会推送最终模型。
    • "checkpoint"：与 "every_save" 类似，但最新的检查点还会被推送到名为 last-checkpoint 的子文件夹中，方便您使用 trainer.train(resume_from_checkpoint="last-checkpoint") 轻松恢复训练。
    • "all_checkpoints"：与 "checkpoint" 类似，但所有检查点都会按照它们在输出文件夹中的出现方式被推送（因此，最终仓库中的每个文件夹都会对应一个检查点文件夹）。
  • token (str, 可选) — 用于将模型推送到 Hub 的 token。默认使用通过 hf auth login 获取并存储在缓存文件夹中的 token。
  • private_repo (bool，可选，默认为 False) — 是否将仓库设为私有。如果为 None（默认值），除非组织的默认设置为私有，否则仓库将是公开的。如果仓库已存在，则忽略此值。
  • always_push (bool，可选，默认为 False) — 除非此参数为 True，否则当上一次推送尚未完成时，Trainer 将跳过推送检查点。
  • revision (str, 可选) — 推送到 Hub 时使用的版本。可以是分支名称、标签或提交哈希值。

一种用于重新整理所有与 Hub 同步检查点相关的参数的方法。

调用此方法会将 self.push_to_hub 设置为 True，这意味着 output_dir 将开始一个与仓库（由 model_id 确定）同步的 git 目录，并且每次触发保存时（取决于您的 self.save_strategy）内容都会被推送。调用 save_model() 也会触发推送。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_push_to_hub("me/awesome-model")
>>> args.hub_model_id
'me/awesome-model'

set_save

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'steps'steps: int = 500total_limit: int | None = Noneon_each_node: bool = False )

参数

  • strategy (str 或 IntervalStrategy, 可选, 默认为 "steps") — 训练期间采用的检查点保存策略。可能的取值如下：
    • "no"：训练过程中不会执行任何保存操作。
    • "epoch"：在每个 epoch 结束时执行保存。
    • "steps"：每 save_steps 步执行一次保存。
  • steps (int，可选，默认为 500) — 当 strategy="steps" 时，两次保存检查点之间的更新步数。
  • total_limit (int, 可选) — 如果传入了值，将限制检查点的总数。会删除 output_dir 中较旧的检查点。
  • on_each_node (bool, 可选, 默认为 False) — 在进行多节点分布式训练时，是否在每个节点上保存模型和检查点，还是仅在主要节点上保存。

    当不同节点使用相同的存储时，不应启用此功能，因为每个节点保存的文件将具有相同的名称。

一种将所有与检查点保存相关的参数归组在一起的方法。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_save(strategy="steps", steps=100)
>>> args.save_steps
100

set_testing

< >

( batch_size: int = 8loss_only: bool = False )

参数

  • batch_size (int 可选，默认为 8) — 用于测试的每个设备（GPU/TPU 核心/CPU…）的批大小。
  • loss_only（bool，可选，默认为 False）— 忽略除损失以外的所有输出。

一种将所有与在留出数据集上进行测试相关的基本参数归集在一起的方法。

调用此方法会自动将 self.do_predict 设置为 True。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_testing(batch_size=32)
>>> args.per_device_eval_batch_size
32

set_training

< >

( learning_rate: float = 5e-05batch_size: int = 8weight_decay: float = 0num_epochs: float = 3max_steps: int = -1gradient_accumulation_steps: int = 1seed: int = 42activation_checkpointing: bool = Falsegradient_checkpointing: bool | None = None )

参数

  • learning_rate (float，可选，默认值为 5e-5) — 优化器的初始学习率。
  • batch_size (int 可选，默认为 8) — 用于训练的每个设备（GPU/TPU 核心/CPU…）的批大小。
  • weight_decay (float, 可选，默认为 0) — 应用于优化器中除所有偏置和 LayerNorm 权重之外的所有层的权重衰减（如果非零）。
  • num_epochs (float，可选，默认为 3.0) — 要执行的训练轮数总数（如果不是整数，将在停止训练前执行最后一轮的相应百分比部分）。
  • max_steps (int, 可选，默认为 -1) — 如果设置为正数，则指定要执行的训练总步数。该参数会覆盖 num_train_epochs。 对于有限数据集，如果所有数据均已用尽，训练将反复遍历数据集，直到达到 max_steps。当训练数据集未实现 __len__（例如流式数据集）时，必须将其设置为正值，因为此时无法推断总步数，而该值对于限定训练循环并配置学习率调度器是必需的。
  • gradient_accumulation_steps (int, 可选, ，默认值为 1）—— 在执行反向传播/更新之前，用于累积梯度的更新步数。

    在使用梯度累积时，一个 step 被计为一次带有反向传播的 step。因此，日志记录、评估和保存操作将在每 gradient_accumulation_steps * xxx_step 个训练样本后执行。

  • seed (int，可选，默认为 42) — 将在训练开始时设置的随机种子。为了确保多次运行之间的可复现性，如果模型包含随机初始化的参数，请使用 ~Trainer.model_init 函数来实例化该模型。
  • activation_checkpointing (bool，可选，默认为 False) — 如果为 True，则使用激活检查点（activation checkpointing）来节省内存，代价是反向传播速度变慢。
  • gradient_checkpointing (bool，可选) — activation_checkpointing 的已弃用别名，将在 v6 中移除。

一种将所有与训练相关的基本参数归组在一起的方法。

调用此方法会自动将 self.do_train 设置为 True。

示例：

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_training(learning_rate=1e-4, batch_size=32)
>>> args.learning_rate
1e-4

to_dict

< >

( )

在序列化此实例时，将 Enum 替换为其值（以支持 JSON 序列化）。它会通过移除值来混淆 token 值。

to_json_string

< >

( )

将此实例序列化为 JSON 字符串。

to_sanitized_dict

< >

( )

用于 TensorBoard hparams 的净化序列化

Seq2SeqTrainingArguments

class transformers.Seq2SeqTrainingArguments

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 5e-05lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool = Falsefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool | None = Nonegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 500logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Falserestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: typing.Any | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Truelabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1sortish_sampler: bool = Falsepredict_with_generate: bool = Falsegeneration_max_length: int | None = Nonegeneration_num_beams: int | None = Nonegeneration_config: str | pathlib.Path | transformers.generation.configuration_utils.GenerationConfig | None = None )

参数

  • output_dir (str，可选，默认为 "trainer_output") — 模型预测结果和检查点将写入的输出目录。

训练时长与批大小

  • per_device_train_batch_size (int，可选，默认值为 8) — 每个设备的批大小。全局批大小的计算方式为： 在多 GPU 或分布式环境中，per_device_train_batch_size * number_of_devices。
  • num_train_epochs(float, 可选，默认值为 3.0) — 要执行的训练轮数总数（如果不是整数，则在停止训练前执行最后一个轮次的相应小数部分）。
  • max_steps (int，可选，默认为 -1) — 覆盖 num_train_epochs。如果设置为正数，则指定要执行的训练总步数。 对于有限数据集，训练会反复遍历数据集（如果所有数据已用尽），直到达到 max_steps。当训练数据集未实现 __len__（例如流式数据集）时，必须将其设置为正值，因为此时无法推断总步数，且需要该值来限定训练循环并配置学习率调度器。

学习率与调度器

  • learning_rate (float，可选，默认值为 5e-5) — 优化器的初始学习率。当使用带有预热（warmup）的调度器时，这通常是峰值学习率。
  • lr_scheduler_type (str 或 SchedulerType, 可选, 默认为 "linear") — 要使用的学习率调度器类型。请参阅 SchedulerType 以查看所有可能的值。常见选择：
  • lr_scheduler_kwargs (dict 或 str，可选，默认为 None) — lr_scheduler 的额外参数。有关可能的取值，请参阅各调度器的文档。
  • warmup_steps (int 或 float, 可选, ，默认为 0）— 从 0 线性预热到 learning_rate. 的步数。预热有助于在训练初期稳定训练过程。可以是：
    • 一个整数：预热步数的精确值
    • 范围在 [0, 1) 内的浮点数：解释为总训练步数的比例

优化器

  • optim (str 或 training_args.OptimizerNames, 可选, 默认为 "adamw_torch" (适用于 torch>=2.8 "adamw_torch_fused")) — 要使用的优化器。常用选项：
    • "adamw_torch"：PyTorch 的 AdamW（推荐的默认值）
    • "adamw_torch_fused"：融合 AdamW 内核
    • "adamw_hf"：HuggingFace 的 AdamW 实现
    • "sgd"：带动量的随机梯度下降
    • "adafactor"：适用于大型模型的内存高效优化器
    • "adamw_8bit"：8 位 AdamW（需要 bitsandbytes） 完整列表请参见 OptimizerNames。
  • optim_args (str, 可选) — 传递给优化器（如 AnyPrecisionAdamW、AdEMAMix 和 GaLore）的可选参数。
  • weight_decay (float, 可选，默认为 0) — 优化器应用的权重衰减系数（而非损失函数）。通过惩罚较大的权重来添加 L2 正则化，以防止过拟合。自动排除 bias 和 LayerNorm 参数。典型值：0.01（标准）、0.1（更强的正则化）、0.0（无正则化）。
  • adam_beta1 (float, 可选，默认为 0.9) — 基于 Adam 的优化器中一阶矩估计（动量）的指数衰减率。控制保留多少梯度历史。
  • adam_beta2 (float, 可选，默认值为 0.999) — 基于 Adam 的优化器中二阶矩估计（方差）的指数衰减率。用于控制自适应学习率的缩放。
  • adam_epsilon (float，可选，默认值为 1e-8) — 基于 Adam 的优化器中用于数值稳定性的 Epsilon 值。可防止更新规则分母中出现除以零的情况。
  • optim_target_modules (Union[str, list[str]], 可选) — 要优化的目标模块，即您希望进行训练的模块名称。 目前用于 GaLore 算法 和 APOLLO 算法。 有关更多详细信息，请参阅 GaLore 实现 和 APOLLO 实现。 请确保传入有效的 GaLore 或 APOLLO 优化器，例如：“apollo_adamw”、“galore_adamw”、“galore_adamw_8bit”、“galore_adafactor”，并确保目标模块仅为 nn.Linear 模块。

正则化与训练稳定性

  • gradient_accumulation_steps (int, 可选, ，默认值为 1）— 在执行反向传播/更新之前累积梯度的更新步数。 可在不增加额外内存的情况下模拟更大的批大小。有效批大小 = per_device_train_batch_size × num_devices × gradient_accumulation_steps.

    在使用梯度累积时，一个“step”被计为一次带有反向传播的 step。因此，日志记录、评估和保存将每 gradient_accumulation_steps × xxx_step 个训练样本发生一次。

  • average_tokens_across_devices (bool，可选，默认为 True) — 是否跨设备对 token 取平均值。如果启用，将使用 all_reduce 来同步 num_tokens_in_batch，以实现精确的损失计算。参考： https://github.com/huggingface/transformers/issues/34242
  • max_grad_norm (float，可选，默认值为 1.0) — 用于梯度裁剪的最大梯度范数。在反向传播之后、优化器更新之前应用。当梯度的全局范数超过此阈值时，通过缩小梯度来防止梯度爆炸。设置为 0 可禁用裁剪。典型取值：1.0（标准）、0.5（更保守）、5.0（更宽松）。
  • label_smoothing_factor (float，可选，默认为 0.0) — 标签平滑系数，用于防止模型过度自信。它将硬性的 0/1 目标替换为软目标：0 变为 ε/num_labels，1 变为 1 - ε + ε/num_labels，其中 ε = label_smoothing_factor。设为 0 表示不进行平滑。典型取值范围：0.0 到 0.1。

混合精度训练

  • bf16 (bool，可选，默认为 False) — 启用 bfloat16 (BF16) 混合精度训练 通常优先于 FP16，因为具有更好的数值稳定性，且无需进行损失缩放。
  • fp16 (bool，可选，默认为 False) — 启用 float16 (FP16) 混合精度训练。 如果硬件支持，建议改用 BF16。
  • bf16_full_eval (bool，可选，默认为 False) — 在评估时使用完整的 BF16 精度（而不仅仅是混合精度）。速度更快且节省内存，但可能会略微影响指标数值。仅在评估阶段生效。
  • fp16_full_eval (bool，可选，默认为 False) — 在评估时使用完整的 FP16 精度（而不仅仅是混合精度）。速度更快且节省内存，但可能会略微影响指标值。仅在评估阶段生效。
  • tf32 (bool, 可选) — 在 Ampere 及更新架构的 GPU 上启用 TensorFloat-32 (TF32) 模式。TF32 在矩阵乘法中使用 19 位精度（而非 FP32 的 23 位），在精度损失可忽略不计的情况下，可提供最高 8 倍的加速。默认值取决于 PyTorch 版本。请参阅 TF32 文档。

激活检查点

  • activation_checkpointing (bool，可选，默认为 False) — 启用激活检查点，以计算换取内存。通过在正向传播期间清除激活值并在反向传播期间重新计算它们来降低内存使用量。代价是训练速度降低约 20%，但可支持训练更大的模型或更大的批处理大小。
  • activation_checkpointing_kwargs (dict, 可选，默认为 None) — 传递给 activation_checkpointing_enable() 的关键字参数。every_n_layers 仅对每 n 个解码器层执行一次检查点，而不是对所有层执行；1 是通常的全有或全无行为，较大的值会释放一些内存以换取速度。offload 将保存的激活值存储在固定的主机内存中，这会释放 layers x sequence x hidden 字节的设备内存，但会使步骤变慢。其他任何键都会转发给 torch.utils.checkpoint.checkpoint。
  • gradient_checkpointing (bool，可选) — activation_checkpointing 的已弃用别名，将在 v6 中移除。
  • gradient_checkpointing_kwargs (dict, 可选) — activation_checkpointing_kwargs 的已弃用别名，将在 v6 中移除。

编译

  • torch_compile（bool，可选，默认为 False）— 使用 PyTorch 2.0 的 torch.compile() 编译模型以加快训练速度。无需修改代码即可提供 20-50% 的速度提升。除非指定了 torch_compile_backend 或 torch_compile_mode，否则使用默认编译设置。
  • torch_compile_backend (str, 可选) — torch.compile() 的后端。如果设置，将自动启用 torch_compile。选项包括 "inductor"（默认值）、"aot_eager"、"cudagraphs"。后端因 PyTorch 版本而异 - 请参阅 PyTorch 文档了解可用选项。
  • torch_compile_mode (str, 可选) — torch.compile() 的编译模式。如果设置，将自动启用 torch_compile。 选项："default"、"reduce-overhead"（最小化 Python 开销）、"max-autotune" （激进优化，编译时间更长）。

内核

  • use_liger_kernel (bool，可选，默认为 False) — 启用 Liger Kernel 优化。可将多 GPU 吞吐量提升约 20%，并将内存占用降低约 60%。兼容 Flash Attention、FSDP 和 DeepSpeed。目前支持 Llama、Mistral、Mixtral 和 Gemma 模型。
  • liger_kernel_config (Optional[dict], 可选) — Liger Kernel 的配置。作为 kwargs 传递给 _apply_liger_kernel_to_instance()。 选项通常包括："rope"、"swiglu"、"cross_entropy"、 "fused_linear_cross_entropy"、"rms_norm"。如果为 None，则使用默认配置。

其他优化

  • use_cache（bool，可选，默认为 False）— 是否启用模型的缓存。在训练过程中，通常不需要启用此功能，除非使用某些依赖 past_key_values 的 PEFT 方法。
  • neftune_noise_alpha (Optional[float]) — 如果不为 None，将启用 NEFTune 噪声嵌入。这可以显著提升指令微调的模型性能。请参阅原始论文和原始代码。支持 Transformers 的 PreTrainedModel，也支持来自 peft 的 PeftModel。原始论文中使用的值范围为 [5.0, 15.0]。
  • torch_empty_cache_steps (int, 可选) — 在调用 torch.<device>.empty_cache() 之前等待的步数。如果未设置或设置为 None，则不会清空缓存。 这可以通过降低峰值 VRAM 使用量来帮助避免 CUDA 内存不足错误，但代价是性能大约降低 10%。
  • auto_find_batch_size（bool，可选，默认为 False）— 是否通过指数衰减自动寻找能够放入内存的训练 batch size，以避免 CUDA Out-of-Memory 错误。评估 batch size 不会进行调整。

训练日志与监控

  • logging_strategy (str 或 IntervalStrategy, 可选, 默认为 "steps") — 训练期间采用的日志记录策略。可能的取值如下：
    • "no"：训练期间不执行任何日志记录。
    • "epoch"：日志记录在每个 epoch 结束时进行。
    • "steps"：每 logging_steps 步记录一次日志。
  • logging_steps（int 或 float，可选，默认值为 500）— 当 logging_strategy="steps" 时，两次日志记录之间的更新步数。应为整数或 [0,1) 范围内的浮点数。如果小于 1，将被解释为总训练步数的比例。
  • logging_first_step (bool，可选，默认为 False) — 是否记录第一个 global_step。
  • log_on_each_node (bool，可选，默认为 True) — 在多节点分布式训练中，是否在每个节点上都使用 log_level 记录日志，还是仅在主节点上记录。
  • logging_nan_inf_filter (bool，可选，默认为 True) — 在记录日志时过滤掉 NaN 和 Inf 损失。如果为 True，则用近期有效损失的均值替换训练损失中的 NaN/Inf，并在评估损失中排除包含 NaN/Inf 的批次（例如没有标签 token 的批次）。不影响梯度计算，仅影响日志记录。
  • include_num_input_tokens_seen (Optional[Union[str, bool]]，可选，默认为 “no”) — 是否跟踪已看到的输入 token 数量。必须是 [“all”, “non_padding”, “no”] 之一，或者是一个映射到 “all” 或 “no” 的布尔值。 在分布式训练中可能会更慢，因为必须调用 gather 操作。

日志记录

  • log_level (str，可选，默认为 passive) — 主进程的日志级别。可选值："debug"、"info"、"warning"、"error"、 "critical" 或 "passive"（不更改当前 Transformers 的日志级别， 其默认值为 "warning"）
  • log_level_replica (str，可选，默认为 "warning") — 分布式训练中副本进程的日志级别。选项与 log_level 相同。
  • disable_tqdm (bool，可选) — 禁用 tqdm 进度条。如果 log_level 为 warning 或更低，则默认为 True，否则为 False。

实验跟踪集成

  • report_to (str 或 list[str]，可选，默认为 "none") — 用于报告结果和日志的集成列表。支持的平台包括 "azure_ml"、 "clearml"、"codecarbon"、"comet_ml"、"dagshub"、"dvclive"、"flyte"、"mlflow"、"swanlab"、 "tensorboard"、"trackio" 和 "wandb"。使用 "all" 可报告到所有已安装的集成，使用 "none" 表示不使用任何集成。
  • run_name (str, 可选) — 用于描述该次运行。通常用于 trackio、wandb、mlflow、comet 和 swanlab 的日志记录。
  • project (str，可选，默认为 "huggingface") — 用于日志记录的项目名称。目前仅由 Trackio 使用。
  • trackio_space_id (str 或 None，可选，默认为 None) — 用于基于 Gradio 的 Space 进行实时 Trackio 日志记录的 Hugging Face Space ID。应为完整的 Space 名称，如 'username/reponame' 或 'orgname/reponame'，或仅为 'reponame'（Space 将创建在当前登录用户的命名空间中）。如果为 None，指标仅记录到 本地 目录（Hub 上没有 Space）。该 Gradio Space 对 Trackio Bucket 具有 读写 权限，这在训练 进行中 时正是您所需要的——例如在 恢复 部分运行或从多台机器 聚合日志 时。除非您设置 hub_private_repo=True 或您的组织默认创建私有 Space，否则该 Space 将是 公开 的。
  • trackio_bucket_id（str 或 None，可选，默认为 None）— Trackio 的可选 Hugging Face Bucket id。如果未设置，Trackio 会自动派生一个。与 Gradio Space（trackio_space_id）配合使用，并在部署静态 Space（trackio_static_space_id 不为 False）时生效。
  • trackio_static_space_id (str、False 或 None，可选，默认为 None) — 训练完成后用于创建静态 Space 的 Hugging Face Space ID。应为完整的 Space 名称，例如 'username/reponame' 或 'orgname/reponame'，或者仅为 'reponame'（该 Space 将创建在当前登录用户的命名空间中）。如果为 False，则不会创建静态 Space。如果为 None 且模型已推送到 Hub，则会使用默认名称创建一个静态 Space，并从模型卡片中链接到该 Space。除非您设置了 hub_private_repo=True 或您的组织默认创建私有 Space，否则该 Space 将是公开的。

评估

  • eval_strategy (str 或 IntervalStrategy, 可选, 默认为 "no") — 何时运行评估。选项：
    • "no"：训练期间不进行任何评估
    • "steps"：每 eval_steps 步执行一次评估
    • "epoch"：在每个 epoch 结束时进行评估
  • eval_steps（int 或 float，可选）— 如果 eval_strategy="steps"，则指定两次评估之间的更新步数。如果未设置，默认值与 logging_steps 相同。应为整数或 [0,1) 范围内的浮点数。如果小于 1，将被解释为总训练步数的比例。
  • eval_delay (float, 可选) — 根据 eval_strategy，在首次执行评估之前需要等待的 epoch 数或步数。
  • per_device_eval_batch_size (int，可选，默认为 8) — 评估时每个设备加速器核心/CPU 的批大小。
  • prediction_loss_only（bool，可选，默认为 False）— 在执行评估并生成预测时，仅返回损失值。
  • eval_on_start（bool，可选，默认为 False）— 是否在训练开始前执行一次评估步骤（健全性检查），以确保验证步骤能正确运行。
  • eval_do_concat_batches (bool，可选，默认为 True) — 是否递归地跨批次拼接输入/损失/标签/预测值。如果为 False，则改为将它们存储为列表，每个批次保持独立。
  • eval_use_gather_object (bool，可选，默认为 False) — 是否对所有设备上的嵌套列表/元组/字典中的对象执行递归 gather 操作。仅当用户返回的内容不仅仅是张量时才应启用此选项，且 PyTorch 明确不推荐这样做。 当标签结构非标准时（例如在计算机视觉任务中），此选项非常有用。
  • eval_accumulation_steps (int, 可选) — 在将结果移至 CPU 之前，用于累积输出张量的预测步数。如果未设置，则所有预测结果都将在设备加速器上累积，然后再移至 CPU（速度更快，但需要更多内存）。

指标计算

  • include_for_metrics (list[str], 可选, 默认为 []) — 在需要计算指标时，将额外数据包含在 compute_metrics 函数中。 可添加到 include_for_metrics 列表中的选项：
    • "inputs"：传递给模型的输入数据，用于计算依赖于输入的指标。
    • "loss"：在评估期间计算得出的损失值，用于计算依赖于损失的指标。
  • batch_eval_metrics (bool，可选，默认为 False) — 如果设置为 True，评估将在每个批次结束时调用 compute_metrics 来累积统计信息，而不是将所有评估 logits 保存在内存中。当设置为 True 时，必须传入一个 compute_metrics 函数，该函数接受一个布尔参数 compute_result；当传入 True 时，将基于你在评估集上累积的批次级统计信息，触发最终的全局汇总统计。

检查点与保存

  • save_only_model (bool，可选，默认为 False) — 仅保存模型权重，不保存优化器/调度器/RNG 状态。这会显著减小检查点的大小，但无法从该检查点恢复训练。当只需要使用训练好的模型进行推理，而不需要继续训练时，请使用此选项。 将此选项设置为 True 后，只能通过 from_pretrained 加载模型。
  • save_strategy (str 或 SaveStrategy, 可选, 默认为 "steps") — 训练期间采用的检查点保存策略。可能的取值如下：
    • "no"：训练过程中不会执行任何保存操作。
    • "epoch"：在每个 epoch 结束时执行保存。
    • "steps"：每 save_steps 步执行一次保存。
    • "best"：每当达到新的 best_metric 时执行保存。
  • save_steps（int 或 float，可选，默认值为 500）— 当 save_strategy="steps" 时，两次保存检查点之间的更新步数。应为整数或 [0,1) 范围内的浮点数。如果小于 1，将被解释为总训练步数的比例。
  • save_on_each_node (bool，可选，默认为 False) — 在进行多节点分布式训练时，是否在每个节点上保存模型和检查点，还是仅在主要节点上保存。 当不同节点使用相同的存储时，不应启用此选项，因为每个节点保存的文件将具有相同的名称。
  • save_total_limit (int, 可选) — 要保留的检查点最大数量。会删除 output_dir 中较旧的检查点。当 load_best_model_at_end=True 时，始终保留最佳检查点以及最近的检查点。例如，save_total_limit=5 会保留最近的 4 个检查点以及最佳检查点
  • enable_jit_checkpoint (bool，可选，默认为 False) — 在收到 SIGTERM 信号时启用即时（Just-In-Time）检查点，以便在可抢占工作负载上实现优雅终止。重要：请配置编排器的优雅关闭时间，以确保有足够的时间。对于 Kubernetes，请设置 terminationGracePeriodSeconds（默认的 30 秒通常不够）。对于 Slurm，请使用 --signal=TERM@<seconds>。所需的优雅关闭时间 ≥ 最长迭代时间 + 检查点保存时间。

Hugging Face Hub 集成

  • push_to_hub (bool，可选，默认为 False) — 是否在每次保存模型时将其推送到 Hub。如果启用此选项，output_dir 将启动一个与仓库（由 hub_model_id 确定）同步的 git 目录，并且每次触发保存时（取决于您的 save_strategy）都会推送内容。调用 save_model() 也会触发推送。
  • hub_token (str, 可选) — 用于将模型推送到 Hub 的令牌。默认使用通过 hf auth login 获取并存储在缓存文件夹中的令牌。
  • hub_private_repo (bool, 可选) — 是否将仓库设为私有。如果为 None（默认值），除非组织的默认设置为私有，否则仓库将是公开的。如果仓库已存在，则忽略此值。如果启用了部署到 Hugging Face Spaces 的 Trackio 报告，相同的逻辑将决定该 Space 是否为私有。
  • hub_model_id (str, 可选) — 要与本地 output_dir 保持同步的仓库名称。它可以是一个简单的模型 ID，在这种情况下，模型将推送到你的命名空间。否则，它应该是完整的仓库名称，例如 "user_name/model"，这允许你使用 "organization_name/model" 推送到你所属的组织。默认值为 user_name/output_dir_name，其中 output_dir_name 是 output_dir 的名称。
  • hub_strategy (str 或 HubStrategy, 可选, 默认为 "every_save") — 定义推送至 Hub 的内容和时机。选项：
    • "end"：仅在训练结束时推送
    • "every_save"：每次保存时推送（异步执行，以免阻塞训练）
    • "checkpoint"：与 "every_save" 类似，但会将最新的检查点推送到 "last-checkpoint" 子文件夹中，以便于恢复训练
    • "all_checkpoints"：推送所有出现的检查点
  • hub_always_push (bool，可选，默认为 False) — 除非此参数为 True，否则 Trainer 会在上一次推送尚未完成时跳过推送检查点。
  • hub_revision (str, 可选) — 推送到 Hub 时使用的版本。可以是分支名称、标签或提交哈希。

最佳模型跟踪

  • load_best_model_at_end (bool，可选，默认为 False) — 在训练结束时加载最佳检查点。需要设置 eval_strategy。 启用后，最佳检查点始终会被保存（参见 save_total_limit）。 当为 `True` 时，`save_strategy` 必须与 `eval_strategy` 匹配（除非 `save_strategy` 为 `"best"`），并且如果使用 `"steps"`， `save_steps` 必须是 `eval_steps` 的倍数。
  • metric_for_best_model (str, 可选) — 当 load_best_model_at_end=True 时，用于比较模型的指标。必须是评估返回的指标名称，可以带或不带 "eval_" 前缀。默认值为 "loss"。 如果设置了此项，除非名称以 "loss" 结尾，否则 greater_is_better 的默认值为 True。示例："accuracy"、"f1"、"eval_bleu"。
  • greater_is_better (bool，可选) — 是否指标值越高越好。默认值基于 metric_for_best_model： 如果指标名称不以 "loss" 结尾，则为 True，否则为 False。

恢复训练

  • ignore_data_skip (bool，可选，默认为 False) — 恢复训练时，跳过通过数据集快速前进以到达先前状态的操作。如果为 True，训练将从数据集的开头开始（恢复速度更快，但结果与中断前的训练不匹配）。如果为 False，则跳过已查看的数据（恢复速度较慢，但可精确继续）。
  • restore_callback_states_from_checkpoint (bool，可选，默认为 False) — 在恢复训练时从检查点恢复回调状态。如果为 True，且检查点中存在这些回调，则会覆盖传递给 Trainer 的回调。

可复现性

  • full_determinism (bool，可选，默认为 False) — 如果为 True，将调用 enable_full_determinism() 而非 set_seed()，以确保分布式训练中的结果可复现。重要提示：这会负面影响性能，因此仅建议在调试时使用。
  • seed (int，可选，默认为 42) — 将在训练开始时设置的随机种子。为了确保多次运行之间的可复现性，如果模型包含随机初始化的参数，请使用 ~Trainer.model_init 函数来实例化该模型。
  • data_seed (int, 可选) — 用于数据采样器的随机种子。如果未设置，数据采样的随机生成器将使用与 seed 相同的种子。这可用于确保数据采样的可复现性，且独立于模型种子。

硬件配置

  • use_cpu (bool，可选，默认为 False) — 是否使用 CPU。如果设置为 False，我们将使用可用的 torch 设备/后端。

Accelerate 配置

  • accelerator_config (str, dict, 或 AcceleratorConfig, 可选) — 内部 Accelerate 集成的配置。可以是： 指向 JSON 配置文件的路径："accelerator_config.json" 包含配置选项的字典 AcceleratorConfig 实例 主要选项：split_batches (bool, 默认为 False)：是否跨设备拆分批次。如果为 True，所有设备上的实际批次大小相同（总数必须能被 num_processes 整除）。如果为 False，每个设备获得指定的批次大小。dispatch_batches (bool)：如果为 True，仅主进程遍历 dataloader 并将批次分发到各设备。对于 IterableDataset 默认为 True，否则为 False。even_batches (bool, 默认为 True)：从数据集开头复制样本，以确保所有 worker 获得相等的批次大小。use_seedable_sampler (bool, 默认为 True)：使用完全可播种的随机采样器以实现可复现性。use_configured_state (bool, 默认为 False)：使用预初始化的 AcceleratorState/PartialState，而不是创建新的实例。这可能会导致超参数调优出现问题。
    • JSON 配置文件的路径："accelerator_config.json"
    • 包含配置选项的字典
    • AcceleratorConfig 实例 主要选项：
    • split_batches（bool，默认为 False）：是否将批次拆分到各个设备上。 如果为 True，则所有设备上的实际批次大小相同（总数必须能被 num_processes 整除）。如果为 False，则每个设备获得指定的批次大小。
    • dispatch_batches（bool）：如果为 True，则仅主进程遍历 dataloader 并将批次分发到各设备。对于 IterableDataset，默认值为 True，否则为 False。
    • even_batches（bool，默认为 True）：从数据集开头复制样本，以确保所有工作进程获得相同的批次大小。
    • use_seedable_sampler (bool，默认为 True)：使用完全可复现的随机采样器，以确保结果的可重复性。
    • use_configured_state (bool，默认为 False)：使用预先初始化的 AcceleratorState/PartialState，而不是创建新的实例。这可能会导致超参数调优出现问题。
  • parallelism_config (ParallelismConfig，可选) — 训练运行的并行配置。需要 Accelerate 1.10.1

Dataloader

  • dataloader_drop_last (bool，可选，默认为 False) — 是否丢弃最后一个不完整的批次（当数据集长度不能被批次大小整除时）。
  • dataloader_num_workers (int，可选，默认为 0) — 用于数据加载的子进程数量（仅适用于 PyTorch）。0 表示数据将在主进程中加载。
  • dataloader_pin_memory (bool，可选，默认为 True) — 是否要在数据加载器中固定内存。默认值为 True。
  • dataloader_persistent_workers (bool，可选，默认为 False) — 如果为 True，数据加载器在数据集被消费一次后不会关闭工作进程。 这可以保持工作进程中的 Dataset 实例处于活动状态。可能会加速训练，但会增加内存使用量。默认为 False。
  • dataloader_prefetch_factor (int, 可选) — 每个 worker 预先加载的批次数量。 2 表示所有 worker 总共会预取 2 * num_workers 个批次。
  • dataloader_multiprocessing_context (str, 可选) — 用于数据加载工作进程的多进程启动方法（"fork"、"spawn" 或 "forkserver"）。默认使用 PyTorch 的默认启动方法，但在 MPS 上且 dataloader_num_workers > 1 时，默认值为 "fork"。当从对象不支持 fork 的来源（例如通过 pyarrow 访问的 HDFS）进行流式读取时，请使用 "spawn"。在 "spawn" 模式下，任何自定义的 collate_fn 或数据集代码都必须在模块级别可导入（不能使用 lambda 函数或闭包）。
  • dataloader_in_order (bool，可选，默认为 True) — 如果为 True，数据加载器将按照 worker 被调度的顺序返回批次。将其设置为 False 可在批次就绪时立即返回，从而降低 IterableDataset 流式工作负载的尾部延迟。需要 PyTorch >= 2.6。
  • remove_unused_columns（bool，可选，默认为 True）—— 是否自动移除模型 forward 方法未使用的列。
  • label_names (list[str], 可选) — 输入字典中对应标签的键列表。 最终将默认为模型接受的参数名中包含“label”一词的列表， 但如果使用的模型是 XxxForQuestionAnswering 之一，则还会包含 ["start_positions", "end_positions"] 键。 仅当使用自定义标签名称，或模型的 forward 消耗多个标签张量（例如抽取式问答）时，才应指定 label_names。
  • train_sampling_strategy (str, 可选, 默认值为 "random") — 用于训练数据加载器的采样器。可选值如下：
    • "random"：使用 RandomSampler（默认）。
    • "sequential"：使用 SequentialSampler。
    • "group_by_length"：使用 LengthGroupedSampler 将长度大致相同的样本分组在一起（以减少填充，提高效率）。
    • "batch_rebalance"：使用 BatchRebalanceSampler 在每个有效批次内平衡各设备以及梯度累积步骤之间的填充 token 开销，与 "group_by_length" 相比，可减少填充浪费并降低峰值内存。目前仅支持数据并行训练（尚不支持张量并行）。

    注意：当使用 IterableDataset 时，此参数将被忽略。

  • length_column_name (str, 可选，默认为 "length") — 预计算长度的列名。如果该列存在，按长度分组时将使用这些值，而不是在训练启动时进行计算。除非 train_sampling_strategy 为 "group_by_length" 或 "batch_rebalance" 且数据集是 Dataset 的实例，否则此参数将被忽略。

DDP（DistributedDataParallel）

  • ddp_find_unused_parameters (bool, 可选) — 在使用分布式训练时，传递给 DistributedDataParallel 的 find_unused_parameters 标志的值。如果使用了梯度检查点，则默认为 False，否则为 True。
  • ddp_bucket_cap_mb (int，可选) — 在使用分布式训练时，传递给 DistributedDataParallel 的 bucket_cap_mb 标志的值。
  • ddp_broadcast_buffers (bool，可选) — 在使用分布式训练时，传递给 DistributedDataParallel 的 broadcast_buffers 标志的值。如果使用了梯度检查点，则默认为 False，否则为 True。
  • ddp_static_graph (bool, 可选) — 在使用分布式训练时，传递给 DistributedDataParallel 的 static_graph 标志的值。
  • ddp_backend (str, 可选) — 用于分布式训练的 backend。必须是 "nccl"、"mpi"、"xccl"、"gloo"、"hccl" 之一。
  • ddp_timeout (int，可选，默认值为 1800) — torch.distributed.init_process_group 调用的超时时间，用于在分布式运行中执行耗时操作时避免 GPU 套接字超时。有关更多信息，请参阅 PyTorch 文档。

FSDP（Fully Sharded Data Parallel）

  • fsdp (bool，可选，默认为 None) — 启用 PyTorch Fully Sharded Data Parallel (FSDP) 以进行分布式训练。传入 True 以启用 FSDP。
  • fsdp_config (str 或 dict, 可选) — 启用 fsdp 时的配置设置。传入 JSON 配置文件的路径，例如 fsdp_config.json, ，或已加载的 dict。

    支持的键：

    • version (int，可选，默认为 2)： 要使用的 FSDP 版本（2 表示 FSDP2，1 表示旧版 FSDP1）。
    • reshard_after_forward (bool, 可选, 默认为 True): 是否在前向传播后重新分片参数。将其设置为 False 可在前向传播和反向传播之间保持参数聚合状态，避免重新执行 all-gather 操作，但会占用更高的峰值内存。
    • cpu_offload (bool，可选，默认为 False)： 在参数和梯度未使用时将其卸载到 CPU，以节省 GPU 内存。
    • activation_checkpointing (bool, 可选, 默认为 False): 设置为 True 可在反向传播过程中通过重新计算激活值来减少内存占用。在使用 FSDP 时，建议优先使用此参数，而非 activation_checkpointing 训练参数，因为后者会在反向传播中引入冗余的 all-gather 操作。
    • cpu_ram_efficient_loading (bool, 可选，默认为 False)： 设置为 True 时，仅在第一个进程上加载预训练检查点。其他进程以空权重启动，并通过广播接收权重。
    • state_dict_type (str，可选，默认为 "FULL_STATE_DICT")： 检查点格式："FULL_STATE_DICT"（单个兼容 HF 的文件）或 "SHARDED_STATE_DICT"（每个 rank 一个文件，对大型模型更快）。
    • auto_wrap_policy (str, 可选，默认为 "TRANSFORMER_BASED_WRAP")： 要使用的自动包装策略。选择 "TRANSFORMER_BASED_WRAP"、"SIZE_BASED_WRAP" 或 "NO_WRAP"。
    • transformer_layer_cls_to_wrap (list[str], 可选)： 需要包装的 Transformer 层类名（区分大小写），例如 LlamaDecoderLayer。通常无需设置：包装策略会回退到模型的 _no_split_modules，该属性涵盖了大多数 transformers 模型。
    • min_num_params (int, 可选，默认为 0)： 用于基于大小的自动包装时，每个模块所需的最小参数量（与 auto_wrap_policy="SIZE_BASED_WRAP" 配合使用）。
    • xla (bool，可选，默认为 False)： 是否使用 PyTorch/XLA 完全分片数据并行训练。实验性功能。
    • xla_fsdp_settings (dict, 可选)： XLA FSDP 包装参数的字典。完整的选项列表，请参阅 XLA FSDP 源代码。
    • xla_fsdp_grad_ckpt (bool, 可选，默认为 False)： 设置为 True 以在每个嵌套的 XLA FSDP 包装层上使用梯度检查点。需要 xla=True 以及自动包装策略（min_num_params 或 transformer_layer_cls_to_wrap）。

DeepSpeed

  • deepspeed (str 或 dict, 可选) — 启用 DeepSpeed 集成。取值可以是：
    • DeepSpeed JSON 配置文件的路径："ds_config.json"
    • 已加载配置为字典

      如果使用 ZeRO 初始化，请在初始化 TrainingArguments 之后再实例化模型，否则 ZeRO 将不会生效。

调试与性能分析（实验性）

  • debug (str 或 DebugOption, 可选, 默认为 "") — 启用一个或多个调试功能。这是一个实验性功能。 可选选项包括：
    • “underflow_overflow”：检测模型输入/输出中的溢出，并报告导致该事件的最后几帧
    • “tpu_metrics_debug”：在 TPU 上打印调试指标
  • skip_memory_metrics (bool，可选，默认为 True) — 是否跳过将内存分析器报告添加到指标中。默认情况下会跳过此操作，因为它会降低训练和评估的速度。

外部脚本标志（Trainer 未使用）

  • do_train (bool，可选，默认为 False) — 是否执行训练。该参数不会被 Trainer 直接使用，而是供您的训练/评估脚本使用。
  • do_eval (bool, 可选) — 是否对验证集运行评估。如果 eval_strategy 不同于 "no"，则会被设置为 True。此参数不会被 Trainer 直接使用，而是供您的训练/评估脚本使用。
  • do_predict (bool，可选，默认为 False) — 是否对测试集运行预测。该参数不会被 Trainer 直接使用，而是供您的训练/评估脚本使用。
  • resume_from_checkpoint (str, 可选) — 指向包含模型有效检查点文件夹的路径。此参数不会被 Trainer 直接使用，而是供您的训练/评估脚本使用。
  • sortish_sampler (bool, 可选, 默认为 False) — 是否使用 sortish sampler 。目前仅当底层数据集为 Seq2SeqDataset 时可用，但很快将普遍支持。

    它会根据长度对输入进行排序，以最小化填充大小，并在训练集中加入少量随机性。

  • predict_with_generate（bool，可选，默认为 False）—— 是否使用 generate 来计算生成式指标（ROUGE、BLEU）。
  • generation_max_length (int, 可选) — 当 predict_with_generate=True 时，在每个评估循环中使用的 max_length。默认使用模型配置中的 max_length 值。
  • generation_num_beams (int, 可选) — 当 predict_with_generate=True 时，每个评估循环中使用的 num_beams。默认使用模型配置中的 num_beams 值。
  • generation_config (str 或 Path 或 GenerationConfig, ，可选) — 允许通过 GenerationConfig 从 from_pretrained 方法加载。可以是以下之一：
    • 一个字符串，即托管在 huggingface.co 模型仓库中的预训练模型配置的 model id。
    • 指向一个目录的路径，该目录包含使用save_pretrained()方法保存的配置文件，例如 ./my_model_directory/。
    • 一个 GenerationConfig 对象。

用于控制 Trainer 模型训练所有方面的配置类。 TrainingArguments 集中管理了训练所需的所有超参数、优化设置、日志记录偏好以及基础设施选择。

HfArgumentParser 可以将此类转换为 argparse 参数，从而可以在命令行中指定。

to_dict

< >

( )

在序列化此实例时，将 Enum 替换为其值，并将 GenerationConfig 替换为字典（以支持 JSON 序列化）。它会通过移除 token 的值来混淆 token 值。

Update on GitHub

←分词器 DeepSpeed→