TRL documentation

IW-OPD

You are viewing v1.18.0 version. A newer version v1.18.1 is available.
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

IW-OPD

En el artículo On the Position Bias of On-Policy Distillation, los autores introducen Importance-Weighted On-Policy Distillation (IW-OPD). IW-OPD aborda el sesgo de posición en la destilación on-policy reponderando las actualizaciones de los tokens muestreados según la discrepancia acumulada del prefijo entre el modelo maestro y el estudiante. Los tokens iniciales conservan pesos mayores, mientras que los tokens posteriores a un alto desplazamiento se reponderan a la baja.

Para usar IW-OPD, puedes utilizar la clase experimental.iw_opd.IWOPDTrainer en trl.experimental.iw_opd.

IW-OPD forma actualmente parte del espacio de nombres trl.experimental. Las APIs pueden cambiar sin previo aviso mientras se itera sobre la funcionalidad.

Uso

from trl.experimental.iw_opd import IWOPDConfig, IWOPDTrainer

training_args = IWOPDConfig(
    distillation_objective="iw_opd",
    iw_opd_gamma=0.5,
)
trainer = IWOPDTrainer(
    model="Qwen/Qwen3-0.6B",
    teacher_model="...",
    train_dataset=...,
    args=training_args,
)
trainer.train()

IW-OPD es un objetivo on-policy: distillation_objective="iw_opd" requiere lmbda=1.0 (el valor predeterminado). iw_opd_gamma es la amplificación por ponderación de importancia del Algoritmo 1 del artículo.

IWOPDTrainer

clase trl.experimental.iw_opd.IWOPDTrainer

< >

( 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.iw_opd.iw_opd_config.IWOPDConfig | 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 )

Trainer para Destilación On-Policy con Pesos de Importancia (IW-OPD).

IW-OPD (Sobre el sesgo de posición en la destilación on-policy) repondera la señal de destilación de los tokens muestreados mediante la discrepancia acumulada del prefijo entre el maestro y el estudiante, reduciendo el peso de los tokens posteriores cuya supervisión se ha desviado de la distribución. Selecciónalo con distillation_objective=“iw_opd”.

Este entrenador es una instantánea congelada del DistillationTrainer anterior a la refactorización, conservado como el lugar de IW-OPD (un método de gradiente de política guiado por un maestro que no encaja en el DistillationTrainer estable y de vocabulario completo). No se mantiene de forma activa y no incorporará las mejoras posteriores de ese entrenador.

Soporta:

  • Pérdida JSD generalizada (KL directa, KL inversa o JSD interpolada mediante beta)
  • Objetivo IW-OPD de tokens muestreados (distillation_objective=“iw_opd”)
  • Mezcla on-policy / off-policy mediante lmbda (almacenada en el buffer a lo largo de la acumulación de gradientes)
  • Modelo de maestro local o maestro externo a través de un servidor vLLM
  • Generación on-policy del estudiante mediante vLLM o model.generate()

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.

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.

IWOPDConfig

clase trl.experimental.iw_opd.IWOPDConfig

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-06lr_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 = Truegradient_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 = Falsemax_length: int | None = 1024temperature: float = 1.0lmbda: float = 1.0beta: float = 1.0distillation_objective: str = 'iw_opd'iw_opd_gamma: float = 0.5iw_opd_epsilon: float = 1e-08reverse_kl_top_1_mode: str = 'sampled'max_completion_length: int = 512max_prompt_length: int | None = Nonedisable_dropout: bool = Trueteacher_model_name_or_path: str | None = Noneteacher_model_revision: str | None = Noneteacher_model_init_kwargs: dict[str, typing.Any] | str | None = Noneuse_teacher_server: bool = Falseteacher_model_server_url: str | None = Noneloss_top_k: int = 1loss_add_tail: bool = Truenum_generations: int = 1generation_batch_size: int | None = Nonetop_p: float = 0.95top_k: int = 0use_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.3vllm_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 = None )

Parámetros que controlan el modelo

  • model_init_kwargs (dict[str, Any], opcional) — Argumentos de palabra clave para AutoModelForCausalLM.from_pretrained, utilizados cuando el argumento model del trainer se proporciona como una cadena de caracteres. El valor de revision también se utiliza al cargar la clase de procesamiento.
  • trust_remote_code (bool, opcional, valor predeterminado False) — Si se permite cargar modelos y tokenizadores que incluyen código Python personalizado desde el Hub. Se reenvía a from_pretrained y from_pretrained, tanto para el estudiante como para el profesor.
  • max_length (int o None, opcional, valor predeterminado 1024) — Longitud total máxima de la secuencia (prompt + completion) para la tokenización y la truncación.

Parámetros que controlan la destilación

  • temperature (float, opcional, valor predeterminado 1.0) — Temperatura para el muestreo durante la generación y para el cálculo de la pérdida de destilación. Valores más altos producen distribuciones de probabilidad más suaves.
  • lmbda (float, opcional, valor predeterminado 1.0) — Probabilidad de usar datos on-policy (generados por el estudiante) para cada rebanada de acumulación de gradientes. Un valor de 0.0 significa completamente off-policy (solo completados del conjunto de datos), 1.0 significa completamente on-policy.
  • beta (float, opcional, valor predeterminado 1.0) — Coeficiente de interpolación para la pérdida de Divergencia Generalizada de Jensen-Shannon. Cuando 0.0, la pérdida es la divergencia KL directa. Cuando 1.0, la pérdida es la divergencia KL inversa. Cuando 0.5, es la JSD estándar.
  • distillation_objective (str, opcional, valor predeterminado "iw_opd") — Objetivo a optimizar. "iw_opd" utiliza el objetivo de Destilación On-Policy con Pesos de Importancia sobre el token muestreado. "jsd" mantiene el objetivo generalizado JSD/KL.
  • iw_opd_gamma (float, opcional, valor predeterminado 0.5) — Amplificación ponderada por importancia para distillation_objective="iw_opd".
  • iw_opd_epsilon (float, opcional, valor predeterminado 1e-8) — Estabilizador utilizado al normalizar los pesos de prefijo de IW-OPD.
  • reverse_kl_top_1_mode (str, opcional, valor predeterminado "sampled") — Regla de selección para el token top-1 de la KL inversa cuando beta > 0 y loss_top_k == 1. "sampled" utiliza el token de finalización real del lote. "argmax" utiliza el token con mayor probabilidad del estudiante. Esta configuración no afecta al soporte de la KL directa, que siempre utiliza el token top-1 del maestro. Se ignora cuando beta == 0 o loss_top_k != 1.
  • max_completion_length (int, opcional, valor predeterminado 512) — Número máximo de tokens que se generarán por completado durante la generación on-policy.
  • max_prompt_length (int o None, opcional) — Número máximo de tokens para el prompt. Si es None, se calcula automáticamente como max_length - max_completion_length. Los prompts se truncan según la configuración truncation_side del tokenizer.
  • disable_dropout (bool, opcional, valor predeterminado True) — Si se desactiva el dropout en el modelo estudiante durante el entrenamiento.

Parámetros que controlan el modelo maestro

  • teacher_model_name_or_path (str o None, opcional) — Nombre o ruta del modelo para el modelo maestro. Se utiliza cuando el maestro se carga localmente.
  • teacher_model_revision (str o None, opcional) — Revisión del modelo del maestro (p. ej., nombre de rama, etiqueta o hash de commit).
  • teacher_model_init_kwargs (dict[str, Any] o None, opcional) — Argumentos de palabra clave que se pasan a AutoModelForCausalLM.from_pretrained al instanciar el modelo maestro a partir de una cadena.
  • use_teacher_server (bool, opcional, valor predeterminado False) — Si se debe utilizar un servidor de maestro vLLM externo en lugar de un modelo de maestro local.
  • teacher_model_server_url (str o None, opcional) — URL base de un servidor de vLLM que aloja el modelo teacher (p. ej., "http://localhost:8000"). Cuando se establece, los logprobs del teacher se obtienen del servidor en lugar de ejecutar una pasada local hacia adelante cuando use_teacher_server=True.
  • loss_top_k (int, opcional, valor predeterminado 1) — Número de tokens principales a utilizar al calcular la pérdida JSD/KL. Tanto las distribuciones del estudiante como las del maestro se restringen a estos K tokens y se renormalizan antes de calcular la divergencia. Si es 0, se utiliza el vocabulario completo. Para los maestros locales, la regla general de soporte es top-k del maestro para KL hacia adelante, top-k del estudiante para KL inverso, y la unión para JSD mixto. Cuando beta > 0 y loss_top_k == 1, el soporte hacia adelante sigue utilizando el token top-1 del maestro, mientras que el token top-1 inverso lo controla reverse_kl_top_1_mode. Cuando use_teacher_server=True, la ruta pura hacia adelante (beta=0) requiere que este valor sea positivo y utiliza los logprobs top-k del maestro para el término hacia adelante. Cuando beta > 0, la destilación basada en servidor requiere loss_top_k == 1 y solo admite tokens top-1 inversos "sampled".
  • loss_add_tail (bool, opcional, valor predeterminado True) — Si se debe agregar un bucket de cola que representa la masa de probabilidad restante fuera del soporte top-k seleccionado al calcular la pérdida.

Parámetros que controlan la generación on-policy

  • num_generations (int, opcional, valor predeterminado 1) — Número de finalizaciones que se generan por indicación durante la generación on-policy.
  • generation_batch_size (int o None, opcional) — 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.
  • top_p (float, opcional, valor predeterminado 0.95) — 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.

Parámetros que controlan vLLM para la generación del estudiante

  • use_vllm (bool, opcional, valor predeterminado False) — Si se debe usar vLLM para generar completados on-policy desde el modelo estudiante.
  • vllm_mode (str, opcional, valor predeterminado "colocate") — Modo para la integración de vLLM del estudiante. Puede ser "server" o "colocate".
  • vllm_server_base_url (str o None, opcional) — URL base para el servidor vLLM del estudiante. Si se proporciona, vllm_server_host y vllm_server_port se ignoran.
  • vllm_server_host (str, opcional, por defecto "0.0.0.0") — Host del servidor vLLM del estudiante.
  • vllm_server_port (int, opcional, valor predeterminado 8001) — Puerto del servidor vLLM del estudiante.
  • vllm_server_timeout (float, opcional, valor predeterminado 240.0) — Tiempo de espera para conectar con el servidor vLLM del estudiante.
  • vllm_group_port (int, opcional, valor predeterminado 51216) — Puerto para el grupo de actualización de pesos de vLLM (comunicador NCCL).
  • vllm_gpu_memory_utilization (float, opcional, valor predeterminado 0.3) — Utilización de la memoria de GPU para el motor vLLM del estudiante colocalizado.
  • vllm_tensor_parallel_size (int, opcional, valor predeterminado 1) — Tamaño de paralelismo de tensor para el motor vLLM del estudiante colocalizado.
  • vllm_max_model_length (int o None, opcional) — Longitud máxima de secuencia del modelo para el motor vLLM colocalizado.
  • vllm_model_impl (str, opcional, valor predeterminado "vllm") — Backend de implementación del modelo para vLLM. Use "vllm" o "transformers".
  • vllm_structured_outputs_regex (str o None, opcional) — Patrón de expresión regular para las salidas estructuradas de vLLM.
  • vllm_sync_frequency (int, opcional, valor predeterminado 1) — Frecuencia (en pasos de entrenamiento) para sincronizar los pesos del modelo estudiante con el motor vLLM.
  • vllm_enable_sleep_mode (bool, opcional, valor predeterminado False) — Activa el modo de suspensión de vLLM para descargar los pesos del estudiante durante el paso del optimizador.

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 pasos. Si rich está instalado, imprime la muestra. Si la registración de wandb y/o trackio está habilitada, la registra en wandb y/o trackio.
  • log_completions_steps (int, opcional, valor predeterminado 100) — Número de pasos entre el registro de completions. Solo se utiliza si log_completions es True.
  • num_completions_to_print (int o None, opcional) — Número de completions a imprimir. Si es None, se registran todas las completions.

Clase de configuración para experimental.iw_opd.IWOPDTrainer.

Extiende TrainingArguments con parámetros específicos para la destilación de conocimiento. Esta configuración es independiente de SFTConfig: todos los campos necesarios se declaran aquí.

Con HfArgumentParser podemos convertir esta clase en argumentos de argparse que se pueden especificar en la línea de comandos.

Update on GitHub