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

Dalam makalah On the Position Bias of On-Policy Distillation, para penulis memperkenalkan Importance-Weighted On-Policy Distillation (IW-OPD). IW-OPD mengatasi bias posisi dalam on-policy distillation dengan menimbang ulang pembaruan token yang disampelkan berdasarkan akumulasi perbedaan prefiks antara teacher dan student. Token awal mempertahankan bobot yang lebih besar, sementara token yang muncul kemudian setelah drift tinggi diberi bobot yang lebih kecil.

Untuk menggunakan IW-OPD, Anda dapat menggunakan kelas experimental.iw_opd.IWOPDTrainer di trl.experimental.iw_opd.

IW-OPD saat ini merupakan bagian dari namespace trl.experimental. API dapat berubah tanpa pemberitahuan selama fitur ini masih dalam tahap iterasi.

Penggunaan

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 adalah tujuan on-policy: distillation_objective="iw_opd" membutuhkan lmbda=1.0 (default). iw_opd_gamma adalah amplifikasi bobot kepentingan dari Algoritma 1 dalam makalah tersebut.

IWOPDTrainer

kelas 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 untuk Importance-Weighted On-Policy Distillation (IW-OPD).

IW-OPD (Tentang Bias Posisi pada Distilasi On-Policy) menimbang ulang sinyal distilasi token yang di-sampling berdasarkan akumulasi perbedaan prefiks antara guru dan siswa, dengan menurunkan bobot token yang lebih akhir karena supervisinya telah menyimpang dari distribusi. Pilihnya dengan distillation_objective=“iw_opd”.

Pelatih ini adalah snapshot beku dari DistillationTrainer pra-refaktor, yang dipertahankan sebagai tempat untuk IW-OPD (metode policy-gradient yang dipandu guru yang tidak cocok dengan DistillationTrainer yang stabil dan ber-vokabulari penuh). Pelatit ini tidak dipelihara secara aktif dan tidak akan mengikuti perbaikan lanjutan dari pelatih tersebut.

Mendukung:

  • Loss JSD yang digeneralisasi (KL maju, KL mundur, atau JSD yang diinterpolasi melalui beta)
  • Objektif IW-OPD token-tercontohkan (distillation_objective=“iw_opd”)
  • Pencampuran on-policy / off-policy melalui lmbda (di-buffer melintasi akumulasi gradien)
  • Model guru lokal atau guru eksternal melalui server vLLM
  • Generasi on-policy oleh Student melalui vLLM atau model.generate()

latih

< >

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

Parameter

  • resume_from_checkpoint (str atau bool, opsional) — Jika berupa str, jalur lokal ke checkpoint yang disimpan oleh instance Trainer sebelumnya. Jika berupa bool dan bernilai True, muat checkpoint terakhir di args.output_dir yang disimpan oleh instance Trainer sebelumnya. Jika ada, pelatihan akan dilanjutkan dari status model/optimizer/scheduler yang dimuat di sini.
  • trial (optuna.Trial atau dict[str, Any], opsional) — Jalankan trial atau kamus hiperparameter untuk pencarian hiperparameter.
  • ignore_keys_for_eval (list[str], opsional) — Daftar kunci dalam output model Anda (jika berupa dictionary) yang harus diabaikan saat mengumpulkan prediksi untuk evaluasi selama pelatihan.

Mengembalikan

~trainer_utils.TrainOutput

Objek yang berisi jumlah langkah global, kerugian pelatihan, dan metrik.

Titik masuk utama pelatihan.

save_model

< >

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

Akan menyimpan model, sehingga Anda dapat memuatnya kembali menggunakan from_pretrained().

Hanya akan menyimpan dari proses utama.

push_to_hub

< >

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

Parameter

  • commit_message (str, opsional, default "End of training") — Pesan untuk commit saat melakukan push.
  • blocking (bool, opsional, default True) — Apakah fungsi harus hanya mengembalikan nilai setelah git push selesai.
  • token (str, opsional, defaultnya None) — Token dengan izin tulis untuk menimpa argumen asli Trainer.
  • revision (str, opsional) — Revisi git untuk di-commit. Secara default menggunakan head dari branch “main”.
  • private (bool, opsional) — Apakah membuat repo menjadi privat saat dibuat. Defaultnya adalah args.hub_private_repo. Tidak berpengaruh jika repo sudah ada.
  • kwargs (dict[str, Any], opsional) — Argumen kata kunci tambahan yang diteruskan ke ~Trainer.create_model_card.

Unggah self.model dan self.processing_class ke 🤗 model hub di repo self.args.hub_model_id.

IWOPDConfig

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

Parameter yang mengontrol model

  • model_init_kwargs (dict[str, Any], opsional) — Argumen kata kunci untuk AutoModelForCausalLM.from_pretrained, digunakan ketika argumen model dari trainer diberikan sebagai string. Nilai revision juga digunakan saat memuat kelas pemrosesan.
  • trust_remote_code (bool, opsional, default False) — Apakah mengizinkan pemuatan model dan tokenizer yang menyertakan kode Python kustom dari Hub. Diteruskan ke from_pretrained dan from_pretrained, untuk student dan teacher.
  • max_length (int atau None, opsional, defaultnya 1024) — Panjang total maksimum urutan (prompt + completion) untuk tokenisasi dan pemotongan.

Parameter yang mengontrol distilasi

  • temperature (float, opsional, default 1.0) — Suhu untuk sampling selama generasi dan untuk menghitung distillation loss. Nilai yang lebih tinggi menghasilkan distribusi probabilitas yang lebih lembut.
  • lmbda (float, opsional, default 1.0) — Probabilitas penggunaan data on-policy (yang dihasilkan oleh student) untuk setiap slice akumulasi gradien. Nilai 0.0 berarti sepenuhnya off-policy (hanya completion dari dataset), 1.0 berarti sepenuhnya on-policy.
  • beta (float, opsional, default 1.0) — Koefisien interpolasi untuk loss Generalized Jensen-Shannon Divergence. Ketika 0.0, loss-nya adalah forward KL divergence. Ketika 1.0, loss-nya adalah reverse KL divergence. Ketika 0.5, loss-nya adalah JSD standar.
  • distillation_objective (str, opsional, default "iw_opd") — Objektif yang dioptimalkan. "iw_opd" menggunakan objektif Importance-Weighted On-Policy Distillation untuk token yang disampelkan. "jsd" mempertahankan objektif JSD/KL yang digeneralisasi.
  • iw_opd_gamma (float, opsional, default 0.5) — Penguatan bobot kepentingan untuk distillation_objective="iw_opd".
  • iw_opd_epsilon (float, opsional, default 1e-8) — Stabilizer yang digunakan saat menormalisasi bobot prefix IW-OPD.
  • reverse_kl_top_1_mode (str, opsional, default "sampled") — Aturan seleksi untuk token top-1 reverse-KL ketika beta > 0 dan loss_top_k == 1. "sampled" menggunakan token completion aktual dalam batch. "argmax" menggunakan token dengan probabilitas tertinggi dari student. Pengaturan ini tidak memengaruhi dukungan forward-KL, yang selalu menggunakan token top-1 dari teacher. Diabaikan ketika beta == 0 atau loss_top_k != 1.
  • max_completion_length (int, opsional, defaultnya 512) — Jumlah maksimum token yang dihasilkan per completion selama on-policy generation.
  • max_prompt_length (int atau None, opsional) — Jumlah token maksimum untuk prompt. Jika None, dihitung otomatis sebagai max_length - max_completion_length. Prompt dipangkas sesuai pengaturan truncation_side tokenizer.
  • disable_dropout (bool, opsional, default True) — Apakah dropout akan dinonaktifkan pada model student selama pelatihan.

Parameter yang mengontrol model guru

  • teacher_model_name_or_path (str atau None, opsional) — Nama atau path untuk model teacher. Digunakan ketika teacher dimuat secara lokal.
  • teacher_model_revision (str atau None, opsional) — Revisi model dari model teacher (misalnya, nama branch, tag, atau hash commit).
  • teacher_model_init_kwargs (dict[str, Any] atau None, opsional) — Argumen kata kunci yang diteruskan ke AutoModelForCausalLM.from_pretrained saat menginstansiasi model teacher dari string.
  • use_teacher_server (bool, opsional, default False) — Apakah akan menggunakan server vLLM teacher eksternal alih-alih model teacher lokal.
  • teacher_model_server_url (str atau None, opsional) — URL dasar dari server vLLM yang menampung model teacher (misalnya, "http://localhost:8000"). Jika disetel, logprobs teacher diambil dari server alih-alih menjalankan forward pass lokal ketika use_teacher_server=True.
  • loss_top_k (int, opsional, default 1) — Jumlah token teratas yang digunakan saat menghitung loss JSD/KL. Distribusi student dan teacher sama-sama dibatasi pada K token ini dan dinormalisasi ulang sebelum menghitung divergensi. Jika 0, seluruh kosakata digunakan. Untuk teacher lokal, aturan dukungan umum adalah top-k teacher untuk forward KL, top-k student untuk reverse KL, dan gabungan (union) untuk mixed JSD. Ketika beta > 0 dan loss_top_k == 1, dukungan forward tetap menggunakan token top-1 dari teacher, sedangkan token top-1 reverse dikendalikan oleh reverse_kl_top_1_mode. Ketika use_teacher_server=True, jalur forward murni (beta=0) mengharuskan nilai ini positif dan menggunakan logprobs top-k dari teacher untuk suku forward. Ketika beta > 0, distilasi berbasis server mengharuskan loss_top_k == 1 dan hanya mendukung token top-1 reverse "sampled".
  • loss_add_tail (bool, opsional, default True) — Apakah akan menambahkan bucket ekor yang mewakili massa probabilitas sisa di luar dukungan top-k yang dipilih saat menghitung loss.

Parameter yang mengontrol generasi on-policy

  • num_generations (int, opsional, default 1) — Jumlah penyelesaian yang akan dihasilkan per prompt selama generasi on-policy.
  • generation_batch_size (int atau None, opsional) — Jumlah prompt unik per worker per langkah optimizer. Jika None, dihitung dari (per_device_train_batch_size * gradient_accumulation_steps) // num_generations.
  • top_p (float, opsional, default 0.95) — Parameter sampling top-p (nucleus) untuk generasi on-policy.
  • top_k (int, opsional, default 0) — Parameter top-k sampling untuk generasi on-policy. 0 menonaktifkan penyaringan top-k.

Parameter yang mengontrol vLLM untuk generasi student

  • use_vllm (bool, opsional, default False) — Apakah akan menggunakan vLLM untuk menghasilkan kelengkapan on-policy dari model student.
  • vllm_mode (str, opsional, default "colocate") — Mode untuk integrasi vLLM student. Bisa "server" atau "colocate".
  • vllm_server_base_url (str atau None, opsional) — URL dasar untuk server vLLM student. Jika disediakan, vllm_server_host dan vllm_server_port diabaikan.
  • vllm_server_host (str, opsional, default "0.0.0.0") — Host dari server vLLM student.
  • vllm_server_port (int, opsional, default 8001) — Port dari server vLLM student.
  • vllm_server_timeout (float, opsional, default 240.0) — Timeout untuk terhubung ke server vLLM student.
  • vllm_group_port (int, opsional, default 51216) — Port untuk grup pembaruan bobot vLLM (komunikator NCCL).
  • vllm_gpu_memory_utilization (float, opsional, default 0.3) — Utilisasi memori GPU untuk mesin vLLM student yang dikolokasi.
  • vllm_tensor_parallel_size (int, opsional, default 1) — Ukuran paralel tensor untuk mesin vLLM siswa yang terkolokasi.
  • vllm_max_model_length (int atau None, opsional) — Panjang urutan maksimum model untuk mesin vLLM yang terkolokasi.
  • vllm_model_impl (str, opsional, default "vllm") — Backend implementasi model untuk vLLM. Gunakan "vllm" atau "transformers".
  • vllm_structured_outputs_regex (str atau None, opsional) — Pola regex untuk structured outputs vLLM.
  • vllm_sync_frequency (int, opsional, default 1) — Frekuensi (dalam langkah pelatihan) untuk menyinkronkan bobot model siswa ke mesin vLLM.
  • vllm_enable_sleep_mode (bool, opsional, default False) — Aktifkan mode tidur vLLM untuk memindahkan bobot siswa selama langkah optimizer.

Parameter yang mengontrol logging

  • log_completions (bool, opsional, default False) — Apakah akan mencatat sampel pasangan (prompt, completion) setiap log_completions_steps langkah. Jika rich terpasang, sampel tersebut akan dicetak. Jika logging wandb dan/atau trackio diaktifkan, sampel akan dicatat ke wandb dan/atau trackio.
  • log_completions_steps (int, opsional, default 100) — Jumlah langkah antara pencatatan completions. Hanya digunakan jika log_completions adalah True.
  • num_completions_to_print (int atau None, opsional) — Jumlah completion yang dicetak. Jika None, semua completion dicatat.

Kelas konfigurasi untuk experimental.iw_opd.IWOPDTrainer.

Memperluas TrainingArguments dengan parameter yang spesifik untuk knowledge distillation. Konfigurasi ini berdiri sendiri dari SFTConfig — semua field yang diperlukan dideklarasikan di sini.

Dengan HfArgumentParser, kita dapat mengubah kelas ini menjadi argumen argparse yang dapat ditentukan di baris perintah.

Update on GitHub