# DPO 训练器

[![All_models-DPO-blue](https://img.shields.io/badge/All_models-DPO-blue)](https://huggingface.co/models?other=dpo,trl) [![smol_course-Chapter_2-yellow](https://img.shields.io/badge/smol_course-Chapter_2-yellow)](https://github.com/huggingface/smol-course/tree/main/2_preference_alignment)

## 概述

TRL 支持用于训练语言模型的直接偏好优化（DPO）Trainer，如 [Rafael Rafailov](https://huggingface.co/rmrafailov)、Archit Sharma、Eric Mitchell、[Stefano Ermon](https://huggingface.co/ermonste)、[Christopher D. Manning](https://huggingface.co/manning) 和 [Chelsea Finn](https://huggingface.co/cbfinn) 在论文 [Direct Preference Optimization: Your Language Model is Secretly a Reward Model](https://huggingface.co/papers/2305.18290) 中所述。

该论文的摘要如下：

> 尽管大规模无监督语言模型（LMs）能够学习广泛的世界知识和部分推理技能，但由于其训练过程完全无监督，精确控制其行为仍然十分困难。现有的方法通过收集人类对模型生成内容相对质量的评价标签，并对无监督 LM 进行微调以使其与这些偏好对齐，通常采用基于人类反馈的强化学习（RLHF）。然而，RLHF 是一个复杂且往往不稳定的过程：首先需要拟合一个反映人类偏好的奖励模型，然后使用强化学习对大型无监督 LM 进行微调，以最大化该估计奖励，同时避免偏离原始模型过远。在本文中，我们提出了一种 RLHF 中奖励模型的新参数化方法，该方法能够以闭式解提取对应的最优策略，从而使我们仅通过一个简单的分类损失即可求解标准的 RLHF 问题。我们提出的算法称为直接偏好优化（DPO），具有稳定性高、性能良好且计算开销低的特点，消除了微调期间从 LM 中采样以及进行大量超参数调优的需求。我们的实验表明，DPO 能够将 LM 微调至与人类偏好对齐，其效果与现有方法相当甚至更优。值得注意的是，使用 DPO 进行微调在控制生成内容情感方面优于基于 PPO 的 RLHF，并且在摘要生成和单轮对话任务中，其响应质量与现有方法相当或有所提升，同时实现和训练过程显著更简单。

该后训练方法由 [Kashif Rasul](https://huggingface.co/kashif) 贡献，之后由 [Quentin Gallouédec](https://huggingface.co/qgallouedec) 进行了重构。

## 快速入门

本示例演示了如何使用 TRL 中的 [DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 来训练语言模型。我们在 [UltraFeedback dataset](https://huggingface.co/datasets/openbmb/UltraFeedback) 上训练了一个 [Qwen 3 0.6B](https://huggingface.co/Qwen/Qwen3-0.6B) 模型。

```python
from trl import DPOTrainer
from datasets import load_dataset

trainer = DPOTrainer(
    model="Qwen/Qwen3-0.6B",
    train_dataset=load_dataset("trl-lib/ultrafeedback_binarized", split="train"),
)
trainer.train()
```

## 预期的数据集类型和格式

DPO 需要一个[偏好](dataset_formats#preference)数据集。[DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 同时兼容[标准](dataset_formats#standard)和[对话](dataset_formats#conversational)数据集格式。当提供对话数据集时，训练器会自动将聊天模板应用于该数据集。

```python
# Standard format
## Explicit prompt (recommended)
preference_example = {"prompt": "The sky is", "chosen": " blue.", "rejected": " green."}
# Implicit prompt
preference_example = {"chosen": "The sky is blue.", "rejected": "The sky is green."}

# Conversational format
## Explicit prompt (recommended)
preference_example = {"prompt": [{"role": "user", "content": "What color is the sky?"}],
                      "chosen": [{"role": "assistant", "content": "It is blue."}],
                      "rejected": [{"role": "assistant", "content": "It is green."}]}
## Implicit prompt
preference_example = {"chosen": [{"role": "user", "content": "What color is the sky?"},
                                 {"role": "assistant", "content": "It is blue."}],
                      "rejected": [{"role": "user", "content": "What color is the sky?"},
                                   {"role": "assistant", "content": "It is green."}]}
```

如果您的数据集不属于上述任何一种格式，您可以对其进行预处理，将其转换为预期的格式。以下是使用 [Vezora/Code-Preference-Pairs](https://huggingface.co/datasets/Vezora/Code-Preference-Pairs) 数据集的示例：

```python
from datasets import load_dataset

dataset = load_dataset("Vezora/Code-Preference-Pairs")

def preprocess_function(example):
    return {
        "prompt": [{"role": "user", "content": example["input"]}],
        "chosen": [{"role": "assistant", "content": example["accepted"]}],
        "rejected": [{"role": "assistant", "content": example["rejected"]}],
    }

dataset = dataset.map(preprocess_function, remove_columns=["instruction", "input", "accepted", "ID"])
print(next(iter(dataset["train"])))
```

```json
{
    "prompt": [{"role": "user", "content": "Create a nested loop to print every combination of numbers [...]"}],
    "chosen": [{"role": "assistant", "content": "Here is an example of a nested loop in Python [...]"}],
    "rejected": [{"role": "assistant", "content": "Here is an example of a nested loop in Python [...]"}],
}
```

## 深入了解 DPO 方法

直接偏好优化（DPO）是一种旨在使语言模型与偏好数据对齐的训练方法。与监督式输入-输出对不同，该模型在同一提示词的两个补全对上接受训练，其中一个补全优于另一个。其目标直接优化模型，以相对于参考模型扩大偏好补全与非偏好补全之间的对数似然差距，而无需显式的奖励模型。在实践中，这通常通过抑制非偏好补全的似然性来实现，而不是通过提高偏好补全的似然性。

本节详细说明了 DPO 在实际中的工作原理，涵盖关键步骤：**预处理**和**损失计算**。

### 预处理和分词

在训练过程中，每个样本应包含一个提示（prompt），以及一个首选（`chosen`）和一个非首选（`rejected`）的补全。有关预期格式的详细信息，请参阅[数据集格式](dataset_formats)。[DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 会使用模型的 tokenizer 对每个输入进行分词。

### 计算损失

![dpo_figure](https://huggingface.co/datasets/trl-lib/documentation-images/resolve/main/dpo_figure.png)

DPO 中使用的损失函数定义如下：$$ \mathcal{L}_{\mathrm{DPO}}(\theta) = -\mathbb{E}_{(x,y^{+},y^{-})}\!\left[\log \sigma\!\left(\beta\Big(\log\frac{\pi_{\theta}(y^{+}\!\mid x)}{\pi_{\mathrm{ref}}(y^{+}\!\mid x)}-\log \frac{\pi_{\theta}(y^{-}\!\mid x)}{\pi_{\mathrm{ref}}(y^{-}\!\mid x)}\Big)\right)\right] $$

其中 \\( x \\) 是提示，\\( y^+ \\) 是首选补全，\\( y^- \\) 是非首选补全。\\( \pi_{\theta} \\) 是正在训练的策略模型，\\( \pi_{\mathrm{ref}} \\) 是参考模型，\\( \sigma \\) 是 sigmoid 函数，\\( \beta > 0 \\) 是一个控制偏好信号强度的超参数。

#### 损失类型

文献中已提出目标函数的多种表述形式。最初，DPO 的目标函数定义如上所述。

| `loss_type=` | 描述 |
| --- | --- |
| `"sigmoid"`（默认） | 给定偏好数据，我们可以根据 Bradley-Terry 模型拟合一个二分类器，事实上 [DPO](https://huggingface.co/papers/2305.18290) 的作者提出通过对归一化似然使用 `logsigmoid` 上的 sigmoid 损失来拟合逻辑回归。 |
| `"hinge"` | [RSO](https://huggingface.co/papers/2309.06657) 的作者建议对 [SLiC](https://huggingface.co/papers/2305.10425) 论文中的归一化似然使用铰链损失。在这种情况下，`beta` 是间隔的倒数。 |
| `"ipo"` | [IPO](https://huggingface.co/papers/2310.12036) 的作者认为 logit 变换可能导致过拟合，并提出了恒等变换以直接优化偏好；TRL 将其暴露为 `loss_type="ipo"`。 |
| `"exo_pair"` | [EXO](https://huggingface.co/papers/2402.00856) 的作者提出了反向 KL 偏好优化。`label_smoothing` 必须严格大于 `0.0`；推荐值为 `1e-3`（简化成对变体参见公式 16）。完整方法使用 `K>2` 个 SFT 补全，并随着 `K` 的增大而趋近于 PPO。 |
| `"nca_pair"` | [NCA](https://huggingface.co/papers/2402.05369) 的作者表明，NCA 优化的是每个响应的绝对似然，而非相对似然。 |
| `"robust"` | [Robust DPO](https://huggingface.co/papers/2403.00409) 的作者提出了一种在噪声偏好下无偏的 DPO 损失。在 [DPOConfig](/docs/trl/main/zh/dpo_trainer#trl.DPOConfig) 中使用 `label_smoothing` 来建模标签翻转概率；有效值范围为 `[0.0, 0.5)`。 |
| `"bco_pair"` | [BCO](https://huggingface.co/papers/2404.04656) 的作者训练了一个二元分类器，其 logit 作为奖励，使该分类器将 {prompt, chosen completion} 对映射为 1，将 {prompt, rejected completion} 对映射为 0。 |
| `"sppo_hard"` | [SPPO](https://huggingface.co/papers/2405.00675) 的作者声称，SPPO 能够通过迭代求解纳什均衡，将选中的奖励推高至 1/2，将拒绝的奖励压低到 -1/2，从而缓解数据稀疏性问题。该实现通过采用硬标签概率来近似此算法，将获胜者赋值为 1，将失败者赋值为 0。 |
| `"aot"` 或 `loss_type="aot_unpaired"` | [AOT](https://huggingface.co/papers/2406.05882) 的作者提出了基于最优传输的分布偏好对齐。`loss_type="aot"` 适用于配对数据；`loss_type="aot_unpaired"` 适用于非配对数据。两者均通过排序分位数来强制实现随机占优；增大每个 GPU 的批处理大小会有所帮助。 |
| `"apo_zero"` 或 `loss_type="apo_down"` | [APO](https://huggingface.co/papers/2408.06266) 方法引入了锚定目标。`apo_zero` 会提升获胜者的权重并降低失败者的权重（适用于模型表现不及获胜者的情况）。`apo_down` 会同时降低两者的权重，但对失败者施加更强的压力（适用于模型表现已优于获胜者的情况）。 |
| `"discopop"` | [DiscoPOP](https://huggingface.co/papers/2406.08414) 论文利用大语言模型来发现更高效的离线偏好优化损失函数。在该论文中，所提出的 DiscoPOP 损失函数（一种对数比率调制损失）在多项任务（IMDb 正面文本生成、Reddit TLDR 摘要以及 Alpaca Eval 2.0）上均优于其他优化损失函数。 |
| `"sft"` | SFT（Supervised Fine-Tuning）损失是负对数似然损失，用于训练模型生成首选回复。 |
| `"sigmoid_norm"` | [SimPO](https://huggingface.co/papers/2405.14734) 的作者通过按非掩码 token 的数量进行归一化，解决了原始 sigmoid 损失中的长度偏差问题；TRL 将其暴露为 `loss_type="sigmoid_norm"`。 |
| `"udpo"` | [UDPO](https://huggingface.co/papers/2607.03248) 的作者提出了一种在噪声偏好下无偏的 DPO 损失，与 `"robust"` 不同，当翻转概率被高估时，该损失仍保持无偏。在 [DPOConfig](/docs/trl/main/zh/dpo_trainer#trl.DPOConfig) 中使用 `label_smoothing` 来设置翻转概率 ε；有效值范围为 `[0.0, 0.5)`。 |

## 记录的指标

在训练和评估过程中，我们记录以下指标：

- `global_step`：迄今为止已执行的优化器步数总数。
- `epoch`：当前 epoch 编号，基于数据集迭代。
- `num_tokens`：迄今为止处理的 token 总数。
- `loss`：当前日志记录区间内的平均 DPO 损失。
- `entropy`：模型在未屏蔽 token 上的预测 token 分布的平均熵。
- `aux_loss`：混合专家（Mixture-of-Experts）模型的负载均衡辅助损失，在乘以 `router_aux_loss_coef` 并加到总损失之前。仅当模型为 MoE 模型且 `router_aux_loss_coef` 非零时记录。
- `mean_token_accuracy`：模型 top-1 预测与所选补全中 token 相匹配的非掩码 token 的比例。
- `learning_rate`：当前学习率，如果使用调度器，该值可能会动态变化。
- `grad_norm`：梯度裁剪前计算的梯度 L2 范数。
- `logits/chosen`：模型为所选补全中的 token 分配的平均 logit 值。
- `logits/rejected`：模型分配给被拒绝补全中各个 token 的平均 logit 值。
- `logps/chosen`：模型为所选补全中的 token 分配的平均对数概率。
- `logps/rejected`：模型为被拒绝的补全中的 token 分配的平均对数概率。
- `rewards/chosen`：为选中的补全计算的平均隐式奖励，计算公式为  \\( \beta \log \frac{\pi_{\theta}(y^{+}\!\mid x)}{\pi_{\mathrm{ref}}(y^{+}\!\mid x)} \\)。
- `rewards/rejected`：为被拒绝的补全计算的平均隐式奖励，计算公式为  \\( \beta \log \frac{\pi_{\theta}(y^{-}\!\mid x)}{\pi_{\mathrm{ref}}(y^{-}\!\mid x)} \\)。
- `rewards/margins`：所选完成项与被拒绝完成项之间的平均隐式奖励差值。
- `rewards/accuracies`：隐式奖励中，被选中的补全高于被拒绝的补全的示例所占的比例。

## 自定义

### 兼容性与约束

当前 [DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 实现中，部分参数组合被有意限制：

- `use_weighting=True` 不支持与 `loss_type="aot"` 或 `loss_type="aot_unpaired"` 一起使用。
- 针对 `lm_head` 的 PEFT 适配器不受支持（请改用 `modules_to_save=["lm_head"]`）。
- `sync_ref_model=True` 不适用于使用未保留独立 `ref_model` 的 PEFT 模型进行训练的情况。
- `sync_ref_model=True` 不能与 `precompute_ref_log_probs=True` 同时使用。
- `precompute_ref_log_probs=True` 不支持与 `IterableDataset`（训练或评估）一起使用。

### 多损失组合

DPO 训练器支持以不同权重组合多个损失函数，从而实现更精细的优化策略。这在实现诸如 MPO（混合偏好优化）等算法时尤为有用。MPO 是一种结合多个优化目标的训练方法，如论文 [Enhancing the Reasoning Ability of Multimodal Large Language Models via Mixed Preference Optimization](https://huggingface.co/papers/2411.10442) 中所述。

要组合多个损失，请以列表形式指定损失类型及对应的权重：

```python
# MPO: Combines DPO (sigmoid) for preference and BCO (bco_pair) for quality
training_args = DPOConfig(
    loss_type=["sigmoid", "bco_pair", "sft"],  # loss types to combine
    loss_weights=[0.8, 0.2, 1.0]  # corresponding weights, as used in the MPO paper
)
```

### 模型初始化

您可以直接将 `from_pretrained()` 方法的 kwargs 传递给 [DPOConfig](/docs/trl/main/zh/dpo_trainer#trl.DPOConfig)。例如，如果您想以不同的精度加载模型，类似于

```python
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", dtype=torch.bfloat16)
```

您可以通过向 [DPOConfig](/docs/trl/main/zh/dpo_trainer#trl.DPOConfig) 传递 `model_init_kwargs={"dtype": torch.bfloat16}` 参数来实现此操作。

```python
from trl import DPOConfig

training_args = DPOConfig(
    model_init_kwargs={"dtype": torch.bfloat16},
)
```

请注意，`from_pretrained()` 的所有关键字参数均受支持。

### 使用 PEFT 训练适配器

我们支持与 🤗 PEFT 库的紧密集成，允许任何用户方便地训练适配器并在 Hub 上共享，而无需训练整个模型。

```python
from datasets import load_dataset
from trl import DPOTrainer
from peft import LoraConfig

dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

trainer = DPOTrainer(
    "Qwen/Qwen3-0.6B",
    train_dataset=dataset,
    peft_config=LoraConfig(),
)

trainer.train()
```

您还可以继续训练您的 [PeftModel](https://huggingface.co/docs/peft/main/en/package_reference/peft_model#peft.PeftModel)。为此，首先在 [DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 外部加载一个 `PeftModel`，然后直接将其传递给 trainer，而不传入 `peft_config` 参数。

```python
from datasets import load_dataset
from trl import DPOTrainer
from peft import AutoPeftModelForCausalLM

model = AutoPeftModelForCausalLM.from_pretrained("trl-lib/Qwen3-4B-LoRA", is_trainable=True)
dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

trainer = DPOTrainer(
    model=model,
    train_dataset=dataset,
)

trainer.train()
```

> [!TIP]
> 在训练适配器时，由于只学习新参数，通常使用比全量微调更高的学习率（≈1e‑5）。
>
> ```python
> DPOConfig(learning_rate=1e-5, ...)
> ```

### 用于 DPO 的快速实验

RapidFire AI 是一个构建在 TRL 之上的开源实验引擎，允许你同时启动多个 DPO 配置，即使只有一块 GPU 也是如此。与按顺序尝试配置不同，RapidFire 让你能够**更早地查看所有配置的学习曲线，停止表现不佳的运行，并在运行过程中使用新设置克隆有前景的配置**，而无需重启。有关更多信息，请参阅[RapidFire AI Integration](rapidfire_integration)。

### 使用 Unsloth 进行训练

Unsloth 是一个用于微调和强化学习的开源框架，可将 LLM（如 Llama、Mistral、Gemma、DeepSeek 等）的训练速度提升高达 2 倍，同时减少高达 70% 的 VRAM 占用，并提供简化的、与 Hugging Face 兼容的训练、评估和部署工作流。更多信息请参阅 [Unsloth 集成](unsloth_integration)。

## 使用 DPO 进行工具调用

[DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 完全支持对具有 _tool calling_ 能力的模型进行微调。在这种情况下，每个数据集示例应包含：

- 对话消息（提示、选中和拒绝），包括任何工具调用（`tool_calls`）和工具响应（`tool` 角色消息）
- `tools` 列中可用工具列表，通常以 JSON 模式提供

有关预期数据集结构的详细信息，请参阅 [Dataset Format — Tool Calling](dataset_formats#tool-calling) 部分。

## 训练视觉语言模型

[DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 完全支持训练视觉语言模型（VLM）。要训练 VLM，请提供一个包含 `image` 列（每个样本一张图像）或 `images` 列（每个样本一个图像列表）的数据集。有关预期数据集结构的更多信息，请参阅 [数据集格式 — 视觉数据集](dataset_formats#vision-dataset) 部分。此类数据集的一个示例是 [RLAIF-V Dataset](https://huggingface.co/datasets/HuggingFaceH4/rlaif-v_formatted) 数据集。

```python
from trl import DPOConfig, DPOTrainer
from datasets import load_dataset

trainer = DPOTrainer(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    args=DPOConfig(max_length=None),
    train_dataset=load_dataset("HuggingFaceH4/rlaif-v_formatted", split="train"),
)
trainer.train()
```

> [!TIP]
> 对于 VLM，截断可能会移除图像 token，从而导致训练过程中出现错误。为避免这种情况，请在 [DPOConfig](/docs/trl/main/zh/dpo_trainer#trl.DPOConfig) 中设置 `max_length=None`。这允许模型处理完整的序列长度，而不会截断图像 token。
>
> ```python
> DPOConfig(max_length=None, ...)
> ```
>
> 仅在确认截断不会移除整个数据集中的图像标记后，才使用 `max_length`。

## DPOTrainer[[trl.DPOTrainer]]

#### trl.DPOTrainer[[trl.DPOTrainer]]

```python
trl.DPOTrainer(model: str | PreTrainedModel | PeftModel, ref_model: transformers.modeling_utils.PreTrainedModel | None = None, args: trl.trainer.dpo_config.DPOConfig | None = None, data_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = None, train_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = None, eval_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | datasets.dataset_dict.DatasetDict | datasets.dataset_dict.IterableDatasetDict | dict[str, datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset] | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.processing_utils.ProcessorMixin | 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), quantization_config: BitsAndBytesConfig | None = None, peft_config: PeftConfig | None = None)
```

[源代码](https://github.com/huggingface/trl/blob/main/trl/trainer/dpo_trainer.py#L407)

**参数：**

model (`str` 或 [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) 或 [PeftModel](https://huggingface.co/docs/peft/main/en/package_reference/peft_model#peft.PeftModel)) : 要训练的模型。可以是以下之一： - 一个字符串，即托管在 huggingface.co 模型仓库中的预训练模型的 *model id*，或者一个指向使用 [save_pretrained](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.save_pretrained) 保存模型权重的 *directory* 的路径，例如 `'./my_model_directory/'`。该模型使用 `<ModelArchitecture>.from_pretrained`（其中 `<ModelArchitecture>` 从模型配置中推导得出）加载，并传入 `args.model_init_kwargs` 中的关键字参数。如果未在 `args.model_init_kwargs` 中指定 `dtype`，则默认为 `float32`。这与 [from_pretrained](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.from_pretrained) 不同，在后者中（自 Transformers v5 起）dtype 是从模型配置中推断的。 - 一个 [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) 对象。仅支持因果语言模型。 - 一个 [PeftModel](https://huggingface.co/docs/peft/main/en/package_reference/peft_model#peft.PeftModel) 对象。仅支持因果语言模型。

ref_model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel), *可选*) : 用于计算参考对数概率的参考模型。 - 如果提供，该模型将直接用作参考策略。它不能是 [PeftModel](https://huggingface.co/docs/peft/main/en/package_reference/peft_model#peft.PeftModel)。 - 如果为 `None`，训练器将自动使用与 `model` 对应的初始策略，即 DPO 训练开始前的模型状态。

args ([DPOConfig](/docs/trl/main/zh/dpo_trainer#trl.DPOConfig)，*可选*)：此训练器的配置。如果为 `None`，则使用默认配置。

data_collator (`DataCollator`, *可选*) : 用于将处理后的 `train_dataset` 或 `eval_dataset` 中的元素列表组合成批次的函数。如果模型是语言模型，则默认为 `DataCollatorForPreference`；如果模型是视觉-语言模型，则默认为 `DataCollatorForVisionPreference`。自定义的 collator 必须在填充之前截断序列；训练器不会在 collation 之后应用截断。

train_dataset ([Dataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset) 或 [IterableDataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.IterableDataset))：用于训练的 Dataset。该 trainer 同时支持 [language modeling](#language-modeling) 类型和 [prompt-completion](#prompt-completion) 类型。样本的格式可以是以下两种之一： - [Standard](dataset_formats#standard)：每个样本包含纯文本。 - [Conversational](dataset_formats#conversational)：每个样本包含结构化消息（例如 role 和 content）。 当 `train_dataset` 是一个 [IterableDataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.IterableDataset)（例如流式数据集）时，必须在训练参数中设置 `max_steps`，因为其长度无法推断，而确定训练循环边界和配置学习率调度器需要知道总的训练步数。

eval_dataset ([Dataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset)、[IterableDataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.IterableDataset)、[DatasetDict](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.DatasetDict)、[IterableDatasetDict](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.IterableDatasetDict) 或 `dict[str, Dataset | IterableDataset]`)：用于评估的数据集。它必须满足与 `train_dataset` 相同的要求。

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/main/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) 或 [ProcessorMixin](https://huggingface.co/docs/transformers/main/en/main_classes/processors#transformers.ProcessorMixin)，*可选*)：用于处理数据的处理类。填充侧必须设置为 "left"。如果为 `None`，则使用 [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoProcessor.from_pretrained) 从模型名称加载处理类。必须设置填充标记 `tokenizer.pad_token`。如果处理类未设置填充标记，则默认使用 `tokenizer.eos_token`。

compute_metrics (`Callable[[EvalPrediction], dict]`，*可选*)：用于在评估期间计算指标的函数。必须接受一个 [EvalPrediction](https://huggingface.co/docs/transformers/main/en/internal/trainer_utils#transformers.EvalPrediction) 并返回一个从字符串到指标值的字典。当使用 [SFTConfig](/docs/trl/main/zh/sft_trainer#trl.SFTConfig) 并将 `batch_eval_metrics` 设置为 `True` 时，您的 `compute_metrics` 函数必须接受一个布尔类型的 `compute_result` 参数。这将在最后一个评估批次之后触发，以指示该函数需要计算并返回全局汇总统计信息，而不是累积批次级别的统计信息。它接收的 logits 将通过额外的前向传播重新计算。此功能已弃用，并将在 v2.0.0 中移除。

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

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

quantization_config ([BitsAndBytesConfig](https://huggingface.co/docs/transformers/main/en/main_classes/quantization#transformers.BitsAndBytesConfig)，*可选*)：从模型标识符加载模型时使用的量化配置。与 `peft_config` 结合用于 QLoRA 训练。如果模型已经实例化，则忽略此配置。

peft_config ([PeftConfig](https://huggingface.co/docs/peft/main/en/package_reference/config#peft.PeftConfig)，*可选*)：用于包装模型的 PEFT 配置。如果为 `None`，则不包装模型。

用于直接偏好优化（DPO）方法的 Trainer。该算法最初在论文 [Direct Preference Optimization: Your Language Model is Secretly a Reward Model](https://huggingface.co/papers/2305.18290) 中提出。此类是 [Trainer](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.Trainer) 类的封装，并继承其所有属性和方法。

示例：

```python
>>> from trl import DPOTrainer
>>> from datasets import load_dataset

>>> dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

>>> trainer = DPOTrainer(
...     model="Qwen/Qwen2.5-0.5B-Instruct",
...     train_dataset=dataset,
... )
>>> trainer.train()
```

#### train[[trl.DPOTrainer.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/trl/blob/main/transformers/trainer.py#L1450)

**参数：**

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

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

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

**返回：** `~trainer_utils.TrainOutput`

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

主要训练入口。

#### save_model[[trl.DPOTrainer.save_model]]

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

[源代码](https://github.com/huggingface/trl/blob/main/transformers/trainer.py#L4077)

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

仅从主进程保存。

#### push_to_hub[[trl.DPOTrainer.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/trl/blob/main/transformers/trainer.py#L4337)

**参数：**

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]`，*可选*)：传递给 `~Trainer.create_model_card` 的额外关键字参数。

**返回：**

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

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

## DPOConfig[[trl.DPOConfig]]

#### trl.DPOConfig[[trl.DPOConfig]]

```python
trl.DPOConfig(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 = 1e-06, 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 | None = None, 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 = 10, 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: accelerate.parallelism_config.ParallelismConfig | 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, model_init_kwargs: dict[str, typing.Any] | str | None = None, trust_remote_code: bool = False, router_aux_loss_coef: float | None = None, disable_dropout: bool = True, dataset_num_proc: int | None = None, max_length: int | None = 1024, truncation_mode: str = 'keep_start', padding_free: bool = False, pad_to_multiple_of: int | str | None = 'auto', precompute_ref_log_probs: bool = False, precompute_ref_batch_size: int | None = None, loss_type: list[str] = <factory>, loss_weights: list[float] | None = None, ld_alpha: float | None = None, f_divergence_type: str = 'reverse_kl', f_alpha_divergence_coef: float = 0.5, label_smoothing: float = 0.0, beta: float = 0.1, use_weighting: bool = False, discopop_tau: float = 0.05, activation_offloading: bool = False, sync_ref_model: bool = False, ref_model_mixup_alpha: float = 0.6, ref_model_sync_steps: int = 512, pad_token: str | None = None)
```

[源代码](https://github.com/huggingface/trl/blob/main/trl/trainer/dpo_config.py#L23)

**控制模型的参数：**

model_init_kwargs (`dict[str, Any]`, *可选*) : [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) 的关键字参数，当 [DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 的 `model` 参数以字符串形式提供时使用。加载处理类时也会使用 `revision` 的值。

trust_remote_code (`bool`, *optional*, defaults to `False`) : Whether to allow loading models and tokenizers that ship custom Python code from the Hub. Forwarded to [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) and [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoProcessor.from_pretrained).

router_aux_loss_coef (`float`, *可选*) : 混合专家（Mixture-of-Experts, MoE）模型中负载均衡辅助损失的系数，该损失会以该权重加到训练损失中。如果未设置，则使用模型配置中声明的值。设置为 `0.0` 可将其禁用。与非 MoE 模型一起使用时会失败。

disable_dropout (`bool`，*可选*，默认为 `True`)：是否禁用模型和参考模型中的 dropout。

**控制数据预处理的参数：**

dataset_num_proc (`int`, *可选*) : 用于处理数据集的进程数。

max_length (`int` 或 `None`，*可选*，默认为 `1024`)：标记化序列的最大长度。长度超过 `max_length` 的序列将根据 `truncation_mode` 从左侧或右侧截断。如果为 `None`，则不应用截断。

truncation_mode (`str`，*可选*，默认为 `"keep_start"`)：当序列长度超过 `max_length` 时使用的截断模式。唯一支持的值为 `"keep_start"`。`"keep_end"` 值已弃用，并将在 v2.0.0 中移除。

padding_free (`bool`, *可选*，默认为 `False`) : 是否通过展平批次中的所有序列为单个连续序列，来执行无填充的前向传播。这通过消除填充开销来减少内存使用。目前，这仅在 FlashAttention 2 或 3 中受支持，它们可以高效处理展平后的批次结构。暂时不可用：自 DPO 重构以来，将其设置为 `True` 会发出警告并回退到标准填充。计划在后续更新中恢复此功能。

pad_to_multiple_of (`int` 或 `str`，*可选*，默认为 `"auto"`)：如果设置，序列将被填充为该值的倍数。`"auto"` 在 Neuron (AWS Trainium) 上填充为 128 的倍数，因为该硬件针对每个输入形状仅编译一次，而在其他平台上不进行填充。

precompute_ref_log_probs (`bool`, *可选*，默认为 `False`)：是否在训练前预先计算整个训练数据集的参考模型对数概率。这可以节省训练期间的内存，因为无需将参考模型保留在内存中。

precompute_ref_batch_size (`int`, *可选*) : 预计算参考模型对数概率时使用的批次大小。可以将其设置为高于训练批次大小以加快预处理速度。如果为 `None`，则训练时默认为 `per_device_train_batch_size`，评估时默认为 `per_device_eval_batch_size`。

**控制训练的参数：**

loss_type (`list[str]`, *可选*, 默认为 `["sigmoid"]`) : 要使用的损失类型。可能的值包括： `'sigmoid'`、`'hinge'`、`'ipo'`、`'exo_pair'`、`'nca_pair'`、`'robust'`、`'bco_pair'`、`'sppo_hard'`、`'aot'`、`'aot_unpaired'`、`'apo_zero'`、`'apo_down'`、`'discopop'`、`'sft'`、`'sigmoid_norm'`、`'udpo'`。如果提供了多种损失类型，它们将根据 `loss_weights` 中指定的权重进行组合。

loss_weights (`list[float]`, *可选*) : 多损失组合的损失权重列表。在组合多种损失类型时使用。示例：对于 MPO，使用 `[0.8, 0.2, 1.0]`。如果未提供，则默认对所有损失类型使用相等的权重（`1.0`）。

ld_alpha (`float`, *可选*) : 来自 LD-DPO 论文的 α 参数，用于控制响应中冗长 token 对数概率的权重。如果为 `None`，则不对冗长部分应用权重，损失函数等同于标准 DPO 损失。取值必须在 [0.0, 1.0] 范围内：`ld_alpha=1.0` 表示不应用权重，而 `ld_alpha=0.0` 会屏蔽超出共享长度的 token。

f_divergence_type (`str`, *可选*，默认为 `"reverse_kl"`)：策略与参考模型之间的 f-散度正则化项（f-DPO 论文）。可能的取值为：`reverse_kl`（默认值）、`forward_kl`、`js_divergence`、`alpha_divergence`。仅基于 chosen-rejected 奖励差构建的损失类型支持非默认值：`'sigmoid'`、`'sigmoid_norm'`、`'hinge'`、`'ipo'`、`'exo_pair'`、`'robust'`、`'discopop'`、`'sft'`、`'udpo'`。其他损失类型没有有效的 f-散度推广形式，若传入非默认值将被拒绝。

f_alpha_divergence_coef (`float`, *可选*, 默认为 `0.5`) : α 散度正则化项 u^-α 的 α 系数，仅在 `f_divergence_type='alpha_divergence'` 时使用。

label_smoothing (`float`, *可选*，默认为 `0.0`) : 用于 Robust DPO、UDPO 和 EXO 的标签平滑参数。在 Robust DPO 和 UDPO 中，它被解释为偏好标签被翻转的概率 ε，且必须位于 [0.0, 0.5) 区间内；Robust DPO 论文推荐的典型值为 0.1。UDPO 使用它来设置 a = ε / (1 - ε)，UDPO 论文推荐 a = 0.8，即 ε = 4/9。在 EXO 中，它对应于 ε 标签平滑参数，该论文推荐的典型值为 1e-3。

beta (`float`, *可选*，默认为 `0.1`)：控制与参考模型偏差的参数。β 值越高，表示与参考模型的偏差越小。对于 IPO 损失（`loss_type='ipo'`），该值是[论文](https://huggingface.co/papers/2310.12036)中用 τ 表示的正则化参数。

use_weighting (`bool`, *可选*, 默认为 `False`) : 是否使用策略的长度归一化序列概率，对偏好对应用 [WPO](https://huggingface.co/papers/2406.11827) 风格的加权。

discopop_tau (`float`, *可选*，默认为 `0.05`) : 来自 DiscoPOP 论文的 τ/温度参数，在使用 `loss_type='discopop'` 时控制对数比率调制损失的形状。该论文建议默认值为 `discopop_tau=0.05`。

activation_offloading (`bool`，*可选*，默认为 `False`)：是否将激活值卸载到 CPU。

sync_ref_model (`bool`, *可选*，默认为 `False`) : 是否使用 `ref_model_mixup_alpha` 参数，每隔 `ref_model_sync_steps` 步将参考模型与活动模型同步一次。此同步机制源自 [TR-DPO](https://huggingface.co/papers/2404.09656) 论文。`sync_ref_model=True` 目前尚不兼容 PEFT 或 `precompute_ref_log_probs=True`。

ref_model_mixup_alpha (`float`, *可选*，默认为 `0.6`) : TR-DPO 论文中的 α 参数，用于控制更新过程中当前策略与先前参考策略之间的混合比例。参考策略根据以下公式更新：`π_ref = α * π_θ + (1 - α) * π_ref_prev`。要使用此参数，必须设置 `sync_ref_model=True`。

ref_model_sync_steps (`int`, *可选*，默认为 `512`) : [TR-DPO](https://huggingface.co/papers/2404.09656) 论文中的 τ 参数，用于确定当前策略与参考策略同步的频率。要使用此参数，必须设置 `sync_ref_model=True`。

**已弃用的参数：**

pad_token :   参数 `pad_token` 已弃用，并将在 v2.0.0 版本中移除。请直接将 `tokenizer.pad_token` 设置为 `processing_class` 并传递给 trainer。

[DPOTrainer](/docs/trl/main/zh/dpo_trainer#trl.DPOTrainer) 的配置类。

此类仅包含 DPO 训练特有的参数。完整的训练参数列表请参阅 [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments) 文档。请注意，此类中的默认值可能与 [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments) 中的不同。

使用 [HfArgumentParser](https://huggingface.co/docs/transformers/main/en/internal/trainer_utils#transformers.HfArgumentParser)，我们可以将该类转换为可在命令行中指定的 [argparse](https://docs.python.org/3/library/argparse#module-argparse) 参数。

> [!NOTE]
> 这些参数的默认值与 [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments) 不同： - `logging_steps`：默认值为 `10`，而非 `500`。 - `gradient_checkpointing`：默认值为 `True`，而非 `False`。 - `bf16`：如果未设置 `fp16`，则默认值为 `True`，而非 `False`。 - `learning_rate`：默认值为 `1e-6`，而非 `5e-5`。

