TRL documentation
IW-OPD
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
< 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 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
DistillationTrainerpra-refaktor, yang dipertahankan sebagai tempat untuk IW-OPD (metode policy-gradient yang dipandu guru yang tidak cocok denganDistillationTraineryang 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
< 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
Parameter
- resume_from_checkpoint (
strataubool, opsional) — Jika berupastr, jalur lokal ke checkpoint yang disimpan oleh instanceTrainersebelumnya. Jika berupabooldan bernilaiTrue, muat checkpoint terakhir di args.output_dir yang disimpan oleh instanceTrainersebelumnya. Jika ada, pelatihan akan dilanjutkan dari status model/optimizer/scheduler yang dimuat di sini. - trial (
optuna.Trialataudict[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.
Akan menyimpan model, sehingga Anda dapat memuatnya kembali menggunakan from_pretrained().
Hanya akan menyimpan dari proses utama.
push_to_hub
< source >( 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, defaultTrue) — Apakah fungsi harus hanya mengembalikan nilai setelahgit pushselesai. - token (
str, opsional, defaultnyaNone) — 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 adalahargs.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
< 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 )
Parameter yang mengontrol model
- model_init_kwargs (
dict[str, Any], opsional) — Argumen kata kunci untukAutoModelForCausalLM.from_pretrained, digunakan ketika argumenmodeldari trainer diberikan sebagai string. Nilairevisionjuga digunakan saat memuat kelas pemrosesan. - trust_remote_code (
bool, opsional, defaultFalse) — 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 (
intatauNone, opsional, defaultnya1024) — Panjang total maksimum urutan (prompt + completion) untuk tokenisasi dan pemotongan.
Parameter yang mengontrol distilasi
- temperature (
float, opsional, default1.0) — Suhu untuk sampling selama generasi dan untuk menghitung distillation loss. Nilai yang lebih tinggi menghasilkan distribusi probabilitas yang lebih lembut. - lmbda (
float, opsional, default1.0) — Probabilitas penggunaan data on-policy (yang dihasilkan oleh student) untuk setiap slice akumulasi gradien. Nilai0.0berarti sepenuhnya off-policy (hanya completion dari dataset),1.0berarti sepenuhnya on-policy. - beta (
float, opsional, default1.0) — Koefisien interpolasi untuk loss Generalized Jensen-Shannon Divergence. Ketika0.0, loss-nya adalah forward KL divergence. Ketika1.0, loss-nya adalah reverse KL divergence. Ketika0.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, default0.5) — Penguatan bobot kepentingan untukdistillation_objective="iw_opd". - iw_opd_epsilon (
float, opsional, default1e-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 ketikabeta > 0danloss_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 ketikabeta == 0atauloss_top_k != 1. - max_completion_length (
int, opsional, defaultnya512) — Jumlah maksimum token yang dihasilkan per completion selama on-policy generation. - max_prompt_length (
intatauNone, opsional) — Jumlah token maksimum untuk prompt. JikaNone, dihitung otomatis sebagaimax_length - max_completion_length. Prompt dipangkas sesuai pengaturantruncation_sidetokenizer. - disable_dropout (
bool, opsional, defaultTrue) — Apakah dropout akan dinonaktifkan pada model student selama pelatihan.
Parameter yang mengontrol model guru
- teacher_model_name_or_path (
stratauNone, opsional) — Nama atau path untuk model teacher. Digunakan ketika teacher dimuat secara lokal. - teacher_model_revision (
stratauNone, opsional) — Revisi model dari model teacher (misalnya, nama branch, tag, atau hash commit). - teacher_model_init_kwargs (
dict[str, Any]atauNone, opsional) — Argumen kata kunci yang diteruskan keAutoModelForCausalLM.from_pretrainedsaat menginstansiasi model teacher dari string. - use_teacher_server (
bool, opsional, defaultFalse) — Apakah akan menggunakan server vLLM teacher eksternal alih-alih model teacher lokal. - teacher_model_server_url (
stratauNone, 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 ketikause_teacher_server=True. - loss_top_k (
int, opsional, default1) — 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. Ketikabeta > 0danloss_top_k == 1, dukungan forward tetap menggunakan token top-1 dari teacher, sedangkan token top-1 reverse dikendalikan olehreverse_kl_top_1_mode. Ketikause_teacher_server=True, jalur forward murni (beta=0) mengharuskan nilai ini positif dan menggunakan logprobs top-k dari teacher untuk suku forward. Ketikabeta > 0, distilasi berbasis server mengharuskanloss_top_k == 1dan hanya mendukung token top-1 reverse"sampled". - loss_add_tail (
bool, opsional, defaultTrue) — 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, default1) — Jumlah penyelesaian yang akan dihasilkan per prompt selama generasi on-policy. - generation_batch_size (
intatauNone, opsional) — Jumlah prompt unik per worker per langkah optimizer. JikaNone, dihitung dari(per_device_train_batch_size * gradient_accumulation_steps) // num_generations. - top_p (
float, opsional, default0.95) — Parameter sampling top-p (nucleus) untuk generasi on-policy. - top_k (
int, opsional, default0) — Parameter top-k sampling untuk generasi on-policy.0menonaktifkan penyaringan top-k.
Parameter yang mengontrol vLLM untuk generasi student
- use_vllm (
bool, opsional, defaultFalse) — 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 (
stratauNone, opsional) — URL dasar untuk server vLLM student. Jika disediakan,vllm_server_hostdanvllm_server_portdiabaikan. - vllm_server_host (
str, opsional, default"0.0.0.0") — Host dari server vLLM student. - vllm_server_port (
int, opsional, default8001) — Port dari server vLLM student. - vllm_server_timeout (
float, opsional, default240.0) — Timeout untuk terhubung ke server vLLM student. - vllm_group_port (
int, opsional, default51216) — Port untuk grup pembaruan bobot vLLM (komunikator NCCL). - vllm_gpu_memory_utilization (
float, opsional, default0.3) — Utilisasi memori GPU untuk mesin vLLM student yang dikolokasi. - vllm_tensor_parallel_size (
int, opsional, default1) — Ukuran paralel tensor untuk mesin vLLM siswa yang terkolokasi. - vllm_max_model_length (
intatauNone, 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 (
stratauNone, opsional) — Pola regex untuk structured outputs vLLM. - vllm_sync_frequency (
int, opsional, default1) — Frekuensi (dalam langkah pelatihan) untuk menyinkronkan bobot model siswa ke mesin vLLM. - vllm_enable_sleep_mode (
bool, opsional, defaultFalse) — Aktifkan mode tidur vLLM untuk memindahkan bobot siswa selama langkah optimizer.
Parameter yang mengontrol logging
- log_completions (
bool, opsional, defaultFalse) — Apakah akan mencatat sampel pasangan (prompt, completion) setiaplog_completions_stepslangkah. Jikarichterpasang, sampel tersebut akan dicetak. Jika loggingwandbdan/atautrackiodiaktifkan, sampel akan dicatat kewandbdan/atautrackio. - log_completions_steps (
int, opsional, default100) — Jumlah langkah antara pencatatan completions. Hanya digunakan jikalog_completionsadalahTrue. - num_completions_to_print (
intatauNone, opsional) — Jumlah completion yang dicetak. JikaNone, 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.