TRL documentation
مدرب SFT
مدرب SFT
نظرة عامة
يدعم 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 هي خسارة الانتروبيا المتقاطعة على مستوى الرموز, المعرّفة على النحو التالي:
حيث هو الرمز المستهدف عند خطوة الزمن , ويتم تدريب النموذج للتنبؤ بالرمز التالي بناءً على الرموز السابقة. عمليًا، يتم إخفاء رموس الحشو أثناء حساب الخسارة.
يقترح البحث 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)
يتطلب هذا الميزة أن تتضمن قالب المحادثة كلمات
{% 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()
التدريب على الإكمال فقط متوافق مع التدريب على رسائل المساعد فقط. في هذه الحالة، استخدم مجموعة بيانات حوارية من نوع موجّه-إكمال وقم بتعيين
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.
مثال على الضبط التعليمي
يُعلّم التدريب على التعليمات نموذج اللغة الأساسي على اتباع تعليمات المستخدم والمشاركة في المحادثات. ويتطلب ذلك:
- قالب المحادثة: يحدد كيفية هيكلة المحادثات إلى تسلسلات نصية، بما في ذلك علامات الأدوار (المستخدم/المساعد)، الرموز الخاصة، وحدود الأدوار. اقرأ المزيد حول قوالب المحادثة في قوالب المحادثة.
- مجموعة بيانات محادثة: تحتوي على أزواج تعليمات-استجابات
يُظهر هذا المثال كيفية تحويل نموذج 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
< source >( 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. يتم دعم نماذج اللغة السببية فقط.
- سلسلة نصية، تكون معرف النموذج لنموذج مُدرَّب مسبقًا مستضاف داخل مستودع نماذج على huggingface.co، أو مسارًا إلى مجلد يحتوي على أوزان النموذج المحفوظة باستخدام save_pretrained، مثل
- 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()تدريب
< 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.
SFTConfig
فئة trl.SFTConfig
< source >( 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 toFalse) — 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).
معاملات غير مستخدمة
فئة التهيئة الخاصة بـ 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.