# KTO Trainer

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

## Visão geral

O TRL oferece suporte ao Treinador de Otimização Kahneman-Tversky (KTO) para o treinamento de modelos de linguagem, conforme descrito no artigo [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).

O resumo do artigo é o seguinte:

> A teoria da perspectiva de Kahneman & Tversky nos diz que os humanos percebem variáveis aleatórias de uma maneira enviesada, porém bem definida; por exemplo, os humanos são notoriamente avessos a perdas. Mostramos que os objetivos para alinhar LLMs com feedback humano incorporam implicitamente muitas dessas viés -- o sucesso desses objetivos (por exemplo, DPO) em relação à minimização da entropia cruzada pode ser atribuído em parte ao fato de serem funções de perda conscientes dos humanos (HALOs). No entanto, as funções de utilidade que esses métodos atribuem aos humanos ainda diferem daquelas na literatura da teoria da perspectiva. Usando um modelo de utilidade humana de Kahneman-Tversky, propomos um HALO que maximiza diretamente a utilidade das gerações, em vez de maximizar a log-verossimilhança das preferências, como os métodos atuais fazem. Chamamos essa abordagem de Otimização de Kahneman-Tversky (KTO), e ela iguala ou supera o desempenho de métodos baseados em preferências em escalas de 1B a 30B. Crucialmente, o KTO não precisa de preferências -- apenas um sinal binário de se uma saída é desejável ou indesejável para uma entrada dada. Isso o torna muito mais fácil de usar no mundo real, onde dados de preferência são escassos e caros.

O código oficial pode ser encontrado em [ContextualAI/HALOs](https://github.com/ContextualAI/HALOs).

Este método de pós-treinamento foi contribuído por [Kashif Rasul](https://huggingface.co/kashif), [Younes Belkada](https://huggingface.co/ybelkada), [Lewis Tunstall](https://huggingface.co/lewtun), Pablo Vicente e, posteriormente, refatorado por [Albert Villanova del Moral](https://huggingface.co/albertvillanova).

## Início rápido

Este exemplo demonstra como treinar um modelo usando o método KTO. Usamos o [modelo Qwen 0.5B](https://huggingface.co/Qwen/Qwen2-0.5B-Instruct) como modelo base. Usamos os dados de preferência do [KTO Mix 14k](https://huggingface.co/datasets/trl-lib/kto-mix-14k). Você pode visualizar os dados no dataset aqui:

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

Abaixo está o script para treinar o modelo:

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

Execute o script usando o seguinte comando:

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

Distribuído em 8 x H100 GPUs, o treinamento leva aproximadamente 30 minutos. Você pode verificar o progresso do treinamento analisando o gráfico de recompensa. Uma tendência de aumento na margem de recompensa indica que o modelo está melhorando e gerando respostas melhores ao longo do tempo.

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

Para ver como o [modelo treinado](https://huggingface.co/trl-lib/Qwen2-0.5B-KTO) se comporta, você pode usar o [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;: Qual é a melhor linguagem de programação?

&lt;trl-lib/Qwen2-0.5B-KTO&gt;: A melhor linguagem de programação pode variar dependendo das preferências individuais, dos requisitos específicos do setor, das habilidades técnicas e da familiaridade com o caso de uso ou tarefa específica. Aqui estão algumas linguagens de programação amplamente utilizadas que foram notadas como populares e amplamente usadas:

Aqui estão alguns outros fatores a considerar ao escolher uma linguagem de programação para um projeto:

 1 JavaScript: JavaScript está no coração da web e pode ser usado para construir aplicações web, APIs e aplicações front-end interativas, como frameworks como React e Angular. Sua estrutura de sintaxe é semelhante à de C, C++ e F#, sendo acessível e fácil de aprender, o que o torna uma escolha popular tanto para iniciantes quanto para profissionais. 2 Java: Conhecido por sua programação orientada a objetos (OOP) e suporte a Java 8 e .NET, o Java é usado para desenvolver aplicações de software em nível empresarial, jogos de alto desempenho, bem como aplicativos móveis, desenvolvimento de jogos e aplicações desktop. 3 C++: Conhecido por sua flexibilidade e escalabilidade, o C++ oferece programação orientada a objetos abrangente e é uma escolha popular para computação de alto desempenho e outros campos técnicos. É uma plataforma poderosa para construir aplicações e jogos do mundo real em escala. 4 Python: Desenvolvido por Guido van Rossum em 1991, o Python é uma linguagem de alto nível, interpretada e de tipagem dinâmica, conhecida por sua simplicidade, legibilidade e versatilidade.

## Tipo e formato de dataset esperados

O KTO requer um conjunto de dados de [preferência não pareada](dataset_formats#unpaired-preference). Alternativamente, você pode fornecer um conjunto de dados de *preferência pareada* (também conhecido simplesmente como *conjunto de dados de preferências*). Nesse caso, o treinador o converterá automaticamente para o formato não pareado, separando as respostas escolhidas e rejeitadas, atribuindo `label = True` às conclusões escolhidas e `label = False` às rejeitadas.

O [KTOTrainer](/docs/trl/main/pt/kto_trainer#trl.KTOTrainer) é compatível com os formatos de dataset [padrão](dataset_formats#standard) e [conversacional](dataset_formats#conversational). Quando fornecido com um dataset conversacional, o trainer aplica automaticamente o chat template ao dataset.

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

Em teoria, o conjunto de dados deve conter pelo menos uma conclusão escolhida e uma rejeitada. No entanto, alguns usuários executaram o KTO com sucesso usando *apenas* dados escolhidos ou apenas rejeitados. Ao usar apenas dados rejeitados, é aconselhável adotar uma taxa de aprendizado conservadora.

## Aprofundando-se no método KTO

A Otimização Kahneman-Tversky (KTO) é um método de treinamento projetado para alinhar um modelo de linguagem usando apenas um sinal binário de se uma saída é *desejável* ou *indesejável* para uma entrada dada, em vez de pares de conclusões preferidas/despreferidas. Baseando-se na teoria da perspectiva de Kahneman e Tversky, ela define uma *perda consciente do humano* (HALO) que maximiza diretamente a utilidade das gerações, ponderando exemplos desejáveis e indesejáveis de forma assimétrica para refletir a aversão à perda humana.

Esta seção detalha como o KTO funciona na prática, abordando as etapas principais: **pré-processamento** e **cálculo da perda**.

### Pré-processamento e tokenização

Durante o treinamento, cada exemplo deve conter um prompt, uma `completion` e um `label` booleano indicando se a completion é desejável (`True`) ou indesejável (`False`). Para mais detalhes sobre os formatos esperados, consulte [Dataset formats](dataset_formats). O [KTOTrainer](/docs/trl/main/pt/kto_trainer#trl.KTOTrainer) tokeniza cada entrada usando o tokenizer do modelo.

### Calculando a perda

O termo de divergência KL usado pela perda KTO é estimado ao emparelhar cada prompt com uma conclusão não correspondente retirada de outra parte do lote. Por esse motivo, os tipos de perda que estimam o termo KL (todos, exceto `apo_zero_unpaired`) exigem um tamanho de lote de treinamento por dispositivo maior que 1 e uma estratégia de amostragem sequencial, para que os pares não correspondentes sejam estáveis ao longo de um lote.

A perda utilizada no KTO (Eq. 7 do [artigo](https://huggingface.co/papers/2402.01306)) é definida da seguinte forma:

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

onde o valor \\( 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{se } y \text{ é desejável} \\ \sigma\!\left(\beta\big(\mathrm{KL} - \log\frac{\pi_{\theta}(y\mid x)}{\pi_{\mathrm{ref}}(y\mid x)}\big)\right) & \text{se } y \text{ é indesejável} \end{cases} $$

Aqui  \\( x \\) é o prompt,  \\( y \\) é a conclusão,  \\( \pi_{\theta} \\) é o modelo de política em treinamento,  \\( \pi_{\mathrm{ref}} \\) é o modelo de referência,  \\( \sigma \\) é a função sigmoid,  \\( \beta > 0 \\) controla o desvio em relação ao modelo de referência e  \\( \mathrm{KL} \\) é o termo de divergência KL estimado. O peso  \\( w(y) \\) é `desirable_weight` para conclusões desejáveis e `undesirable_weight` para as indesejáveis, usado para compensar um desequilíbrio entre o número de exemplos desejáveis e indesejáveis.

#### Tipos de Perda

| `loss_type=` | Descrição |
| --- | --- |
| `"kto"` (padrão) | A perda KTO do artigo [KTO](https://huggingface.co/papers/2402.01306). Uma perda consciente de humanos (HALO) baseada na teoria da perspectiva de Kahneman-Tversky que maximiza a utilidade de conclusões desejáveis e a minimiza para as indesejáveis, usando um termo de divergência KL estimado como ponto de referência. |
| `"apo_zero_unpaired"` | A variante não pareada da perda APO-zero do artigo [APO](https://huggingface.co/papers/2408.06266). Ela aumenta a probabilidade de conclusões desejáveis e diminui a probabilidade das indesejáveis, sem estimar o termo de divergência de KL. Use esta perda quando você acredita que as conclusões desejáveis são melhores que a saída padrão do modelo. |

## Métricas registradas

Durante o treinamento e a avaliação, registramos as seguintes métricas:

- `global_step`: O número total de etapas do otimizador realizadas até o momento.
- `epoch`: O número do epoch atual, com base na iteração do conjunto de dados.
- `num_tokens`: O número total de tokens processados até o momento.
- `loss`: A perda média de KTO no intervalo de registro atual.
- `entropy`: A entropia média da distribuição de tokens prevista pelo modelo para tokens não mascarados.
- `aux_loss`: A perda auxiliar de balanceamento de carga de um modelo Mixture-of-Experts, antes de ser escalada por `router_aux_loss_coef` e adicionada à perda. Registrada apenas quando o modelo é um modelo MoE e `router_aux_loss_coef` é diferente de zero.
- `kl`: A divergência de KL média estimada entre o modelo de política e o modelo de referência, usada como ponto de referência na perda KTO.
- `learning_rate`: a taxa de aprendizado atual, que pode mudar dinamicamente se um agendador for usado.
- `grad_norm`: A norma L2 dos gradientes, calculada antes do recorte de gradientes.
- `logits/chosen`: Os valores médios de logit atribuídos pelo modelo aos tokens na conclusão escolhida (desejável).
- `logits/rejected`: Os valores médios de logit atribuídos pelo modelo aos tokens na conclusão rejeitada (indesejável).
- `logps/chosen`: A média da log-probabilidade atribuída pelo modelo aos tokens na conclusão escolhida (desejável).
- `logps/rejected`: A média da log-probabilidade atribuída pelo modelo aos tokens na conclusão rejeitada (indesejável).
- `rewards/chosen`: A recompensa implícita média calculada para a conclusão escolhida (desejável), calculada como  \\( \beta \log \frac{\pi_{\theta}(y\mid x)}{\pi_{\mathrm{ref}}(y\mid x)} \\).
- `rewards/rejected`: A recompensa implícita média calculada para a conclusão rejeitada (indesejável), calculada como  \\( \beta \log \frac{\pi_{\theta}(y\mid x)}{\pi_{\mathrm{ref}}(y\mid x)} \\).
- `rewards/margins`: A margem média de recompensa implícita entre as conclusões escolhidas e rejeitadas.

## Personalização

### Compatibilidade e restrições

Algumas combinações de argumentos são intencionalmente restritas na implementação atual do [KTOTrainer](/docs/trl/main/pt/kto_trainer#trl.KTOTrainer):

- Adaptadores PEFT que visam `lm_head` não são suportados (use `modules_to_save=["lm_head"]` em vez disso).
- `sync_ref_model=True` não é suportado ao treinar com modelos PEFT que não mantêm um `ref_model` independente.
- `sync_ref_model=True` não pode ser combinado com `precompute_ref_log_probs=True`.
- `precompute_ref_log_probs=True` não é suportado com `IterableDataset` (treino ou avaliação) nem com conjuntos de dados de visão.
- Os tipos de perda que estimam o termo de divergência KL (todos, exceto `"apo_zero_unpaired"`) exigem `train_sampling_strategy="sequential"` e um tamanho de lote de treinamento por dispositivo maior que 1.

### Inicialização do modelo

Você pode passar diretamente os kwargs do método `from_pretrained()` para o [KTOConfig](/docs/trl/main/pt/kto_trainer#trl.KTOConfig). Por exemplo, se você quiser carregar um modelo em uma precisão diferente, análogo a

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

você pode fazer isso passando o argumento `model_init_kwargs={"dtype": torch.bfloat16}` para o [KTOConfig](/docs/trl/main/pt/kto_trainer#trl.KTOConfig).

```python
from trl import KTOConfig

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

Observe que todos os argumentos de palavra-chave de `from_pretrained()` são suportados.

### Treine adaptadores com PEFT

Suportamos integração estreita com a biblioteca 🤗 PEFT, permitindo que qualquer usuário treine adaptadores de forma conveniente e os compartilhe no Hub, em vez de treinar o modelo inteiro.

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

Você também pode continuar o treinamento do seu [PeftModel](https://huggingface.co/docs/peft/main/en/package_reference/peft_model#peft.PeftModel). Para isso, primeiro carregue um `PeftModel` fora do [KTOTrainer](/docs/trl/main/pt/kto_trainer#trl.KTOTrainer) e passe-o diretamente para o trainer sem passar o argumento `peft_config`.

> [!TIP]
> Ao treinar adaptadores, você geralmente usa uma taxa de aprendizado mais alta do que no ajuste fino completo, pois apenas novos parâmetros estão sendo aprendidos.

## Tool Calling com KTO

O [KTOTrainer](/docs/trl/main/pt/kto_trainer#trl.KTOTrainer) oferece suporte completo ao ajuste fino de modelos com capacidades de _tool calling_. Nesse caso, cada exemplo do conjunto de dados deve incluir:

- As mensagens da conversa (prompt e completion), incluindo qualquer chamada de ferramenta (`tool_calls`) e respostas de ferramenta (mensagens com o papel `tool`)
- A lista de ferramentas disponíveis na coluna `tools`, geralmente fornecida como esquemas JSON

Para mais detalhes sobre a estrutura esperada do conjunto de dados, consulte a seção [Formato do Conjunto de Dados — Chamada de Ferramenta](dataset_formats#tool-calling).

## Treinando Modelos de Visão e Linguagem

[KTOTrainer](/docs/trl/main/pt/kto_trainer#trl.KTOTrainer) oferece suporte completo ao treinamento de Vision-Language Models (VLMs). Para treinar um VLM, forneça um conjunto de dados com uma coluna `image` (uma única imagem por amostra) ou uma coluna `images` (lista de imagens por amostra). Para mais informações sobre a estrutura esperada do conjunto de dados, consulte a seção [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]
> Para VLMs, a truncagem pode remover tokens de imagem, levando a erros durante o treinamento. Para evitar isso, defina `max_length=None` no [KTOConfig](/docs/trl/main/pt/kto_trainer#trl.KTOConfig). Isso permite que o modelo processe o comprimento total da sequência sem truncar tokens de imagem.
>
> ```python
> KTOConfig(max_length=None, ...)
> ```
>
> Use `max_length` apenas quando você tiver verificado que a truncagem não removerá os tokens de imagem para todo o conjunto de dados.

## Script de exemplo

Fornecemos um script de exemplo para treinar um modelo usando o método KTO. O script está disponível em [`trl/scripts/kto.py`](https://github.com/huggingface/trl/blob/main/trl/scripts/kto.py)

Para testar o script KTO com o [modelo Qwen2 0.5B](https://huggingface.co/Qwen/Qwen2-0.5B-Instruct) no [conjunto de dados UltraFeedback](https://huggingface.co/datasets/trl-lib/kto-mix-14k), execute o seguinte comando:

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

## Dicas de uso

### Para Modelos Mixture of Experts: Habilitando a perda auxiliar

MOEs são mais eficientes quando a carga é distribuída de forma aproximadamente igual entre os especialistas. Para garantir que treinemos MOEs de maneira semelhante durante o ajuste de preferências, é benéfico adicionar a perda auxiliar do balanceador de carga à perda final.

Esta opção é ativada ao definir `output_router_logits=True` na configuração do modelo (por exemplo, [MixtralConfig](https://huggingface.co/docs/transformers/main/en/model_doc/mixtral#transformers.MixtralConfig)). Para ajustar a contribuição da perda auxiliar para a perda total, use o hiperparâmetro `router_aux_loss_coef=...` (padrão: `0.001`) na configuração do modelo.

### Recomendações de tamanho de lote

Use um tamanho de lote por etapa de pelo menos 4 e um tamanho de lote efetivo entre 16 e 128. Mesmo que o seu tamanho de lote efetivo seja grande, se o seu tamanho de lote por etapa for inadequado, a estimativa de KL no KTO será inadequada.

### Recomendações de taxa de aprendizado

Cada escolha de `beta` tem uma taxa de aprendizado máxima que pode tolerar antes que o desempenho do aprendizado se degrade. Para a configuração padrão de `beta = 0.1`, a taxa de aprendizado normalmente não deve exceder `1e-6` para a maioria dos modelos. À medida que `beta` diminui, a taxa de aprendizado também deve ser reduzida de forma correspondente. Em geral, recomendamos fortemente manter a taxa de aprendizado entre `5e-7` e `5e-6`. Mesmo com conjuntos de dados pequenos, desaconselhamos o uso de uma taxa de aprendizado fora dessa faixa. Em vez disso, opte por mais épocas para obter melhores resultados.

### Dados desbalanceados

O `desirable_weight` e o `undesirable_weight` do [KTOConfig](/docs/trl/main/pt/kto_trainer#trl.KTOConfig) referem-se aos pesos aplicados às perdas para exemplos desejáveis/positivos e indesejáveis/negativos. Por padrão, ambos são 1. No entanto, se você tiver mais de um ou do outro, deve aumentar o peso do tipo menos comum de modo que a razão entre (`desirable_weight`  \\(\times\\) número de positivos) e (`undesirable_weight`  \\(\times\\) número de negativos) esteja na faixa de 1:1 a 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)
```

[Fonte](https://github.com/huggingface/trl/blob/main/trl/trainer/kto_trainer.py#L462)

**Parâmetros:**

model (`str` ou [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) ou [PeftModel](https://huggingface.co/docs/peft/main/en/package_reference/peft_model#peft.PeftModel)) : Modelo a ser treinado. Pode ser:  - Uma string, sendo o *model id* de um modelo pré-treinado hospedado em um repositório de modelos no huggingface.co, ou um caminho para um *directory* contendo pesos de modelo salvos usando [save_pretrained](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.save_pretrained), por exemplo, `'./my_model_directory/'`. O modelo é carregado usando `<ModelArchitecture>.from_pretrained` (onde `<ModelArchitecture>` é derivado da configuração do modelo) com os argumentos de palavra-chave em `args.model_init_kwargs`. Se `dtype` não for especificado em `args.model_init_kwargs`, o padrão é `float32`. Isso difere de [from_pretrained](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.from_pretrained), onde (desde a v5 do Transformers) o dtype é inferido a partir da configuração do modelo. - Um objeto [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel). Apenas modelos de linguagem causal são suportados. - Um objeto [PeftModel](https://huggingface.co/docs/peft/main/en/package_reference/peft_model#peft.PeftModel). Apenas modelos de linguagem causal são suportados.

ref_model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel), *opcional*) : Modelo de referência usado para calcular as probabilidades log de referência. - Se fornecido, este modelo é usado diretamente como a política de referência. Ele não pode ser um [PeftModel](https://huggingface.co/docs/peft/main/en/package_reference/peft_model#peft.PeftModel). - Se `None`, o treinador usará automaticamente a política inicial correspondente a `model`, ou seja, o estado do modelo antes do início do treinamento KTO.

args ([KTOConfig](/docs/trl/main/pt/kto_trainer#trl.KTOConfig), *opcional*) : Configuração para este treinador. Se `None`, uma configuração padrão é usada.

data_collator (`DataCollator`, *opcional*) : Função a ser usada para formar um lote a partir de uma lista de elementos do `train_dataset` ou `eval_dataset` processado. O padrão será `DataCollatorForUnpairedPreference` se o modelo for um modelo de linguagem e `DataCollatorForVisionUnpairedPreference` se o modelo for um modelo de visão-linguagem. Collators personalizados devem truncar sequências antes do padding; o trainer não aplica truncamento pós-colagem.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset) ou [IterableDataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.IterableDataset)) : Conjunto de dados a ser usado para o treinamento. Este trainer suporta o tipo [preferência não pareada](#unpaired-preference). O formato das amostras pode ser:  - [Padrão](dataset_formats#standard): Cada amostra contém texto simples. - [Conversacional](dataset_formats#conversational): Cada amostra contém mensagens estruturadas (por exemplo, papel e conteúdo).  Quando `train_dataset` é um [IterableDataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.IterableDataset) (por exemplo, um conjunto de dados em streaming), `max_steps` deve ser definido nos argumentos de treinamento, pois seu comprimento não pode ser inferido e o número total de etapas de treinamento é necessário para limitar o loop de treinamento e configurar o agendador de taxa de aprendizado.

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) ou `dict[str, Dataset | IterableDataset]`) : Dataset a ser usado para avaliação. Ele deve atender aos mesmos requisitos de `train_dataset`.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/main/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) ou [ProcessorMixin](https://huggingface.co/docs/transformers/main/en/main_classes/processors#transformers.ProcessorMixin), *opcional*) : Classe de processamento usada para processar os dados. O lado do padding deve ser definido como "left". Se `None`, a classe de processamento é carregada a partir do nome do modelo com [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoProcessor.from_pretrained). Um token de padding, `tokenizer.pad_token`, deve ser definido. Se a classe de processamento não tiver definido um token de padding, `tokenizer.eos_token` será usado como padrão.

compute_metrics (`Callable[[EvalPrediction], dict]`, *opcional*) : A função que será usada para calcular métricas na avaliação. Deve receber um [EvalPrediction](https://huggingface.co/docs/transformers/main/en/internal/trainer_utils#transformers.EvalPrediction) e retornar um dicionário de strings para valores de métricas. Ao passar [SFTConfig](/docs/trl/main/pt/sft_trainer#trl.SFTConfig) com `batch_eval_metrics` definido como `True`, sua função `compute_metrics` deve receber um argumento booleano `compute_result`. Isso será acionado após o último lote de avaliação para sinalizar que a função precisa calcular e retornar as estatísticas de resumo globais, em vez de acumular as estatísticas de nível de lote. Os logits que ela recebe são recalculados com uma passagem de frente extra. Isso está obsoleto e será removido na v2.0.0.

callbacks (lista de [TrainerCallback](https://huggingface.co/docs/transformers/main/en/main_classes/callback#transformers.TrainerCallback), *opcional*) : Lista de callbacks para personalizar o loop de treinamento. Adicionará esses à lista de callbacks padrão detalhada [aqui](https://huggingface.co/docs/transformers/main_classes/callback). Se você quiser remover um dos callbacks padrão usados, use o método [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]`, *opcional*, padrão `(None, None)`) : Uma tupla contendo o otimizador e o agendador a serem usados. Por padrão, será uma instância de `AdamW` no seu modelo e um agendador dado por [get_linear_schedule_with_warmup](https://huggingface.co/docs/transformers/main/en/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) controlado por `args`.

quantization_config ([BitsAndBytesConfig](https://huggingface.co/docs/transformers/main/en/main_classes/quantization#transformers.BitsAndBytesConfig), *opcional*) : Configuração de quantização usada ao carregar o modelo a partir de um identificador de modelo. Combine com `peft_config` para treinamento QLoRA. Ignorado se o modelo já estiver instanciado.

peft_config ([PeftConfig](https://huggingface.co/docs/peft/main/en/package_reference/config#peft.PeftConfig), *opcional*) : configuração PEFT usada para envolver o modelo. Se `None`, o modelo não é envolvido.

Trainer para o método de Otimização Kahneman-Tversky (KTO). Este algoritmo foi inicialmente proposto no artigo [KTO: Model Alignment as Prospect Theoretic Optimization](https://huggingface.co/papers/2402.01306). Esta classe é um wrapper em torno da classe [Trainer](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.Trainer) e herda todos os seus atributos e métodos.

Exemplo:

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

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

[Fonte](https://github.com/huggingface/trl/blob/main/transformers/trainer.py#L1450)

**Parâmetros:**

resume_from_checkpoint (`str` ou `bool`, *opcional*) : Se for um `str`, caminho local para um checkpoint salvo por uma instância anterior de `Trainer`. Se for um `bool` e for igual a `True`, carrega o último checkpoint em *args.output_dir* salvo por uma instância anterior de `Trainer`. Se presente, o treinamento será retomado a partir dos estados do modelo/otimizador/agendador carregados aqui.

trial (`optuna.Trial` ou `dict[str, Any]`, *opcional*) : A execução do trial ou o dicionário de hiperparâmetros para a busca de hiperparâmetros.

ignore_keys_for_eval (`list[str]`, *opcional*) : Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao reunir as previsões para avaliação durante o treinamento.

**Retorna:** `~trainer_utils.TrainOutput`

Objeto contendo a contagem de etapas globais, a perda de treinamento e as métricas.

Ponto de entrada principal do treinamento.

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

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

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

Salvará o modelo, para que você possa recarregá-lo usando `from_pretrained()`.

Salvará apenas a partir do processo 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)
```

[Fonte](https://github.com/huggingface/trl/blob/main/transformers/trainer.py#L4337)

**Parâmetros:**

commit_message (`str`, *opcional*, padrão `"End of training"`) : Mensagem a ser commitada durante o push.

blocking (`bool`, *opcional*, padrão `True`) : Se a função deve retornar apenas quando o `git push` tiver terminado.

token (`str`, *opcional*, padrão `None`) : Token com permissão de escrita para sobrescrever os argumentos originais do Trainer.

revision (`str`, *opcional*) : A revisão do git a partir da qual o commit será feito. O padrão é o topo da branch "main".

private (`bool`, *opcional*) : Se deve tornar o repositório privado quando ele for criado. O padrão é `args.hub_private_repo`. Não tem efeito se o repositório já existir.

kwargs (`dict[str, Any]`, *opcional*) : Argumentos de palavra-chave adicionais passados para `~Trainer.create_model_card`.

**Retorna:**

A URL do repositório para onde o modelo foi enviado se `blocking=False`, ou um objeto `Future` que acompanha o progresso do commit se `blocking=True`.

Envie `self.model` e `self.processing_class` para o hub de modelos do 🤗 no repositório `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)
```

[Fonte](https://github.com/huggingface/trl/blob/main/trl/trainer/kto_config.py#L22)

**Parâmetros que controlam o modelo:**

model_init_kwargs (`dict[str, Any]`, *opcional*) : Argumentos de palavra-chave para [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained), usados quando o argumento `model` do [KTOTrainer](/docs/trl/main/pt/kto_trainer#trl.KTOTrainer) é fornecido como uma string. O valor de `revision` também é usado ao carregar a classe de processamento.

trust_remote_code (`bool`, *opcional*, padrão `False`) : Se permite carregar modelos e tokenizers que incluem código Python personalizado do Hub. Encaminhado para [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) e [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoProcessor.from_pretrained).

router_aux_loss_coef (`float`, *opcional*) : Coeficiente da perda auxiliar de balanceamento de carga para modelos Mixture-of-Experts (MoE), adicionada à perda de treinamento com esse peso. Quando não definido, o valor declarado na configuração do modelo é utilizado. Defina como `0.0` para desativá-la. Falha quando usado com um modelo que não é MoE.

disable_dropout (`bool`, *opcional*, padrão `True`) : Se deve desabilitar o dropout no modelo e no modelo de referência.

**Parâmetros que controlam o pré-processamento de dados:**

dataset_num_proc (`int`, *opcional*) : Número de processos a serem usados para processar o conjunto de dados.

max_length (`int` ou `None`, *opcional*, padrão `1024`) : Comprimento máximo da sequência tokenizada. Sequências maiores que `max_length` são truncadas pela direita. Se `None`, nenhum truncamento é aplicado.

pad_to_multiple_of (`int` ou `str`, *opcional*, padrão `"auto"`) : Se definido, as sequências serão preenchidas até um múltiplo deste valor. `"auto"` preenche até um múltiplo de 128 no Neuron (AWS Trainium), que compila uma vez por forma de entrada, e não preenche em outros ambientes.

precompute_ref_log_probs (`bool`, *opcional*, padrão `False`) : Se deve pré-computar as probabilidades log do modelo de referência para todo o conjunto de dados de treinamento antes do treinamento. Isso permite economizar memória durante o treinamento, pois o modelo de referência não precisa ser mantido em memória.

precompute_ref_batch_size (`int`, *opcional*) : Tamanho do lote a ser usado ao pré-computar as probabilidades de log do modelo de referência. Isso pode ser definido com um valor maior que o tamanho do lote de treinamento para acelerar o pré-processamento. Se `None`, o padrão é `per_device_train_batch_size` para treinamento e `per_device_eval_batch_size` para avaliação.

**Parâmetros que controlam o treinamento:**

loss_type (`str`, *opcional*, padrão `"kto"`) : Tipo de perda a ser usado. Os valores possíveis são:  - `"kto"`: Perda KTO do paper [KTO](https://huggingface.co/papers/2402.01306). - `"apo_zero_unpaired"`: Variante não pareada da perda APO-zero do paper [APO](https://huggingface.co/papers/2408.06266).

beta (`float`, *opcional*, padrão `0.1`) : Parâmetro que controla o desvio em relação ao modelo de referência. Um β maior significa menos desvio em relação ao modelo de referência.

desirable_weight (`float`, *opcional*, padrão `1.0`) : As perdas desejáveis são ponderadas por este fator para compensar o número desigual de pares desejáveis e indesejáveis.

undesirable_weight (`float`, *opcional*, padrão `1.0`) : As perdas indesejáveis são ponderadas por este fator para compensar o número desigual de pares desejáveis e indesejáveis.

activation_offloading (`bool`, *opcional*, padrão `False`) : Se as ativações devem ser transferidas para a CPU.

sync_ref_model (`bool`, *opcional*, padrão `False`) : Se deve sincronizar o modelo de referência com o modelo ativo a cada `ref_model_sync_steps` passos, usando o parâmetro `ref_model_mixup_alpha`. Essa sincronização origina-se do paper [TR-DPO](https://huggingface.co/papers/2404.09656). `sync_ref_model=True` ainda não é compatível com PEFT ou `precompute_ref_log_probs=True`.

ref_model_mixup_alpha (`float`, *opcional*, padrão `0.6`) : parâmetro α do paper TR-DPO, que controla a mistura entre a política atual e a política de referência anterior durante as atualizações. A política de referência é atualizada de acordo com a equação: `π_ref = α * π_θ + (1 - α) * π_ref_prev`. Para usar este parâmetro, você deve definir `sync_ref_model=True`.

ref_model_sync_steps (`int`, *opcional*, padrão `512`) : parâmetro τ do paper [TR-DPO](https://huggingface.co/papers/2404.09656), que determina com que frequência a política atual é sincronizada com a política de referência. Para usar este parâmetro, você deve definir `sync_ref_model=True`.

Classe de configuração para o [KTOTrainer](/docs/trl/main/pt/kto_trainer#trl.KTOTrainer).

Esta classe inclui apenas os parâmetros específicos para o treinamento KTO. Para a lista completa de argumentos de treinamento, consulte a documentação de [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments). Observe que os valores padrão nesta classe podem diferir dos presentes em [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments).

Usando [HfArgumentParser](https://huggingface.co/docs/transformers/main/en/internal/trainer_utils#transformers.HfArgumentParser), podemos transformar essa classe em argumentos [argparse](https://docs.python.org/3/library/argparse#module-argparse) que podem ser especificados na linha de comando.

> [!NOTE]
> Esses parâmetros possuem valores padrão diferentes de [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments): - `logging_steps`: Padrão é `10` em vez de `500`. - `gradient_checkpointing`: Padrão é `True` em vez de `False`. - `bf16`: Padrão é `True` se `fp16` não estiver definido, em vez de `False`. - `learning_rate`: Padrão é `1e-6` em vez de `5e-5`. - `train_sampling_strategy`: Padrão é `"sequential"` em vez de `"random"`. Os tipos de perda que estimam o termo de divergência KL (todos, exceto `"apo_zero_unpaired"`) exigem amostragem sequencial, pois a conclusão KL para cada exemplo é pré-computada em relação aos seus vizinhos em um lote de ordem fixa; qualquer outra estratégia quebra esse pareamento.