TRL documentation

IW-OPD

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

IW-OPD

Dans l'article On the Position Bias of On-Policy Distillation, les auteurs introduisent l'Importance-Weighted On-Policy Distillation (IW-OPD). IW-OPD traite le biais de position dans la distillation on-policy en répondérant les mises à jour des jetons échantillonnés en fonction de l'écart cumulé entre le préfixe de l'enseignant et celui de l'élève. Les jetons initiaux conservent des poids plus élevés, tandis que les jetons ultérieurs, après un dérive importante, voient leur poids réduit.

Pour utiliser IW-OPD, vous pouvez utiliser la classe experimental.iw_opd.IWOPDTrainer dans trl.experimental.iw_opd.

IW-OPD fait actuellement partie de l'espace de noms trl.experimental. Les API peuvent changer sans préavis pendant que la fonctionnalité est itérée.

Utilisation

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 est un objectif on-policy : distillation_objective="iw_opd" exige lmbda=1.0 (la valeur par défaut). iw_opd_gamma est l’amplification par pondération d’importance issue de l’Algorithme 1 de l’article.

IWOPDTrainer

classe 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 pour la distillation on-policy pondérée par importance (IW-OPD).

IW-OPD (On the Position Bias of On-Policy Distillation) réajuste le signal de distillation des jetons échantillonnés en fonction de la divergence cumulée entre les préfixes de l’enseignant et de l’étudiant, en réduisant le poids des jetons ultérieurs dont la supervision s’est éloignée de la distribution. Sélectionnez-le avec distillation_objective=“iw_opd”.

Ce formateur est un instantané figé du DistillationTrainer d’avant la refonte, conservé comme lieu d’accueil de l’IW-OPD (une méthode de gradient de politique guidée par un enseignant qui ne s’adapte pas au DistillationTrainer stable et à vocabulaire complet). Il n’est pas activement maintenu et ne suivra pas les améliorations ultérieures de ce formateur.

Prend en charge :

  • Perte JSD généralisée (KL avant, KL arrière ou JSD interpolée via beta)
  • Objectif IW-OPD sur jetons échantillonnés (distillation_objective=“iw_opd”)
  • Mélange on-policy / off-policy via lmbda (tamponné sur l'accumulation de gradients)
  • Modèle enseignant local ou enseignant externe via serveur vLLM
  • Génération on-policy de l'étudiant via vLLM ou model.generate()

train

< >

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

Paramètres

  • resume_from_checkpoint (str ou bool, facultatif) — Si c'est une str, chemin local d'un point de contrôle enregistré par une instance précédente de Trainer. Si c'est un bool et vaut True, charge le dernier point de contrôle dans args.output_dir enregistré par une instance précédente de Trainer. S'il est présent, l'entraînement reprendra à partir des états du modèle/optimiseur/planificateur chargés ici.
  • trial (optuna.Trial ou dict[str, Any], facultatif) — L’exécution de l’essai ou le dictionnaire d’hyperparamètres pour la recherche d’hyperparamètres.
  • ignore_keys_for_eval (list[str], facultatif) — Une liste de clés dans la sortie de votre modèle (s’il s’agit d’un dictionnaire) qui doivent être ignorées lors de la collecte des prédictions pour l’évaluation pendant l’entraînement.

Retourne

~trainer_utils.TrainOutput

Objet contenant le nombre d'étapes globales, la perte d'entraînement et les métriques.

Point d'entrée principal de l'entraînement.

save_model

< >

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

Enregistrera le modèle, ce qui vous permettra de le recharger à l'aide de from_pretrained().

N'enregistrera que depuis le processus principal.

push_to_hub

< >

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

Paramètres

  • commit_message (str, facultatif, par défaut "End of training") — Message à committer lors de la poussée.
  • blocking (bool, facultatif, par défaut True) — Indique si la fonction doit ne renvoyer que lorsque le git push est terminé.
  • token (str, facultatif, par défaut None) — Jeton avec permission d’écriture pour écraser les arguments originaux du Trainer.
  • revision (str, facultatif) — La révision git à partir de laquelle effectuer le commit. Par défaut, il s'agit de la tête de la branche « main ».
  • private (bool, facultatif) — Indique s'il faut rendre le dépôt privé lors de sa création. La valeur par défaut est args.hub_private_repo. N'a aucun effet si le dépôt existe déjà.
  • kwargs (dict[str, Any], facultatif) — Arguments supplémentaires passés à ~Trainer.create_model_card.

Téléchargez self.model et self.processing_class sur le hub de modèles 🤗 dans le dépôt self.args.hub_model_id.

IWOPDConfig

classe 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 | 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 = 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 )

Paramètres qui contrôlent le modèle

  • model_init_kwargs (dict[str, Any], facultatif) — Arguments par mot-clé pour AutoModelForCausalLM.from_pretrained, utilisés lorsque l’argument model du formateur est fourni sous forme de chaîne de caractères. La valeur de revision est également utilisée lors du chargement de la classe de traitement.
  • trust_remote_code (bool, facultatif, valeur par défaut False) — Indique s'il faut autoriser le chargement de modèles et de tokenizers qui incluent du code Python personnalisé depuis le Hub. Transmis à from_pretrained et from_pretrained, pour l'étudiant comme pour l'enseignant.
  • max_length (int ou None, facultatif, par défaut 1024) — Longueur totale maximale de la séquence (invite + complétion) pour la tokenisation et la troncature.

Paramètres qui contrôlent la distillation

  • temperature (float, facultatif, par défaut 1.0) — Température pour l'échantillonnage lors de la génération et pour le calcul de la perte de distillation. Des valeurs plus élevées produisent des distributions de probabilité plus douces.
  • lmbda (float, facultatif, valeur par défaut 1.0) — Probabilité d’utiliser des données on-policy (générées par l’étudiant) pour chaque tranche d’accumulation de gradients. Une valeur de 0.0 signifie entièrement off-policy (uniquement les complétions du jeu de données), 1.0 signifie entièrement on-policy.
  • beta (float, facultatif, par défaut 1.0) — Coefficient d'interpolation pour la perte de divergence de Jensen-Shannon généralisée. Lorsque 0.0, la perte est la divergence KL avant. Lorsque 1.0, la perte est la divergence KL inverse. Lorsque 0.5, il s'agit de la JSD standard.
  • distillation_objective (str, facultatif, par défaut "iw_opd") — Objectif à optimiser. "iw_opd" utilise l'objectif de distillation On-Policy pondérée par importance (Importance-Weighted On-Policy Distillation) sur les jetons échantillonnés. "jsd" conserve l'objectif généralisé JSD/KL.
  • iw_opd_gamma (float, facultatif, valeur par défaut 0.5) — Amplification pondérée par importance pour distillation_objective="iw_opd".
  • iw_opd_epsilon (float, facultatif, valeur par défaut 1e-8) — Stabilisateur utilisé lors de la normalisation des poids de préfixe IW-OPD.
  • reverse_kl_top_1_mode (str, facultatif, valeur par défaut "sampled") — Règle de sélection pour le jeton top-1 du reverse-KL lorsque beta > 0 et loss_top_k == 1. "sampled" utilise le jeton de complétion réel du lot. "argmax" utilise le jeton ayant la probabilité la plus élevée pour l’étudiant. Ce paramètre n’affecte pas le support du forward-KL, qui utilise toujours le jeton top-1 de l’enseignant. Ignoré lorsque beta == 0 ou loss_top_k != 1.
  • max_completion_length (int, facultatif, par défaut 512) — Nombre maximal de jetons à générer par complétion lors de la génération on-policy.
  • max_prompt_length (int ou None, facultatif) — Nombre maximal de jetons pour le prompt. Si None, calculé automatiquement comme max_length - max_completion_length. Les prompts sont tronqués selon le paramètre truncation_side du tokenizer.
  • disable_dropout (bool, facultatif, valeur par défaut True) — Indique s'il faut désactiver le dropout dans le modèle étudiant pendant l'entraînement.

Paramètres qui contrôlent le modèle enseignant

  • teacher_model_name_or_path (str ou None, facultatif) — Nom ou chemin du modèle enseignant. Utilisé lorsque l’enseignant est chargé localement.
  • teacher_model_revision (str ou None, facultatif) — Révision du modèle enseignant (par exemple, nom de branche, tag ou hachage de commit).
  • teacher_model_init_kwargs (dict[str, Any] ou None, facultatif) — Arguments par mot-clé transmis à AutoModelForCausalLM.from_pretrained lors de l'instantiation du modèle enseignant à partir d'une chaîne de caractères.
  • use_teacher_server (bool, facultatif, valeur par défaut False) — Indique s'il faut utiliser un serveur vLLM externe plutôt qu'un modèle enseignant local.
  • teacher_model_server_url (str ou None, facultatif) — URL de base d’un serveur vLLM hébergeant le modèle enseignant (par exemple, "http://localhost:8000"). Lorsqu’il est défini, les logprobs du modèle enseignant sont récupérés depuis le serveur au lieu d’exécuter un passage avant local lorsque use_teacher_server=True.
  • loss_top_k (int, facultatif, valeur par défaut 1) — Nombre de jetons de tête à utiliser lors du calcul de la perte JSD/KL. Les distributions de l’élève et de l’enseignant sont restreintes à ces K jetons et renormalisées avant le calcul de la divergence. Si la valeur est 0, le vocabulaire complet est utilisé. Pour les enseignants locaux, la règle générale de support est le top-k de l’enseignant pour la KL avant, le top-k de l’élève pour la KL inverse, et l’union pour le JSD mixte. Lorsque beta > 0 et loss_top_k == 1, le support avant utilise toujours le jeton top-1 de l’enseignant, tandis que le jeton top-1 inverse est contrôlé par reverse_kl_top_1_mode. Lorsque use_teacher_server=True, le chemin avant pur (beta=0) exige que cette valeur soit positive et utilise les logprobs top-k de l’enseignant pour le terme avant. Lorsque beta > 0, la distillation basée sur un serveur exige loss_top_k == 1 et ne prend en charge que les jetons top-1 inverses "sampled".
  • loss_add_tail (bool, facultatif, valeur par défaut True) — Indique s'il faut ajouter un seau de fin représentant la masse de probabilité restante hors du support top-k sélectionné lors du calcul de la perte.

Paramètres qui contrôlent la génération on-policy

  • num_generations (int, facultatif, par défaut 1) — Nombre de complétions à générer par invite lors de la génération on-policy.
  • generation_batch_size (int ou None, facultatif) — Nombre de prompts uniques par travailleur et par étape d’optimiseur. Si None, calculé à partir de (per_device_train_batch_size * gradient_accumulation_steps) // num_generations.
  • top_p (float, facultatif, valeur par défaut 0.95) — Paramètre d'échantillonnage Top-p (noyau) pour la génération on-policy.
  • top_k (int, facultatif, valeur par défaut 0) — Paramètre d'échantillonnage top-k pour la génération on-policy. 0 désactive le filtrage top-k.

Paramètres qui contrôlent vLLM pour la génération de l'étudiant

  • use_vllm (bool, facultatif, valeur par défaut False) — Indique s'il faut utiliser vLLM pour générer des complétions on-policy à partir du modèle étudiant.
  • vllm_mode (str, facultatif, par défaut "colocate") — Mode d'intégration de vLLM pour l'étudiant. Soit "server", soit "colocate".
  • vllm_server_base_url (str ou None, facultatif) — URL de base du serveur vLLM de l’étudiant. Si fournie, vllm_server_host et vllm_server_port sont ignorés.
  • vllm_server_host (str, facultatif, par défaut "0.0.0.0") — Hôte du serveur vLLM de l’étudiant.
  • vllm_server_port (int, facultatif, par défaut 8001) — Port du serveur vLLM de l'étudiant.
  • vllm_server_timeout (float, facultatif, par défaut 240.0) — Délai d’attente pour la connexion au serveur vLLM de l’étudiant.
  • vllm_group_port (int, facultatif, par défaut 51216) — Port du groupe de mise à jour des poids vLLM (communicateur NCCL).
  • vllm_gpu_memory_utilization (float, facultatif, valeur par défaut 0.3) — Taux d'utilisation de la mémoire GPU pour le moteur vLLM étudiant co-localisé.
  • vllm_tensor_parallel_size (int, facultatif, valeur par défaut 1) — Taille du parallélisme tensoriel pour le moteur vLLM étudiant co-localisé.
  • vllm_max_model_length (int ou None, facultatif) — Longueur maximale de séquence du modèle pour le moteur vLLM co-localisé.
  • vllm_model_impl (str, facultatif, par défaut "vllm") — Backend d’implémentation du modèle pour vLLM. Utilisez "vllm" ou "transformers".
  • vllm_structured_outputs_regex (str ou None, facultatif) — Motif d'expression régulière pour les sorties structurées de vLLM.
  • vllm_sync_frequency (int, facultatif, valeur par défaut 1) — Fréquence (en nombre d'étapes d'entraînement) à laquelle synchroniser les poids du modèle étudiant vers le moteur vLLM.
  • vllm_enable_sleep_mode (bool, facultatif, valeur par défaut False) — Active le mode veille de vLLM pour décharger les poids de l’étudiant pendant l’étape d’optimiseur.

Paramètres qui contrôlent la journalisation

  • log_completions (bool, facultatif, par défaut False) — Indique s'il faut journaliser un échantillon de paires (prompt, completion) toutes les log_completions_steps étapes. Si rich est installé, l'échantillon est affiché. Si la journalisation wandb et/ou trackio est activée, l'échantillon est journalisé dans wandb et/ou trackio.
  • log_completions_steps (int, facultatif, par défaut 100) — Nombre d'étapes entre les enregistrements des complétions. Utilisé uniquement si log_completions est True.
  • num_completions_to_print (int ou None, facultatif) — Nombre de complétions à afficher. Si None, toutes les complétions sont journalisées.

Classe de configuration pour le experimental.iw_opd.IWOPDTrainer.

Étend TrainingArguments avec des paramètres spécifiques à la distillation de connaissances. Cette configuration est indépendante de SFTConfig — tous les champs nécessaires sont déclarés ici.

À l’aide de HfArgumentParser, nous pouvons transformer cette classe en arguments argparse qui peuvent être spécifiés sur la ligne de commande.

Update on GitHub