# KTO Trainer

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

## Aperçu

TRL prend en charge l’optimisation Kahneman-Tversky (KTO) Trainer pour l’entraînement de modèles de langage, telle que décrite dans l’article [KTO: Model Alignment as Prospect Theoretic Optimization](https://huggingface.co/papers/2402.01306) de [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).

L'abstract de l'article est le suivant :

> La théorie des perspectives de Kahneman & Tversky nous indique que les humains perçoivent les variables aléatoires de manière biaisée mais bien définie ; par exemple, les humains sont réputés pour leur aversion à la perte. Nous montrons que les objectifs d'alignement des LLM avec les retours humains incorporent implicitement de nombreux de ces biais -- le succès de ces objectifs (par exemple, DPO) par rapport à la minimisation de l'entropie croisée peut être partiellement attribué au fait qu'il s'agit de fonctions de perte prenant en compte les humains (HALOs). Cependant, les fonctions d'utilité que ces méthodes attribuent aux humains diffèrent encore de celles de la littérature sur la théorie des perspectives. En utilisant un modèle d'utilité humaine de Kahneman-Tversky, nous proposons un HALO qui maximise directement l'utilité des générations, au lieu de maximiser la log-vraisemblance des préférences, comme le font les méthodes actuelles. Nous appelons cette approche l'Optimisation de Kahneman-Tversky (KTO), et elle égale ou surpasse les performances des méthodes basées sur les préférences à des échelles allant de 1B à 30B. Crucialement, KTO n'a pas besoin de préférences -- seulement un signal binaire indiquant si une sortie est souhaitable ou non souhaitable pour une entrée donnée. Cela le rend beaucoup plus facile à utiliser dans le monde réel, où les données de préférence sont rares et coûteuses.

Le code officiel peut être trouvé dans [ContextualAI/HALOs](https://github.com/ContextualAI/HALOs).

Cette méthode de post-entraînement a été proposée par [Kashif Rasul](https://huggingface.co/kashif), [Younes Belkada](https://huggingface.co/ybelkada), [Lewis Tunstall](https://huggingface.co/lewtun), Pablo Vicente, puis refactorisée par [Albert Villanova del Moral](https://huggingface.co/albertvillanova).

## Démarrage rapide

Cet exemple montre comment entraîner un modèle à l'aide de la méthode KTO. Nous utilisons le [modèle Qwen 0.5B](https://huggingface.co/Qwen/Qwen2-0.5B-Instruct) comme modèle de base. Nous utilisons les données de préférence de [KTO Mix 14k](https://huggingface.co/datasets/trl-lib/kto-mix-14k). Vous pouvez consulter les données du jeu de données ici :

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

Voici le script pour entraîner le modèle :

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

Exécutez le script à l'aide de la commande suivante :

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

Réparti sur 8 x H100 GPU, l’entraînement prend environ 30 minutes. Vous pouvez vérifier la progression de l’entraînement en consultant le graphique de la récompense. Une tendance à la hausse de la marge de récompense indique que le modèle s’améliore et génère de meilleures réponses au fil du temps.

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

Pour voir les performances du [modèle entraîné](https://huggingface.co/trl-lib/Qwen2-0.5B-KTO), vous pouvez utiliser le [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;: Quelle est la meilleure langue de programmation ?

&lt;trl-lib/Qwen2-0.5B-KTO&gt; : Le meilleur langage de programmation peut varier selon les préférences individuelles, les exigences spécifiques au secteur, les compétences techniques et la familiarité avec le cas d'utilisation ou la tâche spécifique. Voici certains langages de programmation largement utilisés qui ont été notés comme populaires et couramment utilisés :

Voici d'autres facteurs à prendre en compte lors du choix d'un langage de programmation pour un projet :

 1 JavaScript : JavaScript est au cœur du web et peut être utilisé pour créer des applications web, des API et des applications front-end interactives, comme les frameworks React et Angular. Sa structure de syntaxe est similaire à celle de C, C++ et F#, et il est accessible et facile à apprendre, ce qui en fait un choix populaire aussi bien pour les débutants que pour les professionnels. 2 Java : Connue pour sa programmation orientée objet (POO) et son support de Java 8 et de .NET, Java est utilisée pour développer des applications logicielles de niveau entreprise, des jeux haute performance, ainsi que des applications mobiles, du développement de jeux et des applications de bureau. 3 C++ : Connue pour sa flexibilité et son évolutivité, C++ offre une programmation orientée objet complète et est un choix populaire pour l'informatique haute performance et d'autres domaines techniques. C'est une plateforme puissante pour construire des applications et des jeux réels à grande échelle. 4 Python : Développé par Guido van Rossum en 1991, Python est un langage de haut niveau, interprété et à typage dynamique, connu pour sa simplicité, sa lisibilité et sa polyvalence.

## Type et format de jeu de données attendus

KTO nécessite un jeu de données de préférences [non appariées](dataset_formats#unpaired-preference). Vous pouvez également fournir un jeu de données de préférences *appariées* (également appelé simplement *jeu de données de préférences*). Dans ce cas, l’entraîneur le convertit automatiquement au format non apparié en séparant les réponses choisies et rejetées, en attribuant `label = True` aux complétions choisies et `label = False` aux complétions rejetées.

Le [KTOTrainer](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOTrainer) est compatible avec les formats de jeu de données [standard](dataset_formats#standard) et [conversationnel](dataset_formats#conversational). Lorsqu’un jeu de données conversationnel est fourni, l’entraîneur applique automatiquement le modèle de chat au jeu de données.

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

En théorie, le jeu de données doit contenir au moins une complétion choisie et une complétion rejetée. Cependant, certains utilisateurs ont exécuté avec succès KTO en utilisant *uniquement* des données choisies ou uniquement des données rejetées. Si vous n'utilisez que des données rejetées, il est conseillé d'adopter un taux d'apprentissage conservateur.

## Explorer plus en profondeur la méthode KTO

L'optimisation Kahneman-Tversky (KTO) est une méthode d'entraînement conçue pour aligner un modèle de langage à l'aide d'un simple signal binaire indiquant si une sortie est *désirable* ou *indésirable* pour une entrée donnée, plutôt que de s'appuyer sur des paires de complétions préférées/dépréciées. S'inspirant de la théorie du prospectus de Kahneman et Tversky, elle définit une *fonction de perte tenant compte de l'humain* (HALO) qui maximise directement l'utilité des générations, en pondérant de manière asymétrique les exemples désirables et indésirables afin de refléter l'aversion à la perte des humains.

Cette section détaille le fonctionnement de KTO en pratique, en couvrant les étapes clés : **prétraitement** et **calcul de la perte**.

### Prétraitement et tokenisation

Lors de l'entraînement, chaque exemple est censé contenir un prompt, une `completion` et un booléen `label` indiquant si la complétion est souhaitable (`True`) ou non (`False`). Pour plus de détails sur les formats attendus, consultez [Formats de jeu de données](dataset_formats). Le [KTOTrainer](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOTrainer) tokenise chaque entrée à l'aide du tokenizer du modèle.

### Calcul de la perte

Le terme de divergence KL utilisé par la perte KTO est estimé en appariant chaque invite avec une complétion non correspondante tirée d’ailleurs dans le lot. Pour cette raison, les types de perte qui estiment le terme KL (tous sauf `apo_zero_unpaired`) exigent une taille de lot d’entraînement par appareil supérieure à 1 et une stratégie d’échantillonnage séquentiel, afin que les paires non correspondantes restent stables au sein d’un lot.

La perte utilisée dans KTO (équation 7 de l'[article](https://huggingface.co/papers/2402.01306)) est définie comme suit :

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

où la valeur \\( v(x, y) \\) est

$$ 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{si } y \text{ est souhaitable} \\ \sigma\!\left(\beta\big(\mathrm{KL} - \log\frac{\pi_{\theta}(y\mid x)}{\pi_{\mathrm{ref}}(y\mid x)}\big)\right) & \text{si } y \text{ est indésirable} \end{cases} $$

Ici  \\( x \\) est le prompt,  \\( y \\) est la complétion,  \\( \pi_{\theta} \\) est le modèle de politique entraîné,  \\( \pi_{\mathrm{ref}} \\) est le modèle de référence,  \\( \sigma \\) est la fonction sigmoïde,  \\( \beta > 0 \\) contrôle l'écart par rapport au modèle de référence, et  \\( \mathrm{KL} \\) est le terme de divergence KL estimé. Le poids  \\( w(y) \\) est `desirable_weight` pour les complétions désirables et `undesirable_weight` pour les indésirables, utilisé pour compenser un déséquilibre entre le nombre d'exemples désirables et indésirables.

#### Types de pertes

| `loss_type=` | Description |
| --- | --- |
| `"kto"` (par défaut) | La perte KTO issue de l'article [KTO](https://huggingface.co/papers/2402.01306). Une perte tenant compte de l'humain (HALO) basée sur la théorie des perspectives de Kahneman-Tversky, qui maximise l'utilité des complétions souhaitables et la minimise pour les complétions indésirables, en utilisant un terme de divergence KL estimé comme point de référence. |
| `"apo_zero_unpaired"` | La variante non appariée de la perte APO-zero issue de l'article [APO](https://huggingface.co/papers/2408.06266). Elle augmente la vraisemblance des complétions souhaitables et diminue celle des complétions indésirables, sans estimer le terme de divergence KL. Utilisez cette perte lorsque vous estimez que les complétions souhaitables sont meilleures que la sortie par défaut du modèle. |

## Métriques journalisées

Lors de l'entraînement et de l'évaluation, nous enregistrons les métriques suivantes :

- `global_step` : le nombre total d'étapes d'optimiseur effectuées jusqu'à présent.
- `epoch` : numéro de l'époque en cours, basé sur l'itération du jeu de données.
- `num_tokens` : le nombre total de jetons traités jusqu'à présent.
- `loss` : perte KTO moyenne sur l'intervalle de journalisation actuel.
- `entropy` : l'entropie moyenne de la distribution de jetons prédite par le modèle sur les jetons non masqués.
- `aux_loss` : perte auxiliaire d'équilibrage de charge d'un modèle Mixture-of-Experts, avant d'être mise à l'échelle par `router_aux_loss_coef` et ajoutée à la perte. Journalisée uniquement lorsque le modèle est un modèle MoE et que `router_aux_loss_coef` est non nul.
- `kl` : divergence KL moyenne estimée entre le modèle de politique et le modèle de référence, utilisée comme point de référence dans la perte KTO.
- `learning_rate` : le taux d'apprentissage actuel, susceptible de changer dynamiquement si un planificateur est utilisé.
- `grad_norm` : la norme L2 des gradients, calculée avant le rognage des gradients.
- `logits/chosen` : Les valeurs de logit moyennes attribuées par le modèle aux jetons de l'achèvement choisi (désirable).
- `logits/rejected` : Les valeurs de logit moyennes attribuées par le modèle aux jetons de la complétion rejetée (indésirable).
- `logps/chosen` : La probabilité logarithmique moyenne attribuée par le modèle aux jetons de la complétion choisie (désirable).
- `logps/rejected` : La probabilité logarithmique moyenne attribuée par le modèle aux jetons de la complétion rejetée (indésirable).
- `rewards/chosen` : La récompense implicite moyenne calculée pour l’achèvement choisi (désirable), calculée comme  \\( \beta \log \frac{\pi_{\theta}(y\mid x)}{\pi_{\mathrm{ref}}(y\mid x)} \\).
- `rewards/rejected` : La récompense implicite moyenne calculée pour l’achèvement rejeté (indésirable), calculée comme  \\( \beta \log \frac{\pi_{\theta}(y\mid x)}{\pi_{\mathrm{ref}}(y\mid x)} \\).
- `rewards/margins` : Marge de récompense implicite moyenne entre les complétions choisies et rejetées.

## Personnalisation

### Compatibilité et contraintes

Certaines combinaisons d’arguments sont volontairement restreintes dans l’implémentation actuelle de [KTOTrainer](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOTrainer) :

- Les adaptateurs PEFT ciblant `lm_head` ne sont pas pris en charge (utilisez plutôt `modules_to_save=["lm_head"]`).
- `sync_ref_model=True` n'est pas pris en charge lors de l'entraînement avec des modèles PEFT qui ne conservent pas de `ref_model` indépendant.
- `sync_ref_model=True` ne peut pas être combiné avec `precompute_ref_log_probs=True`.
- `precompute_ref_log_probs=True` n'est pas pris en charge avec `IterableDataset` (entraînement ou évaluation) ni avec les jeux de données visuels.
- Les types de perte qui estiment le terme de divergence KL (tous sauf `"apo_zero_unpaired"`) nécessitent `train_sampling_strategy="sequential"` et une taille de lot d’entraînement par appareil supérieure à 1.

### Initialisation du modèle

Vous pouvez passer directement les kwargs de la méthode `from_pretrained()` à [KTOConfig](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOConfig). Par exemple, si vous souhaitez charger un modèle dans une précision différente, de manière analogue à

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

vous pouvez le faire en passant l'argument `model_init_kwargs={"dtype": torch.bfloat16}` à [KTOConfig](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOConfig).

```python
from trl import KTOConfig

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

Notez que tous les arguments par mot-clé de `from_pretrained()` sont pris en charge.

### Entraîner des adaptateurs avec PEFT

Nous prenons en charge une intégration étroite avec la bibliothèque 🤗 PEFT, permettant à tout utilisateur d’entraîner et de partager des adaptateurs sur le Hub de manière pratique, plutôt que d’entraîner l’ensemble du modèle.

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

Vous pouvez également poursuivre l’entraînement de votre [PeftModel](https://huggingface.co/docs/peft/v0.22.0/en/package_reference/peft_model#peft.PeftModel). Pour cela, chargez d’abord un `PeftModel` en dehors de [KTOTrainer](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOTrainer) et transmettez-le directement à l’entraîneur sans passer l’argument `peft_config`.

> [!TIP]
> Lors de l’entraînement d’adapters, vous utilisez généralement un taux d’apprentissage plus élevé que lors d’un fine-tuning complet, car seuls les nouveaux paramètres sont appris.

## Appel d'outils avec KTO

Le [KTOTrainer](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOTrainer) prend entièrement en charge l’ajustement fin des modèles dotés de capacités de _tool calling_. Dans ce cas, chaque exemple du jeu de données doit inclure :

- Les messages de la conversation (invite et complétion), y compris les appels d'outils (`tool_calls`) et les réponses d'outils (messages avec le rôle `tool`)
- La liste des outils disponibles dans la colonne `tools`, généralement fournie sous forme de schémas JSON

Pour plus de détails sur la structure attendue du jeu de données, consultez la section [Format du jeu de données — Tool Calling](dataset_formats#tool-calling).

## Entraînement des modèles de vision et de langage

[KTOTrainer](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOTrainer) prend entièrement en charge l’entraînement des modèles Vision-Language (VLM). Pour entraîner un VLM, fournissez un jeu de données contenant soit une colonne `image` (une image par exemple), soit une colonne `images` (liste d’images par exemple). Pour plus d’informations sur la structure attendue du jeu de données, consultez la section [Format du jeu de données — Jeu de données Vision](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]
> Pour les VLM, la troncature peut supprimer des jetons d’image, ce qui entraîne des erreurs lors de l’entraînement. Pour éviter cela, définissez `max_length=None` dans [KTOConfig](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOConfig). Cela permet au modèle de traiter la longueur complète de la séquence sans tronquer les jetons d’image.
>
> ```python
> KTOConfig(max_length=None, ...)
> ```
>
> N'utilisez `max_length` que si vous avez vérifié que la troncature ne supprimera pas les jetons d'image pour l'ensemble du jeu de données.

## Exemple de script

Nous fournissons un script d’exemple pour entraîner un modèle à l’aide de la méthode KTO. Le script est disponible dans [`trl/scripts/kto.py`](https://github.com/huggingface/trl/blob/main/trl/scripts/kto.py)

Pour tester le script KTO avec le [modèle Qwen2 0.5B](https://huggingface.co/Qwen/Qwen2-0.5B-Instruct) sur le [jeu de données UltraFeedback](https://huggingface.co/datasets/trl-lib/kto-mix-14k), exécutez la commande suivante :

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

## Conseils d'utilisation

### Pour les modèles Mixture of Experts : Activer la perte auxiliaire

Les MOEs sont les plus efficaces lorsque la charge est répartie de manière à peu près égale entre les experts. Pour nous assurer d'entraîner les MOEs de manière similaire lors de l'ajustement par préférence, il est bénéfique d'ajouter la perte auxiliaire du répartiteur de charge à la perte finale.

Cette option est activée en définissant `output_router_logits=True` dans la configuration du modèle (par exemple [MixtralConfig](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/mixtral#transformers.MixtralConfig)). Pour ajuster la contribution de la perte auxiliaire à la perte totale, utilisez l'hyperparamètre `router_aux_loss_coef=...` (valeur par défaut : `0.001`) dans la configuration du modèle.

### Recommandations de taille de lot

Utilisez une taille de lot par étape d’au moins 4, et une taille de lot effective comprise entre 16 et 128. Même si votre taille de lot effective est importante, si votre taille de lot par étape est faible, l’estimation du KL dans KTO sera médiocre.

### Recommandations de taux d'apprentissage

Chaque choix de `beta` a un taux d'apprentissage maximal qu'il peut tolérer avant que les performances d'apprentissage ne se dégradent. Pour le réglage par défaut de `beta = 0.1`, le taux d'apprentissage ne devrait généralement pas dépasser `1e-6` pour la plupart des modèles. À mesure que `beta` diminue, le taux d'apprentissage doit également être réduit en conséquence. En général, nous recommandons vivement de maintenir le taux d'apprentissage entre `5e-7` et `5e-6`. Même avec de petits jeux de données, nous déconseillons d'utiliser un taux d'apprentissage en dehors de cette plage. Optez plutôt pour un nombre d'époques plus élevé pour obtenir de meilleurs résultats.

### Données déséquilibrées

Les `desirable_weight` et `undesirable_weight` du [KTOConfig](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOConfig) correspondent aux poids appliqués aux pertes pour les exemples désirables/positifs et indésirables/négatifs. Par défaut, ils sont tous deux égaux à 1. Toutefois, si vous avez plus d’un type que de l’autre, vous devez augmenter le poids du type le moins fréquent afin que le rapport entre (`desirable_weight`  \\(\times\\) nombre de positifs) et (`undesirable_weight`  \\(\times\\) nombre de négatifs) se situe entre 1:1 et 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)
```

[Source](https://github.com/huggingface/trl/blob/v1.18.2/trl/trainer/kto_trainer.py#L462)

**Paramètres :**

model (`str` ou [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) ou [PeftModel](https://huggingface.co/docs/peft/v0.22.0/en/package_reference/peft_model#peft.PeftModel)) : Modèle à entraîner. Peut être :  - Une chaîne de caractères, correspondant à l'*identifiant du modèle* d'un modèle pré-entraîné hébergé dans un dépôt de modèles sur huggingface.co, ou un chemin vers un *dossier* contenant les poids du modèle enregistrés à l'aide de [save_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained), par exemple `'./my_model_directory/'`. Le modèle est chargé à l'aide de `<ModelArchitecture>.from_pretrained` (où `<ModelArchitecture>` est dérivé de la configuration du modèle) avec les arguments nommés de `args.model_init_kwargs`. Si `dtype` n'est pas spécifié dans `args.model_init_kwargs`, la valeur par défaut est `float32`. Cela diffère de [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.from_pretrained), où (depuis Transformers v5) le type de données est déduit de la configuration du modèle. - Un objet [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel). Seuls les modèles de langage causaux sont pris en charge. - Un objet [PeftModel](https://huggingface.co/docs/peft/v0.22.0/en/package_reference/peft_model#peft.PeftModel). Seuls les modèles de langage causaux sont pris en charge.

ref_model ([PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel), *facultatif*) : Modèle de référence utilisé pour calculer les log-probabilités de référence. - S'il est fourni, ce modèle est utilisé directement comme politique de référence. Il ne peut pas être un [PeftModel](https://huggingface.co/docs/peft/v0.22.0/en/package_reference/peft_model#peft.PeftModel). - Si `None`, l'entraîneur utilisera automatiquement la politique initiale correspondant à `model`, c'est-à-dire l'état du modèle avant le début de l'entraînement KTO.

args ([KTOConfig](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOConfig), *facultatif*) : Configuration pour cet entraîneur. Si `None`, une configuration par défaut est utilisée.

data_collator (`DataCollator`, *facultatif*) : Fonction à utiliser pour former un lot à partir d'une liste d'éléments du `train_dataset` ou du `eval_dataset` traités. Par défaut, `DataCollatorForUnpairedPreference` est utilisé si le modèle est un modèle de langage et `DataCollatorForVisionUnpairedPreference` si le modèle est un modèle de vision-langage. Les collateurs personnalisés doivent tronquer les séquences avant le bourrage ; le formateur n'applique pas de troncature après le collation.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) ou [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset)) : Jeu de données à utiliser pour l’entraînement. Cet entraîneur prend en charge le type [préférence non appariée](#unpaired-preference). Le format des échantillons peut être l’un des deux suivants : - [Standard](dataset_formats#standard) : chaque échantillon contient du texte brut. - [Conversationnel](dataset_formats#conversational) : chaque échantillon contient des messages structurés (par exemple, rôle et contenu).  Lorsque `train_dataset` est un [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) (par exemple, un jeu de données en flux), `max_steps` doit être défini dans les arguments d’entraînement, car sa longueur ne peut pas être déduite et le nombre total d’étapes d’entraînement est nécessaire pour borner la boucle d’entraînement et configurer le planificateur de taux d’apprentissage.

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) ou `dict[str, Dataset | IterableDataset]`) : Jeu de données à utiliser pour l'évaluation. Il doit répondre aux mêmes exigences que `train_dataset`.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) ou [ProcessorMixin](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/processors#transformers.ProcessorMixin), *facultatif*) : classe de traitement utilisée pour traiter les données. Le côté de bourrage doit être défini sur « left ». Si `None`, la classe de traitement est chargée à partir du nom du modèle avec [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoProcessor.from_pretrained). Un jeton de bourrage, `tokenizer.pad_token`, doit être défini. Si la classe de traitement n’a pas défini de jeton de bourrage, `tokenizer.eos_token` sera utilisé par défaut.

compute_metrics (`Callable[[EvalPrediction], dict]`, *facultatif*) : La fonction qui sera utilisée pour calculer les métriques lors de l'évaluation. Elle doit prendre un [EvalPrediction](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.EvalPrediction) en entrée et renvoyer un dictionnaire associant des chaînes de caractères aux valeurs des métriques. Lors du passage de [SFTConfig](/docs/trl/v1.18.2/fr/sft_trainer#trl.SFTConfig) avec `batch_eval_metrics` défini sur `True`, votre fonction `compute_metrics` doit prendre un argument booléen `compute_result`. Cela sera déclenché après le dernier lot d'évaluation pour indiquer que la fonction doit calculer et renvoyer les statistiques globales de synthèse plutôt que d'accumuler les statistiques au niveau du lot. Les logits qu'elle reçoit sont recalculés lors d'un passage avant supplémentaire. Cette fonctionnalité est obsolète et sera supprimée dans la v2.0.0.

callbacks (liste de [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback), *facultatif*) : Liste de callbacks pour personnaliser la boucle d'entraînement. Ils seront ajoutés à la liste des callbacks par défaut détaillée [ici](https://huggingface.co/docs/transformers/main_classes/callback). Si vous souhaitez supprimer l'un des callbacks par défaut utilisés, utilisez la méthode [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]`, *facultatif*, valeur par défaut `(None, None)`) : Un tuple contenant l'optimiseur et le planificateur à utiliser. Par défaut, une instance de `AdamW` est appliquée à votre modèle, ainsi qu'un planificateur défini par [get_linear_schedule_with_warmup](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) et contrôlé par `args`.

quantization_config ([BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/quantization#transformers.BitsAndBytesConfig), *facultatif*) : Configuration de quantification utilisée lors du chargement du modèle à partir d'un identifiant de modèle. À combiner avec `peft_config` pour l'entraînement QLoRA. Ignorée si le modèle est déjà instancié.

peft_config ([PeftConfig](https://huggingface.co/docs/peft/v0.22.0/en/package_reference/config#peft.PeftConfig), *facultatif*) : configuration PEFT utilisée pour envelopper le modèle. Si `None`, le modèle n'est pas enveloppé.

Trainer pour la méthode d'optimisation de Kahneman-Tversky (KTO). Cet algorithme a été initialement proposé dans l'article [KTO: Model Alignment as Prospect Theoretic Optimization](https://huggingface.co/papers/2402.01306). Cette classe est un wrapper autour de la classe [Trainer](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.Trainer) et hérite de tous ses attributs et méthodes.

Exemple :

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

[Source](https://github.com/huggingface/trl/blob/v1.18.2/transformers/trainer.py#L1450)

**Paramètres :**

resume_from_checkpoint (`str` ou `bool`, *facultatif*) : Si c'est une `str`, chemin local d'un point de contrôle enregistré par une instance précédente de `Trainer`. Si c'est un `bool` et vaut `True`, charge le dernier point de contrôle dans *args.output_dir* tel qu'enregistré par une instance précédente de `Trainer`. S'il est présent, l'entraînement reprendra à partir des états du modèle/optimiseur/planificateur chargés ici.

trial (`optuna.Trial` ou `dict[str, Any]`, *facultatif*) : L'exécution de l'essai ou le dictionnaire d'hyperparamètres pour la recherche d'hyperparamètres.

ignore_keys_for_eval (`list[str]`, *facultatif*) : Une liste de clés dans la sortie de votre modèle (s'il s'agit d'un dictionnaire) qui doivent être ignorées lors de la collecte des prédictions pour l'évaluation pendant l'entraînement.

**Retourne :** `~trainer_utils.TrainOutput`

Objet contenant le nombre d'étapes globales, la perte d'entraînement et les métriques.

Point d'entrée principal de l'entraînement.

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

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

[Source](https://github.com/huggingface/trl/blob/v1.18.2/transformers/trainer.py#L4077)

Enregistrera le modèle, ce qui vous permettra de le recharger à l'aide de `from_pretrained()`.

N'enregistrera que depuis le processus principal.

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

[Source](https://github.com/huggingface/trl/blob/v1.18.2/transformers/trainer.py#L4337)

**Paramètres :**

commit_message (`str`, *facultatif*, par défaut `"End of training"`) : Message à commiter lors de la poussée.

blocking (`bool`, *facultatif*, par défaut `True`) : Indique si la fonction doit ne renvoyer un résultat qu'une fois le `git push` terminé.

token (`str`, *facultatif*, valeur par défaut `None`) : Jeton avec permission d'écriture pour écraser les arguments d'origine du Trainer.

revision (`str`, *facultatif*) : La révision git à partir de laquelle effectuer le commit. Par défaut, il s'agit de la tête de la branche "main".

private (`bool`, *facultatif*) : Indique s'il faut rendre le dépôt privé lors de sa création. La valeur par défaut est `args.hub_private_repo`. N'a aucun effet si le dépôt existe déjà.

kwargs (`dict[str, Any]`, *facultatif*) : Arguments supplémentaires passés à `~Trainer.create_model_card`.

**Retourne :**

L'URL du dépôt où le modèle a été poussé si `blocking=False`, ou un objet `Future` suivant la progression de l'engagement si `blocking=True`.

Téléchargez `self.model` et `self.processing_class` sur le hub de modèles 🤗 dans le dépôt `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 | 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 = '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)
```

[Source](https://github.com/huggingface/trl/blob/v1.18.2/trl/trainer/kto_config.py#L22)

**Paramètres qui contrôlent le modèle :**

model_init_kwargs (`dict[str, Any]`, *facultatif*) : Arguments nommés pour [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained), utilisés lorsque l'argument `model` du [KTOTrainer](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOTrainer) est fourni sous forme de chaîne de caractères. La valeur de `revision` est également utilisée lors du chargement de la classe de traitement.

trust_remote_code (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut autoriser le chargement de modèles et de tokenizers qui incluent du code Python personnalisé depuis le Hub. Transmis à [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) et [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoProcessor.from_pretrained).

router_aux_loss_coef (`float`, *facultatif*) : Coefficient de la perte auxiliaire d'équilibrage de charge pour les modèles Mixture-of-Experts (MoE), ajoutée à la perte d'entraînement avec ce poids. Si non défini, la valeur déclarée par la configuration du modèle est utilisée. Définissez-le sur `0.0` pour le désactiver. Échoue s'il est utilisé avec un modèle non-MoE.

disable_dropout (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut désactiver le dropout dans le modèle et le modèle de référence.

**Paramètres qui contrôlent le prétraitement des données :**

dataset_num_proc (`int`, *facultatif*) : Nombre de processus à utiliser pour le traitement du jeu de données.

max_length (`int` ou `None`, *facultatif*, par défaut `1024`) : Longueur maximale de la séquence tokenisée. Les séquences plus longues que `max_length` sont tronquées à droite. Si `None`, aucun tronquage n'est appliqué.

pad_to_multiple_of (`int` ou `str`, *facultatif*, valeur par défaut `"auto"`) : Si défini, les séquences seront remplies jusqu'à un multiple de cette valeur. `"auto"` remplit jusqu'à un multiple de 128 sur Neuron (AWS Trainium), qui compile une fois par forme d'entrée, et ne remplit pas ailleurs.

precompute_ref_log_probs (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut précalculer les logarithmes des probabilités du modèle de référence pour l'ensemble du jeu de données d'entraînement avant le début de l'entraînement. Cela permet d'économiser de la mémoire pendant l'entraînement, car le modèle de référence n'a pas besoin d'être conservé en mémoire.

precompute_ref_batch_size (`int`, *facultatif*) : Taille du lot à utiliser lors de la précalcul des probabilités log du modèle de référence. Cette valeur peut être définie plus élevée que la taille du lot d’entraînement pour accélérer la prétraitement. Si `None`, la valeur par défaut est `per_device_train_batch_size` pour l’entraînement et `per_device_eval_batch_size` pour l’évaluation.

**Paramètres qui contrôlent l’entraînement :**

loss_type (`str`, *facultatif*, par défaut `"kto"`) : Type de perte à utiliser. Les valeurs possibles sont :  - `"kto"` : Perte KTO issue de l'article [KTO](https://huggingface.co/papers/2402.01306). - `"apo_zero_unpaired"` : Variante non appariée de la perte APO-zero issue de l'article [APO](https://huggingface.co/papers/2408.06266).

beta (`float`, *facultatif*, valeur par défaut `0.1`) : Paramètre contrôlant l'écart par rapport au modèle de référence. Plus β est élevé, moins l'écart par rapport au modèle de référence est important.

desirable_weight (`float`, *facultatif*, par défaut `1.0`) : Les pertes souhaitables sont pondérées par ce facteur pour compenser un nombre inégal de paires souhaitables et non souhaitables.

undesirable_weight (`float`, *facultatif*, par défaut `1.0`) : Les pertes indésirables sont pondérées par ce facteur pour compenser un nombre inégal de paires désirables et indésirables.

activation_offloading (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut décharger les activations sur le CPU.

sync_ref_model (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut synchroniser le modèle de référence avec le modèle actif toutes les `ref_model_sync_steps` étapes, en utilisant le paramètre `ref_model_mixup_alpha`. Cette synchronisation provient de l'article [TR-DPO](https://huggingface.co/papers/2404.09656). `sync_ref_model=True` n'est pas encore compatible avec PEFT ou `precompute_ref_log_probs=True`.

ref_model_mixup_alpha (`float`, *facultatif*, valeur par défaut `0.6`) : paramètre α issu du papier TR-DPO, qui contrôle le mélange entre la politique actuelle et la politique de référence précédente lors des mises à jour. La politique de référence est mise à jour selon l'équation : `π_ref = α * π_θ + (1 - α) * π_ref_prev`. Pour utiliser ce paramètre, vous devez définir `sync_ref_model=True`.

ref_model_sync_steps (`int`, *facultatif*, valeur par défaut `512`) : paramètre τ issu de l'article [TR-DPO](https://huggingface.co/papers/2404.09656), qui détermine la fréquence de synchronisation de la politique actuelle avec la politique de référence. Pour utiliser ce paramètre, vous devez définir `sync_ref_model=True`.

Classe de configuration pour le [KTOTrainer](/docs/trl/v1.18.2/fr/kto_trainer#trl.KTOTrainer).

Cette classe ne contient que les paramètres spécifiques à l’entraînement KTO. Pour la liste complète des arguments d’entraînement, veuillez consulter la documentation de [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments). Notez que les valeurs par défaut de cette classe peuvent différer de celles de [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments).

À l’aide de [HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser), nous pouvons transformer cette classe en arguments [argparse](https://docs.python.org/3/library/argparse#module-argparse) qui peuvent être spécifiés sur la ligne de commande.

> [!NOTE]
> Ces paramètres ont des valeurs par défaut différentes de [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments) : - `logging_steps` : la valeur par défaut est `10` au lieu de `500`. - `gradient_checkpointing` : la valeur par défaut est `True` au lieu de `False`. - `bf16` : la valeur par défaut est `True` si `fp16` n'est pas défini, au lieu de `False`. - `learning_rate` : la valeur par défaut est `1e-6` au lieu de `5e-5`. - `train_sampling_strategy` : la valeur par défaut est `"sequential"` au lieu de `"random"`. Les types de perte qui estiment le terme de divergence KL (tous sauf `"apo_zero_unpaired"`) nécessitent un échantillonnage séquentiel, car la complétion KL pour chaque exemple est précalculée par rapport à ses voisins dans un lot à ordre fixe ; toute autre stratégie rompt cette appariement.

