# Trainer

[Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 类为 PyTorch 提供了功能完备的训练 API，支持在多 GPU/TPU 上进行分布式训练，支持 [NVIDIA GPU](https://nvidia.github.io/apex/)、[AMD GPU](https://rocm.docs.amd.com/en/latest/rocm.html) 的混合精度，以及 PyTorch 的 [`torch.amp`](https://pytorch.org/docs/stable/amp.html)。[Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 与 [TrainingArguments](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.TrainingArguments) 类紧密配合，后者提供了丰富的选项来自定义模型的训练方式。这两个类共同构成了完整的训练 API。

[Seq2SeqTrainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Seq2SeqTrainer) 和 [Seq2SeqTrainingArguments](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Seq2SeqTrainingArguments) 分别继承自 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 和 [TrainingArguments](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.TrainingArguments) 类，并针对摘要或翻译等序列到序列任务的模型训练进行了适配。

[Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 类针对 🤗 Transformers 模型进行了优化，与其他模型配合使用时可能会出现一些意外的行为。在将其用于您自己的模型时，请确保：

- 您的模型始终返回元组或 [ModelOutput](/docs/transformers/v5.24.0/zh/main_classes/output#transformers.utils.ModelOutput) 的子类
- 如果提供了 `labels` 参数，您的模型可以计算损失，并且该损失将作为元组的第一个元素返回（如果您的模型返回元组）。
- 您的模型可以接受多个标签参数（在 [TrainingArguments](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.TrainingArguments) 中使用 `label_names` 来向 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 指定它们的名称），但其中任何参数都不能命名为 `"label"`

## Trainer[[api-reference]][[transformers.Trainer]]

#### transformers.Trainer[[transformers.Trainer]]

```python
transformers.Trainer(model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, NoneType] = None, args: transformers.training_args.TrainingArguments | None = None, data_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = None, train_dataset: Dataset | IterableDataset | datasets.Dataset | None = None, eval_dataset: Dataset | dict[str, Dataset] | datasets.Dataset | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.image_processing_utils.BaseImageProcessor | transformers.feature_extraction_utils.FeatureExtractionMixin | transformers.processing_utils.ProcessorMixin | None = None, model_init: collections.abc.Callable[..., transformers.modeling_utils.PreTrainedModel] | None = None, compute_loss_func: collections.abc.Callable | None = None, compute_metrics: collections.abc.Callable[[transformers.trainer_utils.EvalPrediction], dict] | None = None, callbacks: list[transformers.trainer_callback.TrainerCallback] | None = None, optimizers: 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 = None, preprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L260)

**参数：**

model ([PreTrainedModel](/docs/transformers/v5.24.0/zh/main_classes/model#transformers.PreTrainedModel) 或 `torch.nn.Module`，*可选*)：要训练、评估或用于预测的模型。如果未提供，则必须传入 `model_init`。[Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 针对库提供的 [PreTrainedModel](/docs/transformers/v5.24.0/zh/main_classes/model#transformers.PreTrainedModel) 进行了优化。只要您自定义的 `torch.nn.Module` 模型的工作方式与 🤗 Transformers 模型相同，就可以继续使用它们。

args ([TrainingArguments](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.TrainingArguments)，*可选*)：用于调整训练的参数。如果未提供，将默认为 [TrainingArguments](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.TrainingArguments) 的一个基本实例，其中 `output_dir` 设置为当前目录下名为 *tmp_trainer* 的目录。

data_collator (`DataCollator`, *可选*) : 用于将 `train_dataset` 或 `eval_dataset` 的元素列表组合成一个批次的函数。如果未提供 `processing_class`，则默认为 [default_data_collator()](/docs/transformers/v5.24.0/zh/main_classes/data_collator#transformers.default_data_collator)；否则，如果 processing_class 是特征提取器或分词器，则默认为 [DataCollatorWithPadding](/docs/transformers/v5.24.0/zh/main_classes/data_collator#transformers.DataCollatorWithPadding) 的实例。

train_dataset (`torch.utils.data.Dataset` | `torch.utils.data.IterableDataset` | `datasets.Dataset`, *可选*) : 用于训练的。如果它是 [Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset)，则 `model.forward()` 方法不接受的列会被自动移除。 请注意，如果它是一个带有一定随机性的 `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](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset)，则 `model.forward()` 方法不接受的列会被自动移除。如果它是一个字典，则会在每个数据集上进行评估，并将字典键作为前缀添加到指标名称中。

processing_class (`PreTrainedTokenizerBase` 或 `BaseImageProcessor` 或 `FeatureExtractionMixin` 或 `ProcessorMixin`，*可选*)：用于处理数据的处理类。如果提供，将自动用于处理模型的输入，并随模型一起保存，以便更容易地重新运行中断的训练或复用微调后的模型。

model_init (`Callable[[], PreTrainedModel]`，*可选*)：一个用于实例化待使用模型的函数。如果提供，则每次调用 [train()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.train) 都会从该函数给出的模型新实例开始。该函数可以没有参数，也可以有一个包含 optuna/Ray Tune trial 对象的参数，以便根据超参数（如层数、内层大小、dropout 概率等）选择不同的架构。

compute_loss_func (`Callable`，*可选*)：一个函数，接受原始模型输出、标签以及整个累积批次中的样本数量（batch_size * gradient_accumulation_steps），并返回损失值。例如，参见 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 使用的默认[损失函数](https://github.com/huggingface/transformers/blob/052e652d6d53c2b26ffde87e039b723949a53493/src/transformers/trainer.py#L3618)。

compute_metrics (`Callable[[EvalPrediction], Dict]`，*可选*)：用于在评估时计算指标的函数。必须接受一个 [EvalPrediction](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.EvalPrediction) 并返回一个从字符串到指标值的字典。*注意* 当传入的 TrainingArgs 中 `batch_eval_metrics` 设置为 `True` 时，您的 compute_metrics 函数必须接受一个布尔类型的 `compute_result` 参数。这将在最后一个评估批次之后触发，以指示该函数需要计算并返回全局汇总统计信息，而不是累积批次级别的统计信息

callbacks （[TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 列表，*可选*）：用于自定义训练循环的回调列表。这些回调将被添加到[此处](callback)详述的默认回调列表中。如需移除某个默认使用的回调，请使用 [Trainer.remove_callback()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.remove_callback) 方法。

optimizers (`tuple[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR]`，*可选*，默认为 `(None, None)`)：一个包含要使用的优化器和调度器的元组。默认情况下，将在您的模型上使用 `AdamW` 的实例，并使用由 `args` 控制的、通过 [get_linear_schedule_with_warmup()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) 给出的调度器。

optimizer_cls_and_kwargs (`tuple[Type[torch.optim.Optimizer], dict[str, Any]]`，*可选*)：一个元组，包含要使用的优化器类及其关键字参数。会覆盖 `args` 中的 `optim` 和 `optim_args`。与 `optimizers` 参数不兼容。与 `optimizers` 不同，此参数无需在初始化 Trainer 之前将模型参数放置到正确的设备上。

preprocess_logits_for_metrics (`Callable[[torch.Tensor, torch.Tensor], torch.Tensor]`，*可选*)：一个函数，用于在每个评估步骤缓存 logits 之前对其进行预处理。该函数必须接收两个张量（logits 和 labels），并返回按预期处理后的 logits。此函数所做的修改将反映在传递给 `compute_metrics` 的预测结果中。请注意，如果数据集不包含 labels，则 labels（第二个参数）将为 `None`。

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

重要属性：

- **model** -- 始终指向核心模型。如果使用 transformers 模型，它将是 [PreTrainedModel](/docs/transformers/v5.24.0/zh/main_classes/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[[transformers.Trainer.add_callback]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4700)

**参数：**

callback (`type` 或 [`~transformers.TrainerCallback]`)：一个 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 类或 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 的实例。在前一种情况下，将实例化该类的一个成员。

将回调添加到当前的 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 列表中。

#### autocast_smart_context_manager[[transformers.Trainer.autocast_smart_context_manager]]

```python
autocast_smart_context_manager(cache_enabled: bool | None = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2231)

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

#### call_model_init[[transformers.Trainer.call_model_init]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4591)

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

#### compute_loss[[transformers.Trainer.compute_loss]]

```python
compute_loss(model: Module, inputs: dict[str, typing.Union[torch.Tensor, typing.Any]], return_outputs: bool = False, num_items_in_batch: typing.Union[int, torch.Tensor, NoneType] = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2130)

**参数：**

model (`nn.Module`)：用于计算损失的模型。

inputs (`dict[str, torch.Tensor | Any]`) : 模型的输入数据。

return_outputs (`bool`，*可选*，默认为 `False`)：是否返回模型输出以及损失值。

num_items_in_batch (Optional[torch.Tensor], *可选*) : 批次中的项目数量。如果未传入，则使用默认的批次大小归约逻辑来计算损失。

**返回值：**

如果 return_outputs 设置为 True，则返回模型的损失及其输出

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

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

#### compute_loss_context_manager[[transformers.Trainer.compute_loss_context_manager]]

```python
compute_loss_context_manager()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2219)

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

#### create_accelerator_and_postprocess[[transformers.Trainer.create_accelerator_and_postprocess]]

```python
create_accelerator_and_postprocess()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L806)

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

#### create_model_card[[transformers.Trainer.create_model_card]]

```python
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)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4271)

**参数：**

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[[transformers.Trainer.create_optimizer]]

```python
create_optimizer(model = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L1259)

**返回：** `torch.optim.Optimizer`

优化器实例。

设置优化器。

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

#### create_optimizer_and_scheduler[[transformers.Trainer.create_optimizer_and_scheduler]]

```python
create_optimizer_and_scheduler(num_training_steps: int)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L1248)

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

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

#### create_scheduler[[transformers.Trainer.create_scheduler]]

```python
create_scheduler(num_training_steps: int, optimizer: typing.Optional[torch.optim.Optimizer] = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L1347)

**参数：**

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

**返回：** `torch.optim.lr_scheduler.LRScheduler`

学习率调度器实例。

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

#### 结束[[transformers.Trainer.end]]

```python
end()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L3113)

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

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

示例：

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

#### evaluate[[transformers.Trainer.evaluate]]

```python
evaluate(eval_dataset: typing.Union[torch.utils.data.Dataset, dict[str, torch.utils.data.Dataset], NoneType] = None, ignore_keys: list[str] | None = None, metric_key_prefix: str = 'eval')
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2805)

**参数：**

eval_dataset (`Dataset` | dict[str, `Dataset`], *optional*) : 如果您希望覆盖 `self.eval_dataset`，请传入一个数据集。如果传入的是 [Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.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"。

**返回值：**

一个字典，包含评估损失以及从预测结果中计算得出的潜在指标。该字典还包含来自训练状态的 epoch 编号。

运行评估并返回指标。

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

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

#### evaluation_loop[[transformers.Trainer.evaluation_loop]]

```python
evaluation_loop(dataloader: DataLoader, description: str, prediction_loss_only: bool | None = None, ignore_keys: list[str] | None = None, metric_key_prefix: str = 'eval')
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2904)

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

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

#### floating_point_ops[[transformers.Trainer.floating_point_ops]]

```python
floating_point_ops(inputs: dict[str, typing.Union[torch.Tensor, typing.Any]])
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4224)

**参数：**

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

**返回：** `int`

浮点运算次数。

对于继承自 [PreTrainedModel](/docs/transformers/v5.24.0/zh/main_classes/model#transformers.PreTrainedModel) 的模型，该方法用于计算每次反向传播 + 前向传播的浮点运算次数。如果使用其他模型，则需要在模型中实现此类方法，或者通过子类化并覆盖此方法来实现。

#### get_batch_samples[[transformers.Trainer.get_batch_samples]]

```python
get_batch_samples(epoch_iterator: Iterator, num_batches: int, device: device)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2289)

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

#### get_cp_size[[transformers.Trainer.get_cp_size]]

```python
get_cp_size()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2591)

获取上下文并行大小

#### get_decay_parameter_names[[transformers.Trainer.get_decay_parameter_names]]

```python
get_decay_parameter_names(model: Module)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L1408)

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

此函数通过两种方式过滤参数：
1. 按层类型（ALL_LAYERNORM_LAYERS 中指定的层实例）
2. 按参数名称模式（包含 'bias'，或 'norm' 的变体）

#### get_eval_dataloader[[transformers.Trainer.get_eval_dataloader]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L936)

**参数：**

eval_dataset (`str` 或 `torch.utils.data.Dataset`，*可选*)：如果为 `str`，则将使用 `self.eval_dataset[eval_dataset]` 作为评估数据集。如果为 `Dataset`，则会覆盖 `self.eval_dataset`。如果为 [Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset)，`model.forward()` 方法不接受的列会被自动移除。

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

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

#### get_learning_rates[[transformers.Trainer.get_learning_rates]]

```python
get_learning_rates()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_pt_utils.py#L1304)

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

#### get_num_trainable_parameters[[transformers.Trainer.get_num_trainable_parameters]]

```python
get_num_trainable_parameters()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_pt_utils.py#L1296)

获取可训练参数的数量。

#### get_optimizer_cls_and_kwargs[[transformers.Trainer.get_optimizer_cls_and_kwargs]]

```python
get_optimizer_cls_and_kwargs(args: TrainingArguments, model: transformers.modeling_utils.PreTrainedModel | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L1377)

**参数：**

args (`transformers.training_args.TrainingArguments`)：训练会话的训练参数。

model (`PreTrainedModel`，*可选*)：正在训练的模型。某些优化器（GaLore、Apollo、LOMO）需要此参数。

**返回值：**

一个元组，包含优化器类以及一个包含优化器关键字参数的字典。

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

#### get_optimizer_group[[transformers.Trainer.get_optimizer_group]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_pt_utils.py#L1314)

**参数：**

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

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

#### get_sp_size[[transformers.Trainer.get_sp_size]]

```python
get_sp_size()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2583)

获取序列并行大小

#### get_test_dataloader[[transformers.Trainer.get_test_dataloader]]

```python
get_test_dataloader(test_dataset: Dataset)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L975)

**参数：**

test_dataset (`torch.utils.data.Dataset`，*可选*)：要使用的测试数据集。如果它是 [Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset)，则 `model.forward()` 方法不接受的列会被自动移除。

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

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

#### get_total_train_batch_size[[transformers.Trainer.get_total_train_batch_size]]

```python
get_total_train_batch_size(args: TrainingArguments)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2565)

计算总批大小（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[[transformers.Trainer.get_tp_size]]

```python
get_tp_size()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2599)

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

#### get_train_dataloader[[transformers.Trainer.get_train_dataloader]]

```python
get_train_dataloader()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L916)

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

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

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

#### hyperparameter_search[[transformers.Trainer.hyperparameter_search]]

```python
hyperparameter_search(hp_space: collections.abc.Callable[['optuna.Trial'], dict[str, float]] | None = None, compute_objective: collections.abc.Callable[[dict[str, float]], float] | None = None, n_trials: int = 20, direction: str | list[str] = 'minimize', backend: str | transformers.trainer_utils.HPSearchBackend | None = None, hp_name: collections.abc.Callable[['optuna.Trial'], str] | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4510)

**参数：**

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"`) : 如果是单目标优化，direction 为 `str`，可以是 `"minimize"` 或 `"maximize"`。在优化验证损失时，应选择 `"minimize"`；在优化一个或多个指标时，应选择 `"maximize"`。如果是多目标优化，direction 为 `list[str]`，可以是 `"minimize"` 和 `"maximize"` 的列表。在优化验证损失时，应选择 `"minimize"`；在优化一个或多个指标时，应选择 `"maximize"`。

backend (`str` 或 `~training_utils.HPSearchBackend`，*可选*)：用于超参数搜索的后端。将根据已安装的库，默认使用 optuna 或 Ray Tune。如果两者均已安装，则默认使用 optuna。

hp_name (`Callable[["optuna.Trial"], str]]`, *可选*) : 用于定义试验/运行名称的函数。默认值为 None。

kwargs (`dict[str, Any]`, *可选*) : 每个后端的额外关键字参数：  - `optuna`：来自 [optuna.study.create_study](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.study.create_study.html) 的参数，以及来自 [optuna.study.Study.optimize](https://optuna.readthedocs.io/en/stable/reference/generated/optuna.study.Study.html#optuna.study.Study.optimize) 的参数 `timeout`、`n_jobs` 和 `gc_after_trial` - `ray`：来自 [tune.run](https://docs.ray.io/en/latest/tune/api_docs/execution.html#tune-run) 的参数。如果未在 `kwargs` 中设置 `resources_per_trial`，则默认为 1 个 CPU 核心和 1 个 GPU（如果可用）。如果未在 `kwargs` 中设置 `progress_reporter`，则使用 [ray.tune.CLIReporter](https://docs.ray.io/en/latest/tune/api/doc/ray.tune.CLIReporter.html)。

**返回：** [`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](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer): we need to reinitialize the model at each new run. This is incompatible with the `optimizers` argument, so you need to subclass [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) and override the method [create_optimizer_and_scheduler()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.create_optimizer_and_scheduler) for custom optimizer/scheduler.

#### init_hf_repo[[transformers.Trainer.init_hf_repo]]

```python
init_hf_repo(token: str | None = None, private: bool | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4245)

**参数：**

token (`str`，*可选*)：具有写入权限的令牌。默认为 `self.args.hub_token`。

private (`bool`，*可选*)：创建仓库时是否将其设为私有。默认值为 `self.args.hub_private_repo`。如果仓库已存在，则此参数无效。

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

#### is_local_process_zero[[transformers.Trainer.is_local_process_zero]]

```python
is_local_process_zero()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4740)

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

#### is_world_process_zero[[transformers.Trainer.is_world_process_zero]]

```python
is_world_process_zero()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4747)

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

#### log[[transformers.Trainer.log]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4189)

**参数：**

logs (`dict[str, float]`) : 要记录的值。

start_time (`Optional[float]`) : 训练的起始位置。

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

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

#### log_metrics[[transformers.Trainer.log_metrics]]

```python
log_metrics(split, metrics)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_pt_utils.py#L1152)

**参数：**

split (`str`) : 模式/分割名称：`train`、`eval`、`test` 之一

metrics (`dict[str, float]`) : 从 train/evaluate/predict 返回的指标：指标字典

以特殊格式记录指标。

在分布式环境中，此操作仅由 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](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 的 `__init__`、`train`、`evaluate` 和 `predict` 调用之外的内存分配。

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

这也意味着，如果与 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 配合使用的任何其他工具调用了 `torch.cuda.reset_peak_memory_stats`，GPU 峰值内存统计信息可能会失效。此外，[Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 会干扰那些依赖自行调用 `torch.cuda.reset_peak_memory_stats` 的工具的正常运行。

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

#### metrics_format[[transformers.Trainer.metrics_format]]

```python
metrics_format(metrics: dict[str, float])
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_pt_utils.py#L1125)

**参数：**

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

**返回：** 指标（`dict[str, float]`）

重新格式化后的指标

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

#### num_examples[[transformers.Trainer.num_examples]]

```python
num_examples(dataloader: DataLoader)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L993)

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

#### pop_callback[[transformers.Trainer.pop_callback]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4711)

**参数：**

callback (`type` 或 [`~transformers.TrainerCallback]`)：一个 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 类或一个 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 实例。在前一种情况下，将从回调列表中弹出找到的该类的首个成员。

**返回：** [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback)

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

从当前的 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 列表中移除一个回调并返回它。

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

#### predict[[transformers.Trainer.predict]]

```python
predict(test_dataset: Dataset, ignore_keys: list[str] | None = None, metric_key_prefix: str = 'test')
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L3132)

**参数：**

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[[transformers.Trainer.prediction_step]]

```python
prediction_step(model: Module, inputs: dict[str, typing.Union[torch.Tensor, typing.Any]], prediction_loss_only: bool, ignore_keys: list[str] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L3193)

**参数：**

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[[transformers.Trainer.push_to_hub]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4345)

**参数：**

commit_message (`str`，*可选*，默认为 `"End of training"`)：推送时提交的说明信息。

blocking (`bool`，*可选*，默认为 `True`)：函数是否应在 `git push` 完成后才返回。

token (`str`，*可选*，默认为 `None`)：具有写入权限的令牌，用于覆盖 Trainer 的原始参数。

revision (`str`，*可选*)：要提交来源的 git 修订版本。默认为 "main" 分支的头部。

private (`bool`，*可选*)：创建仓库时是否将其设为私有。默认值为 `args.hub_private_repo`。如果仓库已存在，则此参数无效。

kwargs (`dict[str, Any]`, *可选*) : 传递给 [create_model_card()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.create_model_card) 的额外关键字参数。

**返回值：**

如果 `blocking=False`，则返回推送模型所在仓库的 URL；如果 `blocking=True`，则返回一个跟踪提交进度的 `Future` 对象。

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

#### remove_callback[[transformers.Trainer.remove_callback]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4727)

**参数：**

callback (`type` 或 [`~transformers.TrainerCallback]`)：一个 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 类或 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 的实例。在前一种情况下，将从回调列表中移除找到的该类第一个成员。

从当前的 [TrainerCallback](/docs/transformers/v5.24.0/zh/main_classes/callback#transformers.TrainerCallback) 列表中移除一个回调。

#### save_metrics[[transformers.Trainer.save_metrics]]

```python
save_metrics(split, metrics, combined = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_pt_utils.py#L1243)

**参数：**

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()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.log_metrics) 的文档字符串。唯一的区别是，当前方法保存的是未经格式化的原始数字。

#### save_model[[transformers.Trainer.save_model]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4085)

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

仅从主进程保存。

#### save_state[[transformers.Trainer.save_state]]

```python
save_state()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_pt_utils.py#L1282)

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

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

#### set_initial_training_values[[transformers.Trainer.set_initial_training_values]]

```python
set_initial_training_values(args: TrainingArguments, dataloader: DataLoader)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2495)

计算并返回以下值：
- `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[[transformers.Trainer.store_flos]]

```python
store_flos()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L4213)

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

#### train[[transformers.Trainer.train]]

```python
train(resume_from_checkpoint: str | bool | None = None, trial: optuna.Trial | dict[str, Any] | None = None, ignore_keys_for_eval: list[str] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L1450)

**参数：**

resume_from_checkpoint (`str` 或 `bool`，*可选*)：如果为 `str`，则为之前 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 实例保存的检查点的本地路径。如果为 `bool` 且等于 `True`，则加载之前 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 实例保存在 *args.output_dir* 中的最后一个检查点。如果存在，训练将从此处加载的模型/优化器/调度器状态恢复。

trial (`optuna.Trial` 或 `dict[str, Any]`，*可选*)：用于超参数搜索的试验运行或超参数字典。

ignore_keys_for_eval (`list[str]`, *可选*) : 模型输出（如果输出是字典）中，在训练期间收集预测结果进行评估时应忽略的键列表。

**返回：** `TrainOutput`

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

主要训练入口。

#### training_step[[transformers.Trainer.training_step]]

```python
training_step(model: Module, inputs: dict[str, typing.Union[torch.Tensor, typing.Any]], num_items_in_batch: typing.Union[int, torch.Tensor, NoneType] = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer.py#L2051)

**参数：**

model (`nn.Module`)：要训练的模型。

inputs (`dict[str, torch.Tensor | Any]`) : 模型的输入和目标。该字典在传入模型之前会被解包。大多数模型期望目标位于参数 `labels` 下。请查阅模型的文档以了解所有接受的参数。

**返回：** `torch.Tensor`

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

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

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

## Seq2SeqTrainer[[transformers.Seq2SeqTrainer]]

#### transformers.Seq2SeqTrainer[[transformers.Seq2SeqTrainer]]

```python
transformers.Seq2SeqTrainer(model: typing.Union[ForwardRef('PreTrainedModel'), torch.nn.Module, NoneType] = None, args: typing.Optional[ForwardRef('TrainingArguments')] = None, data_collator: typing.Optional[ForwardRef('DataCollator')] = None, train_dataset: typing.Union[torch.utils.data.Dataset, ForwardRef('IterableDataset'), ForwardRef('datasets.Dataset'), NoneType] = None, eval_dataset: typing.Union[torch.utils.data.Dataset, dict[str, torch.utils.data.Dataset], NoneType] = None, processing_class: typing.Union[ForwardRef('PreTrainedTokenizerBase'), ForwardRef('BaseImageProcessor'), ForwardRef('FeatureExtractionMixin'), ForwardRef('ProcessorMixin'), NoneType] = None, model_init: collections.abc.Callable[[], 'PreTrainedModel'] | None = None, compute_loss_func: collections.abc.Callable | None = None, compute_metrics: collections.abc.Callable[['EvalPrediction'], dict] | None = None, callbacks: list['TrainerCallback'] | None = None, optimizers: 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)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_seq2seq.py#L55)

#### evaluate[[transformers.Seq2SeqTrainer.evaluate]]

```python
evaluate(eval_dataset: typing.Optional[torch.utils.data.Dataset] = None, ignore_keys: list[str] | None = None, metric_key_prefix: str = 'eval', **gen_kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_seq2seq.py#L139)

**参数：**

eval_dataset (`Dataset`，*可选*)：如果您希望覆盖 `self.eval_dataset`，请传入一个数据集。如果它是 [Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.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 方法进行预测时，束搜索所使用的束数量。1 表示不使用束搜索。

gen_kwargs : 额外的 `generate` 特定关键字参数。

**返回值：**

一个字典，包含评估损失以及从预测结果中计算得出的潜在指标。该字典还包含来自训练状态的 epoch 编号。

运行评估并返回指标。

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

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

#### predict[[transformers.Seq2SeqTrainer.predict]]

```python
predict(test_dataset: Dataset, ignore_keys: list[str] | None = None, metric_key_prefix: str = 'test', **gen_kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/trainer_seq2seq.py#L195)

**参数：**

test_dataset (`Dataset`)：用于运行预测的数据集。如果它是 [Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.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 方法进行预测时，束搜索所使用的束数量。1 表示不使用束搜索。

gen_kwargs : 额外的 `generate` 特定关键字参数。

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

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

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

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

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

## TrainingArguments[[transformers.TrainingArguments]]

#### transformers.TrainingArguments[[transformers.TrainingArguments]]

```python
transformers.TrainingArguments(output_dir: str | None = None, per_device_train_batch_size: int = 8, num_train_epochs: float = 3.0, max_steps: int = -1, learning_rate: float = 5e-05, lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool = False, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool | None = None, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 500, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = False, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: typing.Any | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool = True, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L180)

**参数：**

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

**训练时长和批大小：**

per_device_train_batch_size (`int`，*可选*，默认值为 8)：*每个设备*的批大小。**全局批大小**计算方式为：`per_device_train_batch_size * number_of_devices`（适用于多 GPU 或分布式环境）。

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` or [SchedulerType](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.SchedulerType), *optional*, defaults to `"linear"`) : The learning rate scheduler type to use. See [SchedulerType](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.SchedulerType) for all possible values. Common choices: - "linear" = [get_linear_schedule_with_warmup()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) - "cosine" = [get_cosine_schedule_with_warmup()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_cosine_schedule_with_warmup) - "constant" =  [get_constant_schedule()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_constant_schedule) - "constant_with_warmup" = [get_constant_schedule_with_warmup()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_constant_schedule_with_warmup)

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 正则化，以防止过拟合。自动排除偏置和 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 算法](https://huggingface.co/papers/2403.03507) 和 [APOLLO 算法](https://huggingface.co/papers/2412.05270)。有关更多详细信息，请参阅 [GaLore 实现](https://github.com/jiaweizzhao/GaLore) 和 [APOLLO 实现](https://github.com/zhuhanqing/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`。> [!TIP] > 使用梯度累积时，一次“步”被计为一次带有反向传播的步。因此，日志记录、评估和保存将每 `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 文档](https://huggingface.co/docs/transformers/perf_train_gpu_one#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](https://github.com/linkedin/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`)：是否启用模型的缓存。在训练过程中，通常不需要启用此功能，除非使用某些依赖 `cache` 的 PEFT 方法。

neftune_noise_alpha (`Optional[float]`) : 如果不为 `None`，将启用 NEFTune 噪声嵌入。这可以显著提升指令微调的模型性能。请参阅 [原始论文](https://huggingface.co/papers/2310.05914) 和 [原始代码](https://github.com/neelsjain/NEFTune)。支持 transformers 的 `PreTrainedModel` 以及来自 peft 的 `PeftModel`。原始论文中使用的值范围为 [5.0, 15.0]。

torch_empty_cache_steps (`int`, *可选*) : 在调用 `torch.<device>.empty_cache()` 之前等待的步数。如果未设置或设置为 None，则不会清空缓存。这可以通过降低峰值 VRAM 使用量来帮助避免 CUDA 内存不足错误，但代价是性能大约降低 [10%](https://github.com/huggingface/transformers/issues/31372)。

auto_find_batch_size (`bool`，*可选*，默认为 `False`)：是否通过指数衰减自动寻找能够放入内存的训练批次大小，以避免 CUDA 内存不足错误。评估批次大小不会进行调整。

**记录与监控训练：**

logging_strategy (`str` 或 [IntervalStrategy](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.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](https://github.com/gradio-app/trackio)、[wandb](https://www.wandb.com/)、[mlflow](https://www.mlflow.org/)、[comet](https://www.comet.com/site) 和 [swanlab](https://swanlab.cn) 日志记录。

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](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.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`)：是否递归地从所有设备收集嵌套在列表/元组/字典中的对象。仅当用户返回的内容不仅仅是张量时才应启用此选项，PyTorch 明确不推荐这样做。当标签结构不符合标准时（例如在计算机视觉任务中），此选项会很有用。

eval_accumulation_steps (`int`, *optional*) : 在将结果移至 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_result` 的 compute_metrics 函数；当该参数传入 `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()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.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()](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.enable_full_determinism) 而不是 [set_seed()](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.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`，而不是创建新的状态。这可能会导致超参数调优出现问题。

parallelism_config (`ParallelismConfig`，*可选*)：训练运行的并行配置。需要 Accelerate `1.10.1`

**数据加载器：**

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`)：是否自动移除模型前向方法未使用的列。

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`, *可选*) : 用于分布式训练的后端。必须是 `"nccl"`、`"mpi"`、`"xccl"`、`"gloo"`、`"hccl"` 之一。

ddp_timeout (`int`，*可选*，默认值为 1800)：`torch.distributed.init_process_group` 调用的超时时间，用于在分布式运行中执行缓慢操作时避免 GPU 套接字超时。有关更多信息，请参阅 [PyTorch 文档](https://pytorch.org/docs/stable/distributed.html#torch.distributed.init_process_group)。

**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`），或一个已加载的字典。 支持的键： - 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 Fully Sharded Data Parallel Training。实验性功能。 - xla_fsdp_settings (`dict`，*可选*)：XLA FSDP 包装参数的字典。完整选项列表请参阅 [XLA FSDP 源代码](https://github.com/pytorch/xla/blob/master/torch_xla/distributed/fsdp/xla_fully_sharded_data_parallel.py)。 - xla_fsdp_grad_ckpt (`bool`，*可选*，默认为 `False`)：设置为 `True` 可对每个嵌套的 XLA FSDP 包装层使用梯度检查点。需要 `xla=True` 以及一个自动包装策略（`min_num_params` 或 `transformer_layer_cls_to_wrap`）。

**DeepSpeed：**

deepspeed (`str` 或 `dict`，*可选*) : 启用 [DeepSpeed](https://github.com/deepspeedai/DeepSpeed) 集成。取值可以是：- DeepSpeed JSON 配置文件的路径：`"ds_config.json"` - 以字典形式加载的配置 > [!TIP] > 如果使用 ZeRO 初始化，请在初始化 `TrainingArguments` *之后* 再实例化模型，否则 ZeRO 不会生效。

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

debug (`str` 或 `DebugOption` 列表，*可选*，默认为 `""`)：启用一个或多个调试功能。这是一个实验性功能。可选选项包括：- "underflow_overflow"：检测模型输入/输出中的溢出，并报告导致该事件的最后几个帧 - "tpu_metrics_debug"：在 TPU 上打印调试指标

skip_memory_metrics (`bool`，*可选*，默认为 `True`)：是否跳过将内存分析器报告添加到指标中。默认情况下会跳过此操作，因为它会降低训练和评估速度。

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

do_train (`bool`，*可选*，默认为 `False`)：是否运行训练。此参数不会被 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 直接使用，而是供您的训练/评估脚本使用。

do_eval (`bool`，*可选*)：是否在验证集上运行评估。如果 `eval_strategy` 不同于 `"no"`，则会被设置为 `True`。此参数不会被 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 直接使用，而是供您的训练/评估脚本使用。

do_predict (`bool`，*可选*，默认为 `False`)：是否对测试集运行预测。此参数不会被 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 直接使用，而是供您的训练/评估脚本使用。

resume_from_checkpoint (`str`, *可选*) : 包含模型有效检查点（checkpoint）的文件夹路径。此参数不会被 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 直接使用，而是供您的训练/评估脚本使用。

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

[HfArgumentParser](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.HfArgumentParser) 可以将此类转换为可通过命令行指定的 [argparse](https://docs.python.org/3/library/argparse#module-argparse) 参数。

#### get_process_log_level[[transformers.TrainingArguments.get_process_log_level]]

```python
get_process_log_level()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2065)

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

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

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

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

#### get_warmup_steps[[transformers.TrainingArguments.get_warmup_steps]]

```python
get_warmup_steps(num_training_steps: int)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2154)

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

#### main_process_first[[transformers.TrainingArguments.main_process_first]]

```python
main_process_first(local = True, desc = 'work')
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2103)

**参数：**

local (`bool`，*可选*，默认为 `True`)：如果为 `True`，则“first”指每个节点上 rank 为 0 的进程；如果为 `False`，则“first”指 rank 为 0 的节点上 rank 为 0 的进程。在具有共享文件系统的多节点环境中，您通常希望使用 `local=False`，以便仅第一个节点的主进程执行处理。但如果文件系统未共享，则每个节点的主进程都需要执行处理，这是默认行为。

desc (`str`，*可选*，默认为 `"work"`)：用于调试日志的工作描述

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

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

#### set_dataloader[[transformers.TrainingArguments.set_dataloader]]

```python
set_dataloader(train_batch_size: int = 8, eval_batch_size: int = 8, drop_last: bool = False, num_workers: int = 0, pin_memory: bool = True, persistent_workers: bool = False, prefetch_factor: int | None = None, multiprocessing_context: str | None = None, in_order: bool = True, auto_find_batch_size: bool = False, ignore_data_skip: bool = False, sampler_seed: int | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2694)

**参数：**

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 预先加载的批次数。2 表示所有 worker 总共会预取 2 * num_workers 个批次。

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`)：是否通过指数衰减自动寻找适合内存的批大小，以避免 CUDA 内存不足错误。需要安装 accelerate（`pip install accelerate`）

ignore_data_skip (`bool`，*可选*，默认为 `False`)：在恢复训练时，是否跳过相应的 epoch 和 batch，以使数据加载进度与之前训练中断时保持一致。如果设置为 `True`，训练启动会更快（因为跳过步骤可能耗时较长），但结果将与被中断的训练不同。

sampler_seed (`int`, *可选*) : 用于数据采样器的随机种子。如果未设置，数据采样的随机生成器将使用与 `self.seed` 相同的种子。这可用于确保数据采样的可复现性，且独立于模型种子。

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

示例：

```py
>>> 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[[transformers.TrainingArguments.set_evaluate]]

```python
set_evaluate(strategy: str | transformers.trainer_utils.IntervalStrategy = 'no', steps: int = 500, batch_size: int = 8, accumulation_steps: int | None = None, delay: float | None = None, loss_only: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2311)

**参数：**

strategy (`str` 或 [IntervalStrategy](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.IntervalStrategy)，*可选*，默认为 `"no"`)：训练期间采用的评估策略。可能的取值如下： - `"no"`：训练期间不进行任何评估。 - `"steps"`：每 `steps` 步执行一次评估（并记录日志）。 - `"epoch"`：在每个 epoch 结束时执行评估。 将 `strategy` 设置为 `"no"` 以外的值会将 `self.do_eval` 设为 `True`。

steps (`int`，*可选*，默认值为 500)：当 `strategy="steps"` 时，两次评估之间的更新步数。

batch_size (`int` *optional*，默认为 8)：用于评估的每个设备（GPU/TPU 核心/CPU...）的批处理大小。

accumulation_steps (`int`, *optional*) : 在将结果移至 CPU 之前，用于累积输出张量的预测步数。如果未设置，则所有预测结果都将在 GPU/TPU 上累积，然后再移至 CPU（速度更快，但需要更多内存）。

delay (`float`, *可选*) : 根据 eval_strategy，在首次评估可以执行之前需要等待的 epoch 数或步数。

loss_only (`bool`，*可选*，默认为 `False`)：忽略除损失以外的所有输出。

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

示例：

```py
>>> from transformers import TrainingArguments

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

#### set_logging[[transformers.TrainingArguments.set_logging]]

```python
set_logging(strategy: str | transformers.trainer_utils.IntervalStrategy = 'steps', steps: int = 500, report_to: str | list[str] = 'none', level: str = 'passive', first_step: bool = False, nan_inf_filter: bool = False, on_each_node: bool = False, replica_level: str = 'passive')
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2453)

**参数：**

strategy (`str` 或 [IntervalStrategy](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.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` 相同

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

示例：

```py
>>> from transformers import TrainingArguments

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

#### set_lr_scheduler[[transformers.TrainingArguments.set_lr_scheduler]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2651)

**参数：**

name (`str` 或 [SchedulerType](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.SchedulerType)，*可选*，默认为 `"linear"`) : 要使用的调度器类型。有关所有可能的值，请参阅 [SchedulerType](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.SchedulerType) 的文档。

num_epochs(`float`，*可选*，默认值为 3.0)：要执行的训练总轮数（如果不是整数，则在停止训练前执行最后一轮的相应小数部分）。

max_steps (`int`，*可选*，默认值为 -1)：如果设置为正数，则指定要执行的训练总步数。该参数会覆盖 `num_train_epochs`。对于有限数据集，如果所有数据均已用尽，训练将反复遍历数据集，直到达到 `max_steps`。当训练数据集未实现 `__len__`（例如流式数据集）时，必须将其设置为正值，因为此时无法推断总步数，而该值对于限定训练循环和配置学习率调度器是必需的。

warmup_steps (`float`, *可选*，默认为 0) : 用于从 0 到 `learning_rate` 进行线性预热（linear warmup）的步数。 应为整数或 `[0,1)` 范围内的浮点数。 如果小于 1，则将被解释为用于从 0 到 `learning_rate` 进行线性预热的步数比例。

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

示例：

```py
>>> 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[[transformers.TrainingArguments.set_optimizer]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2600)

**参数：**

name (`str` 或 `training_args.OptimizerNames`，*可选*，默认为 `"adamw_torch"`)：要使用的优化器：`"adamw_torch"`、`"adamw_torch_fused"`、`"adamw_anyprecision"` 或 `"adafactor"`。

learning_rate (`float`, *可选*，默认为 5e-5)：初始学习率。

weight_decay (`float`，*可选*，默认为 0)：应用于除所有偏置和 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"` 时有用）。

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

示例：

```py
>>> 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[[transformers.TrainingArguments.set_push_to_hub]]

```python
set_push_to_hub(model_id: str, strategy: str | transformers.trainer_utils.HubStrategy = 'every_save', token: str | None = None, private_repo: bool | None = None, always_push: bool = False, revision: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2528)

**参数：**

model_id (`str`) : 要与本地 *output_dir* 保持同步的仓库名称。它可以是一个简单的模型 ID，在这种情况下，模型将推送到您的命名空间。否则，它应该是完整的仓库名称，例如 `"user_name/model"`，这允许您使用 `"organization_name/model"` 推送到您所属的组织。

strategy (`str` 或 `HubStrategy`，*可选*，默认为 `"every_save"`)：定义推送到 Hub 的内容范围及推送时机。可能的取值如下： - `"end"`：在调用 [save_model()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.save_model) 方法时，推送模型、其配置、processing_class（例如 tokenizer，如果已传递给 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer)）以及模型卡草稿。 - `"every_save"`：每次保存模型时，推送模型、其配置、processing_class（例如 tokenizer，如果已传递给 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer)）以及模型卡草稿。推送是异步进行的，以免阻塞训练；如果保存非常频繁，只有在上一次推送完成后才会尝试新的推送。训练结束时，会推送最终模型。 - `"checkpoint"`：与 `"every_save"` 类似，但还会将最新的检查点推送到名为 last-checkpoint 的子文件夹中，从而允许您使用 `trainer.train(resume_from_checkpoint="last-checkpoint")` 轻松恢复训练。 - `"all_checkpoints"`：与 `"checkpoint"` 类似，但会推送所有检查点，其结构与输出文件夹中的呈现方式一致（因此最终仓库中每个检查点文件夹对应一个文件夹）。

token (`str`, *可选*) : 用于将模型推送到 Hub 的令牌。默认使用通过 `hf auth login` 获取并存储在缓存文件夹中的令牌。

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()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.save_model) 也会触发推送。

示例：

```py
>>> 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[[transformers.TrainingArguments.set_save]]

```python
set_save(strategy: str | transformers.trainer_utils.IntervalStrategy = 'steps', steps: int = 500, total_limit: int | None = None, on_each_node: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2404)

**参数：**

strategy (`str` 或 [IntervalStrategy](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.IntervalStrategy)，*可选*，默认为 `"steps"`)：训练期间采用的检查点保存策略。可能的取值如下： - `"no"`：训练期间不执行保存。 - `"epoch"`：在每个 epoch 结束时执行保存。 - `"steps"`：每 `save_steps` 步执行一次保存。

steps (`int`，*可选*，默认值为 500)：当 `strategy="steps"` 时，两次保存检查点之间的更新步数。

total_limit (`int`，*可选*)：如果传入该值，将限制检查点的总数。会删除 `output_dir` 中较旧的检查点。

on_each_node (`bool`，*可选*，默认为 `False`)：在进行多节点分布式训练时，是否在每个节点上保存模型和检查点，还是仅在主要节点上保存。如果不同节点使用相同的存储，则不应启用此选项，因为每个节点保存的文件将具有相同的名称。

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

示例：

```py
>>> from transformers import TrainingArguments

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

#### set_testing[[transformers.TrainingArguments.set_testing]]

```python
set_testing(batch_size: int = 8, loss_only: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2368)

**参数：**

batch_size (`int` *optional*，默认为 8)：用于测试的每个设备（GPU/TPU 核心/CPU...）的批处理大小。

loss_only (`bool`，*可选*，默认为 `False`)：忽略除损失以外的所有输出。

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

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

示例：

```py
>>> from transformers import TrainingArguments

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

#### set_training[[transformers.TrainingArguments.set_training]]

```python
set_training(learning_rate: float = 5e-05, batch_size: int = 8, weight_decay: float = 0, num_epochs: float = 3, max_steps: int = -1, gradient_accumulation_steps: int = 1, seed: int = 42, activation_checkpointing: bool = False, gradient_checkpointing: bool | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2225)

**参数：**

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)：在执行反向传播/更新之前，用于累积梯度的更新步数。使用梯度累积时，一次带有反向传播的步数计为一步。因此，日志记录、评估和保存将在每 `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`。

示例：

```py
>>> 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[[transformers.TrainingArguments.to_dict]]

```python
to_dict()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2175)

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

#### to_json_string[[transformers.TrainingArguments.to_json_string]]

```python
to_json_string()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2205)

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

#### to_sanitized_dict[[transformers.TrainingArguments.to_sanitized_dict]]

```python
to_sanitized_dict()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args.py#L2211)

用于 TensorBoard hparams 的净化序列化

## Seq2SeqTrainingArguments[[transformers.Seq2SeqTrainingArguments]]

#### transformers.Seq2SeqTrainingArguments[[transformers.Seq2SeqTrainingArguments]]

```python
transformers.Seq2SeqTrainingArguments(output_dir: str | None = None, per_device_train_batch_size: int = 8, num_train_epochs: float = 3.0, max_steps: int = -1, learning_rate: float = 5e-05, lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool = False, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool | None = None, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 500, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = False, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: typing.Any | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool = True, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1, sortish_sampler: bool = False, predict_with_generate: bool = False, generation_max_length: int | None = None, generation_num_beams: int | None = None, generation_config: str | pathlib.Path | transformers.generation.configuration_utils.GenerationConfig | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args_seq2seq.py#L29)

**参数：**

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

**训练时长和批大小：**

per_device_train_batch_size (`int`，*可选*，默认值为 8)：*每个设备*的批大小。**全局批大小**计算方式为：`per_device_train_batch_size * number_of_devices`（适用于多 GPU 或分布式环境）。

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` or [SchedulerType](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.SchedulerType), *optional*, defaults to `"linear"`) : The learning rate scheduler type to use. See [SchedulerType](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.SchedulerType) for all possible values. Common choices: - "linear" = [get_linear_schedule_with_warmup()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) - "cosine" = [get_cosine_schedule_with_warmup()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_cosine_schedule_with_warmup) - "constant" =  [get_constant_schedule()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_constant_schedule) - "constant_with_warmup" = [get_constant_schedule_with_warmup()](/docs/transformers/v5.24.0/zh/main_classes/optimizer_schedules#transformers.get_constant_schedule_with_warmup)

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 正则化，以防止过拟合。自动排除偏置和 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 算法](https://huggingface.co/papers/2403.03507) 和 [APOLLO 算法](https://huggingface.co/papers/2412.05270)。有关更多详细信息，请参阅 [GaLore 实现](https://github.com/jiaweizzhao/GaLore) 和 [APOLLO 实现](https://github.com/zhuhanqing/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`。> [!TIP] > 使用梯度累积时，一次“步”被计为一次带有反向传播的步。因此，日志记录、评估和保存将每 `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 文档](https://huggingface.co/docs/transformers/perf_train_gpu_one#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](https://github.com/linkedin/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`)：是否启用模型的缓存。在训练过程中，通常不需要启用此功能，除非使用某些依赖 `cache` 的 PEFT 方法。

neftune_noise_alpha (`Optional[float]`) : 如果不为 `None`，将启用 NEFTune 噪声嵌入。这可以显著提升指令微调的模型性能。请参阅 [原始论文](https://huggingface.co/papers/2310.05914) 和 [原始代码](https://github.com/neelsjain/NEFTune)。支持 transformers 的 `PreTrainedModel` 以及来自 peft 的 `PeftModel`。原始论文中使用的值范围为 [5.0, 15.0]。

torch_empty_cache_steps (`int`, *可选*) : 在调用 `torch.<device>.empty_cache()` 之前等待的步数。如果未设置或设置为 None，则不会清空缓存。这可以通过降低峰值 VRAM 使用量来帮助避免 CUDA 内存不足错误，但代价是性能大约降低 [10%](https://github.com/huggingface/transformers/issues/31372)。

auto_find_batch_size (`bool`，*可选*，默认为 `False`)：是否通过指数衰减自动寻找能够放入内存的训练批次大小，以避免 CUDA 内存不足错误。评估批次大小不会进行调整。

**记录与监控训练：**

logging_strategy (`str` 或 [IntervalStrategy](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.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](https://github.com/gradio-app/trackio)、[wandb](https://www.wandb.com/)、[mlflow](https://www.mlflow.org/)、[comet](https://www.comet.com/site) 和 [swanlab](https://swanlab.cn) 日志记录。

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](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.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`)：是否递归地从所有设备收集嵌套在列表/元组/字典中的对象。仅当用户返回的内容不仅仅是张量时才应启用此选项，PyTorch 明确不推荐这样做。当标签结构不符合标准时（例如在计算机视觉任务中），此选项会很有用。

eval_accumulation_steps (`int`, *optional*) : 在将结果移至 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_result` 的 compute_metrics 函数；当该参数传入 `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()](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer.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()](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.enable_full_determinism) 而不是 [set_seed()](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.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`，而不是创建新的状态。这可能会导致超参数调优出现问题。

parallelism_config (`ParallelismConfig`，*可选*)：训练运行的并行配置。需要 Accelerate `1.10.1`

**数据加载器：**

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`)：是否自动移除模型前向方法未使用的列。

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`, *可选*) : 用于分布式训练的后端。必须是 `"nccl"`、`"mpi"`、`"xccl"`、`"gloo"`、`"hccl"` 之一。

ddp_timeout (`int`，*可选*，默认值为 1800)：`torch.distributed.init_process_group` 调用的超时时间，用于在分布式运行中执行缓慢操作时避免 GPU 套接字超时。有关更多信息，请参阅 [PyTorch 文档](https://pytorch.org/docs/stable/distributed.html#torch.distributed.init_process_group)。

**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`），或一个已加载的字典。 支持的键： - 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 Fully Sharded Data Parallel Training。实验性功能。 - xla_fsdp_settings (`dict`，*可选*)：XLA FSDP 包装参数的字典。完整选项列表请参阅 [XLA FSDP 源代码](https://github.com/pytorch/xla/blob/master/torch_xla/distributed/fsdp/xla_fully_sharded_data_parallel.py)。 - xla_fsdp_grad_ckpt (`bool`，*可选*，默认为 `False`)：设置为 `True` 可对每个嵌套的 XLA FSDP 包装层使用梯度检查点。需要 `xla=True` 以及一个自动包装策略（`min_num_params` 或 `transformer_layer_cls_to_wrap`）。

**DeepSpeed：**

deepspeed (`str` 或 `dict`，*可选*) : 启用 [DeepSpeed](https://github.com/deepspeedai/DeepSpeed) 集成。取值可以是：- DeepSpeed JSON 配置文件的路径：`"ds_config.json"` - 以字典形式加载的配置 > [!TIP] > 如果使用 ZeRO 初始化，请在初始化 `TrainingArguments` *之后* 再实例化模型，否则 ZeRO 不会生效。

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

debug (`str` 或 `DebugOption` 列表，*可选*，默认为 `""`)：启用一个或多个调试功能。这是一个实验性功能。可选选项包括：- "underflow_overflow"：检测模型输入/输出中的溢出，并报告导致该事件的最后几个帧 - "tpu_metrics_debug"：在 TPU 上打印调试指标

skip_memory_metrics (`bool`，*可选*，默认为 `True`)：是否跳过将内存分析器报告添加到指标中。默认情况下会跳过此操作，因为它会降低训练和评估速度。

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

do_train (`bool`，*可选*，默认为 `False`)：是否运行训练。此参数不会被 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 直接使用，而是供您的训练/评估脚本使用。

do_eval (`bool`，*可选*)：是否在验证集上运行评估。如果 `eval_strategy` 不同于 `"no"`，则会被设置为 `True`。此参数不会被 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 直接使用，而是供您的训练/评估脚本使用。

do_predict (`bool`，*可选*，默认为 `False`)：是否对测试集运行预测。此参数不会被 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.Trainer) 直接使用，而是供您的训练/评估脚本使用。

resume_from_checkpoint (`str`, *可选*) : 包含模型有效检查点（checkpoint）的文件夹路径。此参数不会被 [Trainer](/docs/transformers/v5.24.0/zh/main_classes/trainer#transformers.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`, *optional*) : 当 `predict_with_generate=True` 时，每个评估循环中使用的 `num_beams`。默认使用模型配置中的 `num_beams` 值。

generation_config (`str` 或 `Path` 或 [GenerationConfig](/docs/transformers/v5.24.0/zh/main_classes/text_generation#transformers.GenerationConfig)，*可选*)：允许通过 `from_pretrained` 方法加载 [GenerationConfig](/docs/transformers/v5.24.0/zh/main_classes/text_generation#transformers.GenerationConfig)。可以是以下之一： - 一个字符串，即托管在 huggingface.co 模型仓库中的预训练模型配置的 *model id*。 - 一个 *目录* 的路径，其中包含使用 [save_pretrained()](/docs/transformers/v5.24.0/zh/main_classes/text_generation#transformers.GenerationConfig.save_pretrained) 方法保存的配置文件，例如 `./my_model_directory/`。 - 一个 [GenerationConfig](/docs/transformers/v5.24.0/zh/main_classes/text_generation#transformers.GenerationConfig) 对象。

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

[HfArgumentParser](/docs/transformers/v5.24.0/zh/internal/trainer_utils#transformers.HfArgumentParser) 可以将此类转换为可通过命令行指定的 [argparse](https://docs.python.org/3/library/argparse#module-argparse) 参数。

#### to_dict[[transformers.Seq2SeqTrainingArguments.to_dict]]

```python
to_dict()
```

[来源](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/training_args_seq2seq.py#L84)

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

