# Treinador de Destilação de Conhecimento Generalizada

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

## Visão geral

O Generalized Knowledge Distillation (GKD) foi proposto em [On-Policy Distillation of Language Models: Learning from Self-Generated Mistakes](https://huggingface.co/papers/2306.13649) por Rishabh Agarwal, Nino Vieillard, Yongchao Zhou, Piotr Stanczyk, Sabela Ramos, Matthieu Geist e Olivier Bachem.

O resumo do artigo é o seguinte:

> A destilação de conhecimento (KD) é amplamente utilizada para comprimir um modelo professor, reduzindo seu custo de inferência e sua pegada de memória, por meio do treinamento de um modelo aluno menor. No entanto, os métodos atuais de KD para modelos de sequência auto-regressivos sofrem com o desalinhamento de distribuição entre as sequências de saída vistas durante o treinamento e aquelas geradas pelo aluno durante a inferência. Para abordar essa questão, introduzimos a Destilação de Conhecimento Generalizada (GKD). Em vez de depender exclusivamente de um conjunto fixo de sequências de saída, o GKD treina o aluno em suas próprias sequências de saída auto-geradas, aproveitando o feedback do professor sobre tais sequências. Diferente das abordagens de KD supervisionadas, o GKD também oferece a flexibilidade de empregar funções de perda alternativas entre o aluno e o professor, o que pode ser útil quando o aluno carece da expressividade para imitar a distribuição do professor. Além disso, o GKD facilita a integração sem emendas da destilação com o ajuste fino por RL (RLHF). Demonstramos a eficácia do GKD para destilar modelos de linguagem auto-regressivos em tarefas de sumarização, tradução e raciocínio aritmético, bem como para destilação agnóstica à tarefa para ajuste fino por instruções.

Os principais aspectos do GKD são:

1. Ele aborda a incompatibilidade de distribuição entre treinamento e inferência em modelos de sequência auto-regressivos, treinando o modelo aluno em suas próprias sequências de saída geradas.
2. O GKD permite flexibilidade na escolha de diferentes medidas de divergência entre os modelos de aluno e professor por meio da Divergência Generalizada de Jensen-Shannon (JSD), o que pode ser útil quando o aluno não tem capacidade suficiente para imitar completamente o professor.

Este método de pós-treinamento foi contribuído por [Kashif Rasul](https://huggingface.co/kashif) e [Lewis Tunstall](https://huggingface.co/lewtun).

## Dicas de uso

O [experimental.gkd.GKDTrainer](/docs/trl/v1.18.1/pt/gkd_trainer#trl.experimental.gkd.GKDTrainer) é um wrapper em torno da classe [SFTTrainer](/docs/trl/v1.18.1/pt/sft_trainer#trl.SFTTrainer) que recebe um argumento de modelo professor. Ele precisa que três parâmetros sejam definidos via [experimental.gkd.GKDConfig](/docs/trl/v1.18.1/pt/gkd_trainer#trl.experimental.gkd.GKDConfig), a saber:

* `lmbda`: controla a fração de dados do aluno, ou seja, a proporção de saídas geradas pelo aluno em política. Quando `lmbda=0.0`, a perda se reduz a JSD supervisionada, onde o aluno é treinado com as probabilidades de nível de token do professor. Quando `lmbda=1.0`, a perda se reduz a JSD em política, onde o aluno gera sequências de saída e recebe feedback específico de token sobre essas sequências do professor. Para valores entre [0, 1], a escolha é aleatória entre as duas, com base no valor de `lmbda` para cada lote.
* `seq_kd`: controla se a KD de nível de sequência será executada (pode ser vista como FT supervisionado em saídas geradas pelo professor). Quando `seq_kd=True` e `lmbda=0.0`, a perda se reduz a JSD supervisionado, em que o professor gera sequências de saída e o aluno recebe feedback específico por token sobre essas sequências do professor.
* `beta`: controla a interpolação na Divergência Generalizada de Jensen-Shannon. Quando `beta=0.0`, a perda aproxima a divergência KL direta, enquanto para `beta=1.0` a perda aproxima a divergência KL reversa. Para valores entre [0, 1], ela interpola entre as duas.

Os autores constatam que os dados on-policy (alto `lmbda`) apresentam melhor desempenho e que o `beta` ótimo variava conforme a tarefa e o método de avaliação.

> [!WARNING]
> Certifique-se de que `attn_implementation="kernels-community/flash-attn2"` ao treinar [modelos Gemma](https://huggingface.co/models?other=gemma2). Caso contrário, você encontrará NaNs nos logits devido à [técnica de soft capping](https://huggingface.co/blog/gemma2#soft-capping-and-attention-implementations) adotada por essa arquitetura.

A API básica é a seguinte:

```python
from datasets import Dataset
from transformers import AutoModelForCausalLM, AutoTokenizer
from trl.experimental.gkd import GKDConfig, GKDTrainer

NUM_DUMMY_SAMPLES = 100

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2-0.5B-Instruct")
# The model to optimise
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-0.5B-Instruct")
# The teacher model to calculate the KL divergence against
teacher_model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-1.5B-Instruct")

train_dataset = Dataset.from_dict(
    {
        "messages": [
            [
                {"role": "user", "content": "Hi, how are you?"},
                {"role": "assistant", "content": "I'm great thanks"},
            ]
        ]
        * NUM_DUMMY_SAMPLES
    }
)
eval_dataset = Dataset.from_dict(
    {
        "messages": [
            [
                {"role": "user", "content": "What colour is the sky?"},
                {"role": "assistant", "content": "The sky is blue"},
            ]
        ]
        * NUM_DUMMY_SAMPLES
    }
)

training_args = GKDConfig(output_dir="gkd-model", per_device_train_batch_size=1)
trainer = GKDTrainer(
    model=model,
    teacher_model=teacher_model,
    args=training_args,
    processing_class=tokenizer,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
)
trainer.train()
```

### Tipo de dataset esperado

O conjunto de dados deve ser formatado como uma lista de "messages", em que cada mensagem é uma lista de dicionários com as seguintes chaves:

* `role`: ou `system`, `assistant` ou `user`
* `content`: o conteúdo da mensagem

## GKDTrainer[[trl.experimental.gkd.GKDTrainer]]

#### trl.experimental.gkd.GKDTrainer[[trl.experimental.gkd.GKDTrainer]]

```python
trl.experimental.gkd.GKDTrainer(model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, str, NoneType] = None, teacher_model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, str] = None, args: trl.experimental.gkd.gkd_config.GKDConfig | None = None, data_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = None, train_dataset: datasets.arrow_dataset.Dataset | None = None, eval_dataset: datasets.arrow_dataset.Dataset | dict[str, datasets.arrow_dataset.Dataset] | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.image_processing_utils.BaseImageProcessor | transformers.feature_extraction_utils.FeatureExtractionMixin | transformers.processing_utils.ProcessorMixin | None = None, compute_metrics: collections.abc.Callable[[transformers.trainer_utils.EvalPrediction], dict] | None = None, callbacks: list[transformers.trainer_callback.TrainerCallback] | None = None, optimizers: tuple[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR] = (None, None), preprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = None, peft_config: PeftConfig | None = None, formatting_func: collections.abc.Callable | None = None)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.1/trl/experimental/gkd/gkd_trainer.py#L54)

**Parâmetros:**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) ou `torch.nn.Module` ou `str`, *opcional*) : Modelo a ser treinado, ou o identificador de string do modelo a ser instanciado a partir de um modelo pré-treinado.

teacher_model ([PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) ou `torch.nn.Module` ou `str`, *opcional*) : Modelo de professor para destilação de conhecimento, ou o identificador de string do modelo a ser instanciado a partir de um modelo pré-treinado.

args ([experimental.gkd.GKDConfig](/docs/trl/v1.18.1/pt/gkd_trainer#trl.experimental.gkd.GKDConfig), *opcional*) : Argumentos de treinamento.

data_collator (`DataCollator`, *opcional*) : Data collator para agrupar amostras do dataset. O padrão é um `experimental.utils.DataCollatorForChatML` que usa o `processing_class`.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset), *opcional*) : Dataset para treinamento.

eval_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) ou `dict` de [Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset), *opcional*) : Dataset para avaliação.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase), [BaseImageProcessor](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/image_processor#transformers.BaseImageProcessor), [FeatureExtractionMixin](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/feature_extractor#transformers.FeatureExtractionMixin) ou [ProcessorMixin](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/processors#transformers.ProcessorMixin), *opcional*) : Classe para processar os dados.

compute_metrics (`Callable`, *opcional*) : Função para calcular métricas na avaliação. Deve receber um [EvalPrediction](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.EvalPrediction) e retornar um dicionário de string para float.

callbacks (`list` de [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback), *opcional*) : Callbacks a serem usados durante o treinamento.

optimizers (`tuple` de `torch.optim.Optimizer` e `torch.optim.lr_scheduler.LambdaLR`, *opcional*, padrão `(None, None)`) : Tupla contendo o otimizador e o agendador de taxa de aprendizado a serem usados para o treinamento.

preprocess_logits_for_metrics (`Callable`, *opcional*) : Função para pré-processar os logits antes de calcular as métricas. Deve receber os `logits` e os `labels` e retornar os logits a serem usados para o cálculo das métricas.

peft_config (`PeftConfig`, *opcional*) : configuração do PEFT para usar PEFT no treinamento. Se `None`, o PEFT não é usado. Se fornecida, o `model` será envolvido com o adaptador PEFT especificado.

formatting_func (`Callable`, *opcional*) : Função para formatar o conjunto de dados. Deve receber um exemplo e retornar um exemplo.

Trainer para Generalized Knowledge Distillation (GKD) de modelos de linguagem.

Para mais detalhes sobre o GKD, consulte o artigo: [On-Policy Distillation of Language Models: Learning from Self-Generated Mistakes](https://huggingface.co/papers/2306.13649).

#### treinar[[trl.experimental.gkd.GKDTrainer.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/v1.18.1/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.experimental.gkd.GKDTrainer.save_model]]

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

[Fonte](https://github.com/huggingface/trl/blob/v1.18.1/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.experimental.gkd.GKDTrainer.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/v1.18.1/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`.

## GKDConfig[[trl.experimental.gkd.GKDConfig]]

#### trl.experimental.gkd.GKDConfig[[trl.experimental.gkd.GKDConfig]]

```python
trl.experimental.gkd.GKDConfig(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 = 2e-05, lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool | None = None, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool | None = None, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 10, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = False, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: accelerate.parallelism_config.ParallelismConfig | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool = True, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1, model_init_kwargs: dict[str, typing.Any] | str | None = None, trust_remote_code: bool = False, router_aux_loss_coef: float | None = None, chat_template_path: str | None = None, dataset_text_field: str = 'text', dataset_kwargs: dict[str, typing.Any] | str | None = None, dataset_num_proc: int | None = None, eos_token: str | None = None, max_length: int | None = 1024, truncation_mode: str = 'keep_start', shuffle_dataset: bool = False, packing: bool = False, packing_strategy: str = 'bfd', padding_free: bool = False, pad_to_multiple_of: int | str | None = 'auto', eval_packing: bool | None = None, completion_only_loss: bool | None = None, assistant_only_loss: bool = False, loss_type: str = 'nll', activation_offloading: bool = False, pad_token: str | None = None, temperature: float = 0.9, lmbda: float = 0.5, beta: float = 0.5, max_new_tokens: int = 128, teacher_model_name_or_path: str | None = None, teacher_model_init_kwargs: dict[str, typing.Any] | str | None = None, disable_dropout: bool = True, seq_kd: bool = False)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.1/trl/experimental/gkd/gkd_config.py#L22)

**Parâmetros:**

temperature (`float`, *opcional*, padrão `0.9`) : Temperatura para amostragem. Quanto maior a temperatura, mais aleatórias são as conclusões.

lmbda (`float`, *opcional*, padrão `0.5`) : Parâmetro lambda que controla a fração de dados do aluno (ou seja, a proporção de saídas geradas pelo aluno em política).

beta (`float`, *opcional*, padrão `0.5`) : Coeficiente de interpolação entre `0.0` e `1.0` da perda de Divergência Generalizada de Jensen-Shannon. Quando beta é `0.0`, a perda é a divergência KL. Quando beta é `1.0`, a perda é a Divergência KL Inversa.

max_new_tokens (`int`, *opcional*, padrão `128`) : Número máximo de tokens a serem gerados por conclusão.

teacher_model_name_or_path (`str`, *opcional*) : Nome ou caminho do modelo teacher. Se `None`, o modelo teacher será o mesmo que o modelo em treinamento.

teacher_model_init_kwargs (`dict[str, Any]`, *opcional*) : Argumentos de palavra-chave para passar a `AutoModelForCausalLM.from_pretrained` ao instanciar o modelo teacher a partir de uma string.

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

seq_kd (`bool`, *opcional*, padrão `False`) : Parâmetro Seq_kd que controla se a KD de Nível de Sequência deve ser executada (pode ser vista como FT supervisionado na saída gerada pelo professor).

Classe de configuração para [experimental.gkd.GKDTrainer](/docs/trl/v1.18.1/pt/gkd_trainer#trl.experimental.gkd.GKDTrainer).

Esta classe inclui apenas os parâmetros específicos para o treinamento GKD. Para a lista completa de argumentos de treinamento, consulte a documentação de [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments) e [SFTConfig](/docs/trl/v1.18.1/pt/sft_trainer#trl.SFTConfig).

