TRL documentation
IW-OPD
IW-OPD
في ورقة On the Position Bias of On-Policy Distillation، يُقدّم المؤلفون تقنية Importance-Weighted On-Policy Distillation (IW-OPD). تعالج IW-OPD انحياز الموقع في التقطير على السياسة (on-policy distillation) عن طريق إعادة وزن تحديثات الرموز المُستخرجة (sampled-token) وفقاً لفرق البادئة التراكمي بين المعلم والطالب. تحافظ الرموز المبكرة على أوزان أكبر، بينما تُخفَّض أوزان الرموز اللاحقة بعد انحراف عالٍ.
للاستفادة من IW-OPD، يمكنك استخدام فئة experimental.iw_opd.IWOPDTrainer الموجودة في trl.experimental.iw_opd.
IW-OPD هو حاليًا جزء من مساحة الأسماء
trl.experimental. قد تتغير واجهات برمجة التطبيقات دون إشعار مسبق أثناء تطوير الميزة.
الاستخدام
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 هو هدف على السياسة: يتطلب distillation_objective="iw_opd" قيمة lmbda=1.0 (الافتراضية). أما iw_opd_gamma فهو معامل تضخيم الأوزان المهمة من الخوارزمية 1 في الورقة البحثية.
IWOPDTrainer
فئة 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 للتقطير على السياسة الموزونة بالأهمية (IW-OPD).
يعيد IW-OPD (حول تحيز الموقع في التقطير أثناء السياسة) وزن إشارة التقطير للرموز المُستخرجة بناءً على انحراف البادئة التراكمي بين المعلم والطالب، مخفضًا وزن الرموز اللاحقة التي انجرف إشرافها خارج التوزيع. اختره باستخدام distillation_objective=“iw_opd”.
هذا المدرب هو لقطة مجمّدة من
DistillationTrainerقبل إعادة الهيكلة، ويُحتفظ به كمقرّ لـ IW-OPD (وهو أسلوب تدرّج سياسة موجّه من قِبل معلّم لا يتناسب معDistillationTrainerالمستقرّ ذي المفردات الكاملة). وهو غير مُدار بنشاط ولن يتتبع التحسينات اللاحقة لذلك المدرب.
يدعم:
- خسارة JSD المعممة (KL الأمامي، KL العكسي، أو JSD المُستوفى عبر beta)
- دالة IW-OPD للرموز المُستخرجة (distillation_objective=“iw_opd”)
- خلط على السياسة / خارج السياسة عبر lmbda (مخزّن عبر تراكم التدرجات)
- نموذج المعلم المحلي أو المعلم الخارجي عبر خادم vLLM
- توليد الطالب وفق السياسة عبر vLLM أو model.generate()
تدريب
< 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
المعاملات
- resume_from_checkpoint (
strأوbool، اختياري) — إذا كانstr، فهو المسار المحلي لنقطة تفتيش محفوظة بواسطة نسخة سابقة منTrainer. وإذا كانboolويساويTrue، يتم تحميل آخر نقطة تفتيش في args.output_dir كما حفظتها نسخة سابقة منTrainer. إذا كانت موجودة، فسيستأنف التدريب من حالات النموذج/المُحسِّن/المُجدوِل المحمَّلة هنا. - trial (
optuna.Trialأوdict[str, Any]، اختياري) — التجربة أو قاموس المعاملات الفائقة للبحث في المعاملات الفائقة. - ignore_keys_for_eval (
list[str]، اختياري) — قائمة بالمفاتيح في مخرجات النموذج الخاص بك (إذا كان قاموسًا) التي يجب تجاهلها عند جمع التوقعات للتقييم أثناء التدريب.
يعيد
~trainer_utils.TrainOutput
كائن يحتوي على عدد الخطوات العالمية، وخسارة التدريب، والمقاييس.
نقطة الدخول الرئيسية للتدريب.
سيحفظ النموذج، بحيث يمكنك إعادة تحميله باستخدام from_pretrained().
سيتم الحفظ من العملية الرئيسية فقط.
push_to_hub
< source >( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )
المعاملات
- commit_message (
str، اختياري، الافتراضي"End of training") — الرسالة التي تُرسل عند الدفع. - blocking (
bool، اختياري، الافتراضيTrue) — ما إذا كان ينبغي للدالة أن تُرجع فقط بعد اكتمالgit push. - token (
str، اختياري، القيمة الافتراضيةNone) — رمز (Token) يملك صلاحية الكتابة لتجاوز الحجج الأصلية الخاصة بـ Trainer. - revision (
str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع “main”. - private (
bool، اختياري) — ما إذا كان يجب جعل المستودع خاصًا عند إنشائه. القيمة الافتراضية هيargs.hub_private_repo. لا يكون له أي تأثير إذا كان المستودع موجودًا مسبقًا. - kwargs (
dict[str, Any]، اختياري) — معلمات إضافية تُمرَّر إلى~Trainer.create_model_card.
ارفع self.model وself.processing_class إلى مركز النماذج 🤗 في المستودع self.args.hub_model_id.
IWOPDConfig
فئة 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 )
المعاملات التي تتحكم في النموذج
- model_init_kwargs (
dict[str, Any], اختياري) — حجج الكلمات المفتاحية لـAutoModelForCausalLM.from_pretrained، تُستخدم عندما يُقدَّم معاملmodelفي المدرب كسلسلة نصية. كما يُستخدم قيمةrevisionعند تحميل فئة المعالجة. - trust_remote_code (
bool, optional, defaults toFalse) — Whether to allow loading models and tokenizers that ship custom Python code from the Hub. Forwarded to from_pretrained and from_pretrained, for both the student and teacher. - max_length (
intأوNone، اختياري، القيمة الافتراضية1024) — الطول الأقصى الكلي للتسلسل (الموجّه + الإكمال) لأغراض الترميز والتقليص.
المعاملات التي تتحكم في التقطير
- temperature (
float، اختياري، القيمة الافتراضية1.0) — درجة الحرارة المستخدمة في أخذ العينات أثناء التوليد وفي حساب خسارة التقطير. تؤدي القيم الأعلى إلى توزيعات احتمالية أكثر نعومة. - lmbda (
float، اختياري، القيمة الافتراضية1.0) — احتمال استخدام بيانات على السياسة (التي يولدها الطالب) لكل شريحة تراكم التدرج. القيمة0.0تعني خارج السياسة بالكامل (اكتمالات مجموعة البيانات فقط)، و1.0تعني على السياسة بالكامل. - beta (
float، اختياري، القيمة الافتراضية1.0) — معامل الاستيفاء لخسارة تباعد جنسن-شانون المعمّم. عندما تكون القيمة0.0، تكون الخسارة هي تباعد KL الأمامي. عندما تكون القيمة1.0، تكون الخسارة هي تباعد KL العكسي. عندما تكون القيمة0.5، تكون الخسارة هي JSD القياسي. - distillation_objective (
str، اختياري، القيمة الافتراضية"iw_opd") — الهدف الذي سيتم تحسينه. يستخدم"iw_opd"هدف التقطير على السياسة المرجّح بأهمية الرموز المُستخرجة. يحافظ"jsd"على هدف JSD/KL المعمّم. - iw_opd_gamma (
float، اختياري، القيمة الافتراضية0.5) — تضخيم الأوزان المهمة لـdistillation_objective="iw_opd". - iw_opd_epsilon (
float، اختياري، القيمة الافتراضية1e-8) — مستقر يُستخدم عند تطبيع أوزان بادئة IW-OPD. - reverse_kl_top_1_mode (
str، اختياري، القيمة الافتراضية"sampled") — قاعدة الاختيار للرمز الأول (top-1) في دالة KL العكسية عندما يكونbeta > 0وloss_top_k == 1. يستخدم"sampled"الرمز الفعلي للإكمال في الدفعة. يستخدم"argmax"الرمز ذو أعلى احتمال لدى الطالب. لا تؤثر هذه الإعدادات على نطاق دعم KL الأمامي، الذي يستخدم دائمًا الرمز الأول (top-1) للمعلم. يتم تجاهلها عندما يكونbeta == 0أوloss_top_k != 1. - max_completion_length (
int، اختياري، القيمة الافتراضية512) — الحد الأقصى لعدد الرموز (tokens) التي سيتم توليدها لكل إكمال أثناء التوليد وفق السياسة (on-policy). - max_prompt_length (
intأوNone، اختياري) — الحد الأقصى لعدد الرموز (tokens) في الاستعلام. إذا كانتNone، يتم حسابها تلقائياً على أنهاmax_length - max_completion_length. تُقتطع الاستعلامات وفقاً لإعدادtruncation_sideالخاص بمجزّئ الرموز (tokenizer). - disable_dropout (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم تعطيل إسقاط العينة (dropout) في نموذج الطالب أثناء التدريب.
المعاملات التي تتحكم في نموذج المعلم
- teacher_model_name_or_path (
strأوNone، اختياري) — اسم النموذج أو المسار لنموذج المعلم. يُستخدم عند تحميل المعلم محليًا. - teacher_model_revision (
strأوNone، اختياري) — مراجعة نموذج المعلم (مثل اسم الفرع، أو العلامة، أو تجزئة الالتزام). - teacher_model_init_kwargs (
dict[str, Any]أوNone، اختياري) — حجج الكلمات المفتاحية التي تُمرَّر إلىAutoModelForCausalLM.from_pretrainedعند إنشاء نموذج المعلم من نص. - use_teacher_server (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان سيتم استخدام خادم معلم vLLM خارجي بدلاً من نموذج معلم محلي. - teacher_model_server_url (
strأوNone، اختياري) — الرابط الأساسي لخادم vLLM الذي يستضيف نموذج المعلم (على سبيل المثال،"http://localhost:8000"). عند ضبطه، يتم جلب احتمالات السجلات (logprobs) الخاصة بالمعلم من الخادم بدلاً من تنفيذ تمريرة أمامية محلية عندuse_teacher_server=True. - loss_top_k (
int, اختياري، القيمة الافتراضية1) — عدد الرموز العلوية المستخدمة عند حساب خسارة JSD/KL. يتم تقييد توزيعي الطالب والمعلم بهذه الرموز K وإعادة تطبيعها قبل حساب التباعد. إذا كانت القيمة 0، يُستخدم المفردات الكاملة. بالنسبة للمعلمين المحليين، القاعدة العامة للدعم هي: أعلى k من المعلم للتباعد الأمامي KL، وأعلى k من الطالب للتباعد العكسي KL، والاتحاد بينهما لـ JSD المختلط. عندماbeta > 0وloss_top_k == 1، لا يزال الدعم الأمامي يستخدم الرمز العلوي الأول للمعلم، بينما يتحكمreverse_kl_top_1_modeفي الرمز العلوي الأول العكسي. عندماuse_teacher_server=True، تتطلب المسار الأمامي النقي (beta=0) أن تكون هذه القيمة موجبة، وتستخدم سجلات الاحتمالات العلوية k للمعلم للحد الأمامي. عندماbeta > 0، تتطلب التقطير المدعوم بالخادمloss_top_k == 1ولا يدعم سوى الرموز العلوية الأولى العكسية"sampled". - loss_add_tail (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إضافة دلو ذيل يمثل كتلة الاحتمال المتبقية خارج نطاق top-k المحدد عند حساب الخسارة.
المعاملات التي تتحكم في التوليد وفق السياسة
- num_generations (
int، اختياري، القيمة الافتراضية1) — عدد الإكمالات التي سيتم توليدها لكل موجه أثناء التوليد وفق السياسة. - generation_batch_size (
intأوNone، اختياري) — عدد الموجهات الفريدة لكل عامل في كل خطوة من خطوات المُحسِّن. إذا كانتNone، يتم حسابها من(per_device_train_batch_size * gradient_accumulation_steps) // num_generations. - top_p (
float، اختياري، القيمة الافتراضية0.95) — معامل أخذ العينة Top-p (النواة) لتوليد السياسة. - top_k (
int، اختياري، القيمة الافتراضية0) — معامل أخذ العينة Top-k للتوليد وفق السياسة. تعطيل0تصفية Top-k.
المعاملات التي تتحكم في vLLM لتوليد الطالب
- use_vllm (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان سيتم استخدام vLLM لتوليد إكمالات على السياسة من نموذج الطالب. - vllm_mode (
str، اختياري، القيمة الافتراضية"colocate") — الوضع الخاص بتكامل vLLM للطالب. إما"server"أو"colocate". - vllm_server_base_url (
strأوNone، اختياري) — العنوان الأساسي لخادم vLLM الخاص بالطالب. إذا تم تقديمه، يتم تجاهلvllm_server_hostوvllm_server_port. - vllm_server_host (
str، اختياري، القيمة الافتراضية"0.0.0.0") — عنوان مضيف خادم vLLM للطالب. - vllm_server_port (
int، اختياري، القيمة الافتراضية8001) — منفذ خادم vLLM للطالب. - vllm_server_timeout (
float، اختياري، القيمة الافتراضية240.0) — مهلة الاتصال بخادم vLLM الخاص بالطالب. - vllm_group_port (
int، اختياري، القيمة الافتراضية51216) — منفذ لمجموعة تحديث أوزان vLLM (مُوصِّل NCCL). - vllm_gpu_memory_utilization (
float، اختياري، القيمة الافتراضية0.3) — نسبة استخدام ذاكرة وحدة معالجة الرسوميات (GPU) لمحرك vLLM للطالب المُستضاف في نفس الموقع. - vllm_tensor_parallel_size (
int، اختياري، القيمة الافتراضية1) — حجم التوازي للتوتر (Tensor parallel) لمحرك vLLM للطالب المُقام في نفس الموقع. - vllm_max_model_length (
intأوNone، اختياري) — أقصى طول لسلسلة النموذج لمحرك vLLM المُجمَّع. - vllm_model_impl (
str، اختياري، القيمة الافتراضية"vllm") — خلفية التنفيذ للنموذج في vLLM. استخدم"vllm"أو"transformers". - vllm_structured_outputs_regex (
strأوNone، اختياري) — نمط Regex للمخرجات المهيكلة في vLLM. - vllm_sync_frequency (
int، اختياري، القيمة الافتراضية1) — التردد (بخطوات التدريب) لمزامنة أوزان نموذج الطالب مع محرك vLLM. - vllm_enable_sleep_mode (
bool، اختياري، القيمة الافتراضيةFalse) — تفعيل وضع السكون في vLLM لتفريغ أوزان الطالب أثناء خطوة المُحسِّن.
المعاملات التي تتحكم في التسجيل
- log_completions (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان سيتم تسجيل عينة من أزواج (الموجّه، الإكمال) كلlog_completions_stepsخطوات. إذا كانrichمثبّتًا، فإنه يطبع العينة. إذا كان تسجيلwandbو/أوtrackioمفعّلًا، فإنه يسجّلها فيwandbو/أوtrackio. - log_completions_steps (
int، اختياري، القيمة الافتراضية100) — عدد الخطوات بين تسجيل عمليات الإكمال. يُستخدم فقط إذا كانlog_completionsهوTrue. - num_completions_to_print (
intأوNone، اختياري) — عدد المكملات التي سيتم طباعتها. إذا كانتNone، فسيتم تسجيل جميع المكملات.
فئة التهيئة الخاصة بـ experimental.iw_opd.IWOPDTrainer.
يمدّد TrainingArguments بمعاملات محددة للتقطير المعرفي. هذا الإعداد مستقل عن SFTConfig — حيث تُعلن جميع الحقول الضرورية هنا.
باستخدام HfArgumentParser يمكننا تحويل هذه الفئة إلى حُجج argparse يمكن تحديدها على سطر الأوامر.