# KTO 训练器

[![All_models-KTO-blue](https://img.shields.io/badge/All_models-KTO-blue)](https://huggingface.co/models?other=kto,trl)

## 概述

TRL 支持 Kahneman-Tversky 优化（KTO）Trainer，用于训练语言模型，如 [Kawin Ethayarajh](https://huggingface.co/kawine)、[Winnie Xu](https://huggingface.co/xwinxu)、[Niklas Muennighoff](https://huggingface.co/Muennighoff)、Dan Jurafsky 和 [Douwe Kiela](https://huggingface.co/douwekiela) 在论文 [KTO: Model Alignment as Prospect Theoretic Optimization](https://huggingface.co/papers/2402.01306) 中所述。

该论文的摘要如下：

> Kahneman & Tversky 的前景理论指出，人类以有偏但定义明确的方式感知随机变量；例如，人类以损失厌恶而闻名。我们表明，用于将 LLM 与人类反馈对齐的目标函数隐式地融入了许多此类偏差——这些目标函数（例如 DPO）相较于交叉熵最小化的成功，部分可归因于它们是人类感知的损失函数（HALOs）。然而，这些方法所赋予人类的效用函数仍与前景理论文献中的效用函数存在差异。利用 Kahneman-Tversky 人类效用模型，我们提出了一种 HALO，它直接最大化生成的效用，而非像当前方法那样最大化偏好的对数似然。我们将这种方法称为 Kahneman-Tversky 优化（KTO），在 1B 到 30B 的规模上，其性能与基于偏好的方法相当或更优。至关重要的是，KTO 不需要偏好数据——对于给定输入，它只需要一个二元信号，表明输出是可取的还是不可取的。这使得它在偏好数据稀缺且昂贵的现实世界中更容易使用。

官方代码可在 [ContextualAI/HALOs](https://github.com/ContextualAI/HALOs) 中找到。

此训练后方法由 [Kashif Rasul](https://huggingface.co/kashif)、[Younes Belkada](https://huggingface.co/ybelkada)、[Lewis Tunstall](https://huggingface.co/lewtun)、Pablo Vicente 贡献，之后由 [Albert Villanova del Moral](https://huggingface.co/albertvillanova) 进行了重构。

## 快速入门

本示例演示了如何使用 KTO 方法训练模型。我们使用 [Qwen 0.5B 模型](https://huggingface.co/Qwen/Qwen2-0.5B-Instruct) 作为基础模型。我们使用来自 [KTO Mix 14k](https://huggingface.co/datasets/trl-lib/kto-mix-14k) 的偏好数据。您可以在以下位置查看该数据集：

<iframe src="https://huggingface.co/datasets/trl-lib/kto-mix-14k/embed/viewer/default/train?row=0" frameborder="0" width="100%" height="560px"
>

以下是用于训练模型的脚本：

```python
# train_kto.py
from datasets import load_dataset
from trl import KTOConfig, KTOTrainer
from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-0.5B-Instruct")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2-0.5B-Instruct")
train_dataset = load_dataset("trl-lib/kto-mix-14k", split="train")

training_args = KTOConfig(output_dir="Qwen2-0.5B-KTO")
trainer = KTOTrainer(model=model, args=training_args, processing_class=tokenizer, train_dataset=train_dataset)
trainer.train()
```

使用以下命令执行该脚本：

```bash
torchrun --nproc_per_node 8 train_kto.py
```

在 8 块 H100 GPU 上分布式训练，大约需要 30 分钟。您可以通过查看奖励曲线来验证训练进度。奖励差值呈上升趋势表明模型正在改进，并随时间推移生成更好的响应。

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

要查看[训练后的模型](https://huggingface.co/trl-lib/Qwen2-0.5B-KTO)的表现，您可以使用[Transformers Chat CLI](https://huggingface.co/docs/transformers/quicktour#chat-with-text-generation-models)。

$ transformers chat trl-lib/Qwen2-0.5B-KTO &lt;quentin_gallouedec&gt;: 最好的编程语言是什么？

&lt;trl-lib/Qwen2-0.5B-KTO&gt;: 最好的编程语言可能因个人偏好、行业特定需求、技术技能以及对特定用例或任务的熟悉程度而异。以下是一些被公认为流行且广泛使用的编程语言：

在为项目选择编程语言时，还有一些其他因素需要考虑：

 1 JavaScript：JavaScript 是 Web 的核心，可用于构建 Web 应用程序、API 以及 React 和 Angular 等框架的交互式前端应用。其语法结构与 C、C++ 和 F# 相似，易于上手和学习，因此深受初学者和专业人士的青睐。 2 Java：Java 以其面向对象编程（OOP）以及对 Java 8 和 .NET 的支持而闻名，用于开发企业级软件应用、高性能游戏，以及移动应用、游戏开发和桌面应用。 3 C++：C++ 以灵活性和可扩展性著称，提供全面的面向对象编程支持，是高性能计算及其他技术领域的热门选择。它是构建大规模实际应用和游戏的强大平台。 4 Python：Python 由 Guido van Rossum 于 1991 年开发，是一种高级、解释型、动态类型语言，以其简洁性、可读性和多功能性而闻名。

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

KTO 需要一个[非配对偏好](dataset_formats#unpaired-preference)数据集。或者，您也可以提供一个*配对*偏好数据集（通常简称为*偏好数据集*）。在这种情况下，训练器会自动将其转换为非配对格式，方法是分离被选中（chosen）和被拒绝（rejected）的回复，并为被选中的补全分配`label = True`，为被拒绝的补全分配`label = False`。

[KTOTrainer](/docs/trl/v1.18.0/zh/kto_trainer#trl.KTOTrainer) 同时兼容 [标准](dataset_formats#standard) 和 [对话](dataset_formats#conversational) 数据集格式。当提供对话数据集时，训练器会自动将聊天模板应用于该数据集。

```python
# Standard format
unpaired_preference_example = {"prompt": "The sky is", "completion": " blue.", "label": True}

# Conversational format
unpaired_preference_example = {"prompt": [{"role": "user", "content": "What color is the sky?"}],
                               "completion": [{"role": "assistant", "content": "It is blue."}],
                               "label": True}
```

理论上，数据集应至少包含一条被选中的补全和一条被拒绝的补全。不过，一些用户已成功使用*仅*包含被选中数据或仅包含被拒绝数据的集运行 KTO。如果仅使用被拒绝的数据，建议采用较为保守的学习率。

## 深入了解 KTO 方法

Kahneman-Tversky 优化（KTO）是一种训练方法，旨在仅使用给定输入的输出是*可取的*还是*不可取的*这一二元信号来对齐语言模型，而不是使用偏好/非偏好补全对。该方法借鉴了 Kahneman 和 Tversky 的前景理论，定义了一种*人类感知损失*（HALO），直接最大化生成的效用，并通过对可取和不可取示例进行非对称加权来反映人类的损失厌恶。

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

### 预处理和分词

在训练期间，每个样本应包含一个提示（prompt）、一个`completion`以及一个布尔值`label`，用于指示该补全是否可取（`True`）或不可取（`False`）。有关预期格式的详细信息，请参阅[Dataset formats](dataset_formats)。[KTOTrainer](/docs/trl/v1.18.0/zh/kto_trainer#trl.KTOTrainer) 会使用模型的 tokenizer 对每个输入进行分词。

### 计算损失

KTO 损失函数中使用的 KL 散度项是通过将每个提示词与从批次其他位置抽取的不匹配补全进行配对来估计的。因此，估计 KL 项的损失类型（除 `apo_zero_unpaired` 外的所有类型）都需要每个设备的训练批次大小大于 1，并采用顺序采样策略，以确保不匹配对在批次内保持稳定。

KTO 中使用的损失（[论文](https://huggingface.co/papers/2402.01306)中的公式 7）定义如下：

$$ \mathcal{L}_{\mathrm{KTO}}(\theta) = \mathbb{E}_{(x,y)}\!\left[ w(y)\Big(1 - v(x, y)\Big) \right] $$

其中值 \\( v(x, y) \\) 为

$$ v(x, y) = \begin{cases} \sigma\!\left(\beta\big(\log\frac{\pi_{\theta}(y\mid x)}{\pi_{\mathrm{ref}}(y\mid x)} - \mathrm{KL}\big)\right) & \text{如果 } y \text{ 是期望的} \\ \sigma\!\left(\beta\big(\mathrm{KL} - \log\frac{\pi_{\theta}(y\mid x)}{\pi_{\mathrm{ref}}(y\mid x)}\big)\right) & \text{如果 } y \text{ 是非期望的} \end{cases} $$

此处  \\( x \\) 是提示，  \\( y \\) 是补全，  \\( \pi_{\theta} \\) 是正在训练的策略模型，  \\( \pi_{\mathrm{ref}} \\) 是参考模型，  \\( \sigma \\) 是 sigmoid 函数，  \\( \beta > 0 \\) 控制与参考模型的偏差，  \\( \mathrm{KL} \\) 是估计的 KL 散度项。权重  \\( w(y) \\) 对于期望的补全为 `desirable_weight`，对于非期望的补全为 `undesirable_weight`，用于抵消期望与非期望示例数量之间的不平衡。

#### 损失类型

| `loss_type=` | 描述 |
| --- | --- |
| `"kto"`（默认） | 来自 [KTO](https://huggingface.co/papers/2402.01306) 论文的 KTO 损失。这是一种基于卡尼曼-特沃斯基前景理论的人类感知损失（HALO），它使用估计的 KL 散度项作为参考点，以最大化理想补全的效用并最小化不理想补全的效用。 |
| `"apo_zero_unpaired"` | [APO](https://huggingface.co/papers/2408.06266) 论文中 APO-zero 损失的无配对变体。它在不估计 KL 散度项的情况下，提高理想补全的似然并降低不理想补全的似然。当您认为理想补全优于模型的默认输出时，请使用此损失。 |

## 记录的指标

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

- `global_step`：迄今为止已执行的优化器步数总数。
- `epoch`：当前 epoch 编号，基于数据集迭代。
- `num_tokens`：迄今为止处理的 token 总数。
- `loss`：当前日志记录区间内的平均 KTO 损失。
- `entropy`：模型在未屏蔽 token 上的预测 token 分布的平均熵。
- `aux_loss`：混合专家（Mixture-of-Experts）模型的负载均衡辅助损失，在乘以 `router_aux_loss_coef` 并加到总损失之前。仅当模型为 MoE 模型且 `router_aux_loss_coef` 非零时记录。
- `kl`：策略模型与参考模型之间平均估计的 KL 散度，用作 KTO 损失中的参考点。
- `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`：所选完成项与被拒绝完成项之间的平均隐式奖励差值。

## 自定义

### 兼容性与约束

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

- 针对 `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`（训练或评估）或视觉数据集一起使用。
- 用于估计 KL 散度项的损失类型（除 `"apo_zero_unpaired"` 外的所有类型）都需要 `train_sampling_strategy="sequential"`，并且每个设备的训练批次大小必须大于 1。

### 模型初始化

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

```python
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-0.5B-Instruct", dtype=torch.bfloat16)
```

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

```python
from trl import KTOConfig

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

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

### 使用 PEFT 训练适配器

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

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

dataset = load_dataset("trl-lib/kto-mix-14k", split="train")

trainer = KTOTrainer(
    "Qwen/Qwen2-0.5B-Instruct",
    train_dataset=dataset,
    peft_config=LoraConfig(),
)

trainer.train()
```

您还可以继续训练您的 `PeftModel`。为此，首先在 [KTOTrainer](/docs/trl/v1.18.0/zh/kto_trainer#trl.KTOTrainer) 外部加载一个 `PeftModel`，然后将其直接传递给 trainer，而不传入 `peft_config` 参数。

> [!TIP]
> 在训练适配器时，由于只学习新参数，通常会使用比全量微调更高的学习率。

## 使用 KTO 进行工具调用

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

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

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

## 训练视觉语言模型

[KTOTrainer](/docs/trl/v1.18.0/zh/kto_trainer#trl.KTOTrainer) 完全支持训练视觉语言模型（VLM）。要训练 VLM，请提供一个包含 `image` 列（每个样本一张图像）或 `images` 列（每个样本一个图像列表）的数据集。有关预期数据集结构的更多信息，请参阅 [Dataset Format — Vision Dataset](dataset_formats#vision-dataset) 部分。

```python
from trl import KTOConfig, KTOTrainer
from datasets import load_dataset

trainer = KTOTrainer(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    args=KTOConfig(max_length=None),
    train_dataset=load_dataset("trl-internal-testing/zen-image", "conversational_unpaired_preference", split="train"),
)
trainer.train()
```

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

## 示例脚本

我们提供了一个使用 KTO 方法训练模型的示例脚本。该脚本位于 [`trl/scripts/kto.py`](https://github.com/huggingface/trl/blob/main/trl/scripts/kto.py)

要在[UltraFeedback 数据集](https://huggingface.co/datasets/trl-lib/kto-mix-14k)上使用[Qwen2 0.5B 模型](https://huggingface.co/Qwen/Qwen2-0.5B-Instruct)测试 KTO 脚本，请运行以下命令：

```bash
torchrun --nproc_per_node 8 trl/scripts/kto.py \
    --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
    --dataset_name trl-lib/kto-mix-14k \
    --num_train_epochs 1 \
    --output_dir Qwen2-0.5B-KTO
```

## 使用技巧

### 对于混合专家模型：启用辅助损失

当负载在专家之间大致均匀分布时，MOE 的效率最高。为了确保在偏好调优期间以类似的方式训练 MOE，将负载均衡器的辅助损失添加到最终损失中是有益的。

通过在模型配置中设置 `output_router_logits=True`（例如 [MixtralConfig](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/mixtral#transformers.MixtralConfig)）来启用此选项。要调整辅助损失对总损失的贡献程度，请在模型配置中使用超参数 `router_aux_loss_coef=...`（默认值：`0.001`）。

### 批量大小建议

请使用至少为 4 的每步批大小（per-step batch size），以及介于 16 到 128 之间的有效批大小（effective batch size）。即使有效批大小很大，如果每步批大小设置不当，KTO 中的 KL 估计也会不准确。

### 学习率建议

每个 `beta` 取值都有一个可承受的最大学习率，超过该值后训练性能会下降。对于默认设置 `beta = 0.1`，大多数模型的学习率通常不应超过 `1e-6`。随着 `beta` 减小，学习率也应相应降低。总体而言，我们强烈建议将学习率保持在 `5e-7` 到 `5e-6` 之间。即使数据集较小，也不建议使用超出此范围的学习率。相反，应增加训练轮数以获得更好的效果。

### 数据不平衡

[KTOConfig](/docs/trl/v1.18.0/zh/kto_trainer#trl.KTOConfig) 中的 `desirable_weight` 和 `undesirable_weight` 分别指施加于期望/正样本和不可期望/负样本损失上的权重。默认情况下，两者均为 1。但是，如果其中一类样本的数量明显多于另一类，则应提高数量较少那一类的权重，使得（`desirable_weight` \\(\times\\) 正样本数量）与（`undesirable_weight` \\(\times\\) 负样本数量）的比值处于 1:1 到 4:3 的范围内。

## KTOTrainer[[trl.KTOTrainer]]

#### trl.KTOTrainer[[trl.KTOTrainer]]

```python
trl.KTOTrainer(model: str | PreTrainedModel | PeftModel, ref_model: transformers.modeling_utils.PreTrainedModel | None = None, args: trl.trainer.kto_config.KTOConfig | 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/v1.18.0/trl/trainer/kto_trainer.py#L462)

**参数：**

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

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

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

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

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

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

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) 或 [ProcessorMixin](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/processors#transformers.ProcessorMixin)，*可选*)：用于处理数据的处理类。填充侧必须设置为 "left"。如果为 `None`，则使用 [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/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/v5.23.0/en/internal/trainer_utils#transformers.EvalPrediction) 并返回一个从字符串到指标值的字典。当使用 [SFTConfig](/docs/trl/v1.18.0/zh/sft_trainer#trl.SFTConfig) 并将 `batch_eval_metrics` 设置为 `True` 时，您的 `compute_metrics` 函数必须接受一个布尔类型的 `compute_result` 参数。这将在最后一个评估批次之后触发，以指示该函数需要计算并返回全局汇总统计信息，而不是累积批次级别的统计信息。它接收的 logits 将通过额外的前向传播重新计算。此功能已弃用，并将在 v2.0.0 中移除。

callbacks （[TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback) 列表，*可选*）：用于自定义训练循环的回调列表。这些回调将被添加到[此处](https://huggingface.co/docs/transformers/main_classes/callback)详述的默认回调列表中。若要移除某个默认使用的回调，请使用 [remove_callback](https://huggingface.co/docs/transformers/v5.23.0/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/v5.23.0/en/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) 给出的调度器。

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

peft_config (`PeftConfig`，*可选*)：用于包装模型的 PEFT 配置。如果为 `None`，则不包装模型。

用于 Kahneman-Tversky Optimization (KTO) 方法的 Trainer。该算法最初在论文 [KTO: Model Alignment as Prospect Theoretic Optimization](https://huggingface.co/papers/2402.01306) 中提出。此类是 [Trainer](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.Trainer) 类的封装，并继承其所有属性和方法。

示例：

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

>>> dataset = load_dataset("trl-lib/kto-mix-14k", split="train")

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

#### train[[trl.KTOTrainer.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/v1.18.0/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.KTOTrainer.save_model]]

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

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

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

仅从主进程保存。

#### push_to_hub[[trl.KTOTrainer.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/v1.18.0/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`。

## KTOConfig[[trl.KTOConfig]]

#### trl.KTOConfig[[trl.KTOConfig]]

```python
trl.KTOConfig(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 = True, 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 = 'sequential', 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, pad_to_multiple_of: int | str | None = 'auto', precompute_ref_log_probs: bool = False, precompute_ref_batch_size: int | None = None, loss_type: str = 'kto', beta: float = 0.1, desirable_weight: float = 1.0, undesirable_weight: float = 1.0, activation_offloading: bool = False, sync_ref_model: bool = False, ref_model_mixup_alpha: float = 0.6, ref_model_sync_steps: int = 512)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/kto_config.py#L22)

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

model_init_kwargs (`dict[str, Any]`, *可选*) : [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) 的关键字参数，当 [KTOTrainer](/docs/trl/v1.18.0/zh/kto_trainer#trl.KTOTrainer) 的 `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/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) and [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/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` 的序列将从右侧截断。如果为 `None`，则不应用截断。

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 (`str`, *可选*, 默认为 `"kto"`) : 要使用的损失类型。可能的值为： - `"kto"`: 来自 [KTO](https://huggingface.co/papers/2402.01306) 论文的 KTO 损失。 - `"apo_zero_unpaired"`: 来自 [APO](https://huggingface.co/papers/2408.06266) 论文的 APO-zero 损失的无配对变体。

beta (`float`, *可选*，默认为 `0.1`)：控制与参考模型偏差的参数。β 值越高，与参考模型的偏差越小。

desirable_weight (`float`, *可选*，默认为 `1.0`)：期望损失会乘以该因子，以抵消期望对与非期望对数量不均衡的影响。

undesirable_weight (`float`, *可选*，默认为 `1.0`)：不期望的损失会乘以该因子，以抵消期望对与不期望对数量不均衡的影响。

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`。

[KTOTrainer](/docs/trl/v1.18.0/zh/kto_trainer#trl.KTOTrainer) 的配置类。

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

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

> [!NOTE]
> 这些参数的默认值与 [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments) 不同： - `logging_steps`：默认值为 `10`，而非 `500`。 - `gradient_checkpointing`：默认值为 `True`，而非 `False`。 - `bf16`：如果未设置 `fp16`，则默认值为 `True`，而非 `False`。 - `learning_rate`：默认值为 `1e-6`，而非 `5e-5`。 - `train_sampling_strategy`：默认值为 `"sequential"`，而非 `"random"`。 用于估计 KL 散度项的损失类型（除 `"apo_zero_unpaired"` 外的所有类型）都需要顺序采样，因为每个示例的 KL 补全都是针对固定顺序批次中的相邻示例预先计算的；任何其他策略都会破坏这种配对。

