TRL documentation

مدرب SFT

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

مدرب SFT

All_models-SFT-blue smol_course-Chapter_1-yellow

نظرة عامة

يدعم TRL مُدرّب الضبط الدقيق الإشرافي (SFT Trainer) لتدريب نماذج اللغة.

لا يدعم SFTTrainer بشكل أصلي نماذج الانتشار مثل DiffusionGemma، لكنه يمكن توسيعه بسهولة للقيام بذلك، راجع مثال SFT block-diffusion.

تمت مساهمة Younes Belkada في هذه طريقة ما بعد التدريب.

البدء السريع

يُظهر هذا المثال كيفية تدريب نموذج لغوي باستخدام SFTTrainer من TRL. نقوم بتدريب نموذج Qwen 3 0.6B على مجموعة بيانات Capybara، وهي مجموعة بيانات متعددة الأدوار مدمجة ومتنوعة تُستخدم لاختبار القدرات الاستدلالية والتعميم.

from trl import SFTTrainer
from datasets import load_dataset

trainer = SFTTrainer(
    model="Qwen/Qwen3-0.6B",
    train_dataset=load_dataset("trl-lib/Capybara", split="train"),
)
trainer.train()

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

يدعم SFT كلا من مجموعات بيانات نمذجة اللغة ومجموعات بيانات إكمال الموجه. ويتوافق SFTTrainer مع صيغ مجموعات البيانات المعيارية والمحادثة على حد سواء. عند تزويده بمجموعة بيانات محادثة، سيطبّق المدرب قالب المحادثة على مجموعة البيانات تلقائيًا.

# Standard language modeling
{"text": "The sky is blue."}

# Conversational language modeling
{"messages": [{"role": "user", "content": "What color is the sky?"},
              {"role": "assistant", "content": "It is blue."}]}

# Standard prompt-completion
{"prompt": "The sky is",
 "completion": " blue."}

# Conversational prompt-completion
{"prompt": [{"role": "user", "content": "What color is the sky?"}],
 "completion": [{"role": "assistant", "content": "It is blue."}]}

إذا لم يكن مجموعة بياناتك في أحد هذه الصيغ، يمكنك معالجتها مسبقًا لتحويلها إلى الصيغة المتوقعة. إليك مثال باستخدام مجموعة بيانات FreedomIntelligence/medical-o1-reasoning-SFT:

from datasets import load_dataset

dataset = load_dataset("FreedomIntelligence/medical-o1-reasoning-SFT", "en")

def preprocess_function(example):
    return {
        "prompt": [{"role": "user", "content": example["Question"]}],
        "completion": [
            {"role": "assistant", "content": f"<think>{example['Complex_CoT']}</think>{example['Response']}"}
        ],
    }

dataset = dataset.map(preprocess_function, remove_columns=["Question", "Response", "Complex_CoT"])
print(next(iter(dataset["train"])))
{
    "prompt": [
        {
            "content": "Given the symptoms of sudden weakness in the left arm and leg, recent long-distance travel, and the presence of swollen and tender right lower leg, what specific cardiac abnormality is most likely to be found upon further evaluation that could explain these findings?",
            "role": "user",
        }
    ],
    "completion": [
        {
            "content": "<think>Okay, let's see what's going on here. We've got sudden weakness [...] clicks into place!</think>The specific cardiac abnormality most likely to be found in [...] the presence of a PFO facilitating a paradoxical embolism.",
            "role": "assistant",
        }
    ],
}

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

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

تفصّل هذه القسم كيفية عمل SFT عملياً، مع تغطية الخطوات الرئيسية: المعالجة المسبقة، والتجزئة، وحساب الخسارة.

المعالجة المسبقة والتجزئة

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

حساب الخسارة

sft_figure

الخسارة المستخدمة في SFT هي خسارة الانتروبيا المتقاطعة على مستوى الرموز, المعرّفة على النحو التالي: LSFT(θ)=−∑t=1Tlog⁡pθ(yt∣y<t), \mathcal{L}_{\text{SFT}}(\theta) = - \sum_{t=1}^{T} \log p_\theta(y_t \mid y_{<t}),

حيث yt y_t هو الرمز المستهدف عند خطوة الزمن t t , ويتم تدريب النموذج للتنبؤ بالرمز التالي بناءً على الرموز السابقة. عمليًا، يتم إخفاء رموس الحشو أثناء حساب الخسارة.

يقترح البحث On the Generalization of SFT: A Reinforcement Learning Perspective with Reward Rectification دالة خسارة بديلة تُسمى Dynamic Fine-Tuning (DFT)، تهدف إلى تحسين التعميم من خلال تصحيح إشارة المكافأة. يمكن تفعيل هذه الطريقة عن طريق تعيين loss_type="dft" في SFTConfig. لمزيد من التفاصيل، راجع Paper Index - Dynamic Fine-Tuning.

إزاحة التسميات وإخفاؤها

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

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

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

  • global_step: إجمالي عدد خطوات المُحسِّن التي تم اتخاذها حتى الآن.
  • epoch: رقم الحقبة الحالية، بناءً على تكرار مجموعة البيانات.
  • num_tokens: إجمالي عدد الرموز التي تمت معالجتها حتى الآن.
  • loss: متوسط خسارة الانتروبيا المتقاطعة المحسوبة على الرموز غير المقنّعة في فترة التسجيل الحالية.
  • entropy: متوسط إنتروبيا توزيع الرموز المتوقعة من النموذج على الرموز غير المقنّعة.
  • aux_loss: خسارة التوازن على الأحمال المساعدة لنموذج مزيج الخبراء، قبل أن تُضرب في router_aux_loss_coef وتُضاف إلى الخسارة. تُسجَّل فقط عندما يكون النموذج من نوع MoE وrouter_aux_loss_coef غير صفري.
  • mean_token_accuracy: نسبة الرموز غير المقنّعة التي تتطابق فيها التنبؤ الأول (top-1) للنموذج مع الرمز الصحيح.
  • learning_rate: معدل التعلم الحالي، والذي قد يتغير ديناميكيًا إذا تم استخدام مُجدوِل.
  • grad_norm: معيار L2 للتدرجات، يُحسب قبل اقتطاع التدرجات.

التخصيص

تهيئة النموذج

يمكنك تمرير معاملات from_pretrained() مباشرة إلى SFTConfig. على سبيل المثال، إذا كنت ترغب في تحميل نموذج بدقة مختلفة، على غرار

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", dtype=torch.bfloat16)

يمكنك القيام بذلك عن طريق تمرير الحجة model_init_kwargs={"dtype": torch.bfloat16} إلى SFTConfig.

from trl import SFTConfig

training_args = SFTConfig(
    model_init_kwargs={"dtype": torch.bfloat16},
)

لاحظ أن جميع معاملات الكلمات المفتاحية لـ from_pretrained() مدعومة.

التعبئة

يدعم SFTTrainer تجميع الأمثلة، حيث يتم تجميع عدة أمثلة في تسلسل إدخال واحد لزيادة كفاءة التدريب. لتفعيل التجميع، ما عليك سوى تمرير packing=True إلى منشئ SFTConfig.

training_args = SFTConfig(packing=True)

لمزيد من التفاصيل حول التعبئة، راجع التعبئة.

التدريب على رسائل المساعد فقط

لتدريب النموذج على رسائل المساعد فقط، استخدم مجموعة بيانات حوارية وقم بتعيين assistant_only_loss=True في SFTConfig. يضمن هذا الإعداد أن يتم حساب الخسارة فقط على ردود المساعد، مع تجاهل رسائل المستخدم أو النظام.

training_args = SFTConfig(assistant_only_loss=True)

train_on_assistant

يتطلب هذا الميزة أن تتضمن قالب المحادثة كلمات {% generation %} و{% endgeneration %}. بالنسبة لعائلات النماذج المعروفة (مثل Qwen3)، يقوم TRL تلقائيًا بإصلاح القالب عند assistant_only_loss=True. راجع قوالب المحادثة للحصول على القائمة الكاملة لقوالب التدريب المدمجة. أما بالنسبة للنماذج الأخرى، فتأكد من أن قالب المحادثة الخاص بك يتضمن هذه الكلمات. راجع HuggingFaceTB/SmolLM3-3B كمثال.

مع مجموعة بيانات الرؤية، يتطلب فقدان المساعد فقط transformers>=5.18.0 ومجموعة بيانات نمذجة اللغة محادثة.

التدريب على الإكمال فقط

لتدريب النموذج على الجزء المكتمل فقط، استخدم مجموعة بيانات prompt-completion. افتراضيًا، يحسب المدرب الخسارة على رموز الجزء المكتمل فقط، متجاهلاً رموز الاستعلام. إذا كنت ترغب في التدريب على التسلسل الكامل، فاضبط completion_only_loss=False في SFTConfig.

from trl import SFTConfig, SFTTrainer
from datasets import load_dataset

# Load a prompt-completion dataset; loss is computed on the completion only by default
dataset = load_dataset("trl-lib/kto-mix-14k", split="train")

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    args=SFTConfig(completion_only_loss=True),  # True by default for prompt-completion datasets
    train_dataset=dataset,
)
trainer.train()

train_on_completion

التدريب على الإكمال فقط متوافق مع التدريب على رسائل المساعد فقط. في هذه الحالة، استخدم مجموعة بيانات حوارية من نوع موجّه-إكمال وقم بتعيين assistant_only_loss=True في SFTConfig.

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

ندعم التكامل الوثيق مع مكتبة 🤗 PEFT، مما يتيح لأي مستخدم تدريب المحوِّلات (adapters) ومشاركتها على Hub بسهولة، بدلاً من تدريب النموذج بأكمله.

from datasets import load_dataset
from trl import SFTTrainer
from peft import LoraConfig

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

trainer = SFTTrainer(
    "Qwen/Qwen3-0.6B",
    train_dataset=dataset,
    peft_config=LoraConfig(),
)

trainer.train()

يمكنك أيضًا مواصلة تدريب PeftModel. لذلك، قم أولًا بتحميل PeftModel خارج SFTTrainer ثم مرّره مباشرةً إلى المدرب دون تمرير معامل peft_config.

from datasets import load_dataset
from trl import SFTTrainer
from peft import AutoPeftModelForCausalLM

model = AutoPeftModelForCausalLM.from_pretrained("trl-lib/Qwen3-4B-LoRA", is_trainable=True)
dataset = load_dataset("trl-lib/Capybara", split="train")

trainer = SFTTrainer(
    model=model,
    train_dataset=dataset,
)

trainer.train()

عند تدريب المُكيِّفات (adapters)، تستخدم عادةً معدل تعلّم أعلى (≈1e‑4) لأن المعاملات الجديدة فقط هي التي يتم تعلّمها.

SFTConfig(learning_rate=1e-4, ...)

التجارب السريعة لتدريب الإشراف

RapidFire AI هو محرك تجارب مفتوح المصدر يعمل فوق TRL ويتيح لك إطلاق عدة تكوينات SFT في وقت واحد، حتى على وحدة معالجة رسومية واحدة. بدلاً من تجربة التكوينات بشكل تسلسلي، يتيح لك RapidFire رؤية منحنيات التعلم الخاصة بها جميعاً في وقت أبكر، وإيقاف التشغيلات ذات الأداء الضعيف، ونسخ الواعدة منها بإعدادات جديدة أثناء التنفيذ دون إعادة التشغيل. لمزيد من المعلومات، راجع تكامل RapidFire AI.

التدريب باستخدام Unsloth

يُعدّ Unsloth إطار عمل مفتوح المصدر للضبط الدقيق والتعلم المعزز، يدرّب نماذج اللغة الكبيرة (مثل Llama وMistral وGemma وDeepSeek وغيرها) بسرعة تصل إلى ضعف السرعة مع تقليل ذاكرة VRAM بنسبة تصل إلى 70%، مع توفير سير عمل مبسّط ومتوافق مع Hugging Face للتدريب والتقييم والنشر. لمزيد من المعلومات، راجع تكامل Unsloth.

مثال على الضبط التعليمي

يُعلّم التدريب على التعليمات نموذج اللغة الأساسي على اتباع تعليمات المستخدم والمشاركة في المحادثات. ويتطلب ذلك:

  1. قالب المحادثة: يحدد كيفية هيكلة المحادثات إلى تسلسلات نصية، بما في ذلك علامات الأدوار (المستخدم/المساعد)، الرموز الخاصة، وحدود الأدوار. اقرأ المزيد حول قوالب المحادثة في قوالب المحادثة.
  2. مجموعة بيانات محادثة: تحتوي على أزواج تعليمات-استجابات

يُظهر هذا المثال كيفية تحويل نموذج Qwen 3 0.6B Base إلى نموذج يتبع التعليمات باستخدام مجموعة بيانات Capybara وقالب محادثة من HuggingFaceTB/SmolLM3-3B. يتولى مُدرّب SFT تلقائيًا معالجة تحديثات المُرمّز (tokenizer) وإعداد الرموز الخاصة.

from trl import SFTConfig, SFTTrainer
from datasets import load_dataset

trainer = SFTTrainer(
    model="Qwen/Qwen3-0.6B-Base",
    args=SFTConfig(
        output_dir="Qwen3-0.6B-Instruct",
        chat_template_path="HuggingFaceTB/SmolLM3-3B",
    ),
    train_dataset=load_dataset("trl-lib/Capybara", split="train"),
)
trainer.train()

بعض النماذج الأساسية، مثل تلك من Qwen، تحتوي على قالب محادثة محدد مسبقًا في مُجزّئ النموذج. في هذه الحالات، لا يكون من الضروري تطبيق clone_chat_template()، إذ يتولى المُجزّئ بالفعل معالجة التنسيق. ومع ذلك، من الضروري مواءمة رمز نهاية الجملة (EOS) مع قالب المحادثة لضمان انتهاء استجابات النموذج بشكل صحيح. في هذه الحالات، حدد eos_token في SFTConfig؛ على سبيل المثال، بالنسبة إلى Qwen/Qwen2.5-1.5B، ينبغي تعيين eos_token="<|im_end|>".

بعد التدريب، يمكن لنموذجك الآن اتباع التعليمات والمشاركة في المحادثات باستخدام قالب الدردشة الجديد الخاص به.

>>> from transformers import pipeline
>>> pipe = pipeline("text-generation", model="Qwen3-0.6B-Instruct/checkpoint-5000")
>>> prompt = "<|im_start|>user\nWhat is the capital of France? Answer in one word.<|im_end|>\n<|im_start|>assistant\n"
>>> response = pipe(prompt)
>>> response[0]["generated_text"]
'<|im_start|>user\nWhat is the capital of France? Answer in one word.<|im_end|>\n<|im_start|>assistant\nThe capital of France is Paris.'

بديلًا عن ذلك، استخدم صيغة المحادثة المهيكلة (موصى به):

>>> prompt = [{"role": "user", "content": "What is the capital of France? Answer in one word."}]
>>> response = pipe(prompt)
>>> response[0]["generated_text"]
[{'role': 'user', 'content': 'What is the capital of France? Answer in one word.'}, {'role': 'assistant', 'content': 'The capital of France is Paris.'}]

استدعاء الأدوات مع SFT

يدعم SFTTrainer بشكل كامل ضبط نماذج تحتوي على قدرات tool calling. في هذه الحالة، يجب أن يتضمن كل مثال في مجموعة البيانات:

  • رسائل المحادثة، بما في ذلك أي استدعاءات للأدوات (tool_calls) وردود الأدوات (رسائل بدور tool)
  • قائمة الأدوات المتاحة في عمود tools، والتي تُقدَّم عادةً كمخططات JSON

لمزيد من التفاصيل حول بنية مجموعة البيانات المتوقعة، راجع قسم Dataset Format — Tool Calling.

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

يدعم SFTTrainer بشكل كامل تدريب نماذج الرؤية واللغة (VLMs). لتدريب نموذج VLM، قدّم مجموعة بيانات تحتوي إما على عمود image (صورة واحدة لكل عينة) أو عمود images (قائمة من الصور لكل عينة). لمزيد من المعلومات حول بنية مجموعة البيانات المتوقعة، راجع قسم Dataset Format — Vision Dataset. مثال على مثل هذه المجموعة هو LLaVA Instruct Mix.

from trl import SFTConfig, SFTTrainer
from datasets import load_dataset

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    args=SFTConfig(max_length=None),
    train_dataset=load_dataset("trl-lib/llava-instruct-mix", split="train"),
)
trainer.train()

بالنسبة لنماذج الرؤية-اللغة (VLMs)، قد يؤدي التقصير إلى إزالة رموز الصور، مما يسبب أخطاء أثناء التدريب. لتجنب ذلك، اضبط max_length=None في SFTConfig. يتيح هذا للنموذج معالجة طول التسلسل الكامل دون تقصير رموز الصور.

SFTConfig(max_length=None, ...)

استخدم max_length فقط بعد أن تتأكد من أن القصّ لن يُزيل رموز الصور في كامل مجموعة البيانات.

SFTTrainer

فئة trl.SFTTrainer

< >

( model: str | PreTrainedModel | PeftModelargs: trl.trainer.sft_config.SFTConfig | transformers.training_args.TrainingArguments | None = Nonedata_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneeval_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | datasets.dataset_dict.DatasetDict | datasets.dataset_dict.IterableDatasetDict | dict[str, datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset] | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.processing_utils.ProcessorMixin | None = Nonecompute_loss_func: collections.abc.Callable | None = Nonecompute_metrics: collections.abc.Callable[[transformers.trainer_utils.EvalPrediction], dict] | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)optimizer_cls_and_kwargs: tuple[type[torch.optim.Optimizer], dict[str, typing.Any]] | None = Nonepreprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = Nonequantization_config: BitsAndBytesConfig | None = Nonepeft_config: PeftConfig | None = Noneformatting_func: collections.abc.Callable[[dict], str] | 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. يتم دعم نماذج اللغة السببية فقط.
  • args (SFTConfig، اختياري) — إعدادات لهذا المدرب. إذا كانت None، يتم استخدام إعداد افتراضي.
  • data_collator (DataCollator، اختياري) — الدالة المستخدمة لتشكيل دفعة من قائمة عناصر مجموعة البيانات train_dataset أو eval_dataset بعد المعالجة. سيتم افتراضياً استخدام DataCollatorForLanguageModeling، أو DataCollatorForVisionLanguageModeling إذا كانت مجموعة البيانات تحتوي على صور.
  • train_dataset (Dataset أو IterableDataset) — مجموعة البيانات المستخدمة للتدريب. يدعم هذا المدرب كلا النوعين: نمذجة اللغة و المُوجِّه-الإكمال يمكن أن يكون تنسيق العينات إما:
    • قياسي: يحتوي كل عينة على نص عادي.
    • حواري: تحتوي كل عينة على رسائل منظمة (مثل الدور والمحتوى).

    يدعم المدرب أيضًا مجموعات بيانات مُرمَّزة مسبقًا، ويُعرَّف وجودها عبر عمود إلزامي باسم input_ids. يُستخدم عمود اختياري باسم labels (حيث تكون القيمة -100 للرموز المستبعدة من حساب الخسارة) كما هو إذا وُجد؛ وإلا تُبنى التسميات من العمودين الاختياريين assistant_masks / completion_mask (يُدمجان ثم يُحذفان، مع حذف completion_mask فقط عندما يكون completion_only_loss=True)، أو تُعتمد نسخة من input_ids افتراضيًا. تُقتطع التسلسلات إلى max_length أثناء التجهيز. عند تعيين skip_prepare_dataset=True، يُتخطى التجهيز ويُتوقع من مُجمِّع البيانات التعامل مع مجموعة البيانات كما هي.

    عندما يكون 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 كقيمة افتراضية.
  • compute_loss_func (Callable، اختياري) — دالة تستقبل مخرجات النموذج، والوسوم، وعدد العناصر في الدفعة المتراكمة بالكامل (batch_size * gradient_accumulation_steps) وتعيد الخسارة. هذا الأمر غير مستحسن وسيتم إزالته في الإصدار v2.0.0: بدلاً من ذلك، قم بإنشاء فئة فرعية من SFTTrainer وتجاوز compute_loss.
  • compute_metrics (Callable[[EvalPrediction], dict]، اختياري) — الدالة التي ستُستخدم لحساب المقاييس أثناء التقييم. يجب أن تستقبل EvalPrediction وتعيد قاموسًا من السلاسل النصية إلى قيم المقاييس. عند تمرير SFTConfig مع ضبط batch_eval_metrics على True، يجب أن تستقبل دالة compute_metrics الخاصة بك معاملًا من نوع compute_result من النوع المنطقي. سيُستدعى هذا بعد آخر دفعة تقييم للإشارة إلى أن الدالة بحاجة إلى حساب وإحصاءات الملخص العامة وإعادتها بدلاً من تراكم إحصاءات مستوى الدفعة. القيم اللوجستية التي تستقبلها تُعاد حسابها عبر تمريرة أمامية إضافية. هذا الأمر غير مدعوم وسيُزال في الإصدار v2.0.0.
  • 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.
  • optimizer_cls_and_kwargs (tuple[Type[torch.optim.Optimizer], Dict[str, Any]], اختياري) — مجموعة تحتوي على فئة المُحسِّن (optimizer) وبارامترات الكلمات المفتاحية للاستخدام. تتجاوز optim و optim_args في args. غير متوافق مع optimizers البارامتر.

    على عكس optimizers، يتجنّب هذا الحُجّة الحاجة إلى وضع معاملات النموذج على الأجهزة الصحيحة قبل تهيئة Trainer.

  • preprocess_logits_for_metrics (Callable[[torch.Tensor, torch.Tensor], torch.Tensor], اختياري) — دالة تعالج logits قبل تخزينها مؤقتًا في كل خطوة تقييم. يجب أن تستقبل مصفوفتين (tensors)، وهما logits والوسوم (labels)، وتعيد logits بعد المعالجة كما هو مطلوب. ستُنعكس التعديلات التي تجريها هذه الدالة في التنبؤات التي تستلمها compute_metrics.

    لاحظ أن التسميات (المعامل الثاني) ستكون None إذا لم تكن موجودة في مجموعة البيانات.

  • quantization_config (BitsAndBytesConfig، اختياري) — إعدادات التكميم المستخدمة عند تحميل النموذج من معرّف النموذج. ادمجها مع peft_config لتدريب QLoRA. يتم تجاهلها إذا كان النموذج مُنشأً بالفعل.
  • peft_config (PeftConfig، اختياري) — إعدادات PEFT المستخدمة لتغليف النموذج. إذا كانت None، فلن يتم تغليف النموذج.
  • formatting_func (Callable، اختياري) — دالة التنسيق التي تُطبَّق على مجموعة البيانات قبل الترميز. تطبيق دالة التنسيق بشكل صريح يحوّل مجموعة البيانات إلى نوع نمذجة اللغة.

مدرّب لطريقة الضبط الدقيق الإشرافي (SFT).

هذا الصنف هو غلاف حول صنف Trainer ويرث جميع خصائصه وطرائقه.

مثال:

>>> from trl import SFTTrainer
>>> from datasets import load_dataset

>>> dataset = load_dataset("roneneldan/TinyStories", split="train[:1%]")

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

تدريب

< >

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

SFTConfig

فئة trl.SFTConfig

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 2e-05lr_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 = Falserouter_aux_loss_coef: float | None = Nonechat_template_path: str | None = Nonedataset_text_field: str = 'text'dataset_kwargs: dict[str, typing.Any] | str | None = Nonedataset_num_proc: int | None = Noneeos_token: str | None = Nonemax_length: int | None = 1024truncation_mode: str = 'keep_start'shuffle_dataset: bool = Falsepacking: bool = Falsepacking_strategy: str = 'bfd'padding_free: bool = Falsepad_to_multiple_of: int | str | None = 'auto'eval_packing: bool | None = Nonecompletion_only_loss: bool | None = Noneassistant_only_loss: bool = Falseloss_type: str = 'nll'activation_offloading: bool = Falsepad_token: str | None = None )

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

  • model_init_kwargs (dict[str, Any]، اختياري) — حجج الكلمات المفتاحية لـ from_pretrained، تُستخدم عندما يُقدَّم معامل model الخاص بـ SFTTrainer كنص. كما يُستخدم قيمة 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.
  • router_aux_loss_coef (float, اختياري) — معامل خسارة التوازن على الأحمال المساعدة لنماذج مزيج الخبراء (MoE)، تُضاف إلى خسارة التدريب بهذا الوزن. عند عدم تعيينه، يُستخدم القيمة المُعلنة في إعدادات النموذج. عيّن 0.0 لتعطيله. يفشل عند استخدامه مع نموذج غير MoE.
  • chat_template_path (str, اختياري) — إذا تم تحديده، يُضبط قالب المحادثة الخاص بالنموذج. يمكن أن يكون هذا المسار إلى مُجزِّئ (مجلد محلي أو نموذج على Hugging Face Hub) أو مسارًا مباشرًا إلى ملف قالب Jinja. عند استخدام ملف Jinja، يجب التأكد من إضافة الرموز الخاصة المشار إليها في القالب إلى المُجزِّئ، وتغيير حجم طبقة التضمين الخاصة بالنموذج وفقًا لذلك.

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

  • dataset_text_field (str، اختياري، القيمة الافتراضية "text") — اسم العمود الذي يحتوي على بيانات النص في مجموعة البيانات.
  • dataset_kwargs (dict[str, Any], اختياري) — قاموس لحجج اختيارية بالاسم لتجهيز مجموعة البيانات. المفتاح المدعوم الوحيد هو skip_prepare_dataset. عندما تحتوي مجموعة البيانات على صور، يُعامل skip_prepare_dataset تلقائيًا على أنه True بغض النظر عن القيمة المقدمة، لأن المعالجة المسبقة تتم على الفور.
  • dataset_num_proc (int، اختياري) — عدد العمليات المستخدمة لمعالجة مجموعة البيانات.
  • eos_token (str، اختياري) — الرمز المستخدم للإشارة إلى نهاية الدور أو التسلسل. إذا كان None، فإن القيمة الافتراضية هي processing_class.eos_token.
  • max_length (int أو None، اختياري، القيمة الافتراضية 1024) — الحد الأقصى لطول التسلسل المُرمَّز. تُقتطع التسلسلات الأطول من max_length من اليسار أو من اليمين اعتماداً على truncation_mode. إذا كانت None، فلا يُطبَّق أي اقتطاع. عند تفعيل التعبئة، يحدد هذا القيمة طول التسلسل.
  • truncation_mode (str، اختياري، القيمة الافتراضية "keep_start") — وضع الاقتطاع المستخدم عندما تتجاوز التسلسل max_length. القيمة المدعومة الوحيدة هي "keep_start". قيمة "keep_end" لم تعد مدعومة وسيتم إزالتها في الإصدار v2.0.0.
  • shuffle_dataset (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب خلط مجموعة البيانات.
  • packing (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تجميع تسلسلات متعددة في كتل ذات طول ثابت لتحسين الكفاءة الحسابية وتقليل الحشو. يستخدم max_length لتحديد طول التسلسل.
  • packing_strategy (str، اختياري، القيمة الافتراضية "bfd") — استراتيجية لتعبئة التسلسلات. يمكن أن تكون "bfd" (أفضل ملاءمة تنازلية، تقصّ الفائض)، أو "bfd_split" (أفضل ملاءمة تنازلية، تقسّم تسلسلات الفائض)، أو "wrapped" (عدوانية، تقطع في منتصف التسلسل).
  • padding_free (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تنفيذ عمليات الأمامية (forward passes) دون حشو (padding) عن طريق تسطيح جميع التسلسلات في الدفعة (batch) إلى تسلسل مستمر واحد. يقلل هذا من استهلاك الذاكرة من خلال إزالة عبء الحشو. حاليًا، يتم دعم هذا فقط مع FlashAttention 2 أو 3، والتي يمكنها التعامل بكفاءة مع بنية الدفعة المسطحة. عند تمكين التعبئة (packing) باستخدام الاستراتيجية "bfd"، يتم تفعيل وضع بدون حشو، بغض النظر عن قيمة هذا المعامل.
  • pad_to_multiple_of (int أو str، اختياري، القيمة الافتراضية "auto") — إذا تم ضبطه، فسيتم ملء التسلسلات حتى تكون مضاعفاً لهذه القيمة. "auto" يملأ حتى مضاعف 128 على Neuron (AWS Trainium)، الذي يُجمَّع مرة واحدة لكل شكل إدخال، ولا يملأ في أي مكان آخر.
  • eval_packing (bool, اختياري) — ما إذا كان سيتم حزم مجموعة بيانات التقييم. إذا كانت None، يتم استخدام نفس قيمة packing.

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

  • completion_only_loss (bool, اختياري) — ما إذا كان يجب حساب الخسارة على جزء الإكمال من التسلسل فقط. إذا تم ضبطه على True، تُحسب الخسارة على الإكمال فقط، وهو ما يُدعم فقط لمجموعات بيانات prompt-completion. إذا كان False، تُحسب الخسارة على التسلسل بأكمله. إذا كان None (الافتراضي)، يعتمد السلوك على مجموعة البيانات: تُحسب الخسارة على الإكمال لمجموعات بيانات prompt-completion، وعلى التسلسل الكامل لمجموعات بيانات language modeling.
  • assistant_only_loss (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب حساب الخسارة على الجزء الخاص بالمساعد من التسلسل فقط. إذا تم ضبطه على True، تُحسب الخسارة على ردود المساعد فقط، وهو ما يُدعم فقط لمجموعات البيانات المحادثية. إذا كان False، تُحسب الخسارة على التسلسل بأكمله.
  • loss_type (str, اختياري, الافتراضي هو "nll") — نوع الدالة الخاسرة (loss) المستخدمة. القيم الممكنة هي:
    • "nll": سالب الاحتمال اللوغاريتمي القياسي.
    • "dft": الضبط الدقيق الديناميكي، كما هو موصوف في هذا الورق.
    • "chunked_nll": اسم مستعار غير مستخدم لم يعد يُنصح به لـ "nll"، الذي يحسب الخسارة بالطريقة نفسها. سيتم إزالته في v2.0.0.
  • activation_offloading (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم نقل التفعيلات إلى وحدة المعالجة المركزية (CPU).

معاملات غير مستخدمة

  • pad_token —

    تم إيقاف استخدام المعامل pad_token وسيتم حذفه في الإصدار v2.0.0. اضبط tokenizer.pad_token مباشرةً وقم بتمريره كـ processing_class إلى المدرب بدلاً من ذلك.

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

تتضمن هذه الفئة فقط المعلمات الخاصة بتدريب SFT. للحصول على قائمة كاملة بحجج التدريب، يرجى الرجوع إلى توثيق TrainingArguments. لاحظ أن القيم الافتراضية في هذه الفئة قد تختلف عن تلك الموجودة في TrainingArguments.

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

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

  • logging_steps: القيمة الافتراضية هي 10 بدلاً من 500.
  • gradient_checkpointing: القيمة الافتراضية هي True بدلاً من False.
  • bf16: القيمة الافتراضية هي True إذا لم يتم تعيين fp16، بدلاً من False.
  • learning_rate: القيمة الافتراضية هي 2e-5 بدلاً من 5e-5.
Update on GitHub