# Entrenador de Destilación General de Logits en Línea (GOLD)

[![All_models-GOLD-blue](https://img.shields.io/badge/All_models-GOLD-blue)](https://huggingface.co/models?other=sft,gold)

## Resumen

General Online Logit Distillation (GOLD) es una extensión de Universal Logit Distillation (ULD) que admite pares de estudiante/profesor con tokenizadores diferentes. Alinea los fragmentos de texto generados por ambos tokenizadores y fusiona los logits asociados para que no se descarten tokens de finalización. Esto permite la destilación de conocimiento entre tokenizadores, incluidas familias de modelos mixtas (por ejemplo, estudiantes LLaMA con profesores Qwen).

Capacidades principales:

1. **Alineación entre tokenizadores** – GOLD decodifica de forma incremental los tokens del estudiante y del profesor, agrupa los pasajes con el mismo texto visible y fusiona las probabilidades dentro de cada grupo. Esto garantiza que los términos de pérdida se calculen sobre la finalización completa, incluso cuando los límites de los tokens difieren.
2. **Pérdida ULD híbrida** – cuando `uld_use_hybrid_loss` está habilitado, GOLD compara directamente las coincidencias exactas del vocabulario y recurre a la pérdida ULD de probabilidad ordenada original para los tokens que no coinciden. Esto mejora la estabilidad para estudiantes cuyos vocabularios solo se superponen parcialmente con los del maestro.
3. **Integración sin problemas con GKD** – GOLD hereda la programación on-policy frente a off-policy del [experimental.gkd.GKDTrainer](/docs/trl/v1.18.0/es/gkd_trainer#trl.experimental.gkd.GKDTrainer), por lo que puedes combinar KD a nivel de secuencia, JSD generalizado y destilación entre tokenizadores en una sola ejecución de entrenamiento.

> [!NOTE]
> GOLD forma parte actualmente del espacio de nombres `trl.experimental`. Las API pueden cambiar sin previo aviso mientras se itera sobre la funcionalidad.

## Consejos de uso

El [experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/es/gold_trainer#trl.experimental.gold.GOLDTrainer) es una subclase de [SFTTrainer](/docs/trl/v1.18.0/es/sft_trainer#trl.SFTTrainer) y acepta los mismos conjuntos de datos que otros entrenadores de TRL (listas de mensajes en estilo ChatML). Las banderas de configuración importantes en [experimental.gold.GOLDConfig](/docs/trl/v1.18.0/es/gold_trainer#trl.experimental.gold.GOLDConfig) incluyen:

* `use_uld_loss` – activa Universal Logit Distillation. Establezca este valor en `True` para configuraciones con tokenizadores cruzados.
* `teacher_tokenizer_name_or_path` – obligatorio cuando `use_uld_loss=True`; GOLD usa el tokenizer del teacher para alinear los tokens.
* `uld_use_hybrid_loss`, `uld_hybrid_matched_weight`, `uld_hybrid_unmatched_weight` – habilita y pondera la pérdida híbrida de coincidencias/no coincidencias.
* `beta`, `lmbda`, `seq_kd` – heredados de [experimental.gkd.GKDConfig](/docs/trl/v1.18.0/es/gkd_trainer#trl.experimental.gkd.GKDConfig), controlan la interpolación de JSD generalizada y la proporción de muestreo on-policy.
* `use_privileged_context`, `teacher_prompt_template`, `privileged_context_column` – permite que el teacher vea un contexto adicional por ejemplo mientras que el prompt del student permanece sin cambios. Actualmente, esto está limitado al entrenamiento con texto, off-policy y JSD estándar.
* `num_generations`, `generation_batch_size` – controlan la generación de rollout con búfer a través de las ventanas de acumulación de gradientes. `generation_batch_size` es el número de prompts únicos por trabajador por paso del optimizador.

Un ejemplo mínimo de extremo a extremo:

```python
from datasets import load_dataset
from trl.experimental.gold import GOLDConfig, GOLDTrainer

train_dataset = load_dataset(
    "HuggingFaceTB/OpenR1-Math-220k-default-verified",
    "all",
    split="train[:1024]",
)

trainer = GOLDTrainer(
    model="meta-llama/Llama-3.2-1B-Instruct",
    teacher_model="Qwen/Qwen2.5-0.5B-Instruct",
    args=GOLDConfig(output_dir="gold-model", use_uld_loss=True, teacher_tokenizer_name_or_path="Qwen/Qwen2.5-0.5B-Instruct"),
    train_dataset=train_dataset,
)
trainer.train()
```

Para flujos de trabajo de inicio rápido, puede confiar en los identificadores de cadena mostrados anteriormente: el trainer cargará el modelo y el tokenizer por usted. Instanciar explícitamente `AutoModelForCausalLM`, `AutoTokenizer` o completar `GOLDConfig` se recomienda solo para casos de uso avanzados en los que se necesite un control detallado sobre la inicialización.

Una configuración más explícita podría verse así cuando necesitas personalizar la carga del modelo, la configuración del tokenizador o los argumentos de entrenamiento:

```python
from datasets import load_dataset
from trl.experimental.gold import GOLDConfig, GOLDTrainer
from transformers import AutoModelForCausalLM, AutoTokenizer

student_name = "meta-llama/Llama-3.2-1B-Instruct"
teacher_name = "Qwen/Qwen2.5-0.5B-Instruct"

tokenizer = AutoTokenizer.from_pretrained(student_name)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

model = AutoModelForCausalLM.from_pretrained(student_name)
teacher_model = AutoModelForCausalLM.from_pretrained(teacher_name)

train_dataset = load_dataset(
    "HuggingFaceTB/Countdown-Task-GOLD",
    "verified_Qwen2.5-0.5B-Instruct",
    split="train",
)

training_args = GOLDConfig(
    output_dir="gold-model",
    per_device_train_batch_size=1,
    teacher_model_name_or_path=teacher_name,
    teacher_tokenizer_name_or_path=teacher_name,
    use_uld_loss=True,
    uld_use_hybrid_loss=True,
)

trainer = GOLDTrainer(
    model=model,
    teacher_model=teacher_model,
    args=training_args,
    processing_class=tokenizer,
    train_dataset=train_dataset,
)
trainer.train()
```

> [!NOTE]
> GOLD almacena un lote completo de generación de la ventana del optimizador (`per_device_train_batch_size * gradient_accumulation_steps`) y lo reutiliza a lo largo de los pasos de acumulación. Si el lote final tiene un tamaño insuficiente, GOLD emite una advertencia y descarta ese último lote (`Dropping last batch due to unexpected batch size`). Establezca `dataloader_drop_last=True` para evitar esta advertencia.

### Tipo de conjunto de datos esperado

GOLD requiere un conjunto de datos de [conversación](dataset_formats#conversational) de [modelado de lenguaje](dataset_formats#language-modeling), por ejemplo:

```python
{"messages": [{"role": "user", "content": "What color is the sky?"},
              {"role": "assistant", "content": "It is blue."}]}
```

`GOLDTrainer` conserva los mensajes crudos para que el collator de ChatML pueda construir los prompts y las completions con los límites correctos.

## Contexto privilegiado

La destilación con contexto privilegiado proporciona al modelo maestro información adicional que no está disponible para el modelo estudiante en el momento de la inferencia. Añade una columna de contexto a un conjunto de datos normal de prompt/completado y luego habilita la función de forma explícita:

```python
from datasets import Dataset

dataset = Dataset.from_list(
    [
        {
            "prompt": [{"role": "user", "content": "What caused the outage?"}],
            "completion": [{"role": "assistant", "content": "A timeout change caused the outage."}],
            "privileged_context": "The deployment changed the timeout immediately before errors began.",
        }
    ]
)

args = GOLDConfig(
    output_dir="gold-model",
    lmbda=0.0,
    use_privileged_context=True,
)
```

El estudiante se entrena con el prompt y la finalización originales. El profesor recibe un prompt separado construido por defecto a partir de `"{prompt}\n\n{privileged_context}"` y luego puntúa la misma finalización exacta. Para datos conversacionales, GOLD reescribe solo el turno final del usuario antes de reaplicar la plantilla de chat; los turnos de sistema, herramienta y asistente permanecen sin cambios. Establezca `teacher_prompt_template` para personalizar este prompt y `privileged_context_column` para usar una columna distinta de `"privileged_context"`.

El prompt del modelo maestro nunca se trunca, por lo que asegúrese de que quepa dentro de la ventana de contexto del modelo maestro. Este soporte inicial está limitado intencionalmente a texto y a destilación estándar JSD off-policy: `lmbda` debe ser `0`, y `seq_kd=True`, `use_uld_loss=True`, X-Token KD (`xtoken_loss_type` distinto de `"none"`), packing, VLMs y Liger Kernel no son compatibles con contexto privilegiado.

## Cómo funciona la fusión de tokens

Cuando el estudiante y el profesor utilizan tokenizadores diferentes, el mismo texto puede dividirse de manera distinta:

- **Estudiante**: `"Hugging Face"` → 1 token
- **Teacher**: `"Hugging"`, `" Face"` → 2 tokens

GOLD alinea estas secuencias y fusiona las probabilidades de múltiples tokens del modelo maestro en una única distribución que puede compararse con la distribución de un solo token del modelo estudiante.

### Fusión de probabilidades

Para una secuencia de tokens de maestro `[token₀, token₁, ..., tokenₖ]` que se mapea a un único token de estudiante, GOLD calcula:

```
P_merged(y) = P(y | context) × P(token₁ | token₀, context) × ... × P(tokenₖ | ..., context)
```

donde:
- `P(y | context)` es la distribución de probabilidad marginal sobre todos los tokens del vocabulario en la primera posición
- `P(tokenᵢ | ..., context)` son probabilidades condicionales **escalares** de los tokens reales que se generaron

**Insight clave**: solo se extraen como escalares las probabilidades condicionales de los **tokens de continuación reales**. La distribución marginal completa en la primera posición se escala entonces multiplicando estas probabilidades escalares.

Esto garantiza:
1. **Probabilidad conjunta correcta** para la secuencia generada real (mediante la regla de la cadena)
2. **Aproximación razonable** para los tokens contrafactuales (escalados por la misma probabilidad de continuación)
3. **Distribuciones no normalizadas** que preservan las probabilidades relativas correctas para el cálculo de la pérdida ULD

### Ejemplo

Dado:
```
P(x₀):         ["HF": 0.6,  "is": 0.3,  "cool": 0.1]
P(x₁ | "HF"):  ["HF": 0.05, "is": 0.9,  "cool": 0.05]
```

Si los tokens 0 y 1 se fusionan, y la secuencia real era `["HF", "is"]`:
```
P_merged("HF")   = 0.6 × 0.9 = 0.54  ✓ (correct joint probability)
P_merged("is")   = 0.3 × 0.9 = 0.27
P_merged("cool") = 0.1 × 0.9 = 0.09
```

La distribución combinada no está normalizada (suma 0.81), pero esto es intencional y correcto para el cálculo de la pérdida ULD, que utiliza ordenamiento y distancia L1.

## Script de ejemplo

Use [`examples/gold_chatbot_arena/gold_chatbot_arena.py`](https://github.com/huggingface/trl/blob/main/examples/gold_chatbot_arena/gold_chatbot_arena.py) para iniciar el entrenamiento de GOLD desde la línea de comandos. El script admite el entrenamiento completo y LoRA mediante las banderas estándar de `ModelConfig`.

```bash
python examples/gold_chatbot_arena/gold_chatbot_arena.py \
    --model_name_or_path meta-llama/Llama-3.2-1B-Instruct \
    --teacher_model_name_or_path Qwen/Qwen2-1.5B-Instruct \
    --dataset_name trl-lib/chatbot_arena_completions \
    --learning_rate 2e-5 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --output_dir gold-model \
    --num_train_epochs 1 \
    --push_to_hub
```

## Entrenamiento de modelos de visión y lenguaje

[experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/es/gold_trainer#trl.experimental.gold.GOLDTrainer) admite la destilación de VLM a VLM. Tanto el estudiante como el maestro deben ser modelos de visión-lenguaje. Para entrenar un VLM, proporcione un conjunto de datos con una columna `image` (una imagen por muestra) o una columna `images` (lista de imágenes por muestra). Para obtener más información sobre la estructura esperada del conjunto de datos, consulte la sección [Formato del conjunto de datos — Conjuntos de datos de visión](dataset_formats#vision-datasets).

Cuando el estudiante y el profesor comparten la misma arquitectura y tokenizador (p. ej., de Qwen3-VL-8B a Qwen3-VL-2B), la pérdida JSD generalizada estándar se aplica directamente. Cuando tienen un `model_type` diferente (p. ej., de Qwen3-VL a LFM2.5-VL), establezca `use_uld_loss=True` para habilitar la alineación entre tokenizadores mediante Universal Logit Distillation. Las imágenes se procesan de forma independiente a través del procesador de cada modelo.

```python
from datasets import load_dataset
import torch
from transformers import AutoModelForImageTextToText, AutoProcessor
from trl.experimental.gold import GOLDConfig, GOLDTrainer

student_name = "Qwen/Qwen3-VL-2B-Instruct"
teacher_name = "Qwen/Qwen3-VL-8B-Instruct"

processor = AutoProcessor.from_pretrained(student_name, padding_side="left")
student_model = AutoModelForImageTextToText.from_pretrained(student_name, dtype=torch.bfloat16)
teacher_model = AutoModelForImageTextToText.from_pretrained(teacher_name, dtype=torch.bfloat16)

train_dataset = load_dataset("trl-lib/llava-instruct-mix", split="train")

trainer = GOLDTrainer(
    model=student_model,
    teacher_model=teacher_model,
    args=GOLDConfig(
        output_dir="gold-vlm-model",
        max_length=None,
        teacher_model_name_or_path=teacher_name,
        use_uld_loss=False,
    ),
    train_dataset=train_dataset,
    processing_class=processor,
)
trainer.train()
```

Para la destilación entre familias, establezca `use_uld_loss=True` y `teacher_tokenizer_name_or_path` en el nombre del modelo maestro.

Use [`examples/gold_qwen3_vl/gold_qwen3_vl.py`](https://github.com/huggingface/trl/blob/main/examples/gold_qwen3_vl/gold_qwen3_vl.py) para iniciar el entrenamiento de GOLD VLM desde la línea de comandos:

```bash
# Same-family distillation (JSD loss, vLLM enabled)
torchrun --nproc_per_node 8 examples/gold_qwen3_vl/gold_qwen3_vl.py \
    --student_model_name Qwen/Qwen3-VL-2B-Instruct \
    --teacher_model_name Qwen/Qwen3-VL-8B-Instruct

# Cross-family distillation (ULD loss, local generation)
torchrun --nproc_per_node 8 examples/gold_qwen3_vl/gold_qwen3_vl.py \
    --student_model_name LiquidAI/LFM2.5-VL-1.6B \
    --teacher_model_name Qwen/Qwen3-VL-8B-Instruct \
    --use_uld_loss \
    --no-use_vllm
```

> [!TIP]
> Para los VLM, `truncation_mode='keep_end'` no está soportado porque los tokens de imagen se encuentran en la parte de la secuencia correspondiente al prompt y podrían eliminarse de forma silenciosa. Utilice `truncation_mode='keep_start'` (el valor predeterminado) o establezca `max_length=None` en [experimental.gold.GOLDConfig](/docs/trl/v1.18.0/es/gold_trainer#trl.experimental.gold.GOLDConfig). Esto permite que el modelo procese la longitud completa de la secuencia sin truncar los tokens de imagen.
>
> ```python
> GOLDConfig(max_length=None, ...)
> ```
>
> Solo usa `max_length` cuando hayas verificado que la truncación no eliminará los tokens de imagen para todo el conjunto de datos.

> [!NOTE]
> La destilación de VLM entre arquitecturas requiere `use_uld_loss=True`. El entrenador generará un error si se intenta una destilación entre arquitecturas sin la pérdida ULD.

## GOLDTrainer[[trl.experimental.gold.GOLDTrainer]]

#### trl.experimental.gold.GOLDTrainer[[trl.experimental.gold.GOLDTrainer]]

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

[Fuente](https://github.com/huggingface/trl/blob/v1.18.0/trl/experimental/gold/gold_trainer.py#L1233)

#### train[[trl.experimental.gold.GOLDTrainer.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.0/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.

#### generate_on_policy_outputs[[trl.experimental.gold.GOLDTrainer.generate_on_policy_outputs]]

```python
generate_on_policy_outputs(model, inputs, generation_config)
```

[Fuente](https://github.com/huggingface/trl/blob/v1.18.0/trl/experimental/gold/gold_trainer.py#L3356)

#### save_model[[trl.experimental.gold.GOLDTrainer.save_model]]

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

[Fuente](https://github.com/huggingface/trl/blob/v1.18.0/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.experimental.gold.GOLDTrainer.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.0/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`.

## GOLDConfig[[trl.experimental.gold.GOLDConfig]]

#### trl.experimental.gold.GOLDConfig[[trl.experimental.gold.GOLDConfig]]

```python
trl.experimental.gold.GOLDConfig(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-07, lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool | None = None, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool = True, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 10, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = False, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: accelerate.parallelism_config.ParallelismConfig | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool = True, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1, model_init_kwargs: dict[str, typing.Any] | str | None = None, trust_remote_code: bool = False, router_aux_loss_coef: float | None = None, chat_template_path: str | None = None, dataset_text_field: str = 'text', dataset_kwargs: dict[str, typing.Any] | str | None = None, dataset_num_proc: int | None = None, eos_token: str | None = None, max_length: int | None = 1024, truncation_mode: str = 'keep_start', shuffle_dataset: bool = False, packing: bool = False, packing_strategy: str = 'bfd', padding_free: bool = False, pad_to_multiple_of: int | str | None = 'auto', eval_packing: bool | None = None, completion_only_loss: bool | None = None, assistant_only_loss: bool = False, loss_type: str = 'nll', activation_offloading: bool = False, pad_token: str | None = None, temperature: float = 0.9, top_p: float = 0.95, top_k: int = 0, lmbda: float = 0.5, beta: float = 0.5, max_completion_length: int = 128, 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, teacher_tokenizer_name_or_path: str | None = None, disable_dropout: bool = True, seq_kd: bool = False, use_privileged_context: bool = False, teacher_prompt_template: str | None = None, privileged_context_column: str = 'privileged_context', num_generations: int = 1, generation_batch_size: int | None = None, use_uld_loss: bool = False, uld_token_merge_strategy: str = 'observed', use_extended_uld: bool = True, uld_use_hybrid_loss: bool = False, uld_hybrid_matched_weight: float | None = None, uld_hybrid_unmatched_weight: float | None = None, uld_crossentropy_weight: float = 0.0, uld_distillation_weight: float = 1.0, uld_student_temperature: float = 1.0, uld_teacher_temperature: float = 1.0, uld_skip_student_eos: bool = True, uld_skip_teacher_eos: bool = True, xtoken_loss_type: str = 'none', xtoken_projection_matrix_path: str | None = None, xtoken_temperature: float = 1.0, xtoken_dynamic_scaling: bool = True, xtoken_uncommon_topk: int = 8192, xtoken_vocab_topk: int = 8192, xtoken_kl_weight: float = 1.0, xtoken_ce_scale: float = 0.1, use_vllm: bool = False, vllm_mode: str = 'colocate', vllm_server_base_url: str | None = None, vllm_server_host: str = '0.0.0.0', vllm_server_port: int = 8001, vllm_server_timeout: float = 240.0, vllm_group_port: int = 51216, vllm_gpu_memory_utilization: float = 0.9, vllm_tensor_parallel_size: int = 1, vllm_max_model_length: int | None = None, vllm_model_impl: str = 'vllm', vllm_structured_outputs_regex: str | None = None, vllm_sync_frequency: int = 1, vllm_enable_sleep_mode: bool = False, log_completions: bool = False, log_completions_steps: int = 100, num_completions_to_print: int | None = None, wandb_log_unique_prompts: bool = True, callbacks: list[str] = <factory>)
```

[Fuente](https://github.com/huggingface/trl/blob/v1.18.0/trl/experimental/gold/gold_config.py#L23)

**Parámetros que controlan la generación y el bucle de entrenamiento:**

temperature (`float`, *opcional*, valor predeterminado `0.9`) : Temperatura para el muestreo. A mayor temperatura, más aleatorias son las completaciones.

top_p (`float`, *opcional*, valor predeterminado `0.95`) : Si se establece en un float < 1, solo se conservan para la generación el conjunto más pequeño de tokens más probables cuyas probabilidades sumen `top_p` o más.

top_k (`int`, *opcional*, valor predeterminado `0`) : Número de tokens del vocabulario con mayor probabilidad que se conservan para el filtrado top-k. Si es `0`, el filtrado top-k se desactiva y se consideran todos los tokens.

lmbda (`float`, *opcional*, valor predeterminado `0.5`) : Parámetro lambda que controla la fracción de datos del estudiante (es decir, la proporción de salidas generadas por el estudiante en la política).

beta (`float`, *opcional*, valor predeterminado `0.5`) : Coeficiente de interpolación entre `0.0` y `1.0` de la pérdida de Divergencia Generalizada de Jensen-Shannon. Cuando beta es `0.0`, la pérdida es la divergencia KL. Cuando beta es `1.0`, la pérdida es la Divergencia KL Inversa.

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

teacher_model_name_or_path (`str`, *opcional*) : Nombre o ruta del modelo maestro. Si es `None`, el modelo maestro será el mismo que el modelo que se está entrenando.

teacher_model_revision (`str` o `None`, *opcional*, valor predeterminado `None`) : Revisión del modelo del maestro (p. ej., nombre de rama, etiqueta o hash de commit). Si es `None`, se utiliza la revisión predeterminada.

teacher_model_init_kwargs (`dict[str, Any]`, *opcional*) : Argumentos de palabra clave para pasar a `AutoModelForCausalLM.from_pretrained` al instanciar el modelo maestro desde una cadena. El valor de `revision` también se utiliza al cargar la clase de procesamiento del maestro.

teacher_tokenizer_name_or_path (`str`, *opcional*) : Nombre o ruta del tokenizador para el modelo maestro. Si es None al usar la pérdida ULD, se utilizará el mismo tokenizador que el modelo estudiante (no recomendado para destilación entre tokenizadores).

disable_dropout (`bool`, *opcional*, valor predeterminado `True`) : Si se debe desactivar el dropout en el modelo.

seq_kd (`bool`, *opcional*, valor predeterminado `False`) : Parámetro de Seq_kd que controla si se realiza KD a nivel de secuencia (se puede ver como FT supervisado sobre la salida generada por el maestro).

use_privileged_context (`bool`, *opcional*, valor predeterminado `False`) : Si se debe condicionar al maestro con un contexto privilegiado por ejemplo, manteniendo el prompt del estudiante sin cambios. Esto solo se admite para texto, en la destilación estándar JSD off-policy.

teacher_prompt_template (`str`, *opcional*) : Plantilla utilizada para construir el prompt del teacher. Debe contener `{prompt}` y puede contener `{privileged_context}`. Cuando es `None`, el valor predeterminado es `"{prompt}\n\n{privileged_context}"`.

privileged_context_column (`str`, *opcional*, valor predeterminado `"privileged_context"`) : Columna del conjunto de datos que contiene el contexto privilegiado por ejemplo utilizado para construir el prompt del maestro.

num_generations (`int`, *opcional*, valor predeterminado `1`) : Número de generaciones por prompt. Cada prompt se repite esta cantidad de veces en el lote de generación.

generation_batch_size (`int` o `None`, *opcional*, valor predeterminado `None`) : Número de prompts únicos por worker por paso del optimizador. Si es `None`, se calcula a partir de `(per_device_train_batch_size * gradient_accumulation_steps) // num_generations`.

**Parámetros que controlan la pérdida ULD:**

use_uld_loss (`bool`, *opcional*, valor predeterminado `False`) : Si se debe usar la pérdida Universal Logit Distillation (ULD) en lugar de la pérdida Generalized Jensen-Shannon Divergence.

use_extended_uld (`bool`, *opcional*, valor predeterminado `True`) : Si se habilita la alineación ULD extendida que utiliza tokenizadores para alinear y fusionar las probabilidades de tokens entre las tokenizaciones del estudiante y del maestro. Cuando es `True`, el entrenador calculará los mapeos de tokens y fusionará las probabilidades de los tokens divididos; cuando es `False`, ULD utilizará una truncación posicional simple, como en el artículo original de ULD. Establezca `False` para tokenizadores que no sean de ByteLevel ni BPE con respaldo de bytes (p. ej., Llama 2).

uld_token_merge_strategy (`str`, *opcional*, valor predeterminado `"observed"`) : Estrategia utilizada para alinear los logits de la respuesta y fusionar las probabilidades de los tokens en la pérdida ULD. Con `"observed"`, los logits de la respuesta se recortan en las posiciones de la respuesta y los tokens divididos (cuando `use_extended_uld=True`) se fusionan multiplicando la distribución marginal en la primera posición por las probabilidades condicionales escalares de los tokens posteriores reales. Con `"bayesian"`, el recorte de los logits de la respuesta se desplaza una posición hacia atrás para que `probs[k]` prediga `token_ids[k]` (regla de la cadena), y los tokens divididos se fusionan utilizando la distribución completa de la última posición, condicionada a los tokens del prefijo reales, multiplicada por las probabilidades escalares de los tokens anteriores. El desplazamiento de alineación de los logits se aplica independientemente de si `use_extended_uld` está habilitado o no.

uld_use_hybrid_loss (`bool`, *opcional*, valor predeterminado `False`) : Si se debe utilizar una pérdida híbrida que combina la pérdida ULD y la pérdida JSD. Cuando es `True`, la pérdida final es una combinación de JSD para las correspondencias de tokens conocidas y ULD para las correspondencias de tokens desconocidas.

uld_hybrid_matched_weight (`float` o `None`, *opcional*) : Peso para el componente de pérdida de tokens coincidentes al usar la pérdida híbrida ULD + JSD. Este peso escala la pérdida JSD calculada sobre los tokens que tienen un mapeo directo entre las tokenizaciones del estudiante y del maestro. Si es `None`, se usa un peso adaptativo basado en la superposición de vocabularios. Debe establecerse junto con `uld_hybrid_unmatched_weight` (ambos `None` o ambos `float`).

uld_hybrid_unmatched_weight (`float` o `None`, *opcional*) : Peso para el componente de pérdida de tokens no coincidentes al usar la pérdida híbrida ULD + JSD. Este peso escala la pérdida ULD calculada sobre los tokens que no tienen un mapeo directo entre las tokenizaciones del estudiante y del maestro. Si es `None`, se utiliza un ponderado adaptativo basado en la superposición de vocabularios. Debe establecerse junto con `uld_hybrid_matched_weight` (ambos `None` o ambos `float`).

uld_crossentropy_weight (`float`, *opcional*, valor predeterminado `0.0`) : Peso para el componente de pérdida de entropía cruzada en la pérdida ULD. Si es 0, solo se utiliza la pérdida de destilación ULD.

uld_distillation_weight (`float`, *opcional*, valor predeterminado `1.0`) : Peso para el componente de pérdida de destilación en la pérdida ULD.

uld_student_temperature (`float`, *opcional*, valor predeterminado `1.0`) : Temperatura para los logits del estudiante en el cálculo de la pérdida ULD.

uld_teacher_temperature (`float`, *opcional*, valor predeterminado `1.0`) : Temperatura para los logits del maestro en el cálculo de la pérdida ULD.

uld_skip_student_eos (`bool`, *opcional*, valor predeterminado `True`) : Si se debe omitir el token EOS para el estudiante en el cálculo de la pérdida ULD.

uld_skip_teacher_eos (`bool`, *opcional*, valor predeterminado `True`) : Si se debe omitir el token EOS del maestro en el cálculo de la pérdida ULD.

**Parámetros para KD de tokenización cruzada X-Token (https:**

xtoken_loss_type (`str`, *opcional*, valor predeterminado `"none"`) : Variante de KD entre tokenizadores: `"none"` (deshabilitado), `"p_kl"` (KL de proyección) o `"h_kl"` (KL híbrido con conjunto común relajado). Requiere `teacher_tokenizer_name_or_path` y `xtoken_projection_matrix_path`.

xtoken_projection_matrix_path (`str`, *opcional*) : Ruta a un archivo de matriz de proyección precalculada. Obligatorio cuando `xtoken_loss_type != "none"`.

xtoken_temperature (`float`, *opcional*, valor predeterminado `1.0`) : Temperatura T para la pérdida KD de X-Token; la pérdida se multiplica por T² (Hinton 2015).

xtoken_dynamic_scaling (`bool`, *opcional*, valor predeterminado `True`) : Escala KD por `stop_gradient(abs(CE) / abs(KD))` por microbatch para equilibrar las magnitudes de la pérdida (Ecuación 7 del artículo).

xtoken_uncommon_topk (`int`, *opcional*, valor predeterminado `8192`) : H-KL: limita la comparación poco frecuente de sorted-L1 a los top-k tokens por lado.

xtoken_vocab_topk (`int`, *opcional*, valor predeterminado `8192`) : P-KL: restringe la KL a los top-k globales de tokens del maestro según el logit máximo. Interactúa con la matriz de proyección `--top-k`: los tokens del maestro que quedan fuera del alcance de la matriz reciben una masa proyectada del estudiante cercana a cero y dominan la KL, por lo que valores más pequeños concentran la pérdida en tokens que el estudiante puede igualar.

xtoken_kl_weight (`float`, *opcional*, valor predeterminado `1.0`) : Peso para el término KD de X-Token cuando `xtoken_dynamic_scaling=False`.

xtoken_ce_scale (`float`, *opcional*, valor predeterminado `0.1`) : Factor de escala para el término de CE en la pérdida de X-Token cuando `xtoken_dynamic_scaling=False`.

**Parámetros que controlan la integración de vLLM:**

use_vllm (`bool`, *opcional*, valor predeterminado `False`) : Si se debe usar vLLM para generar completados desde el modelo estudiante. Requiere que `vllm` esté instalado.

vllm_mode (`str`, *opcional*, valor predeterminado `"colocate"`) : Modo para la integración de vLLM del estudiante. Puede ser `"server"` (conectar a un servidor vLLM en ejecución) o `"colocate"` (ejecutar vLLM en el mismo proceso).

vllm_server_host (`str`, *opcional*, valor predeterminado `"0.0.0.0"`) : Host del servidor de vLLM para el modelo estudiante (si `vllm_mode="server"`).

vllm_server_port (`int`, *opcional*, valor predeterminado `8001`) : Puerto del servidor de vLLM para el modelo estudiante (si `vllm_mode="server"`).

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

vllm_gpu_memory_utilization (`float`, *opcional*, valor predeterminado `0.9`) : utilización de la memoria de GPU para el motor vLLM del estudiante colocalizado (si `vllm_mode="colocate"`). Se recomienda establecer este valor en un número bajo si los modelos de estudiante y profesor comparten la misma GPU.

vllm_tensor_parallel_size (`int`, *opcional*, valor predeterminado `1`) : Tamaño de paralelismo de tensor para el motor vLLM del estudiante coubicado (si `vllm_mode="colocate"`).

vllm_structured_outputs_regex (`str`, *opcional*) : Expresión regular para las salidas estructuradas de vLLM del modelo estudiante.

vllm_server_base_url (`str`, *opcional*) : URL base para el servidor vLLM (p. ej., `"http://localhost:8001"`). Si se proporciona, `vllm_server_host` y `vllm_server_port` se ignoran.

vllm_group_port (`int`, *opcional*, valor predeterminado `51216`) : Puerto para el grupo de actualización de pesos de vLLM (comunicador NCCL). A menos que el puerto esté ocupado, no es necesario cambiarlo.

vllm_max_model_length (`int`, *opcional*) : Longitud máxima de la secuencia del modelo para el motor vLLM colocalizado cuando `vllm_mode="colocate"`. Por defecto, es la longitud máxima de contexto del modelo.

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

vllm_sync_frequency (`int`, *opcional*, valor predeterminado `1`) : Frecuencia (en pasos de entrenamiento) para sincronizar los pesos del modelo estudiante con el motor de vLLM. Establezca 1 para sincronizar después de cada paso.

vllm_enable_sleep_mode (`bool`, *opcional*, valor predeterminado `False`) : Habilita el modo de suspensión de vLLM para descargar los pesos/caché del estudiante durante el paso del optimizador. Mantiene bajo el uso de memoria de GPU, pero despertar el motor añade latencia de transferencia entre host y dispositivo.

**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` está habilitado, lo registra en `wandb`.

log_completions_steps (`int`, *opcional*, valor predeterminado `100`) : Número de pasos entre el registro de pares (prompt, completion). Solo se utiliza si `log_completions` está establecido en `True`.

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

wandb_log_unique_prompts (`bool`, *opcional*, valor predeterminado `True`) : Si se registran los prompts únicos en wandb. Esto creará una nueva ejecución para cada prompt único.

callbacks (`list[str]`, *opcional*, valor predeterminado `[]`) : Los callbacks que se ejecutarán durante el entrenamiento.

Clase de configuración para [experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/es/gold_trainer#trl.experimental.gold.GOLDTrainer).

Esta clase incluye solo los parámetros específicos para el entrenamiento con GOLD. Para obtener la lista completa de argumentos de entrenamiento, consulte la documentación de [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments) y [SFTConfig](/docs/trl/v1.18.0/es/sft_trainer#trl.SFTConfig).

> [!NOTE]
> Estos parámetros tienen valores predeterminados diferentes a los de [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments): - `learning_rate`: El valor predeterminado es `1e-7` en lugar de `5e-5`.

