TRL documentation
IW-OPD
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
< 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 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
DistillationTrainerd’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 auDistillationTrainerstable 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
< 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
Paramètres
- resume_from_checkpoint (
stroubool, facultatif) — Si c'est unestr, chemin local d'un point de contrôle enregistré par une instance précédente deTrainer. Si c'est unboolet vautTrue, charge le dernier point de contrôle dans args.output_dir enregistré par une instance précédente deTrainer. S'il est présent, l'entraînement reprendra à partir des états du modèle/optimiseur/planificateur chargés ici. - trial (
optuna.Trialoudict[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.
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
< source >( 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éfautTrue) — Indique si la fonction doit ne renvoyer que lorsque legit pushest terminé. - token (
str, facultatif, par défautNone) — 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 estargs.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
< 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 | 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é pourAutoModelForCausalLM.from_pretrained, utilisés lorsque l’argumentmodeldu formateur est fourni sous forme de chaîne de caractères. La valeur derevisionest également utilisée lors du chargement de la classe de traitement. - trust_remote_code (
bool, facultatif, valeur par défautFalse) — 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 (
intouNone, facultatif, par défaut1024) — 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éfaut1.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éfaut1.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 de0.0signifie entièrement off-policy (uniquement les complétions du jeu de données),1.0signifie entièrement on-policy. - beta (
float, facultatif, par défaut1.0) — Coefficient d'interpolation pour la perte de divergence de Jensen-Shannon généralisée. Lorsque0.0, la perte est la divergence KL avant. Lorsque1.0, la perte est la divergence KL inverse. Lorsque0.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éfaut0.5) — Amplification pondérée par importance pourdistillation_objective="iw_opd". - iw_opd_epsilon (
float, facultatif, valeur par défaut1e-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 lorsquebeta > 0etloss_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é lorsquebeta == 0ouloss_top_k != 1. - max_completion_length (
int, facultatif, par défaut512) — Nombre maximal de jetons à générer par complétion lors de la génération on-policy. - max_prompt_length (
intouNone, facultatif) — Nombre maximal de jetons pour le prompt. SiNone, calculé automatiquement commemax_length - max_completion_length. Les prompts sont tronqués selon le paramètretruncation_sidedu tokenizer. - disable_dropout (
bool, facultatif, valeur par défautTrue) — 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 (
strouNone, facultatif) — Nom ou chemin du modèle enseignant. Utilisé lorsque l’enseignant est chargé localement. - teacher_model_revision (
strouNone, facultatif) — Révision du modèle enseignant (par exemple, nom de branche, tag ou hachage de commit). - teacher_model_init_kwargs (
dict[str, Any]ouNone, facultatif) — Arguments par mot-clé transmis àAutoModelForCausalLM.from_pretrainedlors de l'instantiation du modèle enseignant à partir d'une chaîne de caractères. - use_teacher_server (
bool, facultatif, valeur par défautFalse) — Indique s'il faut utiliser un serveur vLLM externe plutôt qu'un modèle enseignant local. - teacher_model_server_url (
strouNone, 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 lorsqueuse_teacher_server=True. - loss_top_k (
int, facultatif, valeur par défaut1) — 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. Lorsquebeta > 0etloss_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é parreverse_kl_top_1_mode. Lorsqueuse_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. Lorsquebeta > 0, la distillation basée sur un serveur exigeloss_top_k == 1et ne prend en charge que les jetons top-1 inverses"sampled". - loss_add_tail (
bool, facultatif, valeur par défautTrue) — 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éfaut1) — Nombre de complétions à générer par invite lors de la génération on-policy. - generation_batch_size (
intouNone, facultatif) — Nombre de prompts uniques par travailleur et par étape d’optimiseur. SiNone, calculé à partir de(per_device_train_batch_size * gradient_accumulation_steps) // num_generations. - top_p (
float, facultatif, valeur par défaut0.95) — Paramètre d'échantillonnage Top-p (noyau) pour la génération on-policy. - top_k (
int, facultatif, valeur par défaut0) — Paramètre d'échantillonnage top-k pour la génération on-policy.0dé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éfautFalse) — 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 (
strouNone, facultatif) — URL de base du serveur vLLM de l’étudiant. Si fournie,vllm_server_hostetvllm_server_portsont 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éfaut8001) — Port du serveur vLLM de l'étudiant. - vllm_server_timeout (
float, facultatif, par défaut240.0) — Délai d’attente pour la connexion au serveur vLLM de l’étudiant. - vllm_group_port (
int, facultatif, par défaut51216) — Port du groupe de mise à jour des poids vLLM (communicateur NCCL). - vllm_gpu_memory_utilization (
float, facultatif, valeur par défaut0.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éfaut1) — Taille du parallélisme tensoriel pour le moteur vLLM étudiant co-localisé. - vllm_max_model_length (
intouNone, 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 (
strouNone, facultatif) — Motif d'expression régulière pour les sorties structurées de vLLM. - vllm_sync_frequency (
int, facultatif, valeur par défaut1) — 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éfautFalse) — 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éfautFalse) — Indique s'il faut journaliser un échantillon de paires (prompt, completion) toutes leslog_completions_stepsétapes. Sirichest installé, l'échantillon est affiché. Si la journalisationwandbet/outrackioest activée, l'échantillon est journalisé danswandbet/outrackio. - log_completions_steps (
int, facultatif, par défaut100) — Nombre d'étapes entre les enregistrements des complétions. Utilisé uniquement silog_completionsestTrue. - num_completions_to_print (
intouNone, facultatif) — Nombre de complétions à afficher. SiNone, 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.