# Destilación asíncrona

> [!IMPORTANT]
> Este trainer requiere `vllm`, `transformers>=5.2.0` y `kernels` (el entrenamiento carga FlashAttention desde el Hub a través de este). Para el entrenamiento distribuido, solo se admite FSDP2 (no se admite DeepSpeed ZeRO).
>
> Actualmente, `vllm` y `transformers` tienen restricciones de dependencias en conflicto. Para evitarlo, instale vLLM primero, luego instale transformers de forma forzada y, a continuación, agregue `kernels` a través del extra de TRL, que fija la versión que acepta transformers:
>
> ```bash
> pip install vllm
> pip install 'transformers>=5.2.0' --no-deps
> pip install 'trl[kernels]'
> ```

## Resumen

[experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/main/es/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer) es la contraparte asíncrona de [DistillationTrainer](/docs/trl/main/es/distillation_trainer#trl.DistillationTrainer), con una arquitectura similar a la de [AsyncGRPOTrainer](/docs/trl/main/es/async_grpo_trainer#trl.AsyncGRPOTrainer): un trabajador de rollout en segundo plano genera las propias finalizaciones on-policy del estudiante y las puntúa frente a un maestro, mientras que el entrenamiento avanza de forma concurrente en lugar de alternar entre la generación y las actualizaciones de gradiente. A diferencia del entrenador síncrono, el maestro nunca se carga localmente: solo se necesita la URL de un servidor de vLLM, por lo que el maestro puede ejecutarse en hardware completamente separado del del estudiante y del entrenador, o incluso ser un modelo mucho mayor del que cabría junto al estudiante.

`compute_loss` minimiza una divergencia de Jensen-Shannon generalizada entre las distribuciones de tokens por posición del estudiante y del maestro (`beta=0.0` es KL hacia adelante, `beta=1.0` es KL hacia atrás, los valores intermedios interpolan), el mismo objetivo que utilizan [DistillationTrainer](/docs/trl/main/es/distillation_trainer#trl.DistillationTrainer) y `ServerDistillationTrainer`. El entrenamiento siempre es on-policy: el estudiante genera cada finalización sobre la que se entrena.

### Destilación en política con múltiples maestros (MOPD)

MOPD no forma parte del artículo [2306.13649](https://huggingface.co/papers/2306.13649) en el que se basa el objetivo principal de este entrenador (que describe un entorno síncrono con un solo maestro); es un método independiente, descrito en [MOPD: Multi-Teacher On-Policy Distillation for Capability Integration in LLM Post-Training]( https://huggingface.co/papers/2606.30406). Allí, MOPD es la tercera de tres etapas: SFT general, luego entrenamiento RL independiente por dominio de un experto por dominio, y finalmente MOPD fusiona esos expertos congelados en un único estudiante. `AsyncDistillationTrainer` implementa únicamente esa tercera etapa de fusión: los maestros expertos por dominio deben existir ya (p. ej., entrenados por separado con [GRPOTrainer](/docs/trl/main/es/grpo_trainer#trl.GRPOTrainer)/[RLOOTrainer](/docs/trl/main/es/rloo_trainer#trl.RLOOTrainer)) y estar servidos por HTTP antes de que apuntes `teacher_server_urls` hacia ellos. La propia Etapa 3 del artículo utiliza KL inversa (`beta=1.0`), no el valor predeterminado de este entrenador `beta=0.0` (KL directa).

`teacher_server_urls` acepta más de una entrada. Con una sola entrada, cada muestra se puntúa con ese único maestro (destilación on-policy simple). Con varias entradas, la columna `teacher_id` de cada muestra de entrenamiento selecciona qué maestro la puntúa; por ejemplo, enrutar los prompts de matemáticas a un maestro especialista en matemáticas y los de código a un maestro especialista en código, cada uno servido de forma independiente. Cada muestra se envía a su maestro correspondiente, sin promediar ni ensambles entre maestros. Una muestra con un `teacher_id` ausente o sin mapear genera un error en lugar de recurrir silenciosamente al maestro incorrecto. Consulte `examples/async_distillation_mopd/async_distillation_mopd.py` para un ejemplo ejecutable que fusiona los expertos en matemáticas, código y seguimiento de instrucciones publicados con [Open-MOPD](https://huggingface.co/papers/2608.19098) en su checkpoint SFT compartido, y `examples/async_distillation_mopd/launcher.py` para ejecutarlo en 4 GPUs con un solo comando de [Hugging Face Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs).

> [!WARNING]
> Cada docente debe compartir el tokenizador del estudiante. Las completaciones viajan a los docentes como ids de tokens crudos, y los ids de candidatos que un docente devuelve indexan directamente el vocabulario propio del estudiante en `compute_loss`. Los docentes de la misma familia de modelos que el estudiante (como en el ejemplo de MOPD, donde un estudiante SmolLM3 se fusiona a partir de expertos SmolLM3 entrenados desde el mismo checkpoint) cumplen con esto; un docente con un vocabulario diferente entrena al estudiante contra los tokens incorrectos, de forma silenciosa a menos que su vocabulario sea mayor que el del estudiante.

**Punto de control y reanudación**: `ignore_data_skip` tiene `True` como valor predeterminado; el bucle de omisión y reproducción del Trainer base no se aplica a una cola de despliegue en vivo. En su lugar, el índice del primer prompt que aún no se ha entrenado se guarda en `rollout_state.json` junto con cada punto de control y se restaura al reanudar, de modo que el worker avanza rápidamente hasta ese prompt sin reproducir muestras. Es la posición *entrenada*, no la del generador: el worker se adelanta al entrenamiento en la profundidad de la cola de despliegue, y esas muestras en búfer se pierden cuando termina la ejecución, por lo que reanudar desde la posición del generador omitiría prompts que se generaron pero nunca se entrenaron. Los conjuntos de datos de streaming (`IterableDataset`) no se pueden reposicionar; su worker se reinicia desde el prompt 0 al reanudar. Con FSDP y `bf16=True` (el valor predeterminado) o `fp16=True`, `model.safetensors` se escribe en ese dtype aunque los pesos maestros sean fp32, por lo que un punto de control publicado tiene el tamaño del modelo servido, no el doble; los pesos maestros fp32 y el estado del optimizador siguen yendo a los archivos de reanudación (`pytorch_model_fsdp.bin`, `optimizer.bin`), que son los que lee una reanudación, por lo que reanudar no se ve afectado. Sin FSDP, el punto de control también es el archivo de reanudación, por lo que conserva el dtype maestro.

## En qué se diferencia de [DistillationTrainer](/docs/trl/main/es/distillation_trainer#trl.DistillationTrainer)

En [DistillationTrainer](/docs/trl/main/es/distillation_trainer#trl.DistillationTrainer), el modelo maestro es un modelo cargado localmente: la generación, la pasada hacia adelante del maestro y la actualización de gradientes ocurren de forma secuencial en el mismo proceso. [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/main/es/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer) separa estas preocupaciones de la misma manera en que [AsyncGRPOTrainer](/docs/trl/main/es/async_grpo_trainer#trl.AsyncGRPOTrainer) separa el despliegue de GRPO de su actualización:

- **Trabajador de despliegue** (proceso en segundo plano): genera completados desde el servidor vLLM del estudiante, envía la secuencia completa al `/v1/completions` del maestro resuelto con `prompt_logprobs` para la puntuación forzada por el maestro (sin que el maestro genere nuevos tokens) y envía las muestras listas para entrenar a una cola.
- **Bucle de entrenamiento** (proceso principal): extrae muestras de la cola, calcula la pérdida JSD generalizada y actualiza los pesos del estudiante.

Dado que el maestro se puntúa a través de HTTP en lugar de una pasada local hacia adelante, solo se transmite una porción dispersa de su distribución, la de los `teacher_top_k` elementos principales, y no el vocabulario completo; consulte la documentación de `beta` y `teacher_top_k` de [experimental.async_distillation.AsyncDistillationConfig](/docs/trl/main/es/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationConfig) para saber exactamente para qué candidatos el protocolo de red garantiza un logprob del maestro en cada régimen de `beta`.

Después de cada `weight_sync_steps` pasos de entrenamiento, los pesos actualizados del estudiante se transfieren a su servidor vLLM mediante NCCL. Al igual que con [AsyncGRPOTrainer](/docs/trl/main/es/async_grpo_trainer#trl.AsyncGRPOTrainer), la generación se ejecuta por delante del entrenamiento, por lo que las muestras pueden reflejar una política ligeramente desactualizada; `max_staleness` controla cuántas actualizaciones de pesos puede estar por detrás una muestra antes de ser descartada.

## Inicio rápido

```python
# train_async_distillation.py
from datasets import load_dataset
from trl.experimental.async_distillation import AsyncDistillationTrainer

if __name__ == "__main__":  # the rollout worker is a spawned process that re-imports this script
    dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

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

El servidor de maestro, el servidor vLLM del estudiante y el entrenador deben ejecutarse en **GPUs separadas**. Ambos son instancias simples de `vllm serve`, pero necesitan banderas diferentes: el maestro solo se puntúa (`--logprobs-mode processed_logprobs` para que `teacher_temperature` llegue a sus logprobs devueltos, y `--max-logprobs -1` para que `teacher_top_k` pueda superar el límite predeterminado de 20 de vLLM), mientras que el estudiante solo se genera desde él y necesita habilitar la transferencia de pesos NCCL para que el entrenador pueda enviarle los pesos actualizados. La puntuación envía la secuencia completa del estudiante y le pide al maestro un token más, por lo que el `--max-model-len` del maestro (o su valor predeterminado) debe ser mayor que el del estudiante:

```bash
# Terminal 1: teacher server on GPU 0 (static, never updated)
CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen2.5-1.5B-Instruct \
    --port 8001 \
    --logprobs-mode processed_logprobs \
    --max-logprobs -1
```

```bash
# Terminal 2: student's vLLM server on GPU 1 (dev mode + NCCL weight transfer are required)
CUDA_VISIBLE_DEVICES=1 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-0.5B-Instruct --gpu-memory-utilization 0.9 \
    --port 8000 \
    --weight-transfer-config '{"backend":"nccl"}'
```

```bash
# Terminal 3: training on GPU 2
CUDA_VISIBLE_DEVICES=2 python train_async_distillation.py
```

## LoRA

Pase un `peft_config` para entrenar un adaptador LoRA en el estudiante en lugar del modelo completo:

```python
from peft import LoraConfig

trainer = AsyncDistillationTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    train_dataset=dataset,
    peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
)
```

Cada sincronización de pesos debe enviar el estudiante actualizado a su servidor. De forma predeterminada, el entrenador fusiona el adaptador en el modelo base y envía los pesos fusionados completos, lo que equivale a unos 15 GB para un modelo de 7B en cada sincronización. Inicie el servidor vLLM del estudiante con `--enable-lora` y solo enviará el adaptador, aproximadamente 160 MB con `r=32`:

```bash
CUDA_VISIBLE_DEVICES=1 VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve Qwen/Qwen2.5-0.5B-Instruct --gpu-memory-utilization 0.9 \
    --port 8000 \
    --weight-transfer-config '{"backend":"nccl"}' \
    --enable-lora \
    --max-lora-rank 32 \
    --max-loras 6
```

`VLLM_ALLOW_RUNTIME_LORA_UPDATING=1` expone el endpoint al que el entrenador publica cada nuevo adaptador. Añade `VLLM_WORKER_MULTIPROC_METHOD=spawn` si sirves con paralelismo de tensores, y mantén `--weight-transfer-config` en cualquier caso: el entrenador solo elige un modo de sincronización al iniciar, momento en el que el servidor ya está en marcha, y la sincronización combinada es la opción de respaldo. El servidor de maestro no se ve afectado: nunca se actualiza.

`--max-lora-rank` debe ser uno de `1, 8, 16, 32, 64, 128, 256, 320, 512`. Establece el rango máximo que el servidor puede servir, en lugar del rango que servirá, por lo que un adaptador `r=4` funciona bien bajo `8`. `--max-loras` debe ser al menos `max_staleness + 2`: el entrenador mantiene registradas `max_staleness + 1` versiones de adaptadores para que un rollout que comenzó bajo una política anterior pueda completarse bajo ella en lugar de cambiar de política a mitad de la generación, y cada sincronización carga la siguiente versión antes de descargar la más antigua. El entrenador comprueba ambos valores al iniciar y te indica con qué valores reiniciar el servidor.

vLLM carga los adaptadores desde el disco en lugar de a través de la red, por lo que el entrenador escribe cada versión bajo `<output_dir>/.vllm_lora/` y le proporciona la ruta al servidor. Si el servidor se ejecuta en una máquina diferente, ese directorio debe estar en un sistema de archivos al que ambos puedan acceder.

> [!WARNING]
> `<output_dir>/.vllm_lora/` es una caché de servicio, no el lugar donde se guarda el adaptador entrenado. Solo contiene las versiones más recientes y cada una se elimina poco después de salir de la ventana de obsolescencia. Los checkpoints son los que preservan el adaptador que entrenaste, así que no los desactives: con `save_strategy="no"`, una ejecución de varias horas termina sin dejar nada. `output_dir` también debe ser legible por el servidor y debe sobrevivir al trabajo, por lo que un espacio temporal local al nodo no funcionará, aunque evitaría las sincronizaciones en un sistema de archivos compartido lento.

> [!TIP]
> La sincronización de adaptadores no siempre es más rápida. vLLM genera aproximadamente 1,33–1,39 veces más lento por token cuando sirve un adaptador LoRA en comparación con cuando sirve pesos fusionados, y la generación suele ser lo que domina el tiempo real. Lo que se obtiene a cambio es una pausa mucho más corta en cada sincronización y aproximadamente el 1% de la banda ancha de sincronización. Si el rendimiento de generación es su cuello de botella, la sincronización fusionada suele ser la mejor opción.

## Métricas registradas

Un rollout atraviesa varias etapas antes de convertirse en un gradiente. Primero, echemos un vistazo a las diferentes etapas, desde un prompt hasta la composición final de nuestro batch:

```
Dataset row = PROMPT (message list + optional `teacher_id`)
 └─ ROLLOUT            (1 prompt -> 1 student completion -> 1 teacher scoring call)
     ├─ generate       (student's vLLM /v1/completions, sampled)
     └─ score          (the routed teacher's /v1/completions with `prompt_logprobs`, teacher-forced)
         └─ SAMPLE     (prompt + completion + the teacher's sparse per-position distribution)

════════════ Trainer process boundary: `rollout_buffer` (mp.Queue) ════════════

         └─ SAMPLE (Pulled 1 at a time; dropped if staleness > `max_staleness`)
             └─ ROW            (Planner assigns it to one of `dp` rows, Σ Lᵢ²-balanced)
                 └─ MICRO-BATCH (`dp` rows, one per rank)
                     └─ PACKED ROW (1 concat sequence, `position_ids` reset per sample)
                         └─ FORWARD (`compute_loss`, bs=1, inter-rank padding stripped)
             └─ OPTIMIZER STEP (from `grad_accum` micro-batches)
```

Leyéndolo de arriba a abajo:

- Un **rollout** es un único prompt generado una vez y puntuado una vez. No existe un grupo: la destilación no tiene una línea base de ventaja que calcular entre generaciones, por lo que un prompt no se repite y un rollout produce exactamente una muestra de entrenamiento.
- una **muestra** es esa finalización más los `teacher_top_k` candidatos principales del maestro por cada posición de la finalización. Esto es lo que cruza el límite de proceso.
- más allá del límite, el trainer planifica las muestras en **filas** (una por cada rango de DP), empaqueta cada fila en una secuencia concatenada y acumula `grad_accum` micro-lotes en un único paso del optimizador.

Por lo tanto, dividimos nuestras métricas según la etapa (o _entidad_) a la que se refieren:

| namespace      | entidad que cuenta                                                            |
| -------------- | --------------------------------------------------------------------------- |
| `rollout/`     | un viaje de ida y vuelta de generación y puntuación: cuánto tiempo tardó, hasta dónde llegó         |
| `completions/` | lo que el estudiante (vLLM) generó para un solo prompt                            |
| `sample/`      | representa _una_ muestra de entrenamiento, tal como llega a la cola                |
| `batch/`       | un micro-lote o un paso del optimizador (construido a partir de una o varias muestras)  |
| `perf/`        | segundos y FLOPs medidos                                                  |

Todo lo que mide la pérdida en sí se registra sin prefijo (`jsd`, `entropy`, `teacher_entropy`), con un desglose `teacher/<teacher_id>/*` bajo MOPD; consulte [la divergencia](#the-divergence) a continuación.

Definamos también algunos términos para que las métricas de tokens no sean ambiguas:

- Los tokens **generados** son los que produjo el estudiante (`completions/*`).
- Los tokens **forwarded** son todos los tokens que la pasada de _forward_ procesa: el prompt y los tokens generados.
- Los tokens **entrenados** son el subconjunto sobre el que se calcula la pérdida, donde `completion_mask == 1`. Entrenados ≠ generados: una posición de finalización para la que el modelo maestro no puntuó ningún candidato se excluye de la divergencia, pero se propaga igualmente.

Las métricas se registran una vez por **ventana de registro**: todo lo registrado desde el registro anterior, que abarca los últimos `logging_steps` pasos del optimizador. En la ventana:

- Una media medida por rollout, muestra o llamada, como `rollout/duration_s` y `rollout/score_s`, se promedia sobre todos los rollouts, muestras o llamadas de la ventana. Una tasa como `rollout/generated_tokens_per_s` es el total de tokens dividido entre el total de segundos.
- En caso contrario, un nombre cuya última parte contiene la palabra `count` se suma: `sample/dropped_stale_count` es el número de muestras descartadas desde el último registro, no desde el inicio del entrenamiento.
- Un nombre cuya última parte contiene la palabra `max` o `min`, como `sample/staleness_max` o `completions/max_length`, conserva el valor más grande o más pequeño.
- Cualquier otra métrica es la media de los valores registrados en la ventana.

Unidades:

- `_s`: segundos.
- `tokens_per_s`: tokens por segundo.
- `_frac`: fracción entre 0 y 1.
- `_per_step`: cantidad en un paso del optimizador, promediada sobre los pasos de la ventana.

Las métricas que [GRPOTrainer](/docs/trl/main/es/grpo_trainer#trl.GRPOTrainer) también registra conservan sus nombres de GRPO (`completions/mean_length`, `completions/clipped_ratio`).

### Cómo se componen los números de lote

Una **fila** es lo que **un** rango de DP procesa en un micro-lote: varias muestras concatenadas en una sola secuencia, con `position_ids` reiniciándose en cada límite de muestra. El planificador decide en qué fila caen las muestras (equilibrando Σ Lᵢ² para que ningún rango se retrase) y un data collator realiza la concatenación.

En todas nuestras métricas, **un "step" siempre significa un paso COMPLETO del optimizador**, nunca un micro-lote. `gradient_accumulation_steps` micro-lotes constituyen un paso, y cada métrica con el sufijo `_per_step` se refiere al paso del optimizador, en concordancia con `global_step`, `logging_steps` y el resto del vocabulario de `Trainer`. Cuando una métrica es por micro-lote, se indica explícitamente (`batch/microbatches_per_step`) o bien es una cantidad por fila (`batch/row_*`, `batch/samples_per_row`).

Por lo tanto, un paso mantiene un número fijo de **row-slots**:

```
row-slots per step = gradient_accumulation_steps x world_size
```

lo que permite que las métricas del lote se combinen en una escala que puedes comparar entre sí:

```
sample                                     sample/forwarded_tokens_mean
  └─ packed into a ROW                     batch/samples_per_row, batch/row_tokens_mean
      └─ one row per DP rank               = one micro-batch
          └─ gradient_accumulation_steps micro-batches = one STEP
                                           batch/samples_per_step, batch/forwarded_tokens_per_step
```

Por lo tanto, `batch/samples_per_step ≈ row-slots x batch/samples_per_row`, y lo mismo aplica para los tokens. Los dos lados solo coinciden hasta la variación entre los micro-lotes dentro del paso: las métricas por paso son sumas, mientras que las por fila son promedios, por lo que se espera una diferencia de una fracción de un porcentaje, no una coincidencia exacta.

`batch/row_fill_frac` es el indicador a vigilar cuando las muestras son largas: una muestra de 10k tokens encaja mal en un presupuesto de 32k (caben tres, pero nunca cuatro, por lo que el empaquetador suele obtener dos y la fila queda llena al ~77%), mientras que las muestras de 1k token encajan casi perfectamente. Se trata de cuantización, no de un error, y `token_budget` es el parámetro de ajuste, teniendo en cuenta que la atención es O(L²) por secuencia, por lo que una fila más llena de secuencias largas no supone un coste de memoria linealmente mayor.

### La cola de despliegue

El worker envía las muestras puntuadas a una cola y el trainer las extrae de ella. Cuatro métricas describen esa única cola y responden a diferentes preguntas:

| métrica                      | question                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `rollout/queue_size`        | cuántas muestras están esperando ahora mismo                                                                  |
| `sample/time_in_queue_s`    | cuánto tiempo **una sola muestra** permaneció allí antes de ser utilizada para el entrenamiento: la mitad de segundos de su carácter no de política |
| `perf/rollout_wait_s`       | cuánto tiempo estuvo el entrenamiento bloqueado porque la cola estaba **vacía**                                            |
| `rollout/backpressure_s`    | cuánto tiempo esperó la generación (el worker) porque iba `max_staleness` pasos por delante del entrenamiento           |

Las dos últimas métricas (`perf/rollout_wait_s` y `rollout/backpressure_s`) son imágenes especulares. Leerlas junto con el tamaño de la cola te indica qué lado es el cuello de botella:

- cola casi vacía, `perf/rollout_wait_s` alto → **limitado por la generación**. El entrenador se queda sin trabajo; revisa `rollout/generated_tokens_per_s`, `rollout/concurrency` y `rollout/score_s`.
- cola que mantiene aproximadamente `max_staleness` pasos de tokens, `rollout/backpressure_s` alto → **limitado por el trainer**. La generación se retrasa y `sample/staleness_mean` se sitúa cerca de su límite.
- ambos altos → el límite de `max_staleness` en sí es demasiado estricto: los rollouts en curso lo llenan antes de que sus muestras lleguen a la cola, por lo que el entrenador espera mientras la generación se retiene. Aumenta `max_staleness`.
- ambos cerca de cero → ¡equilibrado!

### Completions

Un **completion** es lo que el servidor vLLM del estudiante generó para un solo prompt.

| métrica                                             | significado                                                                                             |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `completions/mean_length`                          | tokens generados por rollout                                                                        |
| `completions/min_length`, `completions/max_length` | completación más corta y más larga en la ventana                                                       |
| `completions/clipped_ratio`                        | fracción de las finalizaciones que no terminaron en EOS, es decir, que fueron truncadas por `max_completion_length`        |
| `completions/mean_terminated_length`, `completions/min_terminated_length`, `completions/max_terminated_length` | las mismas longitudes, sobre las finalizaciones que terminaron en EOS |

### Rollouts

Un **rollout** es un prompt llevado hasta el final: generado por el estudiante y luego forzado por su maestro. Dado que la llamada al maestro está en la ruta crítica de cada rollout (a diferencia de GRPO, donde la puntuación es un bucle separado sobre grupos completados), un maestro lento se manifiesta directamente como `rollout/duration_s`.

| métrica                     | significado                                                                                                                                                                                                                                      |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rollout/duration_s`       | tiempo real de un rollout, desde la distribución hasta una muestra puntuada: generación **y** la llamada al teacher                                                                                                                                              |
| `rollout/score_s`          | de eso, el tiempo que tardó la llamada `/v1/completions` del maestro                                                                                                                                                                                  |
| `teacher/<id>/score_s`     | Solo MOPD: lo mismo, por profesor. Un experto lento solo limita las ejecuciones enrutadas a él, algo que la media combinada oculta                                                                                                                     |
| `rollout/generated_tokens_per_s`  | el rendimiento de generación en el último intervalo (con ventana), de modo que una pausa se muestre                                                                                                                                                                 |
| `rollout/concurrency`      | rollouts en curso, es decir, generando o siendo puntuados                                                                                                                                                                                          |
| `rollout/vllm_retry_count` | solicitudes de vLLM reintentadas, ya sea al servidor del estudiante o al de un docente. Un servidor degradado, de lo contrario, se percibe como una lentitud inexplicable. Se ubica aquí y no en `completions/` porque cuenta las solicitudes a un servidor, no el texto generado     |
| `rollout/backpressure_s`   | cuánto tiempo esperó la generación porque iba `max_staleness` pasos por delante. Consulte [la cola de rollout](#the-rollout-queue)                                                                                                                           |
| `rollout/queue_size`       | muestras puntuadas esperando en la cola de rollout, medido en el punto donde el trainer las extrae. Consulta [la cola de rollout](#the-rollout-queue)                                                                                                              |

### Muestras que llegan desde la cola

Cada muestra es una `RolloutSample`: un prompt, la finalización del estudiante y la puntuación escasa del profesor sobre ella. El worker las envía a `rollout_buffer`; todo lo siguiente se mide en el lado del trainer, a medida que las extrae para el entrenamiento.

| métrica                                                        | significado                                                                                                                                             |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sample/forwarded_tokens_mean`, `sample/forwarded_tokens_max` | tokens en una **muestra**: prompt + generado. El empaquetado es una cuestión a nivel de fila, consulte `batch/row_*`                                                      |
| `sample/trained_tokens_mean`                                  | de esos, sobre cuántos se calcula la pérdida                                                                                                           |
| `sample/time_in_queue_s`                                      | cuánto tiempo permaneció esta muestra en esa cola antes de ser utilizada para el entrenamiento. No es lo mismo que `perf/rollout_wait_s`; consulte [la cola de rollout](#the-rollout-queue) |
| `sample/staleness_mean`, `sample/staleness_max`               | cuántas versiones de la política están por detrás de los datos. `jsd` muestra el _efecto_ de la desviación de la política en la pérdida; esto muestra la causa                            |
| `sample/dropped_stale_count`                                  | muestras descartadas por exceder `max_staleness`                                                                                                     |

### Lotes

Un micro-lote es de `world_size` filas (recuerde que el empaquetado aplanar en 1 secuencia), por lo que hay uno por rango de DP, de modo que el rango _i_ realiza la propagación hacia adelante de la fila _i_. `gradient_accumulation_steps` de estos constituyen un paso del optimizador. Un paso cubre entonces `gradient_accumulation_steps × world_size` filas en total. Cada métrica `_per_step` a continuación es una suma sobre todo el paso y a través de todos los rangos; las de `batch/row_*` son _medias_ sobre las filas.

| métrica                                                                   | significado                                                                                                                              |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `batch/forwarded_tokens_per_step`, `batch/trained_tokens_per_step`       | tokens en un paso de optimizador, respectivamente, en la propagación hacia adelante y en el entrenamiento                                                                      |
| `batch/samples_per_step`                                                 | muestras de entrenamiento por paso del optimizador                                                                                                  |
| `batch/microbatches_per_step`                                            | contados, no leídos de la configuración                                                                                                     |
| `batch/masked_token_frac`                                                | tokens reenviados con `completion_mask == 0` — la parte del forward que no genera gradiente                                       |
| `batch/samples_per_row`, `batch/row_tokens_mean`, `batch/row_tokens_max` | la densidad con la que el planificador empaquetó la fila de cada rank                                                                                       |
| `batch/row_fill_frac`                                                    | filas de tokens frente a `token_budget`. Un valor bajo significa que el presupuesto no se está utilizando                                                             |
| `batch/row_imbalance`                                                    | `max Σ Lᵢ² / mean Σ Lᵢ²` en las filas. La atención es O(L²), por lo que esto predice qué rango detiene el all-reduce de gradientes. 1.0 es perfecto |
| `batch/pad_frac`                                                         | relleno entre rangos. Solo incurre en el coste de los bytes de difusión; se elimina antes de la propagación hacia adelante                                                     |
| `batch/dropped_oversize_count`                                           | muestras descartadas por exceder `token_budget`                                                                                          |

### La divergencia

Lo que mide el propio objetivo, promediado sobre los tokens entrenados de la ventana. Estas son las cifras a vigilar para el aprendizaje, en contraposición a las de rendimiento.

| métrica                          | significado                                                                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jsd`                           | la JSD generalizada que la pérdida minimiza, en el `beta` configurado. Que baje significa que la distribución del estudiante está convergiendo hacia la del maestro                             |
| `entropy`                       | la entropía predictiva propia del estudiante. Un colapso aquí con un `jsd` en descenso indica que el estudiante está estrechando su distribución en lugar de aprender                                             |
| `teacher_entropy`               | la entropía del modelo maestro sobre los candidatos que reportó. Acotada por debajo del valor real, ya que solo `teacher_top_k` candidatos cruzan la red                             |
| `teacher/<id>/jsd`              | Solo MOPD: `jsd` restringido a los tokens que puntuó el modelo maestro. Los maestros de diferentes dominios pueden divergir a tasas muy distintas, algo que el `jsd` combinado confunde.  |
| `teacher/<id>/entropy`          | Solo MOPD: el mismo desglose de `teacher_entropy`                                                                                                                  |
| `teacher/<id>/token_frac`       | Solo MOPD: la proporción de tokens puntuados que tomó el teacher. La desviación del enrutamiento es invisible de lo contrario: un teacher al que le faltan filas sigue informando un `teacher/<id>/jsd` saludable   |
| `aux_loss` | la pérdida de equilibrado de carga del enrutador MoE por micro-lote, promediada sobre los rangos, registrada cuando el modelo devuelve logits del enrutador y `router_aux_loss_coef` no es 0. A diferencia de las filas anteriores, no es un promedio por token |

No existe una `entropy` por profesor: la entropía del estudiante es una propiedad de su propia política, no de qué profesor puntuó la muestra, por lo que la métrica combinada ya la cubre.

### Rendimiento

El throughput mide cuántos tokens procesa el entrenador por segundo. **Model FLOPs Utilization (MFU)** estima el porcentaje de la capacidad de cálculo teórica de los dispositivos de entrenamiento que se utiliza para las pasadas hacia adelante y hacia atrás del modelo. La capacidad utilizada para esta estimación depende del hardware y de la precisión del entrenamiento.

El rendimiento y la MFU se informan en dos bases de tiempo:

- **`fwd_bwd_`** mide el rendimiento durante las pasadas hacia adelante y hacia atrás.
- **`wall_clock_`** mide el rendimiento durante el paso completo del optimizador, incluidas las actualizaciones del optimizador, la sincronización de pesos y el tiempo dedicado a esperar las ejecuciones.

La diferencia ayuda a distinguir el rendimiento de cómputo del costo de la espera y la coordinación. Ambas métricas de MFU describen solo los **dispositivos de entrenamiento**: no incluyen el cómputo ni la capacidad de hardware de los servidores externos de rollout o de los maestros. La MFU de tiempo real refleja el tiempo que el entrenador dedica a esperar esos servicios, no la propia utilización de los servicios.

MFU se informa solo cuando se conoce la capacidad de cómputo máxima del dispositivo de entrenamiento local en la precisión seleccionada y cuando la estimación de FLOPs es compatible con la arquitectura del modelo (como Llama, Qwen2, Qwen3, Qwen3-MoE o Qwen3-VL). De lo contrario, se omite MFU; el entrenamiento continúa y las métricas de rendimiento y tiempos siguen estando disponibles.

| métrica                                                            | significado                                                                                                                                               |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `perf/step_s`                                                     | tiempo real entre pasos del optimizador: incluye cálculos, optimizador, sincronización de pesos y esperas en la cola                                                           |
| `perf/fwd_bwd_s`                                                  | forward + backward, sumado sobre los micro-lotes del paso. Este es el denominador de cada métrica `fwd_bwd_` a continuación                                    |
| `perf/fwd_s`                                                      | la parte de propagación hacia adelante. `fwd_s / fwd_bwd_s` cerca de 1/3 es la división habitual; un valor más alto significa que la propagación hacia atrás es barata o que se está pagando el coste de la recomputación en la propagación hacia adelante |
| `perf/optimizer_s`                                                | `optimizer.step()`                                                                                                                                    |
| `perf/rollout_wait_s`                                             | cuánto tiempo el trainer estuvo bloqueado porque la cola estaba vacía. Consulte [la cola de rollout](#the-rollout-queue)                                             |
| `perf/weight_sync_s`                                              | una sincronización completa, más `_pause_s` (espera de vLLM), `_barrier_s` (desajuste de rangos) y `_transfer_s` (los bytes)                                               |
| `perf/fwd_bwd_forwarded_tokens_per_s`, `perf/wall_clock_forwarded_tokens_per_s` | tokens reenviados por segundo en cada base                                                                                                             |
| `perf/wall_clock_trained_tokens_per_s`                                   | lo mismo, contando solo los tokens que vio la pérdida                                                                                                            |
| `perf/fwd_bwd_mfu`, `perf/wall_clock_mfu`                         | utilización de FLOPs del modelo en cada base                                                                                                                 |

## Filosofía de diseño

Este entrenador se mantiene intencionalmente al mínimo y no está diseñado para convertirse en una solución de propósito general. Si necesitas una función que no está soportada, recomendamos clonar el repositorio y adaptar el entrenador directamente a tus necesidades. Las nuevas funciones solo se considerarán cuando exista una demanda significativa de la comunidad.

## AsyncDistillationConfig[[trl.experimental.async_distillation.AsyncDistillationConfig]]

#### trl.experimental.async_distillation.AsyncDistillationConfig[[trl.experimental.async_distillation.AsyncDistillationConfig]]

```python
trl.experimental.async_distillation.AsyncDistillationConfig(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 = 1, 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 = True, 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, dtype: str = 'float32', trust_remote_code: bool = False, router_aux_loss_coef: float | None = None, max_completion_length: int = 2048, temperature: float = 1.0, top_p: float = 1.0, top_k: int = 0, min_p: float | None = None, repetition_penalty: float = 1.0, chat_template_kwargs: dict | str | None = None, vllm_server_base_url: str = 'http://localhost:8000', vllm_server_timeout: float = 1800.0, teacher_server_urls: dict[str, str] | str | None = None, beta: float = 0.0, teacher_temperature: float = 1.0, teacher_top_k: int = 8, add_tail_bucket: bool = True, token_budget: int | None = None, max_concurrent_rollouts: int = 512, max_staleness: int = 4, weight_sync_steps: int = 1, rollout_worker_timeout: float = 300.0, log_completions: bool = False, log_completions_steps: int = 100, num_completions_to_print: int | None = None)
```

[Fuente](https://github.com/huggingface/trl/blob/main/trl/experimental/async_distillation/async_distillation_config.py#L22)

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

model_init_kwargs (`dict[str, Any]` o `str`, *opcional*) : Argumentos de palabra clave para [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained), utilizados al instanciar el modelo estudiante desde una ruta. El valor de `revision` también se utiliza al cargar la clase de procesamiento.

dtype (`str`, *opcional*, por defecto `"float32"`) : Tipo de datos para cargar el modelo estudiante, uno de `"auto"`, `"bfloat16"`, `"float16"` o `"float32"`. El valor por defecto es `"float32"` porque la discrepancia entre entrenamiento e inferencia contra la que se miden los entrenadores asíncronos ([Defeating the Training-Inference Mismatch via FP16](https://huggingface.co/papers/2510.26788)) es sensible a la propia precisión del entrenador. Cerrar esa brecha de principio a fin también requiere servir el servidor vLLM del estudiante en el mismo dtype (`vllm serve --dtype`). Un `dtype` en `model_init_kwargs` tiene prioridad. Los servidores maestro no se ven afectados: nunca se actualizan. Esto solo establece el dtype en el que se cargan los pesos. Con FSDP y precisión mixta (`bf16=True` es el valor por defecto), accelerate convierte cada parámetro entrenable a fp32 antes de hacer el sharding, por lo que los pesos maestros y el estado del optimizador son fp32 sin importar lo que diga `dtype`, mientras que el forward y el backward se ejecutan en bf16 o fp16. Los checkpoints se escriben entonces en ese dtype de precisión mixta, no en fp32. Sin FSDP, nada se convierte a un tipo superior: `dtype="bfloat16"` con `bf16=True` mantiene pesos y estados del optimizador en bf16, lo que es entrenamiento puro en bf16.

trust_remote_code (`bool`, *opcional*, por defecto `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/main/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) y [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained).

router_aux_loss_coef (`float`, *opcional*) : Coeficiente de la pérdida auxiliar de equilibrado de carga para modelos Mixture-of-Experts (MoE), que se suma a la pérdida de entrenamiento con este peso. Si no se establece, se utiliza el valor declarado en la configuración del modelo. Establezca `0.0` para desactivarlo. Falla si se usa con un modelo que no es MoE.

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

max_completion_length (`int`, *opcional*, valor predeterminado `2048`) : Número máximo de tokens a generar por completado.

temperature (`float`, *opcional*, valor predeterminado `1.0`) : Temperatura para muestrear las completaciones on-policy del estudiante.

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

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.

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.

**Parámetros que controlan los servidores de vLLM:**

vllm_server_base_url (`str`, *opcional*, valor predeterminado `"http --//localhost:8000"`): URL base del servidor vLLM del estudiante, utilizada tanto para la generación como para la transmisión de actualizaciones de pesos.

vllm_server_timeout (`float`, *opcional*, valor predeterminado `1800.0`) : Tiempo de espera en segundos para las llamadas a los servidores de vLLM: esperar a que el servidor del estudiante esté listo al inicio, cada solicitud de generación o puntuación, y cada llamada de sincronización de pesos. Esperar al servidor y las llamadas de sincronización de pesos lanzan una excepción cuando se agota el tiempo; una solicitud de generación o puntuación que supera el tiempo de espera se reintenta.

teacher_server_urls (`dict[str, str]`, *opcional*, valor predeterminado `{"default" : "http://localhost:8001"}`): servidor(es) vLLM del maestro, cada uno iniciado con `vllm serve <teacher-model> --logprobs-mode processed_logprobs --max-logprobs -1`. Cada maestro es estático: este entrenador nunca transmite actualizaciones de pesos a ninguno de ellos, por lo que un maestro no necesita ni `VLLM_SERVER_DEV_MODE` ni un backend de transferencia de pesos, solo esas dos banderas, que hacen que su puntuación sea exacta (ver `teacher_temperature` y `teacher_top_k`). Cada maestro debe compartir el tokenizador del estudiante: las finalizaciones se envían como ids de tokens crudos, y los ids que un maestro devuelve se usan directamente para indexar el propio vocabulario del estudiante en `compute_loss`. Un maestro con un vocabulario diferente entrena contra los tokens incorrectos, de forma silenciosa si su vocabulario no es mayor que el del estudiante. La puntuación es una solicitud de maestro forzado contra los propios tokens de finalización del estudiante (`max_tokens=1`, `prompt_logprobs=teacher_top_k`, `temperature=teacher_temperature`), la misma solicitud que `get_sequence_logprobs()` emite para los entrenadores de maestro-servidor síncronos. Debido a ese token descartable, un maestro necesita un `--max-model-len` mayor que el del estudiante, o las finalizaciones más largas no podrán puntuarse. Una sola entrada puntúa cada muestra (destilación on-policy de un solo maestro, el valor predeterminado). Múltiples entradas habilitan MOPD (destilación on-policy de múltiples maestros, ver [MOPD](https://huggingface.co/papers/2606.30406)): la columna `teacher_id` de cada fila de entrenamiento selecciona qué entrada la puntúa, p. ej. `{"math": "http://localhost:8002", "code": "http://localhost:8003"}` con un `teacher_id` de `"math"` o `"code"` por fila.

**Parámetros que controlan la pérdida de destilación:**

beta (`float`, *opcional*, valor predeterminado `0.0`) : Coeficiente de interpolación para la Divergencia de Jensen-Shannon generalizada. `0.0` corresponde a la KL hacia adelante (búsqueda de media), `1.0` a la KL hacia atrás (búsqueda de modo) y los valores intermedios interpolan, siguiendo la misma formulación de JSD generalizada que [DistillationTrainer](/docs/trl/main/es/distillation_trainer#trl.DistillationTrainer) calcula internamente. El soporte sobre el que se calcula la divergencia varía según el régimen, reflejando a `ServerDistillationTrainer`: con `beta=0.0`, se utiliza el soporte completo de ancho `teacher_top_k` reportado por el maestro (más el cubo de cola), ya que el ponderado de la KL hacia adelante es exactamente lo que ese soporte proporciona. Con `beta != 0.0`, el soporte se reduce a solo dos candidatos: el token top-1 del propio maestro y el token real/realizado de la finalización, ya que son las únicas dos identidades de token para las que el protocolo de red garantiza un logprob del maestro sin transmitir un vocabulario más amplio (o completo); cualquier cosa más amplia sería solo una aproximación probabilística de cubrir los tokens probables del propio estudiante, no una garantía.

teacher_temperature (`float`, *opcional*, valor predeterminado `1.0`) : Temperatura del softmax de la divergencia, aplicada a *ambos* lados: se envía al maestro para que vLLM calcule sus logprobs a esta temperatura en el servidor (de forma exacta, no como una reescalación en el cliente) y se aplica a los logits propios del estudiante en `compute_loss`, replicando la única `temperature` de `ServerDistillationTrainer`. No tiene relación con `temperature`, que solo controla cómo el estudiante muestrea sus completados. El servidor del maestro debe ejecutarse con `--logprobs-mode processed_logprobs` para que esto afecte a los logprobs que devuelve; de lo contrario, el maestro informa silenciosamente logprobs crudos y esta configuración solo afecta al lado del estudiante.

teacher_top_k (`int`, *opcional*, valor predeterminado `8`) : Número de tokens candidatos por posición solicitados al maestro a través de `prompt_logprobs`. Solo estos candidatos (más el token realizado, que vLLM siempre informa incluso cuando cae fuera del top-k, más un bucket de cola que captura la masa de probabilidad restante, ver `add_tail_bucket`) se utilizan para aproximar la distribución del maestro; el vocabulario completo nunca se transmite por HTTP. El lado del estudiante de la divergencia es exacto (calculado localmente, no aproximado), ya que el estudiante es el modelo que se está entrenando y sus logits completos ya están disponibles en `compute_loss`. `8` es un valor predeterminado ligero para pruebas de humo; las configuraciones de destilación on-policy de producción en marcos de RL adyacentes utilizan un soporte de maestro disperso en un rango aproximadamente similar (miles predetermina `16`, EasyOPD a `64`), por lo que aumentarlo hacia `16`–`64` es razonable una vez que se entrena de verdad. Cualquier valor superior a `20` requiere que el servidor del maestro se haya iniciado con `--max-logprobs -1`, lo que elimina el límite predeterminado de logprob por token de vLLM.

add_tail_bucket (`bool`, *opcional*, valor predeterminado `True`) : Si se debe agregar un bucket de cola que represente la masa de probabilidad restante fuera de `teacher_top_k`, para evitar una divergencia trivialmente pequeña cuando `teacher_top_k` es pequeño.

token_budget (`int`, *opcional*) : Número máximo de tokens reales empaquetados en una sola fila (el forward de un rank de DP). Un `TokenBudgetBatcher` forma micro-lotes equilibrados en Σ Lᵢ² cuyas filas se mantienen dentro de este presupuesto, limitando la memoria pico de forma independiente al número de muestras (el número de muestras por fila se vuelve dinámico). Si es `None` (predeterminado), se establece en el `max_model_len` del servidor vLLM del estudiante (consultado al inicio del entrenamiento), que es el límite de longitud de prompt + completion, por lo que ninguna muestra de rollout puede superar el presupuesto. Una muestra más larga que `token_budget` no cabe en ninguna fila y se descarta con una advertencia, contándose como `batch/dropped_oversize_count`.

**Parámetros que controlan el pipeline de rollout asíncrono:**

max_concurrent_rollouts (`int`, *opcional*, valor predeterminado `512`) : Número máximo de rollouts en curso simultáneamente contra los servidores vLLM del estudiante y los profesores, ya sea generando o siendo puntuados.

max_staleness (`int`, *opcional*, valor predeterminado `4`) : Número máximo de pasos de actualización de pesos que una muestra de rollout puede rezagar respecto a la versión actual del modelo antes de ser descartada. La generación se limita a esto: un rollout solo comienza mientras los tokens en cola y en vuelo quepan en lo que el entrenador consume en `max(max_staleness, 1)` pasos.

weight_sync_steps (`int`, *opcional*, valor predeterminado `1`) : Número de pasos de entrenamiento entre sincronizaciones de pesos al servidor vLLM del estudiante.

rollout_worker_timeout (`float`, *opcional*, valor predeterminado `300.0`) : Segundos desde el último latido del worker de rollout tras los cuales el trainer lo considera colgado y aborta.

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

log_completions (`bool`, *opcional*, valor predeterminado `False`) : Si se registra una muestra de pares (prompt, completion) cada `log_completions_steps` muestras puntuadas.

log_completions_steps (`int`, *opcional*, valor predeterminado `100`) : Número de muestras puntuadas entre el registro de las finalizaciones. Solo se utiliza si `log_completions` es `True`. Se cuenta en muestras que el trabajador de rollout ha puntuado, no en pasos del optimizador: el trabajador se ejecuta en un proceso separado del entrenador y no tiene visibilidad de `self.state.global_step`.

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

Clase de configuración para [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/main/es/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer).

Esta clase incluye solo los parámetros específicos de la destilación asincrónica on-policy. Para obtener la lista completa de argumentos de entrenamiento, consulte la documentación de [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments). Tenga en cuenta que los valores predeterminados de esta clase pueden diferir de los de [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments). Su estructura refleja la de [AsyncGRPOConfig](/docs/trl/main/es/async_grpo_trainer#trl.AsyncGRPOConfig) (el pipeline asincrónico, el servidor vLLM y los campos de registro son los mismos), con los campos de recorte/grupo de GRPO reemplazados por los campos de pérdida de destilación del maestro a continuación.

> [!NOTE]
> Estos parámetros tienen valores predeterminados diferentes de [TrainingArguments](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments): - `logging_steps`: El valor predeterminado es `1` 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`. - `ignore_data_skip`: El valor predeterminado es `True` en lugar de `False`; el bucle de omisión y reproducción del Trainer base no se aplica a la cola de despliegue asíncrono.

## AsyncDistillationTrainer[[trl.experimental.async_distillation.AsyncDistillationTrainer]]

#### trl.experimental.async_distillation.AsyncDistillationTrainer[[trl.experimental.async_distillation.AsyncDistillationTrainer]]

```python
trl.experimental.async_distillation.AsyncDistillationTrainer(model: str | PreTrainedModel, args: trl.experimental.async_distillation.async_distillation_config.AsyncDistillationConfig | None = None, train_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | 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), peft_config: PeftConfig | None = None)
```

[Fuente](https://github.com/huggingface/trl/blob/main/trl/experimental/async_distillation/async_distillation_trainer.py#L1059)

**Parámetros:**

model (`str` o [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) : Modelo estudiante 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 pesos de modelo guardados usando [save_pretrained](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.save_pretrained). Se carga con [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained). - Un objeto [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel). Su implementación de atención se cambia al backend FlashAttention del trainer para un entrenamiento sin padding.  El nombre del modelo de la configuración se usa para identificar el modelo estudiante en su servidor vLLM.

args ([experimental.async_distillation.AsyncDistillationConfig](/docs/trl/main/es/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationConfig), *opcional*) : Configuración para este entrenador. Si es `None`, se utiliza una configuración predeterminada.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset) o [IterableDataset](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.IterableDataset)): Conjunto de datos para usar en el entrenamiento. Debe incluir una columna `"prompt"` (formato [conversational](dataset_formats#conversational)). Cualquier columna adicional se ignora.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/main/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase), *opcional*) : Clase de procesamiento utilizada para procesar los datos. Si es `None`, se carga desde el nombre del modelo con [from_pretrained](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained). Si no tiene un token de relleno, se utiliza `tokenizer.eos_token`.

callbacks (lista de [TrainerCallback](https://huggingface.co/docs/transformers/main/en/main_classes/callback#transformers.TrainerCallback), *opcional*) : Lista de callbacks para personalizar el bucle de entrenamiento, que se añaden a los callbacks predeterminados (ver [aquí](https://huggingface.co/docs/transformers/main_classes/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, `AdamW` y un programa lineal controlado por `args`.

peft_config ([PeftConfig](https://huggingface.co/docs/peft/main/en/package_reference/config#peft.PeftConfig), *opcional*) : Configuración de PEFT utilizada para envolver el modelo. Si es `None`, el modelo no se envuelve. Cuando el servidor vLLM del estudiante se inició con `--enable-lora`, un adaptador LoRA se sincroniza con él como adaptador en lugar de como pesos fusionados; consulte la sección de LoRA de la documentación de AsyncDistillation.

Contraparte asíncrona de [DistillationTrainer](/docs/trl/main/es/distillation_trainer#trl.DistillationTrainer), diseñada exactamente como [AsyncGRPOTrainer](/docs/trl/main/es/async_grpo_trainer#trl.AsyncGRPOTrainer): un trabajador de rollout en segundo plano genera las completaciones on-policy del estudiante y las puntúa contra un servidor maestro mientras el entrenamiento avanza de forma concurrente, desacoplando el rollout del bucle de actualización de gradientes. Donde la pérdida de gradiente de política recortada de GRPO lee una ventaja relativa al grupo, el `compute_loss` de este entrenador lee una distribución del maestro dispersa por posición y minimiza un JSD generalizado frente a ella (ver `AsyncDistillationConfig.beta`), siempre on-policy: el estudiante genera cada completación sobre la que entrena.

A diferencia del `DistillationTrainer` síncrono, este trainer solo admite la puntuación contra un teacher servido a través de HTTP (un servidor vLLM externo). Una pasada de forward de un teacher local (en proceso, en GPU) no puede ejecutarse dentro del proceso hijo generado del worker de rollout, que tiene CUDA deshabilitado, de la misma manera que lo hacen las funciones de recompensa de GRPO, y en su lugar necesitaría ejecutarse de nuevo en el proceso principal de entrenamiento; esa ruta aún no está implementada.

Ejemplo:

```python
>>> from trl.experimental.async_distillation import AsyncDistillationTrainer
>>> from datasets import load_dataset

>>> dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

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

