TRL documentation

مدرب التقطير

TRL

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v1.17.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

مدرب التقطير

نظرة عامة

يُنفّذ مُدرّب التقطير (Distillation Trainer) التقطير المعرفي وفق السياسة (on-policy) كما هو موصوف في On-Policy Distillation of Language Models: Learning from Self-Generated Mistakes بقلم Rishabh Agarwal، Nino Vieillard، Yongchao Zhou، Piotr Stanczyk، Sabela Ramos، Matthieu Geist، و Olivier Bachem.

المستخلص من الورقة البحثية هو كالتالي:

تُستخدم تقنيات تقطير المعرفة (KD) على نطاق واسع لضغط نموذج المعلم لتقليل تكلفة الاستدلال ومساحة الذاكرة، وذلك من خلال تدريب نموذج طالب أصغر حجماً. ومع ذلك، فإن طرق تقطير المعرفة الحالية للنماذج التسلسلية التلقائية (auto-regressive) تعاني من عدم تطابق التوزيع بين التسلسلات الناتجة التي تُشاهد أثناء التدريب وتلك التي يولدها الطالب أثناء الاستدلال. لمعالجة هذه المشكلة، نطرح تقطير المعرفة المعمم (GKD). بدلاً من الاعتماد حصرياً على مجموعة ثابتة من التسلسلات الناتجة، يدرب GKD الطالب على التسلسلات الناتجة التي يولدها بنفسه، بالاستفادة من ملاحظات المعلم على مثل هذه التسلسلات. وعلى عكس أساليب تقطير المعرفة المُشرفة، يوفر GKD أيضاً المرونة في استخدام دوال خسارة بديلة بين الطالب والمعلم، وهو ما قد يكون مفيداً عندما يفتقر الطالب إلى القدرة التعبيرية اللازمة لمحاكاة توزيع المعلم.

يُدرّب DistillationTrainer نموذج طالب أصغر حجمًا لمطابقة توزيع الرموز التالية للمعلم على توليدات الطالب الخاصة به ضمن سياسته. يقوم بتوليد إكمالات الطالب ضمن سياسته (اختياريًا بدعم من vLLM) ومطابقة المعلم عبر توزيعه الكامل للرموز التالية باستخدام خسارة تباعد Jensen-Shannon مقسّمة إلى أجزاء موفّرة للذاكرة، بحيث لا يتمّ إنشاء التوزيع الكثيف للمعلم بالكامل أبدًا.

تمت مساهمة هذا المدرب بواسطة Carlos Miguel Patiño.

للنظير غير المتزامن الذي يفصل التوليد عن التدريب ويقيّم النتائج مقابل معلمة تُقدَّم عبر HTTP بدلاً من تمريرة أمامية محلية، راجع AsyncDistillationTrainer.

البدء السريع

يُظهر هذا المثال كيفية تدريب نموذج باستخدام طريقة التقطير. نُقطّر نموذج Qwen 2.5 0.5B Instruct من معلم Qwen 2.5 1.5B Instruct على الأوامر الواردة في مجموعة بيانات UltraFeedback prompt. يمكنك عرض البيانات في مجموعة البيانات هنا:

فيما يلي السكربت لتدريب النموذج.

# train_distillation.py
from datasets import load_dataset
from trl import DistillationTrainer

dataset = load_dataset("trl-lib/ultrafeedback-prompt", split="train")

trainer = DistillationTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    teacher_model="Qwen/Qwen2.5-1.5B-Instruct",
    train_dataset=dataset,
)
trainer.train()

نفّذ السكربت باستخدام الأمر التالي:

accelerate launch train_distillation.py

النظر بعمق أكبر في طريقة التقطير

تدرّب تقنيّة تقطير المعرفة على السياسة (On-policy knowledge distillation) نموذج الطالب على إعادة إنتاج توزيع الرموز التالية للمعلم على الإكمالات التي يولّدها الطالب نفسه، بدلاً من مجموعة ثابتة من مخرجات المعلم. يتيح التعلّم من توليداته الخاصة للطالب تصحيح أخطائه، وهو ما يتفوّق بشكل عام على تقطير المعرفة خارج السياسة (Off-policy distillation). تفصّل هذه القسم كيفية عملها عملياً، مع تغطية الخطوتين الرئيسيتين: توليد الإكمالات وحساب الدالة الخاسرة.

توليد الاكتمالات

في كل خطوة تدريب، يولّد الطالب دفعة من الإكمالات للموجّهات المُستخرجة.

حساب الخسارة

الدالة الخاسرة هي انحراف Jensen-Shannon المعمّم (JSD) بين توزيع الطالب $p_S$ وتوزيع المعلم $p_T$ عبر رموز الإكمال المولّدة، مع الاستيفاء بواسطة beta والمعرّفة على النحو التالي: $\mathcal{L}_\beta = \beta \, \mathbb{D}_{\mathrm{KL}}\!\left[ p_T \| p_M \right] + (1 - \beta) \, \mathbb{D}_{\mathrm{KL}}\!\left[ p_S \| p_M \right], \qquad p_M = (1 - \beta) \, p_S + \beta \, p_T,$

حيث $p_M$ هو $\beta$ -مزيج التوزيعين. تتقلص نقاط النهاية إلى تباعدات نقية: beta=0.0 يعطي تباعد $\mathbb{D}_{\mathrm{KL}}\!\left[ p_T \| p_S \right]$ و beta=1.0 تباعد $\mathbb{D}_{\mathrm{KL}}\!\left[ p_S \| p_T \right]$ .

عملياً، يتم حساب الإسقاط إلى سجلات المفردات (vocabulary logits) والانحراف على شكل مقاطع، لذا فإن ذروة ذاكرة التفعيل لا تتناسب مع حجم مصفوفة السجلات الكاملة (المفردات × طول التسلسل). راجع تقليل استخدام الذاكرة.

نوع مجموعة البيانات المتوقع

يجب تنسيق مجموعة البيانات كمجموعة بيانات حوارية تتضمن المحفّز فقط. يقوم الطالب بتوليد إكمالاته الخاصة على السياسة، لذا لا يُحتاج إلى المحفّز فقط:

{"prompt": [{"role": "user", "content": "What color is the sky?"}]}

المقاييس المسجّلة

أثناء التدريب والتقييم، نسجّل المقاييس التالية:

num_tokens: إجمالي عدد الرموز التي تمت معالجتها حتى الآن، بما في ذلك كل من الاستعلامات (prompts) والإكمالات (completions). عند استخدام الأدوات، يتم احتساب الرموز غير المرتبطة بالأدوات فقط.
step_time: متوسط الوقت (بالثواني) المستغرق لكل خطوة تدريب (بما في ذلك التوليد).
completions/mean_length: متوسط طول المكملات المولّدة. عند استخدام الأدوات، تُحتسب الرموز غير المتعلقة بالأدوات فقط.
completions/min_length: الحد الأدنى لطول المكملات المولّدة. عند استخدام الأدوات، تُحتسب الرموز غير المرتبطة بالأدوات فقط.
completions/max_length: الحد الأقصى لطول المكملات المولّدة. عند استخدام الأدوات، يتم احتساب رموز غير الأدوات فقط.
completions/mean_terminated_length: متوسط طول الإكمالات المولّدة التي تنتهي بـ EOS. عند استخدام الأدوات، يتم احتساب رموز غير الأدوات فقط.
completions/min_terminated_length: الحد الأدنى لطول المكملات المولّدة التي تنتهي بـ EOS. عند استخدام الأدوات، يتم احتساب رموز غير الأدوات فقط.
completions/max_terminated_length: الحد الأقصى لطول المكملات المولّدة التي تنتهي بـ EOS. عند استخدام الأدوات، يتم احتساب رموز غير الأدوات فقط.
completions/clipped_ratio: نسبة الإكمالات المقطوعة (المُقصاة).
tools/call_frequency: متوسط عدد استدعاءات الأدوات لكل إكمال في دفعة التوليد. يُسجَّل فقط عند توفير tools.
tools/failure_frequency: نسبة استدعاءات الأدوات التي فشلت (لم يتم العثور على الأداة، أو أثار استثناءً، أو أن نوع الاستدعاء غير مدعوم). تكون قيمتها 0.0 عندما لم يتم استدعاء أي أداة. تُسجَّل فقط عند توفير tools.
entropy: متوسط إنتروبيا توقعات الرموز عبر المكملات المولّدة (بالنات).

التخصيص

تسريع التدريب باستخدام التوليد المدعوم من vLLM

غالبًا ما يكون التوليد هو العائق الرئيسي عند التدريب باستخدام طرق على السياسة. لتسريع التوليد، يمكنك استخدام vLLM، وهو محرك استدلال عالي الإنتاجية ومنخفض الكمون للنماذج اللغوية الكبيرة. لتفعيله، قم أولاً بتثبيت الحزمة باستخدام

pip install trl[vllm]

ندعم طريقتين لاستخدام vLLM أثناء التدريب: وضع التشارك ووضع الخادم.

الخيار 1: وضع التجميع

في هذا الوضع، يعمل vLLM داخل عملية المُدرِّب ويتشارك ذاكرة GPU مع نموذج التدريب. يتجنّب هذا إطلاق خادم منفصل ويمكن أن يحسّن استخدام GPU، لكنه قد يؤدي إلى تنافس على الذاكرة في وحدات GPU الخاصة بالتدريب. هذا هو الوضع الافتراضي.

from trl import DistillationConfig

training_args = DistillationConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)

الخيار 2: وضع الخادم

في هذا الوضع، يعمل vLLM في عملية منفصلة (ويعتمد على وحدات معالجة رسومية منفصلة) ويتواصل مع المُدرِّب عبر HTTP. وهذا مثالي إذا كانت لديك وحدات معالجة رسومية مخصصة للاستدلال.

بدء خادم vLLM:

VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --max-logprobs -1

تفعيل وضع الخادم في سكربت التدريب الخاص بك:

from trl import DistillationConfig

training_args = DistillationConfig(
    ...,
    use_vllm=True,
    vllm_mode="server",
)

تأكد من أن الخادم يستخدم وحدات معالجة رسومية مختلفة عن تلك التي يستخدمها المدرب، وإلا فقد تواجه أخطاء NCCL. يمكنك تحديد وحدات المعالجة الرسومية المراد استخدامها باستخدام متغير البيئة CUDA_VISIBLE_DEVICES.

يعتمد على حجم النموذج ومتطلبات ذاكرة وحدة معالجة الرسوميات (GPU) الإجمالية للتدريب، قد تحتاج إلى ضبط معامل vllm_gpu_memory_utilization في DistillationConfig لتجنب سوء الاستخدام أو أخطاء نفاد الذاكرة.

لمزيد من المعلومات، راجع تسريع التدريب باستخدام vLLM.

تدريب المحوِّلات باستخدام PEFT

ندعم التكامل الوثيق مع مكتبة 🤗 PEFT، مما يتيح لك تدريب المُكيِّفات (adapters) ومشاركتها على Hub بدلاً من تدريب الطالب (student) بالكامل.

from datasets import load_dataset
from trl import DistillationTrainer
from peft import LoraConfig

dataset = load_dataset("trl-lib/ultrafeedback-prompt", split="train")

trainer = DistillationTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    teacher_model="Qwen/Qwen2.5-1.5B-Instruct",
    train_dataset=dataset,
    peft_config=LoraConfig(),
)
trainer.train()

تقرأ خسارة التقطير lm_head.weight مباشرةً وتشغّل هيكل الطالب دون المرور عبر PeftModel.forward(). لذلك، يتم رفض الملاءمات على lm_head (عبر target_modules) وطرق تعلم المحفز (PromptTuning، PrefixTuning، P-Tuning)، لأنها ستُتجاهل بصمت. لتدريب الرأس، استخدم modules_to_save=["lm_head"] بدلاً من ذلك.

تدريب الوكيل

يدعم DistillationTrainer تدريب الوكيل: حيث يستدعي الطالب الأدوات أثناء التوليد ويُقَطَّر على المسار الناتج. يتم إخفاء رموز نتائج الأدوات من دالة الخسارة، بحيث يُدرَّب الطالب فقط على الرموز التي ولّدها بنفسه.

الأدوات

يتوقع الحجة tools قائمة من دوال بايثون تُعرّف الأدوات المتاحة للوكيل:

from trl import DistillationTrainer

trainer = DistillationTrainer(
    tools=[tool1, tool2],
    ...,
)

يجب أن يكون كل أداة دالة بايثون قياسية مع حُجج وأنواع إرجاع مُعلَّمة بالنوع، إلى جانب سلسلة توثيق بنمط Google تصف غرضها وحُججها وقيمة الإرجاع. لمزيد من التفاصيل، راجد دليل تمرير الأدوات.

يتطلب حلقة استدعاء الأداة أن يكون قالب المحادثة حافظًا على البادئة (فإضافة رسالة أداة يجب ألا تُغيّر طريقة عرض الرسائل السابقة). بالنسبة لعائلات النماذج المعروفة (مثل Qwen3 وDeepSeek-V3)، يقوم TRL تلقائيًا باستبدال قالب التدريب المُعدّل عند تمكين الأدوات. راجع قوالب المحادثة للحصول على القائمة الكاملة.

استخدم max_tool_calling_iterations في DistillationConfig لتحديد الحد الأقصى لعدد جولات استدعاء الأدوات. افتراضيًا، لا يوجد حد، ويتوقف التوليد عندما ينتج الطالب ردًا في جولة دون أي استدعاءات للأدوات.

مثال:

from trl import DistillationTrainer

def multiply(a: int, b: int) -> int:
    """
    Multiplies two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The product of the two integers.
    """
    return a * b

trainer = DistillationTrainer(
    tools=[multiply],
    ...,
)

لا تُدعَم الأدوات غير المتزامنة بعد — قم بتمرير دوال متزامنة.

استجابات الأدوات متعددة الوسائط

يمكن للأدوات إرجاع الصور إلى جانب النص عن طريق إرجاع قائمة من كتل المحتوى. وهذا مفيد لتدريب وكلاء نماذج اللغة المرئية (VLM) حيث يوفر الأداة تغذية راجعة بصرية (مثل لقطات الشاشة، والمخططات، والتقاطات الكاميرا).

from PIL import Image

def take_screenshot() -> list:
    """
    Takes a screenshot of the current screen.

    Returns:
        The screenshot image with a description.
    """
    img = Image.open("screenshot.png")
    return [{"type": "image", "image": img}, {"type": "text", "text": "Here is the screenshot."}]

تُحقن الصور المُعادَة تلقائيًا في المحادثة وتُمرَّر إلى VLM لجولات التوليد اللاحقة.

تدريب نماذج اللغة البصرية

يدعم DistillationTrainer تقطير نماذج الرؤية واللغة (VLMs) على مجموعات بيانات متعددة الوسائط تحتوي على نص وصور. مرّر نموذج VLM كل طالب ومعلم، وفّر مجموعة بيانات تحتوي على الموجه فقط مع عمود image (صورة واحدة لكل عينة) أو عمود images (قائمة صور لكل عينة). لمزيد من المعلومات حول بنية مجموعة البيانات المتوقعة، راجع قسم Dataset Format — Vision datasets.

تم الاختبار مع:

Gemma 3 — على سبيل المثال google/gemma-3-4b-it
LLaVA-NeXT — على سبيل المثال، llava-hf/llava-v1.6-mistral-7b-hf
Qwen2-VL — على سبيل المثال، Qwen/Qwen2-VL-2B-Instruct
Qwen2.5-VL — على سبيل المثال، Qwen/Qwen2.5-VL-3B-Instruct

لا يُكفَل التوافق مع جميع نماذج VLM. إذا كنت تعتقد أنه ينبغي دعم نموذج معين، فلا تتردد في فتح مشكلة على GitHub — أو الأفضل من ذلك، تقديم طلب سحب يتضمن التغييرات المطلوبة.

واجهة سطر الأوامر

استخدم أداة سطر الأوامر trl distillation لبدء تدريب التقطير من سطر الأوامر. تدعم هذه الأداة التدريب الكامل وتقنية LoRA عبر أعلام ModelConfig القياسية.

# Full training:
trl distillation \
    --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
    --teacher_model_name_or_path Qwen/Qwen2.5-1.5B-Instruct \
    --dataset_name trl-lib/ultrafeedback-prompt \
    --learning_rate 2e-5 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --output_dir distilled-model \
    --num_train_epochs 1

# LoRA:
trl distillation \
    --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
    --teacher_model_name_or_path Qwen/Qwen2.5-1.5B-Instruct \
    --dataset_name trl-lib/ultrafeedback-prompt \
    --learning_rate 2e-4 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --output_dir distilled-model \
    --num_train_epochs 1 \
    --use_peft \
    --lora_r 64 \
    --lora_alpha 16

DistillationTrainer

فئة trl.DistillationTrainer

< source >

( model: str | PreTrainedModel | PeftModelteacher_model: str | transformers.modeling_utils.PreTrainedModel | None = Noneargs: trl.trainer.distillation_config.DistillationConfig | 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.processing_utils.ProcessorMixin | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)quantization_config: BitsAndBytesConfig | None = Nonepeft_config: PeftConfig | None = Nonetools: list[collections.abc.Callable] | None = None )

المعاملات

model (str أو PreTrainedModel أو PeftModel) — النموذج المراد تدريبه. يمكن أن يكون أحد ما يلي:
- سلسلة نصية، تكون معرف النموذج لنموذج مُدرَّب مسبقًا مستضاف داخل مستودع نماذج على huggingface.co، أو مسارًا إلى مجلد يحتوي على أوزان النموذج المحفوظة باستخدام save_pretrained، مثل './my_model_directory/'. يتم تحميل النموذج باستخدام <ModelArchitecture>.from_pretrained (حيث يُشتق <ModelArchitecture> من إعدادات النموذج) مع الحُجج المُسمّاة الموجودة في args.model_init_kwargs. إذا لم يُحدد dtype في args.model_init_kwargs، فإن القيمة الافتراضية هي float32. وهذا يختلف عن from_pretrained، حيث (منذ Transformers v5) يُستنتج نوع البيانات من إعدادات النموذج.
- كائن PreTrainedModel. يتم دعم نماذج اللغة السببية فقط.
- كائن PeftModel. يتم دعم نماذج اللغة السببية فقط.
teacher_model (str أو PreTrainedModel، اختياري) — نموذج المعلم الذي تُدرَّب عليه شبكة الطالب لمطابقة توزيع الرموز التالية. يمكن أن يكون معرف نموذج / مسارًا (يُحمَّل مثل model، باستخدام args.teacher_model_init_kwargs) أو نموذج PreTrainedModel مُهيّأ. يجب أن يتشارك معجم الطالب. قد يُستغنى عنه في الفئات الفرعية التي توفر المعلم بطريقة أخرى (مثل خادم عن بُعد).
args (DistillationConfig، اختياري) — إعدادات هذا المدرب. إذا كانت None، يتم استخدام إعداد افتراضي.
train_dataset (Dataset أو IterableDataset) — مجموعة البيانات المستخدمة للتدريب. يجب أن تتضمن عمودًا "prompt". أي أعمدة إضافية في مجموعة البيانات يتم تجاهلها. يمكن أن يكون تنسيق العينات إما:
- قياسي: يحتوي كل عينة على نص عادي.
- حواري: تحتوي كل عينة على رسائل منظمة (مثل الدور والمحتوى).
عندما يكون train_dataset من نوع IterableDataset (مثل مجموعة بيانات التدفق)، يجب تعيين max_steps في حُجج التدريب، لأن طولها لا يمكن استنتاجه، ويُطلب تحديد إجمالي عدد خطوات التدريب لتحديد نطاق حلقة التدريب وإعداد مجدول معدل التعلم.
eval_dataset (Dataset أو IterableDataset أو DatasetDict أو IterableDatasetDict أو dict[str, Dataset | IterableDataset]) — مجموعة البيانات المستخدمة للتقييم. يجب أن تستوفي نفس المتطلبات التي تستوفيها train_dataset.
processing_class (PreTrainedTokenizerBase، ProcessorMixin، اختياري) — فئة المعالجة المستخدمة لمعالجة البيانات. يجب ضبط جانب الحشو على “يسار”. إذا كانت None، يتم تحميل فئة المعالجة من اسم النموذج باستخدام from_pretrained. يجب ضبط رمز الحشو، tokenizer.pad_token. إذا لم تضبط فئة المعالجة رمز الحشو، سيتم استخدام tokenizer.eos_token كقيمة افتراضية.
callbacks (قائمة من TrainerCallback, اختياري) — قائمة من استدعاءات المراجعة (callbacks) لتخصيص حلقة التدريب. ستُضاف هذه الاستدعاءات إلى قائمة استدعاءات المراجعة الافتراضية المفصّلة هنا.
إذا كنت ترغب في إزالة أحد المراجعات الافتراضية المستخدمة، فاستخدم طريقة remove_callback.
optimizers (tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None]، اختياري، القيمة الافتراضية (None, None)) — مجموعة (tuple) تحتوي على المُحسِّن (optimizer) والمُجدوِل (scheduler) المطلوبين للاستخدام. ستكون القيمة الافتراضية هي نسخة من AdamW على النموذج الخاص بك، مع مُجدوِل يُحدده get_linear_schedule_with_warmup ويُتحكم به عبر args.
quantization_config (BitsAndBytesConfig، اختياري) — إعدادات التكميم المستخدمة عند تحميل النموذج من معرّف النموذج. ادمجها مع peft_config لتدريب QLoRA. يتم تجاهلها إذا كان النموذج مُنشأً بالفعل.
peft_config (PeftConfig، اختياري) — إعدادات PEFT المستخدمة لتغليف النموذج. إذا كانت None، فلن يتم تغليف النموذج.
tools (قائمة من Callable، اختياري) — قائمة من دوال الأدوات القابلة للاستدعاء التي يمكن للنموذج استدعاؤها أثناء التوليد. يجب أن تكون كل أداة دالة بايثون قياسية مع حُجج وقيم إرجاع مُعلَّمة الأنواع بشكل صحيح، وتعليق مستند بنمط Google يصف غرضها وحُججها وقيمة الإرجاع. لمزيد من التفاصيل، راجع: https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. يستخدم النموذج اسم الدالة، وتلميحات الأنواع، وتعليق المستند لتحديد كيفية استدعائها. تأكد من أن قالب الدردشة الخاص بالنموذج يدعم استخدام الأدوات وأنه تم ضبطه الدقيق (fine-tuned) لاستدعاء الأدوات.

مدرب لتقطير المعرفة. يتم تدريب الطالب وفق السياسة — فهو يولّد الاكتمالات بنفسه — لمطابقة توزيع الرمز التالي للمعلم تحت تباعد جنسن-شونن المعمم (الذي يمزج بين تباعد KL الأمامي، وتباعد KL العكسي، وتباعد JSD عبر beta)، كما تم تقديمه في On-Policy Distillation of Language Models.

مثال:

>>> from trl import DistillationTrainer
>>> from datasets import load_dataset

>>> dataset = load_dataset("trl-lib/tldr", split="train")

>>> trainer = DistillationTrainer(
...     model="Qwen/Qwen2.5-0.5B-Instruct",
...     teacher_model="Qwen/Qwen2.5-1.5B-Instruct",
...     train_dataset=dataset,
... )
>>> trainer.train()

تدريب

< source >

المعاملات

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

< source >

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

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

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

push_to_hub

< source >

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

المعاملات

commit_message (str، اختياري، الافتراضي "End of training") — الرسالة التي تُرسل عند الدفع.
blocking (bool، اختياري، الافتراضي True) — ما إذا كان ينبغي للدالة أن تُرجع فقط بعد اكتمال git push.
token (str، اختياري، القيمة الافتراضية None) — رمز (Token) يملك صلاحية الكتابة لتجاوز الحجج الأصلية الخاصة بـ Trainer.
revision (str، اختياري) — مراجعة git التي سيتم الالتزام منها. الافتراضي هو رأس فرع “main”.
kwargs (dict[str, Any]، اختياري) — معلمات إضافية تُمرَّر إلى ~Trainer.create_model_card.

ارفع self.model وself.processing_class إلى مركز النماذج 🤗 في المستودع self.args.hub_model_id.

DistillationConfig

فئة trl.DistillationConfig

< 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 = 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 | None = Falselabel_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 = Falseteacher_model_name_or_path: str | None = Noneteacher_model_revision: str | None = Noneteacher_model_init_kwargs: dict[str, typing.Any] | str | None = Nonedisable_dropout: bool = Falsemax_completion_length: int | None = 512ds3_gather_for_generation: bool = Trueshuffle_dataset: bool | None = Truepad_to_multiple_of: int | str | None = 'auto'temperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonegeneration_kwargs: dict | str | None = Nonechat_template_kwargs: dict | str | None = Nonerepetition_penalty: float = 1.0cache_implementation: str | None = Noneuse_vllm: bool = Falsevllm_mode: str = 'colocate'vllm_model_impl: str = 'vllm'vllm_enable_sleep_mode: bool = Falsevllm_structured_outputs_regex: str | None = Nonevllm_server_base_url: str | None = Nonevllm_server_host: str = '0.0.0.0'vllm_server_port: int = 8000vllm_server_timeout: float = 240.0vllm_group_port: int = 51216vllm_gpu_memory_utilization: float = 0.3vllm_max_model_length: int | None = Nonevllm_tensor_parallel_size: int = 1beta: float = 1.0max_tool_calling_iterations: int | None = Nonelog_completions: bool = Falsenum_completions_to_print: int | None = Nonelog_unique_prompts: bool = False )

المعاملات التي تتحكم في النموذج ونموذج المعلم

model_init_kwargs (str أو 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.
teacher_model_name_or_path (str, اختياري) — اسم النموذج أو المسار الخاص بنموذج المعلم. يُستخدم عند تحميل المعلم محليًا.
teacher_model_revision (str, اختياري) — مراجعة النموذج المُعلِّم (مثل اسم الفرع، أو العلامة، أو تجزئة الالتزام).
teacher_model_init_kwargs (str أو dict[str, Any]، اختياري) — حجج الكلمات المفتاحية التي تُمرَّر إلى AutoModelForCausalLM.from_pretrained عند إنشاء نموذج المعلم من نص.
disable_dropout (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تعطيل إسقاط العينة (dropout) في نموذج الطالب أثناء التدريب.

المعاملات التي تتحكم في معالجة البيانات المسبقة

remove_unused_columns (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم الاحتفاظ فقط بالعمود "prompt" في مجموعة البيانات. يستهلك المدرب عمود prompt الخام ويولّد الإكمالات على السياسة، لذا تكون القيمة الافتراضية False.
max_completion_length (int أو None، اختياري، القيمة الافتراضية 512) — الحد الأقصى لعدد الرموز (tokens) التي سيتم توليدها لكل إكمال أثناء التوليد وفق السياسة (on-policy).
ds3_gather_for_generation (bool، اختياري، القيمة الافتراضية True) — تنطبق هذه الإعدادات على DeepSpeed ZeRO-3. إذا تم تفعيلها، يتم تجميع أوزان نموذج السياسة للتوليد، مما يحسّن سرعة التوليد. ومع ذلك، فإن تعطيل هذا الخيار يتيح تدريب نماذج تتجاوز سعة ذاكرة VRAM لبطاقة رسومات واحدة، على الرغم من أن ذلك يأتي على حساب بطء التوليد. لا يتوافق تعطيل هذا الخيار مع توليد vLLM.
shuffle_dataset (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم خلط مجموعة بيانات التدريب.
pad_to_multiple_of (int أو str، اختياري، القيمة الافتراضية "auto") — إذا تم ضبطه، فسيتم ملء معرّفات الأوامر (prompts ids) ومعرّفات الإكمالات (completions ids) إلى مضاعف لهذا القيمة. "auto" يملأ إلى مضاعف لـ 128 على Neuron (AWS Trainium)، حيث يُترجم مرة واحدة لكل شكل إدخال، ولا يملأ في أي مكان آخر.

المعاملات التي تتحكم في التوليد

temperature (float، اختياري، القيمة الافتراضية 1.0) — درجة الحرارة المستخدمة في أخذ العينات أثناء التوليد وفي حساب خسارة التقطير. تؤدي القيم الأعلى إلى توزيعات احتمالية أكثر نعومة.
top_p (float، اختياري، القيمة الافتراضية 1.0) — معامل أخذ العينات Top-p (النواة) للتوليد وفق السياسة.
top_k (int، اختياري، القيمة الافتراضية 0) — معامل أخذ العينة Top-k للتوليد وفق السياسة. تعطيل 0 تصفية Top-k.
min_p (float, اختياري) — أدنى احتمال للرمز، والذي يُضرب في احتمال الرمز الأكثر احتمالاً. يجب أن يكون قيمة بين 0.0 و1.0. القيم النموذجية تقع في نطاق 0.01-0.2.
generation_kwargs (dict[str, Any]، اختياري) — معلمات إضافية بالكلمات المفتاحية تُمرَّر إلى GenerationConfig (في حال استخدام transformers) أو SamplingParams (في حال استخدام vLLM) عند أخذ عينات من المكملات. يمكن استخدام هذا لتخصيص سلوك التوليد بشكل أكبر، مثل تعيين suppress_tokens، num_beams، وما إلى ذلك. إذا احتوى على مفاتيح تتعارض مع معلمات التوليد الأخرى (مثل min_p، top_p، وما إلى ذلك)، فإنها ستُلغيها.
chat_template_kwargs (dict[str, Any]، اختياري) — معلمات إضافية بالكلمات المفتاحية تُمرَّر إلى دالة apply_chat_template عند توليد الإكمالات.
repetition_penalty (float، اختياري، القيمة الافتراضية 1.0) — قيمة عشرية تعاقب الرموز الجديدة بناءً على ما إذا كانت تظهر في الاستعلام والنص المولَّد حتى الآن. القيم > 1.0 تشجع النموذج على استخدام رموز جديدة، بينما القيم < 1.0 تشجع النموذج على تكرار الرموز.
cache_implementation (str، اختياري) — تنفيذ طريقة التخزين المؤقت لتسريع التوليد عندما يكون use_vllm مضبوطًا على False.

المعاملات التي تتحكم في تسريع التوليد المدعوم بواسطة vLLM

use_vllm (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم استخدام vLLM لتوليد إكمالات على السياسة من نموذج الطالب.
vllm_mode (str، اختياري، القيمة الافتراضية "colocate") — الوضع الخاص بتكامل vLLM للطالب. إما "server" أو "colocate".
vllm_model_impl (str، اختياري، القيمة الافتراضية "vllm") — خلفية التنفيذ للنموذج في vLLM. استخدم "vllm" أو "transformers".
vllm_enable_sleep_mode (bool، اختياري، القيمة الافتراضية False) — تفعيل وضع السكون في vLLM لتفريغ أوزان الطالب أثناء خطوة المُحسِّن.
vllm_structured_outputs_regex (str، اختياري) — نمط Regex للمخرجات المهيكلة في vLLM.

المعاملات التي تتحكم في خادم vLLM (تُستخدم فقط عندما تكون `vllm_mode` هي `"server"`)

vllm_server_base_url (str، اختياري) — العنوان الأساسي لخادم vLLM الخاص بالطالب. إذا تم تقديمه، يتم تجاهل vllm_server_host وvllm_server_port.
vllm_server_host (str، اختياري، القيمة الافتراضية "0.0.0.0") — عنوان مضيف خادم vLLM للطالب.
vllm_server_port (int، اختياري، القيمة الافتراضية 8000) — منفذ خادم vLLM للطالب.
vllm_server_timeout (float، اختياري، القيمة الافتراضية 240.0) — مهلة الاتصال بخادم vLLM الخاص بالطالب.
vllm_group_port (int، اختياري، القيمة الافتراضية 51216) — منفذ لمجموعة تحديث أوزان vLLM (مُوصِّل NCCL).

المعاملات التي تتحكم في تنفيذ vLLM المتزامن (تُستخدم فقط عندما يكون `vllm_mode` هو `"colocate"`)

vllm_gpu_memory_utilization (float، اختياري، القيمة الافتراضية 0.3) — نسبة استخدام ذاكرة وحدة معالجة الرسوميات (GPU) لمحرك vLLM للطالب المُستضاف في نفس الموقع.
vllm_max_model_length (int، اختياري) — أقصى طول لسلسلة النموذج لمحرك vLLM المشترك.
vllm_tensor_parallel_size (int، اختياري، القيمة الافتراضية 1) — حجم التوازي للتوتر (Tensor parallel) لمحرك vLLM للطالب المُقام في نفس الموقع.

المعاملات التي تتحكم في التدريب

beta (float، اختياري، القيمة الافتراضية 1.0) — معامل الاستيفاء لفقدان تباعد جنسن-شانون المعمّم. عندما تكون القيمة 0.0، يكون الفقدان هو تباعد KL الأمامي. عندما تكون القيمة 1.0، يكون الفقدان هو تباعد KL العكسي. عندما تكون القيمة 0.5، يكون الفقدان هو JSD القياسي. على عكس beta في GRPO (وهو معامل عقوبة KL مقابل نموذج مرجعي)، هنا يتم اختيار التباعد نفسه؛ فلا توجد عقوبة KL لنموذج مرجعي.
max_tool_calling_iterations (int, اختياري) — الحد الأقصى لعدد جولات استدعاء الأدوات عند تدريب وكيل. إذا كانت None، فلا يوجد حد، ويتوقف التوليد عندما يولّد النموذج ردًا في جولة دون أي استدعاءات للأدوات، أو عندما يبلغ طول الرد الإجمالي max_model_length.

المعاملات التي تتحكم في التسجيل

log_completions (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تسجيل عينة من أزواج (الموجّه، الإكمال) كل logging_steps خطوات. إذا كان rich مثبّتًا، فسيتم طباعة العينة. إذا كان تسجيل wandb و/أو trackio مفعّلًا، فسيتم تسجيلها في wandb و/أو trackio.
num_completions_to_print (int, اختياري) — عدد الإكمالات التي سيتم طباعتها باستخدام rich. إذا كانت None، فسيتم تسجيل جميع الإكمالات.
log_unique_prompts (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تسجيل الأوامر الفريدة. إذا كانت True، يتم تسجيل الأوامر الفريدة فقط. إذا كانت False، يتم تسجيل جميع الأوامر.

فئة التهيئة الخاصة بـ DistillationTrainer.

يمدّد TrainingArguments بمعاملات محددة للتقطير المعرفي. جميع الحقول الضرورية مُعلَّنة هنا.

باستخدام HfArgumentParser يمكننا تحويل هذه الفئة إلى حُجج argparse يمكن تحديدها على سطر الأوامر.

تتميز هذه المعلمات بقيم افتراضية مختلفة عن TrainingArguments:

logging_steps: القيمة الافتراضية هي 10 بدلاً من 500.

gradient_checkpointing: القيمة الافتراضية هي True بدلاً من False.

bf16: القيمة الافتراضية هي True إذا لم يتم تعيين fp16، بدلاً من False.

learning_rate: القيمة الافتراضية هي 1e-6 بدلاً من 5e-5.

Update on GitHub

←فهرس الأوراق DPO→