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

في ورقة 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

< >

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

تدريب

< >

( 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

كائن يحتوي على عدد الخطوات العالمية، وخسارة التدريب، والمقاييس.

نقطة الدخول الرئيسية للتدريب.

save_model

< >

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

سيحفظ النموذج، بحيث يمكنك إعادة تحميله باستخدام from_pretrained().

سيتم الحفظ من العملية الرئيسية فقط.

push_to_hub

< >

( 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

< >

( 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 to False) — 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 يمكن تحديدها على سطر الأوامر.

Update on GitHub