TRL documentation

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

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v1.18.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

All_models-GOLD-blue

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, por lo que puedes combinar KD a nivel de secuencia, JSD generalizado y destilación entre tokenizadores en una sola ejecución de entrenamiento.

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 es una subclase de 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 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, 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 estándar-JSD con texto y off-policy.
  • 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:

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:

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

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 de modelado de lenguaje, por ejemplo:

{"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:

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 completion originales. El profesor recibe un prompt separado construido por defecto a partir de "{prompt}\n\n{privileged_context}" y luego puntúa la misma completion exacta. Para datos conversacionales, GOLD reescribe solo el turno final del usuario antes de reaplicar la plantilla de chat; los turnos de system, tool y assistant permanecen sin cambios. Establece 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 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.

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

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.

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 para iniciar el entrenamiento de GOLD VLM desde la línea de comandos:

# 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

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. Esto permite que el modelo procese la longitud completa de la secuencia sin truncar los tokens de imagen.

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.

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

clase trl.experimental.gold.GOLDTrainer

< >

( model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, str, NoneType] = Noneteacher_model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, str] = Noneargs: trl.experimental.gold.gold_config.GOLDConfig | None = Nonedata_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | None = Noneeval_dataset: datasets.arrow_dataset.Dataset | dict[str, datasets.arrow_dataset.Dataset] | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.image_processing_utils.BaseImageProcessor | transformers.feature_extraction_utils.FeatureExtractionMixin | transformers.processing_utils.ProcessorMixin | None = Nonecompute_metrics: collections.abc.Callable[[transformers.trainer_utils.EvalPrediction], dict] | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: 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 = Nonepeft_config: typing.Optional[ForwardRef('PeftConfig')] = None )

entrenar

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput

Parámetros

  • resume_from_checkpoint (str o bool, opcional) — Si es una 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 tu 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

< >

( modelinputsgeneration_config )

save_model

< >

( output_dir: str | None = None_internal_call: bool = False )

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

Solo se guardará desde el proceso principal.

push_to_hub

< >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )

Parámetros

  • commit_message (str, opcional, valor predeterminado "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 el repositorio privado cuando se crea. El valor predeterminado es args.hub_private_repo. No tiene efecto si el repositorio ya existe.
  • kwargs (dict[str, Any], opcional) — Argumentos de palabra clave adicionales que se pasan a ~Trainer.create_model_card.

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

GOLDConfig

clase trl.experimental.gold.GOLDConfig

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-07lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool | None = Nonefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool | None = Nonegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 10logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Falserestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: accelerate.parallelism_config.ParallelismConfig | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Truelabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1model_init_kwargs: dict[str, typing.Any] | str | None = Nonetrust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonechat_template_path: str | None = Nonedataset_text_field: str = 'text'dataset_kwargs: dict[str, typing.Any] | str | None = Nonedataset_num_proc: int | None = Noneeos_token: str | None = Nonemax_length: int | None = 1024truncation_mode: str = 'keep_start'shuffle_dataset: bool = Falsepacking: bool = Falsepacking_strategy: str = 'bfd'padding_free: bool = Falsepad_to_multiple_of: int | str | None = 'auto'eval_packing: bool | None = Nonecompletion_only_loss: bool | None = Noneassistant_only_loss: bool = Falseloss_type: str = 'nll'activation_offloading: bool = Falsepad_token: str | None = Nonetemperature: float = 0.9top_p: float = 0.95top_k: int = 0lmbda: float = 0.5beta: float = 0.5max_completion_length: int = 128teacher_model_name_or_path: str | None = Noneteacher_model_revision: str | None = Noneteacher_model_init_kwargs: dict[str, typing.Any] | str | None = Noneteacher_tokenizer_name_or_path: str | None = Nonedisable_dropout: bool = Trueseq_kd: bool = Falseuse_privileged_context: bool = Falseteacher_prompt_template: str | None = Noneprivileged_context_column: str = 'privileged_context'num_generations: int = 1generation_batch_size: int | None = Noneuse_uld_loss: bool = Falseuld_token_merge_strategy: str = 'observed'use_extended_uld: bool = Trueuld_use_hybrid_loss: bool = Falseuld_hybrid_matched_weight: float | None = Noneuld_hybrid_unmatched_weight: float | None = Noneuld_crossentropy_weight: float = 0.0uld_distillation_weight: float = 1.0uld_student_temperature: float = 1.0uld_teacher_temperature: float = 1.0uld_skip_student_eos: bool = Trueuld_skip_teacher_eos: bool = Truextoken_loss_type: str = 'none'xtoken_projection_matrix_path: str | None = Nonextoken_temperature: float = 1.0xtoken_dynamic_scaling: bool = Truextoken_uncommon_topk: int = 8192xtoken_vocab_topk: int = 8192xtoken_kl_weight: float = 1.0xtoken_ce_scale: float = 0.1use_vllm: bool = Falsevllm_mode: str = 'colocate'vllm_server_base_url: str | None = Nonevllm_server_host: str = '0.0.0.0'vllm_server_port: int = 8001vllm_server_timeout: float = 240.0vllm_group_port: int = 51216vllm_gpu_memory_utilization: float = 0.9vllm_tensor_parallel_size: int = 1vllm_max_model_length: int | None = Nonevllm_model_impl: str = 'vllm'vllm_structured_outputs_regex: str | None = Nonevllm_sync_frequency: int = 1vllm_enable_sleep_mode: bool = Falselog_completions: bool = Falselog_completions_steps: int = 100num_completions_to_print: int | None = Nonewandb_log_unique_prompts: bool = Truecallbacks: list[str] = <factory> )

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 finalizaciones.
  • 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 que se generarán por cada finalización.
  • teacher_model_name_or_path (str, opcional) — Nombre o ruta del modelo de maestro. Si es None, el modelo de 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 modelo 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 teacher desde una cadena. El valor de revision también se utiliza al cargar la clase de procesamiento del teacher.
  • teacher_tokenizer_name_or_path (str, opcional) — Nombre o ruta del tokenizador para el modelo teacher. Si es None al usar la pérdida ULD, se utilizará el mismo tokenizador que el modelo student (no recomendado para destilación entre tokenizadores).
  • disable_dropout (bool, opcional, valor predeterminado True) — Si se debe deshabilitar el dropout en el modelo.
  • seq_kd (bool, opcional, valor predeterminado False) — Parámetro que controla si se debe realizar KD a nivel de secuencia (puede considerarse como FT supervisado sobre la salida generada por el teacher).
  • 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 trabajador 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 tokenizers para alinear y fusionar las probabilidades de tokens entre las tokenizaciones del estudiante y del profesor. Cuando True, el trainer calculará los mapeos de tokens y fusionará las probabilidades de los tokens divididos; cuando False, ULD utilizará una truncación posicional simple, como en el artículo original de ULD. Establezca False para tokenizers que no son ni ByteLevel ni BPE con byte-fallback (p. ej. Llama 2).
  • uld_token_merge_strategy (str, opcional, valor predeterminado "observed") — Estrategia utilizada para alinear los logits de respuesta y fusionar las probabilidades de tokens en la pérdida ULD. Con "observed", los logits de 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 logits de 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 fusionen utilizando la distribución completa de la última posición, condicionada a los tokens de prefijo reales, multiplicada por las probabilidades escalares de los tokens anteriores. El desplazamiento de alineación de logits se aplica independientemente de si use_extended_uld está habilitado.
  • 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 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, 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 peso 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 docente 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 para el teacher 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 no común de L1 ordenado 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 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 tensores 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 del 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 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, valor predeterminado "vllm") — Backend de implementación del modelo a utilizar en vLLM. Use "vllm" (predeterminado) 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 vLLM. Establezca 1 para sincronizar después de cada paso.
  • vllm_enable_sleep_mode (bool, opcional, valor predeterminado False) — Activa el modo de suspensión de vLLM para descargar los pesos/caché del estudiante durante el paso del optimizador. Mantiene el uso de memoria de GPU bajo, pero despertar el motor añade latencia de transferencia host-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 completions que se imprimen con rich. Si es None, se registran todas las completions.
  • 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.

Esta clase incluye solo los parámetros específicos del entrenamiento GOLD. Para obtener la lista completa de argumentos de entrenamiento, consulte la documentación de TrainingArguments y SFTConfig.

Estos parámetros tienen valores predeterminados diferentes de TrainingArguments:

  • learning_rate: El valor predeterminado es 1e-7 en lugar de 5e-5.
Update on GitHub