TRL documentation
IW-OPD
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
< source >( 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
DistillationTraineranterior 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 elDistillationTrainerestable 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
< source >( 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 (
strobool, opcional) — Si es unastr, ruta local a un punto de control guardado por una instancia anterior deTrainer. Si es unbooly es igual aTrue, carga el último punto de control en args.output_dir guardado por una instancia anterior deTrainer. Si está presente, el entrenamiento se reanudará desde los estados del modelo/optimizador/planificador cargados aquí. - trial (
optuna.Trialodict[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.
Guardará el modelo, por lo que podrás recargarlo usando from_pretrained().
Solo se guardará desde el proceso principal.
push_to_hub
< source >( 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 predeterminadoTrue) — Si la función debe devolver el control solo cuando elgit pushhaya terminado. - token (
str, opcional, valor predeterminadoNone) — 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 esargs.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
< source >( 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 paraAutoModelForCausalLM.from_pretrained, utilizados cuando el argumentomodeldel trainer se proporciona como una cadena de caracteres. El valor derevisiontambién se utiliza al cargar la clase de procesamiento. - trust_remote_code (
bool, opcional, valor predeterminadoFalse) — 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 (
intoNone, opcional, valor predeterminado1024) — 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 predeterminado1.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 predeterminado1.0) — Probabilidad de usar datos on-policy (generados por el estudiante) para cada rebanada de acumulación de gradientes. Un valor de0.0significa completamente off-policy (solo completados del conjunto de datos),1.0significa completamente on-policy. - beta (
float, opcional, valor predeterminado1.0) — Coeficiente de interpolación para la pérdida de Divergencia Generalizada de Jensen-Shannon. Cuando0.0, la pérdida es la divergencia KL directa. Cuando1.0, la pérdida es la divergencia KL inversa. Cuando0.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 predeterminado0.5) — Amplificación ponderada por importancia paradistillation_objective="iw_opd". - iw_opd_epsilon (
float, opcional, valor predeterminado1e-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 cuandobeta > 0yloss_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 cuandobeta == 0oloss_top_k != 1. - max_completion_length (
int, opcional, valor predeterminado512) — Número máximo de tokens que se generarán por completado durante la generación on-policy. - max_prompt_length (
intoNone, opcional) — Número máximo de tokens para el prompt. Si esNone, se calcula automáticamente comomax_length - max_completion_length. Los prompts se truncan según la configuracióntruncation_sidedel tokenizer. - disable_dropout (
bool, opcional, valor predeterminadoTrue) — Si se desactiva el dropout en el modelo estudiante durante el entrenamiento.
Parámetros que controlan el modelo maestro
- teacher_model_name_or_path (
stroNone, opcional) — Nombre o ruta del modelo para el modelo maestro. Se utiliza cuando el maestro se carga localmente. - teacher_model_revision (
stroNone, opcional) — Revisión del modelo del maestro (p. ej., nombre de rama, etiqueta o hash de commit). - teacher_model_init_kwargs (
dict[str, Any]oNone, opcional) — Argumentos de palabra clave que se pasan aAutoModelForCausalLM.from_pretrainedal instanciar el modelo maestro a partir de una cadena. - use_teacher_server (
bool, opcional, valor predeterminadoFalse) — Si se debe utilizar un servidor de maestro vLLM externo en lugar de un modelo de maestro local. - teacher_model_server_url (
stroNone, 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 cuandouse_teacher_server=True. - loss_top_k (
int, opcional, valor predeterminado1) — 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. Cuandobeta > 0yloss_top_k == 1, el soporte hacia adelante sigue utilizando el token top-1 del maestro, mientras que el token top-1 inverso lo controlareverse_kl_top_1_mode. Cuandouse_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. Cuandobeta > 0, la destilación basada en servidor requiereloss_top_k == 1y solo admite tokens top-1 inversos"sampled". - loss_add_tail (
bool, opcional, valor predeterminadoTrue) — 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 predeterminado1) — Número de finalizaciones que se generan por indicación durante la generación on-policy. - generation_batch_size (
intoNone, opcional) — Número de prompts únicos por trabajador por paso del optimizador. Si esNone, se calcula a partir de(per_device_train_batch_size * gradient_accumulation_steps) // num_generations. - top_p (
float, opcional, valor predeterminado0.95) — Parámetro de muestreo Top-p (núcleo) para la generación on-policy. - top_k (
int, opcional, valor predeterminado0) — Parámetro de muestreo top-k para la generación on-policy.0deshabilita el filtrado top-k.
Parámetros que controlan vLLM para la generación del estudiante
- use_vllm (
bool, opcional, valor predeterminadoFalse) — 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 (
stroNone, opcional) — URL base para el servidor vLLM del estudiante. Si se proporciona,vllm_server_hostyvllm_server_portse ignoran. - vllm_server_host (
str, opcional, por defecto"0.0.0.0") — Host del servidor vLLM del estudiante. - vllm_server_port (
int, opcional, valor predeterminado8001) — Puerto del servidor vLLM del estudiante. - vllm_server_timeout (
float, opcional, valor predeterminado240.0) — Tiempo de espera para conectar con el servidor vLLM del estudiante. - vllm_group_port (
int, opcional, valor predeterminado51216) — Puerto para el grupo de actualización de pesos de vLLM (comunicador NCCL). - vllm_gpu_memory_utilization (
float, opcional, valor predeterminado0.3) — Utilización de la memoria de GPU para el motor vLLM del estudiante colocalizado. - vllm_tensor_parallel_size (
int, opcional, valor predeterminado1) — Tamaño de paralelismo de tensor para el motor vLLM del estudiante colocalizado. - vllm_max_model_length (
intoNone, 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 (
stroNone, opcional) — Patrón de expresión regular para las salidas estructuradas de vLLM. - vllm_sync_frequency (
int, opcional, valor predeterminado1) — Frecuencia (en pasos de entrenamiento) para sincronizar los pesos del modelo estudiante con el motor vLLM. - vllm_enable_sleep_mode (
bool, opcional, valor predeterminadoFalse) — 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 predeterminadoFalse) — Si se registra una muestra de pares (prompt, completion) cadalog_completions_stepspasos. Sirichestá instalado, imprime la muestra. Si la registración dewandby/otrackioestá habilitada, la registra enwandby/otrackio. - log_completions_steps (
int, opcional, valor predeterminado100) — Número de pasos entre el registro de completions. Solo se utiliza silog_completionsesTrue. - num_completions_to_print (
intoNone, opcional) — Número de completions a imprimir. Si esNone, 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.