# Distillation Trainer

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

## Resumen

El Distillation Trainer implementa la destilación de conocimiento on-policy tal como se describe en [On-Policy Distillation of Language Models: Learning from Self-Generated Mistakes](https://huggingface.co/papers/2306.13649) de [Rishabh Agarwal](https://huggingface.co/agarwl), Nino Vieillard, Yongchao Zhou, [Piotr Stanczyk](https://huggingface.co/PiotrStanczyk), Sabela Ramos, [Matthieu Geist](https://huggingface.co/matthieu-geist) y [Olivier Bachem](https://huggingface.co/bachem).

El resumen del artículo es el siguiente:

> La destilación de conocimiento (KD) se utiliza ampliamente para comprimir un modelo maestro y reducir su costo de inferencia y su huella de memoria, mediante el entrenamiento de un modelo estudiante más pequeño. Sin embargo, los métodos actuales de KD para modelos de secuencia auto-regresivos sufren de un desajuste de distribución entre las secuencias de salida vistas durante el entrenamiento y las generadas por el estudiante durante la inferencia. Para abordar este problema, introducimos la Destilación de Conocimiento Generalizada (GKD). En lugar de depender únicamente de un conjunto fijo de secuencias de salida, GKD entrena al estudiante en sus propias secuencias de salida auto-generadas, aprovechando la retroalimentación del maestro sobre dichas secuencias. A diferencia de los enfoques de KD supervisados, GKD también ofrece la flexibilidad de emplear funciones de pérdida alternativas entre el estudiante y el maestro, lo cual puede ser útil cuando el estudiante carece de la expresividad necesaria para imitar la distribución del maestro.

El `DistillationTrainer` entrena un modelo estudiante más pequeño para que coincida con la distribución de tokens siguientes de un modelo maestro sobre las propias generaciones on-policy del estudiante. Genera las completas del estudiante on-policy (opcionalmente con vLLM) y ajusta el maestro sobre su distribución completa de tokens siguientes mediante una pérdida de divergencia de Jensen-Shannon por bloques eficiente en memoria, de modo que la distribución densa del maestro nunca se materializa por completo.

Este entrenador fue aportado por [Carlos Miguel Patiño](https://huggingface.co/cmpatino).

Para una contraparte asíncrona que desacopla la generación del entrenamiento y puntúa contra un maestro servido a través de HTTP en lugar de una pasada hacia adelante local, consulte [`AsyncDistillationTrainer`](async_distillation_trainer).

## Inicio rápido

Este ejemplo demuestra cómo entrenar un modelo utilizando el método de destilación. Destilamos un [modelo Qwen 2.5 0.5B Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct) a partir de un [modelo maestro Qwen 2.5 1.5B Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct) con los prompts del [conjunto de datos de prompts UltraFeedback](https://huggingface.co/datasets/trl-lib/ultrafeedback-prompt). Puede ver los datos del conjunto de datos aquí:

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

A continuación se muestra el script para entrenar el modelo.

```python
# train_distillation.py
from datasets import load_dataset
from trl import DistillationTrainer

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

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

Ejecute el script usando el siguiente comando:

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

## Mirando más a fondo el método de destilación

La destilación de conocimiento on-policy entrena a un estudiante para reproducir la distribución de tokens siguientes de un profesor en las finalizaciones que el propio estudiante genera, en lugar de hacerlo sobre un conjunto fijo de salidas del profesor. Aprender de sus propias generaciones permite al estudiante corregir sus propios errores, lo que generalmente supera al rendimiento de la destilación off-policy. Esta sección detalla cómo funciona en la práctica, cubriendo los dos pasos clave: **generar finalizaciones** y **calcular la pérdida**.

### Generar completiones

En cada paso de entrenamiento, el estudiante genera un lote de finalizaciones para los prompts muestreados.

### Cálculo de la pérdida

La pérdida es la **divergencia de Jensen-Shannon generalizada (JSD)** entre la distribución del estudiante  \\( p_S \\)  y la distribución del maestro  \\( p_T \\)  sobre los tokens de la generación completada, interpolada por `beta` y definida como:

$$ \mathcal{L}_\beta = \beta \, \mathbb{D}_{\mathrm{KL}}\!\left[ p_T \| p_M \right] + (1 - \beta) \, \mathbb{D}_{\mathrm{KL}}\!\left[ p_S \| p_M \right], \qquad p_M = (1 - \beta) \, p_S + \beta \, p_T, $$

donde  \\( p_M \\)  es la mezcla  \\( \beta \\)  de las dos distribuciones. Los extremos se reducen a las divergencias puras:  `beta=0.0`  da la KL hacia adelante  \\( \mathbb{D}_{\mathrm{KL}}\!\left[ p_T \| p_S \right] \\)  y  `beta=1.0`  la KL hacia atrás  \\( \mathbb{D}_{\mathrm{KL}}\!\left[ p_S \| p_T \right] \\).

En la práctica, la proyección a logits de vocabulario y la divergencia se calculan en bloques, por lo que la memoria de activación máxima no escala con el tensor completo de logits de vocabulario × longitud de secuencia. Consulte [Reducing Memory Usage](reducing_memory_usage).

### Tipo de conjunto de datos esperado

El conjunto de datos debe estar formateado como un conjunto de datos [conversacional](dataset_formats#conversational) [solo con el prompt](dataset_formats#prompt-only). El estudiante genera sus propias completaciones on-policy, por lo que solo se necesita el prompt:

```python
{"prompt": [{"role": "user", "content": "What color is the sky?"}]}
```

## Métricas registradas

Durante el entrenamiento y la evaluación, registramos las siguientes métricas:

- `num_tokens`: El número total de tokens procesados hasta el momento, incluyendo tanto los prompts como las completions. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
- `step_time`: Tiempo promedio (en segundos) por paso de entrenamiento (incluida la generación).
- `completions/mean_length`: La longitud media de las completaciones generadas. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
- `completions/min_length`: La longitud mínima de las completaciones generadas. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
- `completions/max_length`: La longitud máxima de las completaciones generadas. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
- `completions/mean_terminated_length`: La longitud media de las completaciones generadas que terminan con EOS. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
- `completions/min_terminated_length`: La longitud mínima de las completaciones generadas que terminan con EOS. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
- `completions/max_terminated_length`: La longitud máxima de las completaciones generadas que terminan con EOS. Al usar herramientas, solo se cuentan los tokens que no son de herramientas.
- `completions/clipped_ratio`: La proporción de completados truncados (recortados).
- `tools/call_frequency`: El número medio de llamadas a herramientas por finalización en el lote de generación. Se registra solo cuando se proporcionan `tools`.
- `tools/failure_frequency`: La proporción de llamadas a herramientas que fallaron (la herramienta no se encontró, lanzó una excepción o el tipo de llamada no es compatible). Es `0.0` cuando no se llamó a ninguna herramienta. Se registra solo cuando se proporcionan `tools`.
- `entropy`: Entropía media de las predicciones de tokens en las completaciones generadas (en nats).

## Personalización

### Acelera el entrenamiento con generación impulsada por vLLM

La generación suele ser el principal cuello de botella al entrenar con métodos on-policy. Para acelerar la generación, puedes usar [vLLM](https://github.com/vllm-project/vllm), un motor de inferencia de alto rendimiento y baja latencia para LLMs. Para habilitarlo, primero instala el paquete con

```shell
pip install trl[vllm]
```

Admitimos dos formas de usar vLLM durante el entrenamiento: **modo colocate** y **modo servidor**.

#### Opción 1: Modo Colocate

En este modo, vLLM se ejecuta dentro del proceso del entrenador y comparte la memoria de GPU con el modelo de entrenamiento. Esto evita iniciar un servidor separado y puede mejorar la utilización de la GPU, pero puede provocar una contención de memoria en las GPUs de entrenamiento. Este es el modo predeterminado.

```python
from trl import DistillationConfig

training_args = DistillationConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)
```

#### Opción 2: Modo servidor

En este modo, vLLM se ejecuta en un proceso separado (y usando GPUs separadas) y se comunica con el entrenador a través de HTTP. Esto es ideal si tienes GPUs dedicadas para inferencia.

1. **Iniciar el servidor de vLLM**:

   ```bash
   VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
       --weight-transfer-config '{"backend": "nccl"}' \
       --logprobs-mode processed_logprobs \
       --max-logprobs -1
   ```

2. **Habilita el modo de servidor en tu script de entrenamiento**:

   ```python
   from trl import DistillationConfig

   training_args = DistillationConfig(
       ...,
       use_vllm=True,
       vllm_mode="server",
   )
   ```

> [!WARNING]
> Asegúrate de que el servidor utilice GPUs diferentes a las del entrenador, de lo contrario es posible que aparezcan errores de NCCL. Puedes especificar las GPUs a utilizar con la variable de entorno `CUDA_VISIBLE_DEVICES`.

> [!TIP]
> En función del tamaño del modelo y de los requisitos generales de memoria de GPU para el entrenamiento, es posible que necesites ajustar el parámetro `vllm_gpu_memory_utilization` en [DistillationConfig](/docs/trl/v1.18.1/es/distillation_trainer#trl.DistillationConfig) para evitar la subutilización o errores de memoria insuficiente.

Para obtener más información, consulte [Acelerar el entrenamiento con vLLM](speeding_up_training#vllm-for-fast-generation-in-online-methods).

### Entrenar adaptadores con PEFT

Soportamos una integración estrecha con la biblioteca 🤗 PEFT, lo que te permite entrenar adaptadores y compartirlos en el Hub en lugar de entrenar todo el modelo estudiante.

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

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

trainer = DistillationTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    teacher_model="Qwen/Qwen2.5-1.5B-Instruct",
    train_dataset=dataset,
    peft_config=LoraConfig(),
)
trainer.train()
```

> [!WARNING]
> La pérdida de destilación lee `lm_head.weight` directamente y ejecuta el backbone del estudiante sin pasar por `PeftModel.forward()`. Por lo tanto, se rechazan los adaptadores en `lm_head` (vía `target_modules`) y los métodos de prompt-learning (PromptTuning, PrefixTuning, P-Tuning), ya que se ignorarían de forma silenciosa. Para entrenar la cabeza, use `modules_to_save=["lm_head"]` en su lugar.

## Entrenamiento de agentes

[DistillationTrainer](/docs/trl/v1.18.1/es/distillation_trainer#trl.DistillationTrainer) admite **entrenamiento de agentes**: el estudiante llama a herramientas durante la generación y se destila sobre la trayectoria resultante. Los tokens de resultado de herramienta se excluyen de la pérdida, por lo que el estudiante solo se entrena con los tokens que él mismo generó.

### Herramientas

El argumento `tools` espera una lista de funciones de Python que definen las herramientas disponibles para el agente:

```python
from trl import DistillationTrainer

trainer = DistillationTrainer(
    tools=[tool1, tool2],
    ...,
)
```

Cada herramienta debe ser una función de Python estándar con **argumentos y tipos de retorno con anotaciones de tipo**, junto con una **docstring en estilo Google** que describa su propósito, sus argumentos y su valor de retorno. Para más detalles, consulte la [guía para pasar herramientas](https://huggingface.co/docs/transformers/en/chat_extras#passing-tools).

> [!TIP]
> El bucle de llamadas a herramientas requiere que la plantilla de chat sea *de prefijo conservador* (añadir un mensaje de herramienta no debe cambiar cómo se renderizan los mensajes anteriores). Para las familias de modelos conocidas (p. ej., Qwen3, DeepSeek-V3), TRL cambia automáticamente a una plantilla de entrenamiento parcheada cuando se habilitan las herramientas. Consulte [Plantillas de chat](chat_templates#training-templates) para obtener la lista completa.

Use `max_tool_calling_iterations` en [DistillationConfig](/docs/trl/v1.18.1/es/distillation_trainer#trl.DistillationConfig) para limitar el número de turnos de llamada a herramientas. Por defecto no hay límite, y la generación se detiene cuando el estudiante produce un turno de respuesta sin llamadas a herramientas, cuando la finalización (todos los turnos y resultados de herramientas) alcanza `max_completion_length` tokens, o cuando la secuencia completa alcanza la longitud máxima del modelo (`vllm_max_model_length` con `vllm_mode="colocate"`, o `max_position_embeddings` del modelo en caso contrario).

Ejemplo:

```python
from trl import DistillationTrainer

def multiply(a: int, b: int) -> int:
    """
    Multiplies two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The product of the two integers.
    """
    return a * b

trainer = DistillationTrainer(
    tools=[multiply],
    ...,
)
```

> [!WARNING]
> Las herramientas asíncronas aún no se admiten: pase funciones síncronas.

### Respuestas de herramientas multimodales

Las herramientas pueden devolver imágenes junto con texto devolviendo una lista de bloques de contenido. Esto es útil para el entrenamiento de agentes VLM donde la herramienta proporciona retroalimentación visual (p. ej., capturas de pantalla, gráficos, capturas de cámara).

```python
from PIL import Image

def take_screenshot() -> list:
    """
    Takes a screenshot of the current screen.

    Returns:
        The screenshot image with a description.
    """
    img = Image.open("screenshot.png")
    return [{"type": "image", "image": img}, {"type": "text", "text": "Here is the screenshot."}]
```

Las imágenes devueltas se inyectan automáticamente en la conversación y se pasan al VLM para los turnos de generación posteriores.

## Entrenamiento de modelos de visión y lenguaje

[DistillationTrainer](/docs/trl/v1.18.1/es/distillation_trainer#trl.DistillationTrainer) permite destilar modelos de visión-lenguaje (VLM) en conjuntos de datos multimodales que contienen tanto texto como imágenes. Pasa un VLM como estudiante y como maestro, y proporciona un conjunto de datos solo con prompts que tenga una columna `image` (una imagen por muestra) o una columna `images` (lista de imágenes por muestra). Para más información sobre la estructura esperada del conjunto de datos, consulta la sección [Formato del conjunto de datos — Conjuntos de datos de visión](dataset_formats#vision-datasets).

Probado con:

- **Gemma 3** — p. ej., `google/gemma-3-4b-it`
- **LLaVA-NeXT** — p. ej., `llava-hf/llava-v1.6-mistral-7b-hf`
- **Qwen2-VL** — por ejemplo, `Qwen/Qwen2-VL-2B-Instruct`
- **Qwen2.5-VL** — por ejemplo, `Qwen/Qwen2.5-VL-3B-Instruct`

> [!TIP]
> No se garantiza la compatibilidad con todos los VLM. Si crees que un modelo debería ser compatible, no dudes en abrir un issue en GitHub o, mejor aún, enviar un pull request con los cambios necesarios.

## Interfaz de línea de comandos

Use [`trl distillation` CLI](clis) para iniciar el entrenamiento de destilación desde la línea de comandos. Admite entrenamiento completo y LoRA mediante las banderas estándar de `ModelConfig`.

```bash
# Full training:
trl distillation \
    --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
    --teacher_model_name_or_path Qwen/Qwen2.5-1.5B-Instruct \
    --dataset_name trl-lib/ultrafeedback-prompt \
    --learning_rate 2e-5 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --output_dir distilled-model \
    --num_train_epochs 1
```

```bash
# LoRA:
trl distillation \
    --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
    --teacher_model_name_or_path Qwen/Qwen2.5-1.5B-Instruct \
    --dataset_name trl-lib/ultrafeedback-prompt \
    --learning_rate 2e-4 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --output_dir distilled-model \
    --num_train_epochs 1 \
    --use_peft \
    --lora_r 64 \
    --lora_alpha 16
```

## DistillationTrainer[[trl.DistillationTrainer]]

#### trl.DistillationTrainer[[trl.DistillationTrainer]]

```python
trl.DistillationTrainer(model: str | PreTrainedModel | PeftModel, teacher_model: str | transformers.modeling_utils.PreTrainedModel | None = None, args: trl.trainer.distillation_config.DistillationConfig | 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.processing_utils.ProcessorMixin | 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, tools: list[collections.abc.Callable] | None = None)
```

[Fuente](https://github.com/huggingface/trl/blob/v1.18.1/trl/trainer/distillation_trainer.py#L220)

**Parámetros:**

model (`str` o [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) o `PeftModel`) : Modelo que se va a entrenar. Puede ser:  - Una cadena de caracteres, que es el *model id* de un modelo preentrenado alojado en un repositorio de modelos en huggingface.co, o una ruta a un *directorio* que contiene los pesos del modelo guardados usando [save_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained), por ejemplo, `'./my_model_directory/'`. El modelo se carga usando `<ModelArchitecture>.from_pretrained` (donde `<ModelArchitecture>` se deriva de la configuración del modelo) con los argumentos de palabra clave en `args.model_init_kwargs`. Si `dtype` no se especifica en `args.model_init_kwargs`, el valor predeterminado es `float32`. Esto difiere de [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.from_pretrained), donde (desde Transformers v5) el dtype se infiere de la configuración del modelo. - Un objeto [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel). Solo se admiten modelos de lenguaje causales. - Un objeto `PeftModel`. Solo se admiten modelos de lenguaje causales.

teacher_model (`str` o [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel), *opcional*) : Modelo maestro cuya distribución de tokens siguientes debe coincidir con la del estudiante. Puede ser un *id de modelo* / ruta (se carga igual que `model`, usando `args.teacher_model_init_kwargs`) o un [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) instanciado. Debe compartir el vocabulario del estudiante. Los subclases pueden omitirlo si proporcionan el maestro de otra manera (p. ej., un servidor remoto).

args ([DistillationConfig](/docs/trl/v1.18.1/es/distillation_trainer#trl.DistillationConfig), *opcional*) : Configuración para este entrenador. Si es `None`, se utiliza una configuración predeterminada.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) o [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset)) : Conjunto de datos para usar en el entrenamiento. Debe incluir una columna `"prompt"`. Cualquier columna adicional en el conjunto de datos se ignora. El formato de las muestras puede ser:  - [Estándar](dataset_formats#standard): Cada muestra contiene texto plano. - [Conversacional](dataset_formats#conversational): Cada muestra contiene mensajes estructurados (p. ej., rol y contenido).  Cuando `train_dataset` es un [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) (p. ej., un conjunto de datos en streaming), `max_steps` debe establecerse en los argumentos de entrenamiento, ya que su longitud no se puede inferir y se requiere el número total de pasos de entrenamiento para acotar el bucle de entrenamiento y configurar el programador de la tasa de aprendizaje.

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) o `dict[str, Dataset | IterableDataset]`) : Conjunto de datos para usar en la evaluación. Debe cumplir los mismos requisitos que `train_dataset`.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase), [ProcessorMixin](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/processors#transformers.ProcessorMixin), *opcional*) : Clase de procesamiento utilizada para procesar los datos. El lado de relleno debe establecerse en "left". Si es `None`, la clase de procesamiento se carga desde el nombre del modelo con [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoProcessor.from_pretrained). Debe establecerse un token de relleno, `tokenizer.pad_token`. Si la clase de procesamiento no ha establecido un token de relleno, se utilizará `tokenizer.eos_token` como valor predeterminado.

callbacks (lista de [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback), *opcional*) : Lista de callbacks para personalizar el bucle de entrenamiento. Se añadirán a la lista de callbacks predeterminados detallada [aquí](https://huggingface.co/docs/transformers/main_classes/callback). Si deseas eliminar uno de los callbacks predeterminados, utiliza el método [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]`, *opcional*, por defecto `(None, None)`) : Una tupla que contiene el optimizador y el programador a utilizar. Por defecto, se utilizará una instancia de `AdamW` en tu modelo y un programador dado por [get_linear_schedule_with_warmup](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) controlado por `args`.

quantization_config ([BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/quantization#transformers.BitsAndBytesConfig), *opcional*) : Configuración de cuantización utilizada al cargar el modelo desde un identificador de modelo. Combínala con `peft_config` para el entrenamiento QLoRA. Se ignora si el modelo ya está instanciado.

peft_config (`PeftConfig`, *opcional*) : Configuración de PEFT utilizada para envolver el modelo. Si es `None`, el modelo no se envuelve.

tools (lista de `Callable`, *opcional*) : Una lista de funciones de herramientas invocables que el modelo puede llamar durante la generación. Cada herramienta debe ser una función de Python estándar con argumentos y valores de retorno con anotaciones de tipo adecuadas, y una docstring en estilo Google que describa su propósito, argumentos y valor de retorno. Para más detalles, consulte: https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. El modelo utiliza el nombre de la función, las anotaciones de tipo y la docstring para determinar cómo llamarla. Asegúrese de que la plantilla de chat del modelo admita el uso de herramientas y de que haya sido afinada para la invocación de herramientas.

Trainer para destilación de conocimiento. El estudiante se entrena on-policy —genera él mismo las completaciones— para coincidir con la distribución de tokens siguientes del maestro bajo una divergencia de Jensen-Shannon generalizada (interpolando KL hacia adelante, KL hacia atrás y JSD mediante `beta`), tal como se introduce en [On-Policy Distillation of Language Models](https://huggingface.co/papers/2306.13649).

Ejemplo:

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

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

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

#### train[[trl.DistillationTrainer.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)
```

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

**Parámetros:**

resume_from_checkpoint (`str` o `bool`, *opcional*) : Si es un `str`, ruta local a un punto de control guardado por una instancia anterior de `Trainer`. Si es un `bool` y es igual a `True`, carga el último punto de control en *args.output_dir* guardado por una instancia anterior de `Trainer`. Si está presente, el entrenamiento se reanudará desde los estados del modelo/optimizador/planificador cargados aquí.

trial (`optuna.Trial` o `dict[str, Any]`, *opcional*) : La ejecución del ensayo o el diccionario de hiperparámetros para la búsqueda de hiperparámetros.

ignore_keys_for_eval (`list[str]`, *opcional*) : Una lista de claves en la salida de su modelo (si es un diccionario) que deben ignorarse al recopilar predicciones para la evaluación durante el entrenamiento.

**Devuelve:** `~trainer_utils.TrainOutput`

Objeto que contiene el número de pasos globales, la pérdida de entrenamiento y las métricas.

Punto de entrada principal del entrenamiento.

#### save_model[[trl.DistillationTrainer.save_model]]

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

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

Guardará el modelo, por lo que podrás recargarlo usando `from_pretrained()`.

Solo se guardará desde el proceso principal.

#### push_to_hub[[trl.DistillationTrainer.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)
```

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

**Parámetros:**

commit_message (`str`, *opcional*, por defecto `"End of training"`) : Mensaje para el commit al hacer push.

blocking (`bool`, *opcional*, valor predeterminado `True`) : Si la función debe devolver el control solo cuando el `git push` haya terminado.

token (`str`, *opcional*, valor predeterminado `None`) : Token con permiso de escritura para sobrescribir los argumentos originales de Trainer.

revision (`str`, *opcional*) : La revisión de git desde la que se realizará el commit. Por defecto, es la cabecera de la rama "main".

private (`bool`, *opcional*) : Si se debe hacer privada la repositorio cuando se crea. El valor predeterminado es `args.hub_private_repo`. No tiene efecto si la repositorio ya existe.

kwargs (`dict[str, Any]`, *opcional*) : Argumentos de palabra clave adicionales que se pasan a `~Trainer.create_model_card`.

**Devuelve:**

La URL del repositorio donde se subió el modelo si `blocking=False`, o un objeto `Future` que rastrea el progreso del commit si `blocking=True`.

Sube `self.model` y `self.processing_class` al hub de modelos de 🤗 en el repositorio `self.args.hub_model_id`.

## DistillationConfig[[trl.DistillationConfig]]

#### trl.DistillationConfig[[trl.DistillationConfig]]

```python
trl.DistillationConfig(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 | None = False, 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, teacher_model_name_or_path: str | None = None, teacher_model_revision: str | None = None, teacher_model_init_kwargs: dict[str, typing.Any] | str | None = None, disable_dropout: bool = False, max_completion_length: int | None = 512, ds3_gather_for_generation: bool = True, shuffle_dataset: bool | None = True, pad_to_multiple_of: int | str | None = 'auto', temperature: float = 1.0, top_p: float = 1.0, top_k: int = 0, min_p: float | None = None, generation_kwargs: dict | str | None = None, chat_template_kwargs: dict | str | None = None, repetition_penalty: float = 1.0, cache_implementation: str | None = None, use_vllm: bool = False, vllm_mode: str = 'colocate', vllm_model_impl: str = 'vllm', vllm_enable_sleep_mode: bool = False, vllm_structured_outputs_regex: str | None = None, vllm_server_base_url: str | None = None, vllm_server_host: str = '0.0.0.0', vllm_server_port: int = 8000, vllm_server_timeout: float = 240.0, vllm_group_port: int = 51216, vllm_gpu_memory_utilization: float = 0.3, vllm_max_model_length: int | None = None, vllm_tensor_parallel_size: int = 1, beta: float = 1.0, max_tool_calling_iterations: int | None = None, log_completions: bool = False, num_completions_to_print: int | None = None, log_unique_prompts: bool = False)
```

[Fuente](https://github.com/huggingface/trl/blob/v1.18.1/trl/trainer/distillation_config.py#L22)

**Parámetros que controlan el modelo y el modelo maestro:**

model_init_kwargs (`str` o `dict[str, Any]`, *opcional*) : Argumentos de palabra clave para `AutoModelForCausalLM.from_pretrained`, utilizados cuando el argumento `model` del trainer se proporciona como una cadena. El valor de `revision` también se utiliza al cargar la clase de procesamiento.

trust_remote_code (`bool`, *opcional*, valor predeterminado `False`) : Si se permite cargar modelos y tokenizadores que incluyen código Python personalizado desde el Hub. Se reenvía a [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) y [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained), tanto para el estudiante como para el profesor.

teacher_model_name_or_path (`str`, *opcional*) : Nombre o ruta del modelo para el modelo maestro. Se utiliza cuando el maestro se carga localmente.

teacher_model_revision (`str`, *opcional*) : Revisión del modelo del modelo maestro (p. ej., nombre de rama, etiqueta o hash de commit).

teacher_model_init_kwargs (`str` o `dict[str, Any]`, *opcional*) : Argumentos de palabra clave pasados a `AutoModelForCausalLM.from_pretrained` al instanciar el modelo maestro a partir de una cadena.

disable_dropout (`bool`, *opcional*, valor predeterminado `False`) : Si se deshabilita el dropout en el modelo estudiante durante el entrenamiento.

**Parámetros que controlan el preprocesamiento de datos:**

remove_unused_columns (`bool`, *opcional*, valor predeterminado `False`) : Si se debe conservar únicamente la columna `"prompt"` en el conjunto de datos. El entrenador consume la columna de prompt sin procesar y genera completados on-policy, por lo que su valor predeterminado es `False`.

max_completion_length (`int` o `None`, *opcional*, valor predeterminado `512`) : Número máximo de tokens a generar por completado durante la generación on-policy.

ds3_gather_for_generation (`bool`, *opcional*, valor predeterminado `True`) : Esta configuración se aplica a DeepSpeed ZeRO-3. Si se habilita, los pesos del modelo de política se recopilan para la generación, lo que mejora la velocidad de generación. Sin embargo, deshabilitar esta opción permite entrenar modelos que superan la capacidad de VRAM de una sola GPU, aunque a costa de una generación más lenta. Deshabilitar esta opción no es compatible con la generación de vLLM.

shuffle_dataset (`bool`, *opcional*, valor predeterminado `True`) : Si se debe barajar el conjunto de datos de entrenamiento.

pad_to_multiple_of (`int` o `str`, *opcional*, valor predeterminado `"auto"`) : Si se establece, los ids de los prompts y los ids de las completions se rellenarán hasta un múltiplo de este valor. `"auto"` rellena hasta un múltiplo de 128 en Neuron (AWS Trainium), que compila una vez por forma de entrada, y no rellena en otros entornos.

**Parámetros que controlan la generación:**

temperature (`float`, *opcional*, valor predeterminado `1.0`) : Temperatura para el muestreo durante la generación y para el cálculo de la pérdida de destilación. Valores más altos producen distribuciones de probabilidad más suaves.

top_p (`float`, *opcional*, valor predeterminado `1.0`) : Parámetro de muestreo top-p (núcleo) para la generación on-policy.

top_k (`int`, *opcional*, valor predeterminado `0`) : Parámetro de muestreo top-k para la generación on-policy. `0` deshabilita el filtrado top-k.

min_p (`float`, *opcional*) : Probabilidad mínima del token, que se escalará por la probabilidad del token más probable. Debe ser un valor entre `0.0` y `1.0`. Los valores típicos están en el rango `0.01-0.2`.

generation_kwargs (`dict[str, Any]`, *opcional*) : Argumentos de palabra clave adicionales para pasar a [GenerationConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/text_generation#transformers.GenerationConfig) (si se usa transformers) o `SamplingParams` (si se usa vLLM) al muestrear las completaciones. Esto se puede usar para personalizar aún más el comportamiento de la generación, como establecer `suppress_tokens`, `num_beams`, etc. Si contiene claves que entran en conflicto con los otros parámetros de generación (como `min_p`, `top_p`, etc.), los sobrescribirán.

chat_template_kwargs (`dict[str, Any]`, *opcional*) : Argumentos de palabra clave adicionales para pasar a la función `apply_chat_template` al generar las completaciones.

repetition_penalty (`float`, *opcional*, valor predeterminado `1.0`) : Flotante que penaliza los nuevos tokens en función de si aparecen en el prompt y en el texto generado hasta el momento. Los valores > `1.0` animan al modelo a usar tokens nuevos, mientras que los valores < `1.0` animan al modelo a repetir tokens.

cache_implementation (`str`, *opcional*) : Implementación del método de caché para una generación más rápida cuando `use_vllm` se establece en `False`.

**Parámetros que controlan la aceleración de la generación impulsada por vLLM:**

use_vllm (`bool`, *opcional*, por defecto `False`) : Si se debe usar vLLM para generar completados on-policy desde el modelo estudiante.

vllm_mode (`str`, *opcional*, por defecto `"colocate"`) : Modo para la integración de vLLM del estudiante. Puede ser `"server"` o `"colocate"`.

vllm_model_impl (`str`, *opcional*, por defecto `"vllm"`) : Backend de implementación del modelo para vLLM. Use `"vllm"` o `"transformers"`.

vllm_enable_sleep_mode (`bool`, *opcional*, valor predeterminado `False`) : Habilita el modo de suspensión de vLLM para descargar los pesos del estudiante durante el paso del optimizador.

vllm_structured_outputs_regex (`str`, *opcional*) : Patrón de expresión regular para las salidas estructuradas de vLLM.

**Parámetros que controlan el servidor de vLLM (solo se usan cuando `vllm_mode` es `"server"`):**

vllm_server_base_url (`str`, *opcional*) : URL base para el servidor vLLM del estudiante. Si se proporciona, `vllm_server_host` y `vllm_server_port` se ignoran.

vllm_server_host (`str`, *opcional*, valor predeterminado `"0.0.0.0"`) : Host del servidor vLLM del estudiante.

vllm_server_port (`int`, *opcional*, valor predeterminado `8000`) : Puerto del servidor vLLM del estudiante.

vllm_server_timeout (`float`, *opcional*, valor predeterminado `240.0`) : Tiempo de espera para conectar con el servidor vLLM del estudiante.

vllm_group_port (`int`, *opcional*, valor predeterminado `51216`) : Puerto para el grupo de actualización de pesos de vLLM (comunicador NCCL).

**Parámetros que controlan la ejecución de vLLM colocada (solo se usan cuando `vllm_mode` es `"colocate"`):**

vllm_gpu_memory_utilization (`float`, *opcional*, valor predeterminado `0.3`) : utilización de la memoria de GPU para el motor vLLM del estudiante colocalizado.

vllm_max_model_length (`int`, *opcional*) : Longitud máxima de la secuencia del modelo para el motor vLLM colocalizado.

vllm_tensor_parallel_size (`int`, *opcional*, valor predeterminado `1`) : Tamaño de paralelismo de tensor para el motor vLLM del estudiante colocalizado.

**Parámetros que controlan el entrenamiento:**

beta (`float`, *opcional*, valor predeterminado `1.0`) : Coeficiente de interpolación para la pérdida de Divergencia de Jensen-Shannon Generalizada. Cuando es `0.0`, la pérdida es la divergencia KL hacia adelante. Cuando es `1.0`, la pérdida es la divergencia KL inversa. Cuando es `0.5`, es la JSD estándar. A diferencia de `beta` de GRPO (un coeficiente de penalización KL contra un modelo de referencia), aquí se selecciona la propia divergencia; no hay penalización KL de modelo de referencia.

max_tool_calling_iterations (`int`, *opcional*) : Número máximo de turnos de llamada a herramientas al entrenar un agente. Si es `None`, no hay límite y la generación se detiene cuando el modelo genera un turno de respuesta sin llamadas a herramientas, cuando la finalización (todos los turnos y resultados de herramientas) alcanza `max_completion_length` tokens, o cuando la secuencia completa alcanza la longitud máxima del modelo (`vllm_max_model_length` con `vllm_mode="colocate"`, o los `max_position_embeddings` del modelo en caso contrario).

**Parámetros que controlan el registro:**

log_completions (`bool`, *opcional*, valor predeterminado `False`) : Si se registra una muestra de pares (prompt, completion) cada `logging_steps` pasos. Si `rich` está instalado, imprime la muestra. Si el registro de `wandb` y/o `trackio` está habilitado, lo registra en `wandb` y/o `trackio`.

num_completions_to_print (`int`, *opcional*) : Número de completados que se imprimirán con `rich`. Si es `None`, se registran todos los completados.

log_unique_prompts (`bool`, *opcional*, valor predeterminado `False`) : Si se registran los prompts únicos. Si es `True`, solo se registran los prompts únicos. Si es `False`, se registran todos los prompts.

Clase de configuración para [DistillationTrainer](/docs/trl/v1.18.1/es/distillation_trainer#trl.DistillationTrainer).

Extiende [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments) con parámetros específicos para la destilación de conocimiento. Todos los campos necesarios se declaran aquí.

Con [HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser) podemos convertir esta clase en argumentos de [argparse](https://docs.python.org/3/library/argparse#module-argparse) que se pueden especificar en la línea de comandos.

> [!NOTE]
> Estos parámetros tienen valores predeterminados diferentes de [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments): - `logging_steps`: El valor predeterminado es `10` en lugar de `500`. - `gradient_checkpointing`: El valor predeterminado es `True` en lugar de `False`. - `bf16`: El valor predeterminado es `True` si `fp16` no está establecido, en lugar de `False`. - `learning_rate`: El valor predeterminado es `1e-6` en lugar de `5e-5`.

