Hugging Face's logo

Transformers documentation

Trainer

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Trainer

توفر فئة Trainer واجهة برمجة تطبيقات (API) للتدريب الكامل الميزات في PyTorch، وتدعم التدريب الموزع على عدة وحدات معالجة رسومات (GPUs) ووحدات معالجة TPU، والدقة المختلطة لـ NVIDIA GPUs و AMD GPUs، و torch.amp في PyTorch. تعمل فئة Trainer جنبًا إلى جنب مع فئة TrainingArguments، التي تقدم مجموعة واسعة من الخيارات لتخصيص طريقة تدريب النموذج. معًا، توفر هاتان الفئتان واجهة برمجة تطبيقات كاملة للتدريب.

يرث Seq2SeqTrainer و Seq2SeqTrainingArguments من فئتي Trainer و TrainingArguments، وقد تم تكييفهما لتدريب النماذج على مهام التحويل من تسلسل إلى تسلسل مثل التلخيص أو الترجمة.

تم تحسين فئة Trainer لنماذج 🤗 Transformers، وقد تُظهر سلوكيات غير متوقعة عند استخدامها مع نماذج أخرى. عند استخدامها مع نموذجك الخاص، تأكد من:

  • يعيد نموذجك دائمًا مجموعات (tuples) أو فئات فرعية من ModelOutput
  • يمكن لنموذجك حساب الخسارة إذا تم توفير معامل labels، وتُعاد تلك الخسارة كعنصر أول في المجموعة المرتبة (إذا كان نموذجك يعيد مجموعات مرتبة)
  • يمكن لنموذجك أن يقبل عدة حُجج تسمية (استخدم label_names في TrainingArguments لتوضيح أسمائها إلى Trainer) لكن لا ينبغي أن يكون اسم أي منها "label"

Trainer

فئة transformers.Trainer

< >

( model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, NoneType] = Noneargs: transformers.training_args.TrainingArguments | None = Nonedata_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = Nonetrain_dataset: Dataset | IterableDataset | datasets.Dataset | None = Noneeval_dataset: Dataset | dict[str, Dataset] | datasets.Dataset | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.image_processing_utils.BaseImageProcessor | transformers.feature_extraction_utils.FeatureExtractionMixin | transformers.processing_utils.ProcessorMixin | None = Nonemodel_init: collections.abc.Callable[..., transformers.modeling_utils.PreTrainedModel] | 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 = (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 = None )

المعاملات

  • model (PreTrainedModel أو torch.nn.Module, اختياري) — النموذج الذي سيتم تدريبه أو تقييمه أو استخدامه للتنبؤات. إذا لم يُقدَّم، فيجب تمرير model_init إلزاميًا.

    Trainer مُحسّن للعمل مع PreTrainedModel الذي توفره المكتبة. يمكنك ما زال استخدام نماذجك الخاصة المعرّفة على أنها torch.nn.Module طالما أنها تعمل بنفس طريقة عمل نماذج 🤗 Transformers.

  • args (TrainingArguments، اختياري) — الحُجج التي تُضبط للتدريب. إذا لم تُقدَّم، فسيتم افتراضياً استخدام نسخة أساسية من TrainingArguments مع ضبط output_dir على مجلد باسم tmp_trainer في المجلد الحالي.
  • data_collator (DataCollator، اختياري) — الدالة المستخدمة لتكوين دفعة من قائمة عناصر train_dataset أو eval_dataset. ستكون القيمة الافتراضية default_data_collator() إذا لم يتم تقديم processing_class، وإلا فستكون نسخة من DataCollatorWithPadding إذا كان processing_class مستخرج ميزات أو مُجزئًا.
  • train_dataset (torch.utils.data.Dataset | torch.utils.data.IterableDataset | datasets.Dataset, اختياري) — المجموعة المستخدمة للتدريب. إذا كانت من نوع Dataset, ، فسيتم حذف الأعمدة غير المقبولة تلقائيًا بواسطة model.forward() طريقة

    لاحظ أنه إذا كان torch.utils.data.IterableDataset يحتوي على بعض العشوائية وأنت تقوم بالتدريب بطريقة موزعة، فيجب أن يستخدم مجموعة البيانات القابلة للتكرار إما خاصية داخلية generator تكون من نوع torch.Generator للعشوائية، ويجب أن تكون متطابقة في جميع العمليات (وسيقوم Trainer بإعداد بذرة هذا generator يدوياً في كل حقبة)، أو أن يحتوي على طريقة set_epoch() تقوم داخلياً بإعداد بذرة مولدات الأرقام العشوائية المستخدمة.

    إذا لم ينفّذ مجموعة البيانات __len__ (مثل IterableDataset البثّي)، فيجب تعيين max_steps، لأن عدد خطوات التدريب الإجمالي لا يمكن استنتاجه.

  • eval_dataset (torch.utils.data.Dataset | dict[str, torch.utils.data.Dataset] | datasets.Dataset, اختياري) — مجموعة البيانات المستخدمة للتقييم. إذا كانت من نوع Dataset، تُحذف تلقائيًا الأعمدة غير المقبولة بواسطة طريقة model.forward(). أما إذا كانت قاموسًا، فسيتم التقييم على كل مجموعة بيانات مع إضافة مفتاح القاموس إلى بداية اسم المقياس.
  • processing_class (PreTrainedTokenizerBase أو BaseImageProcessor أو FeatureExtractionMixin أو ProcessorMixin، اختياري) — فئة المعالجة المستخدمة لمعالجة البيانات. إذا تم تقديمها، فستُستخدم لمعالجة المدخلات تلقائيًا للنموذج، وستُحفظ مع النموذج لتسهيل إعادة تشغيل تدريبٍ مُقاطَع أو إعادة استخدام النموذج المُحسَّن.
  • model_init (Callable[[], PreTrainedModel], اختياري) — دالة تُنشئ النموذج المراد استخدامه. إذا تم تقديمها، فستبدأ كل استدعاء لـ من نسخة جديدة من النموذج كما تحددها هذه الدالة. قد تحتوي الدالة على صفر من المعاملات، أو معامل واحد يحتوي على كائن تجربة optuna/Ray Tune، لاختيار معماريات مختلفة وفقًا للمعاملات الفائقة (مثل عدد الطبقات، أحجام الطبقات الداخلية، احتمالات dropout، إلخ).

    قد يكون لدى الدالة صفر من المعاملات، أو معامل واحد يحتوي على كائن التجربة الخاص بـ optuna/Ray Tune، حتى يتمكن المرء من اختيار معماريات مختلفة وفقاً للمعاملات الفائقة (مثل عدد الطبقات، وأحجام الطبقات الداخلية، واحتمالات dropout، وما إلى ذلك).

  • compute_loss_func (Callable, اختياري) — دالة تستقبل مخرجات النموذج الخام، والتسميات، وعدد العناصر في الدفعة المتراكمة بالكامل (batch_size * gradient_accumulation_steps) وتعيد قيمة الخسارة. على سبيل المثال، راجع دالة الخسارة الافتراضية المستخدمة بواسطة Trainer.
  • compute_metrics (Callable[[EvalPrediction], Dict], اختياري) — الدالة التي ستُستخدم لحساب المقاييس أثناء التقييم. يجب أن تستقبل EvalPrediction وتعيد قاموسًا من السلاسل النصية إلى قيم المقاييس. ملاحظة عند تمرير TrainingArgs مع ضبط batch_eval_metrics على True، يجب أن تستقبل دالة compute_metrics معاملًا من نوع boolean باسم compute_result. سيُستدعى هذا بعد آخر دفعة تقييم للإشارة إلى أن الدالة بحاجة إلى حساب وإحصاءات الملخص العام وإعادتها بدلاً من تراكم إحصاءات مستوى الدفعة
  • callbacks (قائمة من TrainerCallback, اختياري) — قائمة من الاستدعاءات (callbacks) لتخصيص حلقة التدريب. ستُضاف هذه الاستدعاءات إلى قائمة الاستدعاءات الافتراضية الموضّحة هنا.

    إذا كنت ترغب في إزالة أحد الاستدعاءات الافتراضية المستخدمة، فاستخدم طريقة Trainer.remove_callback().

  • optimizers (tuple[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR]، اختياري، القيمة الافتراضية (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)، وهما القيم الاحتمالية والوسوم (labels)، ثم تُرجع القيم الاحتمالية بعد معالجتها بالطريقة المطلوبة. ستُنعكس التعديلات التي تُجريها هذه الدالة على التنبؤات التي تستلمها compute_metrics.

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

Trainer هو حلقة تدريب وتقييم بسيطة لكنها متكاملة الميزات لـ PyTorch، مُحسّنة لـ 🤗 Transformers.

الخصائص المهمة:

  • model — يشير دائمًا إلى النموذج الأساسي. إذا كنت تستخدم نموذجًا من transformers، فسيكون PreTrainedModel فئة فرعية منه.
  • model_wrapped — يشير دائمًا إلى النموذج الخارجي الأكثر شمولًا في حال كان هناك وحدة أو أكثر تغلف النموذج الأصلي. هذا هو النموذج الذي يجب استخدامه لتمريرة الأمامية. على سبيل المثال، في إطار DeepSpeed، يُغلَّف النموذج الداخلي بواسطة DeepSpeed ثم مرة أخرى بواسطة torch.nn.DistributedDataParallel. إذا لم يكن النموذج الداخلي مُغلَّفًا، فإن self.model_wrapped هو نفسه self.model.
  • is_model_parallel — ما إذا كان النموذج قد تم تحويله إلى وضع التوازي على مستوى النموذج (على عكس التوازي على مستوى البيانات، حيث يتم تقسيم بعض طبقات النموذج على وحدات معالجة رسومية مختلفة).
  • place_model_on_device — تحديد ما إذا كان سيتم وضع النموذج على الجهاز تلقائيًا أم لا. القيمة الافتراضية هي True ما لم تكن موازنة النموذج، أو DeepSpeed، أو FSDP، أو التقييم الكامل بـ fp16/bf16، أو SageMaker MP مفعّلة. يمكن تجاوز ذلك عن طريق إنشاء فئة فرعية من TrainingArguments وتجاوز الخاصية place_model_on_device.
  • is_in_train — ما إذا كان النموذج يعمل حالياً train (على سبيل المثال، عند استدعاء evaluate أثناء التواجد في train)
  • loss_is_scaled_for_ga — ما إذا كانت الدالة compute_loss تُرجع قيمة الخسارة مُقيَّمة مسبقًا لتراكم التدرجات. True: يستخدم training_step القيمة كما هي. False: يقسم training_step القيمة على عدد خطوات تراكم التدرجات. None (الافتراضي): تُحتسب الخسارة على أنها مُقيَّمة إذا كانت مُطبَّعة بواسطة num_items_in_batch، أي عندما يقبل النموذج معاملات إضافية للخسارة أو عند تمرير compute_loss_func. يجب على الفئات الفرعية التي تحسب خسارتها الخاصة تعيين هذا المعامل.

add_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback )

المعاملات

  • callback (type أو [`~transformers.TrainerCallback`]) — فئة TrainerCallback أو كائن من فئة TrainerCallback. في الحالة الأولى، سيتم إنشاء كائن من تلك الفئة.

أضف مستدعيًا (callback) إلى القائمة الحالية من TrainerCallback.

autocast_smart_context_manager

< >

( cache_enabled: bool | None = True )

غلاف مساعد ينشئ مدير سياق مناسبًا لـautocast مع تزويده بالحجج المطلوبة، اعتمادًا على الموقف. نعتمد على accelerate لـautocast، لذا لا نفعل شيئًا هنا.

call_model_init

< >

( trial: optuna.Trial | dict[str, Any] | None = None )

استدعِ model_init للحصول على نسخة جديدة من النموذج، مع إمكانية اشتراطها على تجربة لمعاملات ضبط.

compute_loss

< >

( model: Moduleinputs: dictreturn_outputs: bool = Falsenum_items_in_batch: typing.Union[torch.Tensor, int, NoneType] = None )

المعاملات

  • model (nn.Module) — النموذج الذي تُحسب عليه دالة الخسارة.
  • inputs (dict[str, torch.Tensor | Any]) — بيانات الإدخال الخاصة بالنموذج.
  • return_outputs (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إخراج مخرجات النموذج إلى جانب دالة الخسارة.
  • num_items_in_batch (Optional[torch.Tensor], اختياري) — عدد العناصر في الدفعة. إذا لم يُمرَّر، يتم حساب الخسارة باستخدام منطق اختزال حجم الدفعة الافتراضي.

كيفية حساب الدالة الخاسرة بواسطة Trainer. افتراضياً، تُرجع جميع النماذج قيمة الخسارة في العنصر الأول.

أنشئ فئة فرعية وأعد تعريف الدوال للحصول على سلوك مخصص. إذا كنت تحسب دالة الخسارة الخاصة بك، فاضبط loss_is_scaled_for_ga للإشارة إلى ما إذا كانت الخسارة مُقيّمة بالفعل لتراكم التدرجات: False إذا كانت متوسطًا لكل دفعة (حيث سيقوم Trainer بقسمتها على عدد خطوات تراكم التدرجات)، وTrue إذا كنت قد قمت بتطبيعها مسبقًا على الدفعة المتراكمة بأكملها.

compute_loss_context_manager

< >

( )

غلاف مساعد لتجميع مُديري السياق معًا.

create_accelerator_and_postprocess

< >

( )

أنشئ المُسرِّع وأجرِ الإعدادات ما بعد الإنشاء (FSDP، DeepSpeed، إلخ).

create_model_card

< >

( language: str | None = Nonelicense: str | None = Nonetags: str | list[str] | None = Nonemodel_name: str | None = Nonefinetuned_from: str | None = Nonetasks: str | list[str] | None = Nonedataset_tags: str | list[str] | None = Nonedataset: str | list[str] | None = Nonedataset_args: str | list[str] | None = None )

المعاملات

  • language (str، اختياري) — لغة النموذج (إن كان ذلك منطبقاً)
  • license (str, اختياري) — رخصة النموذج. ستكون افتراضياً رخصة النموذج المُسبق التدريب المستخدم، إذا كان النموذج الأصلي المُمرَّر إلى Trainer من مستودع على Hub.
  • tags (str أو list[str]، اختياري) — بعض الوسوم التي سيتم تضمينها في البيانات الوصفية لبطاقة النموذج.
  • model_name (str، اختياري) — اسم النموذج.
  • finetuned_from (str، اختياري) — اسم النموذج المستخدم لضبط هذا النموذج (إن كان ذلك ممكنًا). سيُستخدم افتراضيًا اسم المستودع الخاص بالنموذج الأصلي المُقدَّم إلى Trainer (إذا كان من Hub).
  • tasks (str أو list[str]، اختياري) — معرّف واحد أو أكثر للمهام، ليتم تضمينه في البيانات الوصفية لبطاقة النموذج.
  • dataset_tags (str أو list[str]، اختياري) — واحد أو عدة وسوم للبيانات، لتضمينها في البيانات الوصفية لبطاقة النموذج.
  • dataset (str أو list[str]، اختياري) — معرّف واحد أو عدة معرّفات لمجموعات بيانات، لتضمينها في البيانات الوصفية لبطاقة النموذج.
  • dataset_args (str أو list[str]، اختياري) — حجة أو عدة حِجج للمجموعة، لتضمينها في بيانات وصفية لبطاقة النموذج.

ينشئ مسودة لبطاقة نموذج باستخدام المعلومات المتاحة في Trainer.

create_optimizer

< >

( model = None ) → torch.optim.Optimizer

يعيد

torch.optim.Optimizer

مثيل المُحسِّن.

اضبط المُحسِّن.

نوفّر قيمة افتراضية معقولة تعمل بشكل جيد. إذا كنت ترغب في استخدام شيء آخر، يمكنك تمرير مجموعة (tuple) في تهيئة Trainer عبر optimizers، أو إنشاء فئة فرعية وتجاوز هذه الطريقة في الفئة الفرعية.

create_optimizer_and_scheduler

< >

( num_training_steps: int )

اضبط المُحسِّن وجدول مُعدّل التعلّم.

نوفّر قيمة افتراضية معقولة تعمل بشكل جيد. إذا كنت ترغب في استخدام شيء آخر، يمكنك تمرير مجموعة (tuple) عبر optimizers في دالة init الخاصة بـ Trainer، أو إنشاء فئة فرعية وتجاوز هذه الطريقة (أو create_optimizer و/أو create_scheduler) في الفئة الفرعية.

create_scheduler

< >

( num_training_steps: intoptimizer: typing.Optional[torch.optim.Optimizer] = None ) → torch.optim.lr_scheduler.LRScheduler

المعاملات

  • num_training_steps (int) — عدد خطوات التدريب المطلوب تنفيذها.

يعيد

torch.optim.lr_scheduler.LRScheduler

مثيل جدولة معدل التعلم.

اضبط المجدول. يجب أن يكون المُحسِّن الخاص بالمدرِّب قد تم ضبطه إما قبل استدعاء هذه الطريقة أو تم تمريره كحجة.

نهاية

< >

( )

أنهِ المسارات المراقبة وأتلف مجموعة العمليات الموزعة.

استدعِ هذه الدالة مرة واحدة فقط، في نهاية السكربت، بعد كل ما يتطلب العمليات الأخرى: train()، evaluate()، predict()، save_model() وpush_to_hub() تتواصل جميعها بين العمليات وستفشل بمجرد اختفاء المجموعة.

مثال:

trainer.train()
trainer.evaluate()
trainer.push_to_hub()
trainer.end()

evaluate

< >

( eval_dataset: typing.Union[torch.utils.data.Dataset, dict[str, torch.utils.data.Dataset], NoneType] = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval' )

المعاملات

  • eval_dataset (Dataset | dict[str, Dataset], اختياري) — مرر مجموعة بيانات إذا كنت ترغب في تجاوز self.eval_dataset. إذا كانت Dataset, الأعمدة غير المقبولة بواسطة model.forward() طريقة تُزال تلقائيًا. إذا كانت قاموسًا، فسيتم التقييم على كل مجموعة بيانات، مع إضافة مفتاح القاموس إلى بداية اسم المقياس.

    إذا مرّرت قاموسًا تكون مفاتيحه أسماء مجموعات البيانات وقيمها مجموعات البيانات نفسها، فسيُجري evaluate تقييمات منفصلة على كل مجموعة بيانات. وقد يكون ذلك مفيدًا لمراقبة تأثير التدريب على مجموعات بيانات أخرى، أو ببساطة للحصول على تقييم أكثر تفصيلًا. عند الاستخدام مع load_best_model_at_end، تأكد من أن metric_for_best_model يشير إلى مجموعة بيانات واحدة بالضبط. فعلى سبيل المثال، إذا مرّرت {"data1": data1, "data2": data2} لمجموعتي بيانات data1 وdata2، يمكنك تحديد metric_for_best_model="eval_data1_loss" لاستخدام الخسارة على data1، وmetric_for_best_model="eval_data2_loss" للخسارة على data2.

  • ignore_keys (list[str]، اختياري) — قائمة بمفاتيح في مخرجات النموذج (إذا كان قاموسًا) يجب تجاهلها عند جمع التنبؤات.
  • metric_key_prefix (str، اختياري، القيمة الافتراضية "eval") — بادئة اختيارية تُستخدم كبادئة لمفاتيح المقاييس. على سبيل المثال، سيُسمّى المقياس "bleu" باسم "eval_bleu" إذا كانت البادئة هي "eval" (الافتراضية)

تشغيل التقييم وإرجاع المقاييس.

ستكون سكريبت الاستدعاء مسؤولة عن توفير طريقة لحساب المقاييس، إذ إنها تعتمد على المهمة (مرّرها إلى معامل compute_metrics في init).

يمكنك أيضًا إنشاء فئة فرعية وتجاوز هذه الطريقة لحقن سلوك مخصص.

حلقة التقييم evaluation_loop

< >

( dataloader: DataLoaderdescription: strprediction_loss_only: bool | None = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval' )

حلقة التنبؤ/التقييم، المشتركة بين Trainer.evaluate() وTrainer.predict().

يعمل سواءً مع وجود تسميات أو بدونها.

floating_point_ops

< >

( inputs: dict ) → int

المعاملات

  • inputs (dict[str, torch.Tensor | Any]) — مدخلات النموذج وأهدافه.

يعيد

int

عدد عمليات الفاصلة العائمة.

بالنسبة للنماذج التي ترث من PreTrainedModel، تُستخدم تلك الطريقة لحساب عدد عمليات الفاصلة العائمة لكل تمريرة خلفية + أمامية. إذا كنت تستخدم نموذجًا آخر، فإما أن تنفّذ مثل هذه الطريقة داخل النموذج، أو أن ترث منه وتعيد تعريف هذه الطريقة.

get_batch_samples

< >

( epoch_iterator: Iteratornum_batches: intdevice: device )

يجمع عددًا محددًا من الدفعات من مُكرِّر الحقبة، ويحسب اختيارًا عدد العناصر في الدفعات لتقاسم الخسارة بشكل صحيح.

get_cp_size

< >

( )

احصل على حجم التوازي السياقي

get_decay_parameter_names

< >

( model: Module )

احصل على جميع أسماء المعاملات التي سيُطبَّق عليها اضمحلال الوزن.

تُفلتر هذه الدالة المعاملات بطريقتين:

  1. حسب نوع الطبقة (الأمثلة من الطبقات المحددة في ALL_LAYERNORM_LAYERS)
  2. حسب أنماط أسماء المعاملات (تتضمن 'bias' أو أحد أشكال 'norm')

get_eval_dataloader

< >

( eval_dataset: typing.Union[str, torch.utils.data.Dataset, NoneType] = None )

المعاملات

  • eval_dataset (str أو torch.utils.data.Dataset، اختياري) — إذا كان str، فسيتم استخدام self.eval_dataset[eval_dataset] كمجموعة بيانات للتقييم. إذا كان Dataset، فسيتم تجاوز self.eval_dataset. إذا كان Dataset، تُحذف الأعمدة غير المقبولة بواسطة طريقة model.forward() تلقائيًا.

يعيد ~torch.utils.data.DataLoader للتقييم.

قم بإنشاء فئة فرعية وتجاوز هذه الطريقة إذا كنت ترغب في حقن سلوك مخصص.

get_learning_rates

< >

( )

يعيد معدل تعلّم كل معامل من self.optimizer.

get_num_trainable_parameters

< >

( )

احصل على عدد المعاملات القابلة للتدريب.

get_optimizer_cls_and_kwargs

< >

( args: TrainingArgumentsmodel: transformers.modeling_utils.PreTrainedModel | None = None )

المعاملات

  • args (transformers.training_args.TrainingArguments) — حجج التدريب لجلسة التدريب.
  • model (PreTrainedModel، اختياري) — النموذج الذي يتم تدريبه. مطلوب لبعض المُحسِّنات (GaLore، Apollo، LOMO).

يعيد فئة المُحسِّن (optimizer) ومعاملات المُحسِّن بناءً على حُجج التدريب.

get_optimizer_group

< >

( param: typing.Union[str, torch.nn.parameter.Parameter, NoneType] = None )

المعاملات

  • param (str أو torch.nn.parameter.Parameter، اختياري) — المعامل الذي يجب إرجاع مجموعة المُحسِّن الخاصة به.

يعيد مجموعة المُحسِّن الخاصة بمعامل إذا تم تقديمه، وإلا يعيد جميع مجموعات المُحسِّن للمعاملات.

get_sp_size

< >

( )

احصل على حجم التوازي التسلسلي

get_test_dataloader

< >

( test_dataset: Dataset )

المعاملات

  • test_dataset (torch.utils.data.Dataset، اختياري) — مجموعة البيانات الاختبارية المستخدمة. إذا كانت Dataset، تُحذف الأعمدة غير المقبولة تلقائيًا من قبل طريقة model.forward().

يعيد ~torch.utils.data.DataLoader الخاص بالاختبار.

قم بإنشاء فئة فرعية وتجاوز هذه الطريقة إذا كنت ترغب في حقن سلوك مخصص.

get_total_train_batch_size

< >

( args: TrainingArguments )

يحسب حجم الدفعة الإجمالي (micro_batch grad_accum dp_world_size).

تتضمن الحسابات جميع أبعاد التوازي: TP وCP وSP.

الصيغة: dp_world_size = world_size // (tp_size cp_size sp_size)

حيث:

  • TP (توازي الموترات): تقسيم طبقات النموذج على وحدات معالجة الرسوميات
  • CP (توازي السياق): تقسيم التسلسلات باستخدام Ring Attention (FSDP2)
  • SP (توازي التسلسل): تقسيم التسلسلات باستخدام ALST/Ulysses (DeepSpeed)

جميع الأبعاد منفصلة وضربية: world_size = dp_size tp_size cp_size * sp_size

get_tp_size

< >

( )

احصل على حجم التوازي للتينسور من إعدادات النموذج أو DeepSpeed.

get_train_dataloader

< >

( )

يعيد ~torch.utils.data.DataLoader للتدريب.

سيُستخدم عيّنة عشوائية (مُكيّفة للتدريب الموزّع عند الحاجة) إذا كان train_dataset لا ينفّذ __len__، وإلا فلن يُستخدم أي عيّنة.

قم بإنشاء فئة فرعية وتجاوز هذه الطريقة إذا كنت ترغب في حقن سلوك مخصص.

hyperparameter_search

< >

( hp_space: collections.abc.Callable[['optuna.Trial'], dict[str, float]] | None = Nonecompute_objective: collections.abc.Callable[[dict[str, float]], float] | None = Nonen_trials: int = 20direction: str | list[str] = 'minimize'backend: str | transformers.trainer_utils.HPSearchBackend | None = Nonehp_name: collections.abc.Callable[['optuna.Trial'], str] | None = None**kwargs ) → [trainer_utils.BestRun or list[trainer_utils.BestRun]]

المعاملات

  • hp_space (Callable[["optuna.Trial"], dict[str, float]]، اختياري) — دالة تُعرّف مساحة البحث في المعاملات الفائقة. ستكون القيمة الافتراضية هي default_hp_space_optuna() أو default_hp_space_ray() حسب الخلفية البرمجية (backend) التي تستخدمها.
  • compute_objective (Callable[[dict[str, float]], float], اختياري) — دالة تحسب الهدف المطلوب تقليله أو تعظيمه انطلاقًا من المقاييس التي يعيدها أسلوب evaluate. سيتم افتراضيًا استخدام default_compute_objective().
  • n_trials (int، اختياري، القيمة الافتراضية 100) — عدد مرات التشغيل التجريبي للاختبار.
  • direction (str أو list[str]، اختياري، القيمة الافتراضية "minimize") — إذا كان الأمر يتعلق بتحسين هدف واحد، فإن str يكون اتجاهًا، ويمكن أن يكون "minimize" أو "maximize"، وينبغي اختيار "minimize" عند تحسين خسارة التحقق، و"maximize" عند تحسين مقياس واحد أو عدة مقاييس. أما إذا كان الأمر يتعلق بتحسين أهداف متعددة، فإن list[str] يكون اتجاهًا، ويمكن أن يكون قائمة من "minimize" و"maximize"، وينبغي اختيار "minimize" عند تحسين خسارة التحقق، و"maximize" عند تحسين مقياس واحد أو عدة مقاييس.
  • backend (str أو ~training_utils.HPSearchBackend، اختياري) — الخلفية (backend) المستخدمة للبحث في المعلمات الفائقة. ستكون الافتراضية هي optuna أو Ray Tune، اعتمادًا على أيٍّ منهما مثبّت. إذا كان كلاهما مثبّتًا، فستكون الافتراضية هي optuna.
  • hp_name (Callable[["optuna.Trial"], str]]، اختياري) — دالة تحدد اسم التجربة/التشغيل. القيمة الافتراضية هي None.
  • kwargs (dict[str, Any], اختياري) — حجج إضافية بالكلمات المفتاحية لكل واجهة خلفية:
    • optuna: المعاملات من optuna.study.create_study وكذلك المعاملات timeout وn_jobs وgc_after_trial من optuna.study.Study.optimize
    • ray: المعاملات من tune.run. إذا لم يتم تعيين resources_per_trial في kwargs، فإن القيمة الافتراضية هي نواة وحدة معالجة مركزية واحدة ووحدة معالجة رسومية واحدة (إذا كانت متاحة). إذا لم يتم تعيين progress_reporter في kwargs، يتم استخدام ray.tune.CLIReporter.

يعيد

[trainer_utils.BestRun أو list[trainer_utils.BestRun]]

جميع المعلومات حول أفضل تشغيل أو أفضل عمليات التشغيل لتحسين متعدد الأهداف. يمكن العثور على ملخص التجربة في خاصية run_summary لخلفية Ray.

شغّل بحثًا على المعاملات الفائقة باستخدام optuna أو Ray Tune. يُحدَّد الكمية المُحسَّنة بواسطة compute_objective، والتي تكون افتراضيًا دالةً تُرجع خسارة التقييم عند عدم تقديم مقياس، ومجموع جميع المقاييس في حال وجودها.

To use this method, you need to have provided a model_init when initializing your Trainer: we need to reinitialize the model at each new run. This is incompatible with the optimizers argument, so you need to subclass Trainer and override the method create_optimizer_and_scheduler() for custom optimizer/scheduler.

init_hf_repo

< >

( token: str | None = Noneprivate: bool | None = None )

المعاملات

  • token (str، اختياري) — رمز (Token) بصلاحية الكتابة. القيمة الافتراضية هي self.args.hub_token.
  • private (bool، اختياري) — ما إذا كان يجب جعل المستودع خاصًا عند إنشائه. القيمة الافتراضية هي self.args.hub_private_repo. لا يكون له أي تأثير إذا كان المستودع موجودًا مسبقًا.

يُهيّئ مستودع git في self.args.hub_model_id.

is_local_process_zero

< >

( )

ما إذا كانت هذه العملية هي العملية الرئيسية المحلية (على سبيل المثال، على جهاز واحد إذا كان التدريب يتم بطريقة موزعة على عدة أجهزة).

is_world_process_zero

< >

( )

سواء كان هذا العملية الرئيسية العامة أم لا (عند التدريب بطريقة موزعة على عدة أجهزة، لن تكون هذه القيمة True إلا لعملية واحدة).

log

< >

( logs: dictstart_time: float | None = None )

المعاملات

  • logs (dict[str, float]) — القيم التي يجب تسجيلها.
  • start_time (Optional[float]) — بداية التدريب.

سجّل logs على الكائنات المختلفة التي تراقب التدريب.

أنشئ فئة فرعية وأعد تعريف هذه الطريقة لحقن سلوك مخصص.

log_metrics

< >

( splitmetrics )

المعاملات

  • split (str) — اسم الوضع/التقسيم: أحد train، eval، test
  • metrics (dict[str, float]) — المقاييس المُعادَة من train/evaluate/predictmetrics: قاموس المقاييس

سجّل المقاييس بطريقة مُنسّقة بشكل خاص.

في البيئة الموزعة، يتم تنفيذ هذا الإجراء فقط للعملية ذات الترتيب 0.

ملاحظات حول تقارير الذاكرة:

للحصول على تقرير لاستخدام الذاكرة، يجب عليك تثبيت psutil. يمكنك القيام بذلك عبر pip install psutil.

الآن، عند تشغيل هذه الطريقة، ستظهر لك تقرير يتضمن:

init_mem_cpu_alloc_delta   =     1301MB
init_mem_cpu_peaked_delta  =      154MB
init_mem_gpu_alloc_delta   =      230MB
init_mem_gpu_peaked_delta  =        0MB
train_mem_cpu_alloc_delta  =     1345MB
train_mem_cpu_peaked_delta =        0MB
train_mem_gpu_alloc_delta  =      693MB
train_mem_gpu_peaked_delta =        7MB

فهم التقارير:

  • يُخبرك المقطع الأول، مثل train__، بالمرحلة التي تخصها المقاييس. أما التقارير التي تبدأ بـ init_ فتُضاف إلى المرحلة الأولى التي يتم تشغيلها. وبذلك، إذا تم تشغيل التقييم فقط، فسيتم الإبلاغ عن استهلاك الذاكرة الخاص بـ __init__ إلى جانب مقاييس eval_.
  • المقطع الثالث، وهو إما cpu أو gpu، يُخبرك ما إذا كان الأمر يتعلق بمقياس ذاكرة الوصول العشوائي العامة أو ذاكرة gpu0.
  • *_alloc_delta - هو الفرق في عداد الذاكرة المستخدمة/المخصصة بين نهاية المرحلة وبدايتها - وقد يكون سالبًا إذا كانت الدالة أفرجت عن ذاكرة أكثر مما خصصته.
  • *_peaked_delta - هو أي ذاكرة إضافية استُهلكت ثم أُطلِقت - مقارنةً بعدّاد الذاكرة المخصصة الحالي - وهو لا يكون سالبًا أبدًا. عند النظر إلى مقاييس أي مرحلة، تجمع بين alloc_delta + peaked_delta لتعرف مقدار الذاكرة المطلوبة لإكمال تلك المرحلة.

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

تقيس مقياس ذاكرة الوصول العشوائي المعالج (CPU RAM) حجم مجموعة المقيم (RSS)، والذي يشمل الذاكرة الفريدة للعملية والذاكرة المشتركة مع العمليات الأخرى. من المهم ملاحظة أنه لا يشمل الذاكرة المُبدَلة (swapped out)، لذا قد تكون التقارير غير دقيقة.

يُقاس ذروة الذاكرة على المعالج المركزي (CPU) باستخدام خيط عينات (sampling thread). بسبب قفل GIL في بايثون، قد يفوت هذا الخيط بعض ذروات الذاكرة إذا لم يحصل على فرصة للتشغيل في اللحظة التي استُخدمت فيها أعلى كمية من الذاكرة. لذلك، قد تكون هذه التقارير أقل من الواقع. كان استخدام tracemalloc سيُبلغ عن ذروة الذاكرة بدقة، لكنه لا يُبلغ عن تخصيصات الذاكرة خارج بايثون. لذا، إذا خصصت إضافة C++ CUDA ذاكرتها الخاصة، فلن يتم الإبلاغ عنها. ولذلك تم التخلي عنه لصالح نهج أخذ عينات من الذاكرة، الذي يقرأ استخدام الذاكرة الحالي للعملية.

يتم تخصيص وحدة المعالجة الرسومية (GPU) وإبلاغ عن ذروة الذاكرة باستخدام torch.cuda.memory_allocated() وtorch.cuda.max_memory_allocated(). يبلغ هذا المقياس عن “الفروقات” فقط للتخصيصات الخاصة بـ PyTorch، لأن نظام إدارة الذاكرة في torch.cuda لا يتتبع أي ذاكرة مُخصصة خارج PyTorch. على سبيل المثال، عادةً ما يؤدي أول استدعاء لـ CUDA إلى تحميل نواة CUDA، والتي قد تستهلك من 0.5 إلى 2 غيغابايت من ذاكرة GPU.

لاحظ أن هذا المتتبع لا يأخذ في الاعتبار تخصيصات الذاكرة خارج استدعاءات __init__ وtrain وevaluate وpredict الخاصة بـTrainer.

بما أن استدعاءات evaluation قد تحدث أثناء train، فلا يمكننا التعامل مع الاستدعاءات المتداخلة لأن torch.cuda.max_memory_allocated هو عداد واحد، فإذا تم إعادة ضبطه بواسطة استدعاء تقييم متداخل، فإن متتبع train سوف يبلّغ عن معلومات غير صحيحة. إذا تم حل هذه المشكلة في PyTorch فسيصبح من الممكن تغيير هذا الصنف ليكون قابلًا لإعادة الدخول. وحتى ذلك الحين، سنقوم بتتبع المستوى الخارجي فقط لطرق train وevaluate وpredict. وهذا يعني أنه إذا تم استدعاء eval أثناء train، فإن الثاني هو الذي سيحسب استهلاكه للذاكرة واستهلاك الأول.

وهذا يعني أيضًا أنه إذا استدعى أي أداة أخرى تُستخدم مع Trainer الدالة torch.cuda.reset_peak_memory_stats، فقد تصبح إحصائيات ذروة ذاكرة وحدة معالجة الرسوميات غير صالحة. كما أن Trainer سيُخلّ بالسلوك الطبيعي لأي أدوات من هذا النوع تعتمد على استدعاء torch.cuda.reset_peak_memory_stats بنفسها.

للحصول على أفضل أداء، قد ترغب في تعطيل ملفّات الذاكرة (memory profiling) عند التشغيل في بيئة الإنتاج.

metrics_format

< >

( metrics: dict ) → metrics (dict[str, float])

المعاملات

  • metrics (dict[str, float]) — المقاييس المُعادَة من التدريب/التقييم/التنبؤ

يعيد

المقاييس (dict[str, float])

المقاييس المُعاد تنسيقها

إعادة تنسيق قيم مقاييس Trainer إلى صيغة قابلة للقراءة من قِبل المستخدم.

num_examples

< >

( dataloader: DataLoader )

Helper to get number of samples in a ~torch.utils.data.DataLoader by accessing its dataset. When dataloader.dataset does not exist or has no length, estimates as best it can

pop_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback ) → TrainerCallback

المعاملات

  • callback (type أو [`~transformers.TrainerCallback]`) — فئة TrainerCallback أو كائن من فئة TrainerCallback. في الحالة الأولى، سيتم استرجاع أول عضو من تلك الفئة الموجود في قائمة الاستدعاءات.

يعيد

TrainerCallback

المستدعى المُزال، إذا تم العثور عليه.

إزالة مستدعٍ من القائمة الحالية لـ TrainerCallback وإرجاعه.

إذا لم يُعثر على الاستدعاء العكسي، تُرجع None (ولا يتم رفع أي خطأ).

predict

< >

( test_dataset: Datasetignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'test' )

المعاملات

  • test_dataset (Dataset) — مجموعة البيانات التي تُنفَّذ عليها التنبؤات. إذا كانت من نوع datasets.Dataset، تُحذف تلقائيًا الأعمدة غير المقبولة بواسطة طريقة model.forward().
  • ignore_keys (list[str]، اختياري) — قائمة بمفاتيح في مخرجات النموذج (إذا كان قاموسًا) يجب تجاهلها عند جمع التنبؤات.
  • metric_key_prefix (str، اختياري، القيمة الافتراضية "test") — بادئة اختيارية تُستخدم كبادئة لمفاتيح المقاييس. على سبيل المثال، سيُسمى المقياس “bleu” باسم “test_bleu” إذا كانت البادئة “test” (الافتراضية)

تشغيل التنبؤ وإرجاع التنبؤات والمقاييس المحتملة.

اعتمادًا على مجموعة البيانات واستخدامك، قد تحتوي مجموعة الاختبار على تسميات. في هذه الحالة، سيعيد هذا الدالة أيضًا مقاييس، كما في evaluate().

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

تُرجع: NamedTuple tuple مُسمّى بالمفاتيح التالية:

  • التنبؤات (np.ndarray): التنبؤات على test_dataset.
  • label_ids (np.ndarray، اختياري): التسميات (إذا كانت مجموعة البيانات تحتوي على تسميات).
  • المقاييس (dict[str, float]، اختياري): قاموس المقاييس المحتملة (إذا احتوت مجموعة البيانات على تسميات).

خطوة التنبؤ

< >

( model: Moduleinputs: dictprediction_loss_only: boolignore_keys: list[str] | None = None ) → tuple[Optional[torch.Tensor], Optional[torch.Tensor], Optional[torch.Tensor]]

المعاملات

  • model (nn.Module) — النموذج المراد تقييمه.
  • inputs (dict[str, torch.Tensor | Any]) — مدخلات النموذج وأهدافه.

    سيتم فك حزمة القاموس قبل تمريره إلى النموذج. تتوقع معظم النماذج أن تكون الأهداف تحت الحجة labels. راجع توثيق نموذجك لمعرفة جميع الحجج المقبولة.

  • prediction_loss_only (bool) — ما إذا كان يجب إرجاع الخسارة فقط أم لا.
  • ignore_keys (list[str]، اختياري) — قائمة بمفاتيح في مخرجات النموذج (إذا كان قاموسًا) يجب تجاهلها عند جمع التنبؤات.

يعيد

tuple[Optional[torch.Tensor], Optional[torch.Tensor], Optional[torch.Tensor]]

مجموعة (tuple) تحتوي على الخسارة (loss) والنتائج (logits) والوسوم (labels) (كل منها اختياري).

أداء خطوة تقييم على model باستخدام inputs.

أنشئ فئة فرعية وأعد تعريف الدوال لحقن سلوك مخصص.

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]، اختياري) — معلمات إضافية تُمرَّر إلى create_model_card().

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

remove_callback

< >

( callback: type[transformers.trainer_callback.TrainerCallback] | transformers.trainer_callback.TrainerCallback )

المعاملات

  • callback (type أو [`~transformers.TrainerCallback`]) — فئة TrainerCallback أو مثيل من TrainerCallback. في الحالة الأولى، سيتم حذف أول عضو من تلك الفئة الموجود في قائمة الاستدعاءات.

إزالة مستدعٍ من القائمة الحالية لـ TrainerCallback.

save_metrics

< >

( splitmetricscombined = True )

المعاملات

  • split (str) — اسم الوضع/التقسيم: أحد train، eval، test، all
  • metrics (dict[str, float]) — المقاييس المُعادَة من التدريب/التقييم/التنبؤ
  • combined (bool، اختياري، القيمة الافتراضية True) — ينشئ مقاييس مجمّعة من خلال تحديث all_results.json بمقاييس هذه الاستدعاء

احفظ المقاييس في ملف json خاص بتلك التقسيمة، مثل train_results.json.

في البيئة الموزعة، يتم تنفيذ هذا الإجراء فقط للعملية ذات الترتيب 0.

لفهم المقاييس، يرجى قراءة log_metrics() في التوثيق. والفرق الوحيد هو أن الأرقام الخام غير المنسّقة تُحفظ في الطريقة الحالية.

save_model

< >

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

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

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

save_state

< >

( )

يحفظ حالة Trainer، لأن Trainer.save_model يحفظ المرمّز (tokenizer) مع النموذج فقط.

في البيئة الموزعة، يتم تنفيذ هذا الإجراء فقط للعملية ذات الترتيب 0.

set_initial_training_values

< >

( args: TrainingArgumentsdataloader: DataLoader )

يُحسب ويعيد القيم التالية:

  • num_train_epochs
  • num_update_steps_per_epoch
  • num_examples
  • num_train_samples
  • total_train_batch_size
  • steps_in_epoch (إجمالي الدفعات في كل حقبة)
  • max_steps

store_flos

< >

( )

احفظ عدد عمليات الفاصلة العائمة التي تم إجراؤها في النموذج.

تدريب

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → 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]، اختياري) — قائمة بالمفاتيح في مخرجات النموذج (إذا كان قاموسًا) التي يجب تجاهلها عند جمع التنبؤات للتقييم أثناء التدريب.

يعيد

TrainOutput

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

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

خطوة التدريب

< >

( model: Moduleinputs: dictnum_items_in_batch: typing.Union[torch.Tensor, int, NoneType] = None ) → torch.Tensor

المعاملات

  • model (nn.Module) — النموذج المراد تدريبه.
  • inputs (dict[str, torch.Tensor | Any]) — مدخلات النموذج وأهدافه.

    سيتم فك حزمة القاموس قبل تمريره إلى النموذج. تتوقع معظم النماذج أن تكون الأهداف تحت الحجة labels. راجع توثيق نموذجك لمعرفة جميع الحجج المقبولة.

يعيد

torch.Tensor

الموتر الذي يحتوي على خسارة التدريب على هذه الدفعة.

نفّذ خطوة تدريب على دفعة من المدخلات.

أنشئ فئة فرعية وأعد تعريف الدوال لحقن سلوك مخصص.

Seq2SeqTrainer

فئة transformers.Seq2SeqTrainer

< >

( model: typing.Union[ForwardRef('PreTrainedModel'), torch.nn.Module, NoneType] = Noneargs: typing.Optional[ForwardRef('TrainingArguments')] = Nonedata_collator: typing.Optional[ForwardRef('DataCollator')] = Nonetrain_dataset: typing.Union[torch.utils.data.Dataset, ForwardRef('IterableDataset'), ForwardRef('datasets.Dataset'), NoneType] = Noneeval_dataset: typing.Union[torch.utils.data.Dataset, dict[str, torch.utils.data.Dataset], NoneType] = Noneprocessing_class: typing.Union[ForwardRef('PreTrainedTokenizerBase'), ForwardRef('BaseImageProcessor'), ForwardRef('FeatureExtractionMixin'), ForwardRef('ProcessorMixin'), NoneType] = Nonemodel_init: collections.abc.Callable[[], 'PreTrainedModel'] | None = Nonecompute_loss_func: collections.abc.Callable | None = Nonecompute_metrics: collections.abc.Callable[['EvalPrediction'], dict] | None = Nonecallbacks: list['TrainerCallback'] | None = Noneoptimizers: tuple = (None, None)preprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = None )

evaluate

< >

( eval_dataset: typing.Optional[torch.utils.data.Dataset] = Noneignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'eval'**gen_kwargs )

المعاملات

  • eval_dataset (Dataset، اختياري) — مرّر مجموعة بيانات إذا كنت ترغب في تجاوز self.eval_dataset. إذا كانت من نوع Dataset، فسيتم حذف الأعمدة غير المقبولة تلقائيًا بواسطة طريقة model.forward(). يجب أن تنفّذ طريقة __len__.
  • ignore_keys (list[str]، اختياري) — قائمة بمفاتيح في مخرجات النموذج (إذا كان قاموسًا) يجب تجاهلها عند جمع التنبؤات.
  • metric_key_prefix (str، اختياري، القيمة الافتراضية "eval") — بادئة اختيارية تُستخدم كبادئة لمفاتيح المقاييس. على سبيل المثال، سيُسمّى المقياس "bleu" باسم "eval_bleu" إذا كانت البادئة "eval" (الافتراضية)
  • max_length (int، اختياري) — الحد الأقصى لطول الهدف المستخدم عند التنبؤ باستخدام طريقة generate.
  • num_beams (int, اختياري) — عدد الحزم (beams) المستخدمة في بحث الحزم (beam search) عند التنبؤ باستخدام طريقة generate. القيمة 1 تعني عدم استخدام بحث الحزم.
  • gen_kwargs — معلمات إضافية خاصة بـgenerate.

تشغيل التقييم وإرجاع المقاييس.

ستكون سكريبت الاستدعاء مسؤولة عن توفير طريقة لحساب المقاييس، إذ إنها تعتمد على المهمة (مرّرها إلى معامل compute_metrics في init).

يمكنك أيضًا إنشاء فئة فرعية وتجاوز هذه الطريقة لحقن سلوك مخصص.

predict

< >

( test_dataset: Datasetignore_keys: list[str] | None = Nonemetric_key_prefix: str = 'test'**gen_kwargs )

المعاملات

  • test_dataset (Dataset) — مجموعة البيانات التي تُنفَّذ عليها التنبؤات. إذا كانت من نوع Dataset، تُحذف تلقائيًا الأعمدة غير المقبولة بواسطة طريقة model.forward(). يجب أن تُنفّذ الطريقة __len__
  • ignore_keys (list[str]، اختياري) — قائمة بمفاتيح في مخرجات النموذج (إذا كان قاموسًا) يجب تجاهلها عند جمع التنبؤات.
  • metric_key_prefix (str، اختياري، القيمة الافتراضية "eval") — بادئة اختيارية تُستخدم كبادئة لمفاتيح المقاييس. على سبيل المثال، سيُسمّى المقياس "bleu" باسم "eval_bleu" إذا كانت البادئة "eval" (الافتراضية)
  • max_length (int، اختياري) — الحد الأقصى لطول الهدف المستخدم عند التنبؤ باستخدام طريقة generate.
  • num_beams (int, اختياري) — عدد الحزم (beams) المستخدمة في بحث الحزم (beam search) عند التنبؤ باستخدام طريقة generate. القيمة 1 تعني عدم استخدام بحث الحزم.
  • gen_kwargs — معلمات إضافية خاصة بـgenerate.

تشغيل التنبؤ وإرجاع التنبؤات والمقاييس المحتملة.

اعتمادًا على مجموعة البيانات واستخدامك، قد تحتوي مجموعة الاختبار على تسميات. في هذه الحالة، سيعيد هذا الدالة أيضًا مقاييس، كما في evaluate().

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

تُرجع: NamedTuple tuple مُسمّى بالمفاتيح التالية:

  • التنبؤات (np.ndarray): التنبؤات على test_dataset.
  • label_ids (np.ndarray، اختياري): التسميات (إذا كانت مجموعة البيانات تحتوي على تسميات).
  • المقاييس (dict[str, float]، اختياري): قاموس المقاييس المحتملة (إذا احتوت مجموعة البيانات على تسميات).

TrainingArguments

فئة transformers.TrainingArguments

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 5e-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 = Falsefp16: 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 | None = Nonegradient_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 = 500logging_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 = <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: typing.Any | 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 = -1 )

المعاملات

  • output_dir (str، اختياري، القيمة الافتراضية "trainer_output") — مجلد الإخراج الذي سيتم فيه كتابة تنبؤات النموذج ونقاط التفتيش.

مدة التدريب وحجم الدفعة

  • per_device_train_batch_size (int، اختياري، القيمة الافتراضية 8) — حجم الدفعة لكل جهاز. يُحسب حجم الدفعة الكلي على النحو التالي: per_device_train_batch_size * number_of_devices في إعدادات متعددة GPUs أو موزعة.
  • num_train_epochs(float, اختياري، القيمة الافتراضية 3.0) — إجمالي عدد فترات التدريب (epochs) التي يجب تنفيذها (إذا لم تكن قيمة صحيحة، فسيتم تنفيذ الجزء العشري كنسبة مئوية من الفترة الأخيرة قبل إيقاف التدريب).
  • max_steps (int، اختياري، القيمة الافتراضية -1) — يتجاوز num_train_epochs. إذا تم ضبطه على رقم موجب، فهو يمثل العدد الإجمالي لخطوات التدريب التي يجب تنفيذها. بالنسبة إلى مجموعة بيانات محدودة، يتم تكرار التدريب عبر مجموعة البيانات (إذا استُنفد كل البيانات) حتى يتم الوصول إلى max_steps. يجب ضبطه على قيمة موجبة عندما لا تنفّذ مجموعة بيانات التدريب __len__ (مثل مجموعة بيانات البث)، لأن العدد الإجمالي للخطوات لا يمكن استنتاجه في هذه الحالة، وهو مطلوب لتحديد حد حلقة التدريب وإعداد مجدول معدل التعلم.

معدل التعلم والمجدول

  • learning_rate (float، اختياري، القيمة الافتراضية 5e-5) — معدل التعلم الأولي لمُحسِّن التدريب. عادةً ما يكون هذا هو معدل التعلم الأقصى عند استخدام مُجدوِل مع فترة إحماء.
  • lr_scheduler_type (str أو SchedulerType, اختياري, الافتراضي هو "linear") — نوع جدولة معدل التعلم المستخدم. راجع SchedulerType لمعرفة جميع القيم الممكنة. الخيارات الشائعة:
  • lr_scheduler_kwargs (dict أو str، اختياري، القيمة الافتراضية None) — الحجج الإضافية الخاصة بـ lr_scheduler. راجع توثيق كل مُجدول لمعرفة القيم الممكنة.
  • warmup_steps (int أو float, اختياري, الافتراضي 0) — عدد الخطوات لدفء خطي من 0 إلى learning_rate. يساعد الدفء في استقرار التدريب في المرحلة الأولية. يمكن أن يكون:
    • عدد صحيح: عدد خطوات الإحماء الدقيق
    • عدد عشري ضمن المدى [0, 1): يُفسَّر كنسبة من إجمالي خطوات التدريب

المُحسِّن

  • optim (str أو training_args.OptimizerNames, اختياري, الافتراضي هو "adamw_torch" (لـ torch>=2.8 "adamw_torch_fused")) — المُحسِّن (Optimizer) المستخدم. الخيارات الشائعة:
    • "adamw_torch": AdamW في PyTorch (الافتراضي الموصى به)
    • "adamw_torch_fused": نواة AdamW المدمجة
    • "adamw_hf": تنفيذ AdamW من HuggingFace
    • "sgd": هبوط التدرج العشوائي مع الزخم
    • "adafactor": مُحسِّن فعّال من حيث الذاكرة للنماذج الكبيرة
    • "adamw_8bit": AdamW بدقة 8 بت (يتطلب bitsandbytes) راجع OptimizerNames للحصول على القائمة الكاملة.
  • optim_args (str, اختياري) — حجج اختيارية تُمرَّر إلى المُحسِّنات مثل AnyPrecisionAdamW وAdEMAMix وGaLore.
  • weight_decay (float، اختياري، القيمة الافتراضية 0) — معامل اضمحلال الوزن الذي يطبّقه المُحسِّن (وليس دالة الخسارة). يضيف تنظيم L2 لمنع الإفراط في التخصيص من خلال معاقبة الأوزان الكبيرة. يُستثنى تلقائيًا من معاملات الانحياز وLayerNorm. القيم النموذجية: 0.01 (قياسي)، 0.1 (تنظيم أقوى)، 0.0 (بدون تنظيم).
  • adam_beta1 (float, اختياري، القيمة الافتراضية 0.9) — معدل الاضمحلال الأسي لتقديرات اللحظة الأولى (الزخم) في المُحسِّنات القائمة على Adam. يتحكم في مقدار سجل التدرجات الذي يجب الاحتفاظ به.
  • adam_beta2 (float, اختياري، القيمة الافتراضية 0.999) — معدل الاضمحلال الأسي لتقديرات العزوم الثانية (التباين) في المُحسِّنات القائمة على Adam. يتحكم في تحجيم معدل التعلم التكيفي.
  • adam_epsilon (float, اختياري، القيمة الافتراضية 1e-8) — قيمة إيبسلون للاستقرار العددي في المُحسِّنات القائمة على Adam. تمنع القسمة على الصفر في مقام قاعدة التحديث.
  • optim_target_modules (Union[str, list[str]]، اختياري) — وحدات الهدف التي سيتم تحسينها، أي أسماء الوحدات التي ترغب في تدريبها. يُستخدم حاليًا لخوارزمية GaLore وخوارزمية APOLLO. راجع تنفيذ GaLore وتنفيذ APOLLO لمزيد من التفاصيل. يجب التأكد من تمرير مُحسِّن GaLore أو APOLLO صالح، مثل أحد ما يلي: “apollo_adamw” و“galore_adamw” و“galore_adamw_8bit” و“galore_adafactor”، والتأكد من أن وحدات الهدف هي وحدات nn.Linear فقط.

التنظيم واستقرار التدريب

  • gradient_accumulation_steps (int, اختياري, الافتراضي 1) — عدد خطوات التحديث لتجميع التدرجات قبل تنفيذ مسار التراجع/التحديث. يحاكي أحجام دفعات أكبر دون استهلاك ذاكرة إضافية. حجم الدفعة الفعّال = per_device_train_batch_size × num_devices × gradient_accumulation_steps.

    عند استخدام تراكم التدرجات، يُحتسب "خطوة" واحدة على أنها خطوة واحدة تتضمن مسارًا عكسيًا. لذلك، ستتم عمليات التسجيل والتقييم والحفظ كل gradient_accumulation_steps × xxx_step من أمثلة التدريب.

  • average_tokens_across_devices (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم أخذ متوسط الرموز عبر الأجهزة أم لا. إذا تم التفعيل، فسيتم استخدام all_reduce لمزامنة num_tokens_in_batch لحساب الدقة بدقة. المرجع: https://github.com/huggingface/transformers/issues/34242
  • max_grad_norm (float, اختياري، القيمة الافتراضية 1.0) — الحد الأقصى لطول التدرّج (Norm) لقصّ التدرّجات. يُطبَّق بعد مرور التدرّج العكسي وقبل خطوة المُحسِّن. يمنع انفجار التدرّجات عن طريق تصغير التدرّجات عندما يتجاوز طولها الكلي هذا العتبة. اضبطه على 0 لتعطيل القصّ. القيم النموذجية: 1.0 (قياسي)، 0.5 (أكثر تحفظاً)، 5.0 (أقل عدوانية).
  • label_smoothing_factor (float, اختياري، القيمة الافتراضية 0.0) — معامل تنعيم التسميات لمنع الثقة المفرطة. يستبدل الأهداف الصلبة 0/1 بأهداف ناعمة: يصبح 0 هو ε/num_labels ويصبح 1 هو 1 - ε + ε/num_labels، حيث ε = label_smoothing_factor. تعني القيمة صفرًا عدم وجود تنعيم. النطاق النموذجي: من 0.0 إلى 0.1.

التدريب بالدقة المختلطة

  • bf16 (bool، اختياري، القيمة الافتراضية False) — تفعيل تدريب الدقة المختلطة bfloat16 (BF16) يُفضَّل عمومًا على FP16 نظرًا لاستقراره العددي الأفضل وعدم الحاجة إلى تحجيم الفقد.
  • fp16 (bool، اختياري، القيمة الافتراضية False) — تفعيل التدريب بدقة مختلطة float16 (FP16). يُفضَّل استخدام BF16 بدلاً من ذلك إذا كان جهازك يدعمه.
  • bf16_full_eval (bool، اختياري، القيمة الافتراضية False) — استخدام دقة BF16 الكاملة للتقييم (وليس الدقة المختلطة فقط). أسرع ويوفر الذاكرة، لكنه قد يؤثر قليلاً على قيم المقاييس. ينطبق فقط أثناء التقييم.
  • fp16_full_eval (bool، اختياري، القيمة الافتراضية False) — استخدام دقة FP16 الكاملة للتقييم (وليس مجرد دقة مختلطة). أسرع ويوفر الذاكرة، لكنه قد يؤثر قليلاً على قيم المقاييس. ينطبق فقط أثناء التقييم.
  • tf32 (bool، اختياري) — تفعيل وضع TensorFloat-32 (TF32) على وحدات معالجة الرسوميات من نوع Ampere والأحدث. يستخدم TF32 دقة بمقدار 19 بت للضرب المصفوفي (بدلاً من 23 بت في FP32)، مما يوفر تسريعًا يصل إلى 8 أضعاف مع فقدان دقة ضئيل. تعتمد القيمة الافتراضية على إصدار PyTorch. راجع وثائق TF32.

التحقق من التفعيل

  • activation_checkpointing (bool, اختياري، القيمة الافتراضية False) — تفعيل فحص التفعيل لتبادل الحساب مع الذاكرة. يقلل من استهلاك الذاكرة عن طريق مسح التفعيلات أثناء المرور الأمامي وإعادة حسابها أثناء المرور الخلفي. يتيح تدريب نماذج أكبر أو أحجام دفعات أكبر مقابل تكلفة تدريب أبطأ بنسبة ~20%.
  • activation_checkpointing_kwargs (dict، اختياري، القيمة الافتراضية None) — حجج الكلمات المفتاحية التي تُمرَّر إلى activation_checkpointing_enable(). every_n_layers يُنشئ نقاط فحص (checkpoints) لكل طبقة مُفكِّكة (decoder) رقمها مضاعف لـ n بدلاً من جميع الطبقات؛ 1 هو السلوك المعتاد الشامل أو الباطل، والقيم الأكبر تُعيد بعض الذاكرة إلى السرعة. offload يحتفظ بالتفعيلات المحفوظة في ذاكرة مضيف مثبّتة (pinned host memory)، مما يُحرر layers x sequence x hidden بايت من ذاكرة الجهاز ويجعل الخطوة أبطأ. أي مفتاح آخر يُمرَّر إلى torch.utils.checkpoint.checkpoint.
  • gradient_checkpointing (bool، اختياري) — اسم مستعار غير مستخدم لـ activation_checkpointing، وسيتم إزالته في الإصدار v6.
  • gradient_checkpointing_kwargs (dict، اختياري) — اسم مستعار غير مستحسن لـ activation_checkpointing_kwargs، وسيتم إزالته في الإصدار v6.

التجميع

  • torch_compile (bool، اختياري، القيمة الافتراضية False) — تجميع النموذج باستخدام torch.compile() في PyTorch 2.0 لتسريع التدريب. يمكن أن يوفر تسريعًا بنسبة 20-50% دون أي تغييرات في الكود. يستخدم إعدادات التجميع الافتراضية ما لم يتم تحديد torch_compile_backend أو torch_compile_mode.
  • torch_compile_backend (str، اختياري) — الخلفية (Backend) الخاصة بـ torch.compile(). إذا تم ضبطه، يتم تفعيل torch_compile تلقائيًا. تشمل الخيارات "inductor" (الافتراضي)، "aot_eager"، "cudagraphs". تختلف الخلفيات حسب إصدار PyTorch - راجع توثيق PyTorch لمعرفة الخيارات المتاحة.
  • torch_compile_mode (str, اختياري) — وضع التجميع لـ torch.compile(). إذا تم ضبطه، يتم تفعيل torch_compile تلقائيًا. الخيارات: "default"، "reduce-overhead" (لتقليل الحمل الإضافي على Python)، "max-autotune" (تحسين عدواني، مع وقت تجميع أطول).

النوى

  • use_liger_kernel (bool، اختياري، القيمة الافتراضية False) — تفعيل تحسينات Liger Kernel. يزيد من الإنتاجية عبر وحدات معالجة الرسومات المتعددة بنسبة ~20% ويقلل من استهلاك الذاكرة بنسبة ~60%. يعمل مع Flash Attention وFSDP وDeepSpeed. يدعم حاليًا نماذج Llama وMistral وMixtral وGemma.
  • liger_kernel_config (Optional[dict], اختياري) — إعدادات Liger Kernel. تُمرَّر كـ kwargs إلى _apply_liger_kernel_to_instance(). تشمل الخيارات عادةً: "rope"، "swiglu"، "cross_entropy"، "fused_linear_cross_entropy"، "rms_norm". إذا كانت None، يتم استخدام الإعدادات الافتراضية.

تحسينات إضافية

  • use_cache (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تفعيل ذاكرة التخزين المؤقت للنموذج أم لا. في حالة التدريب، عادةً ما لا تكون هذه الخاصية مطلوبة باستثناء بعض طرق PEFT التي تستخدم past_key_values.
  • neftune_noise_alpha (Optional[float]) — إذا لم تكن None، فسيتم تفعيل تضمينات ضوضاء NEFTune. يمكن أن يحسّن هذا أداء النموذج بشكل كبير في الضبط الدقيق التعليمي. اطّلع على الورقة الأصلية و الكود الأصلي. يدعم PreTrainedModel من transformers وكذلك PeftModel من peft. استخدمت الورقة الأصلية قيمًا في النطاق [5.0, 15.0].
  • torch_empty_cache_steps (int, اختياري) — عدد الخطوات التي يجب انتظارها قبل استدعاء torch.<device>.empty_cache(). إذا تُرك غير مضبوط أو تم ضبطه على None، فلن يتم تفريغ ذاكرة التخزين المؤقت. يمكن أن يساعد ذلك في تجنب أخطاء نفاد ذاكرة CUDA عن طريق خفض ذروة استخدام ذاكرة VRAM، مقابل تكلفة تقارب 10% من الأداء الأبطأ.
  • auto_find_batch_size (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تحديد حجم دفعة التدريب الذي يتناسب مع الذاكرة تلقائيًا من خلال التلاشي الأسي، لتجنب أخطاء نفاد ذاكرة CUDA. لا يتم تعديل حجم دفعة التقييم.

تسجيل ومراقبة التدريب

  • logging_strategy (str أو IntervalStrategy, اختياري, الافتراضي هو "steps") — استراتيجية التسجيل المعتمدة أثناء التدريب. القيم الممكنة هي:
    • "no": لا يتم تسجيل أي سجلات أثناء التدريب.
    • "epoch": يتم التسجيل في نهاية كل حقبة.
    • "steps": يتم التسجيل كل logging_steps.
  • logging_steps (int أو float، اختياري، القيمة الافتراضية 500) — عدد خطوات التحديث بين سجلّين إذا كان logging_strategy="steps". يجب أن يكون عددًا صحيحًا أو عددًا عشريًا ضمن النطاق [0,1). إذا كان أقل من 1، فسيُفسَّر كنسبة من إجمالي خطوات التدريب.
  • logging_first_step (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تسجيل الخطوة الأولى global_step أم لا.
  • log_on_each_node (bool، اختياري، القيمة الافتراضية True) — في التدريب الموزّع متعدد العقد، ما إذا كان سيتم التسجيل باستخدام log_level مرة واحدة لكل عقدة، أم على العقدة الرئيسية فقط.
  • logging_nan_inf_filter (bool، اختياري، القيمة الافتراضية True) — تصفية قيم NaN و Inf في الخسائر عند التسجيل. إذا كانت True، يتم استبدال خسائر التدريب التي تكون NaN/Inf بمتوسط الخسائر الصالحة الأخيرة، ويُستثنى الدُفعات التي تحتوي على NaN/Inf (مثل الدُفعات التي لا تحتوي على رموز تسميات) من حساب خسارة التقييم. لا يؤثر ذلك على حساب التدرجات، بل على التسجيل فقط.
  • include_num_input_tokens_seen (Optional[Union[str, bool]]، اختياري، القيمة الافتراضية “no”) — ما إذا كان سيتم تتبع عدد رموز الإدخال التي تم رؤيتها. يجب أن تكون واحدة من [“all”, “non_padding”, “no”] أو قيمة منطقية تُخضع إلى “all” أو “no”. قد يكون أبطأ في التدريب الموزّع لأن عمليات الجمع (gather) يجب أن تُستدعى.

التسجيل

  • log_level (str، اختياري، القيمة الافتراضية passive) — مستوى التسجيل للعملية الرئيسية. الخيارات: "debug"، "info"، "warning"، "error"، "critical"، أو "passive" (لا يغيّر مستوى تسجيل Transformers الحالي، والذي تكون قيمته الافتراضية "warning")
  • log_level_replica (str، اختياري، القيمة الافتراضية "warning") — مستوى التسجيل لعمليات النسخ في التدريب الموزّع. نفس الخيارات المتاحة في log_level.
  • disable_tqdm (bool, اختياري) — تعطيل أشرطة تقدم tqdm. القيمة الافتراضية هي True إذا كان log_level على مستوى warning أو أدنى، وإلا فهي False.

تكامل تتبع التجارب

  • report_to (str أو list[str]، اختياري، القيمة الافتراضية "none") — قائمة التكاملات التي سيتم الإبلاغ عن النتائج والسجلات إليها. المنصات المدعومة هي "azure_ml"، "clearml"، "codecarbon"، "comet_ml"، "dagshub"، "dvclive"، "flyte"، "mlflow"، "swanlab"، "tensorboard"، "trackio" و"wandb". استخدم "all" للإبلاغ إلى جميع التكاملات المثبتة، و"none" لعدم استخدام أي تكاملات.
  • run_name (str, اختياري) — وصف للتشغيل. يُستخدم عادةً لتسجيل trackio، wandb، mlflow، comet و swanlab.
  • project (str، اختياري، القيمة الافتراضية "huggingface") — اسم المشروع المستخدم للتسجيل. حاليًا، يُستخدم فقط بواسطة Trackio.
  • trackio_space_id (str أو None، اختياري، القيمة الافتراضية None) — معرف مساحة Hugging Face التي تُستخدم للتسجيل المباشر عبر Trackio باستخدام مساحة مبنية على Gradio. يجب أن يكون اسمًا كاملًا للمساحة على غرار 'username/reponame' أو 'orgname/reponame'، أو مجرد 'reponame' (تُنشأ المساحة في نطاق المستخدم المسجّل حاليًا). إذا كانت القيمة None، تُسجَّل المقاييس في مجلد محلي فقط (بدون مساحة على Hub). تتمتع مساحة Gradio تلك بصلاحية القراءة والكتابة إلى Bucket الخاص بـ Trackio، وهو ما تريده أثناء استمرار التدريب—على سبيل المثال عند استئناف تشغيل جزئي أو تجميع السجلات من عدة أجهزة. ستكون المساحة عامة ما لم تضبط hub_private_repo=True أو كان الافتراضي في مؤسستك هو إنشاء مساحات خاصة.
  • trackio_bucket_id (str أو None، اختياري، القيمة الافتراضية None) — معرف Bucket اختياري على Hugging Face خاص بـ Trackio. إذا لم يُضبط، فسيُشتقّ Trackio معرّفًا تلقائيًا. يُستخدم مع مساحة Gradio (trackio_space_id) وعند نشر مساحة ثابتة (عندما لا تكون trackio_static_space_id قيمة False).
  • trackio_static_space_id (str أو False أو None، اختياري، القيمة الافتراضية هي None) — معرف مساحة Hugging Face الذي سيتم استخدامه للمساحة الثابتة التي تُنشأ بعد اكتمال التدريب. يجب أن يكون اسمًا كاملاً للمساحة على غرار 'username/reponame' أو 'orgname/reponame'، أو مجرد 'reponame' (تُنشأ المساحة في مساحة المستخدم المسجّل حاليًا). إذا كانت القيمة False، فلن يتم إنشاء مساحة ثابتة. إذا كانت القيمة None، وتم دفع النموذج إلى Hub، فسيتم إنشاء مساحة ثابتة باسم افتراضي وسيتم ربطها من بطاقة النموذج. ستكون المساحة عامة ما لم تضبط hub_private_repo=True أو كان الإعداد الافتراضي لمنظمتك هو إنشاء مساحات خاصة.

التقييم

  • eval_strategy (str أو IntervalStrategy, اختياري, الافتراضي هو "no") — متى يتم تشغيل التقييم. الخيارات:
    • "no": لا يتم إجراء أي تقييم أثناء التدريب
    • "steps": التقييم كل eval_steps
    • "epoch": التقييم في نهاية كل حقبة
  • eval_steps (int أو float، اختياري) — عدد خطوات التحديث بين تقييمين إذا كان eval_strategy="steps". إذا لم يتم ضبطه، فسيُستخدم نفس القيمة الخاصة بـ logging_steps افتراضيًا. يجب أن يكون عددًا صحيحًا أو عددًا عشريًا ضمن المدى [0,1). إذا كان أقل من 1، سيُفسَّر كنسبة من إجمالي خطوات التدريب.
  • eval_delay (float, اختياري) — عدد الفترات أو الخطوات التي يجب انتظارها قبل إجراء أول تقييم، وذلك اعتمادًا على eval_strategy.
  • per_device_eval_batch_size (int، اختياري، القيمة الافتراضية 8) — حجم الدفعة لكل نواة تسريع/وحدة معالجة مركزية على الجهاز للتقييم.
  • prediction_loss_only (bool، اختياري، القيمة الافتراضية False) — عند إجراء التقييم وتوليد التنبؤات، يُرجع الخسارة فقط.
  • eval_on_start (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب تنفيذ خطوة تقييم (فحص صحة) قبل التدريب للتأكد من أن خطوات التحقق تعمل بشكل صحيح.
  • eval_do_concat_batches (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب دمج المدخلات/الخسائر/التسميات/التنبؤات بشكل تكراري عبر الدفعات. إذا كانت القيمة False، فسيتم تخزينها بدلاً من ذلك كقوائم، مع إبقاء كل دفعة منفصلة.
  • eval_use_gather_object (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب تشغيل تجميع الكائنات بشكل تكراري من جميع الأجهزة ضمن قائمة/مجموعة/قاموس متداخل من الكائنات. يجب تفعيل هذا الخيار فقط إذا لم يكن المستخدمون يعيدون مجرد متجهات (tensors)، كما أن PyTorch يوصي صراحةً بعدم تفعيله. يكون هذا الخيار مفيداً عندما تكون بنية التسميات غير قياسية، كما هو الحال في مهام الرؤية الحاسوبية.
  • eval_accumulation_steps (int، اختياري) — عدد خطوات التنبؤ التي يتم فيها تجميع تensors المخرجات، قبل نقل النتائج إلى وحدة المعالجة المركزية (CPU). إذا لم يتم ضبطه، فسيتم تجميع التنبؤات بالكامل على مُسرِّع الجهاز قبل نقلها إلى وحدة المعالجة المركزية (CPU) (أسرع لكن يتطلب ذاكرة أكبر).

حساب المقاييس

  • include_for_metrics (list[str], اختياري, الافتراضي هو []) — تضمين بيانات إضافية في دالة compute_metrics إذا كانت مطلوبة لحساب المقاييس. الخيارات الممكنة للإضافة إلى قائمة include_for_metrics :
    • "inputs": بيانات الإدخال المُمرَّرة إلى النموذج، والمُعدّة لحساب المقاييس المعتمدة على الإدخال.
    • "loss": قيم الخسارة المحسوبة أثناء التقييم، والمخصصة لحساب المقاييس المعتمدة على الخسارة.
  • batch_eval_metrics (bool، اختياري، القيمة الافتراضية False) — إذا تم ضبطه على True، فستقوم عملية التقييم باستدعاء compute_metrics في نهاية كل دفعة لتراكم الإحصاءات بدلاً من حفظ جميع قيم التقييم (logits) في الذاكرة. عند ضبطه على True، يجب عليك تمرير دالة compute_metrics تقبل حجة منطقية compute_result، والتي عند تمرير True إليها، ستُطلق الإحصاءات الإجمالية النهائية من الإحصاءات الإجمالية على مستوى الدفعة التي تراكمها على مجموعة التقييم.

التحقق من النقاط الحرجة والحفظ

  • save_only_model (bool، اختياري، القيمة الافتراضية False) — احفظ أوزان النموذج فقط، دون حالة المُحسِّن/المُجدوِل/حالة المولّد العشوائي. يقلّل هذا بشكل كبير من حجم نقطة التفتيش، لكنه يمنع استئناف التدريب من نقطة التفتيش. استخدمه عندما تحتاج إلى النموذج المدرَّب للاستدلال فقط، وليس للتدريب المستمر. لا يمكنك تحميل النموذج باستخدام from_pretrained إلا إذا كانت هذه الخانة مضبوطة على True.
  • save_strategy (str أو SaveStrategy, اختياري, الافتراضي هو "steps") — استراتيجية حفظ نقاط التفتيش المعتمدة أثناء التدريب. القيم الممكنة هي:
    • "no": لا يتم حفظ أي شيء أثناء التدريب.
    • "epoch": يتم الحفظ في نهاية كل حقبة.
    • "steps": يتم الحفظ كل save_steps.
    • "best": يتم الحفظ كلما تم تحقيق best_metric جديد.
  • save_steps (int أو float، اختياري، القيمة الافتراضية 500) — عدد خطوات التحديث قبل حفظ نقطتي تفتيش إذا كان save_strategy="steps". يجب أن يكون عددًا صحيحًا أو عددًا عشريًا ضمن المدى [0,1). إذا كان أقل من 1، فسيُفسَّر كنسبة من إجمالي خطوات التدريب.
  • save_on_each_node (bool، اختياري، القيمة الافتراضية False) — عند تنفيذ التدريب الموزّع متعدد العقد، يحدد ما إذا كان سيتم حفظ النماذج والنقاط المرجعية على كل عقدة، أم على العقدة الرئيسية فقط. يجب عدم تفعيل هذا الخيار عندما تستخدم العقد المختلفة نفس التخزين، لأن الملفات ستُحفظ بأسماء متطابقة على كل عقدة.
  • save_total_limit (int, اختياري) — الحد الأقصى لعدد نقاط التفتيش التي يجب الاحتفاظ بها. يحذف نقاط التفتيش الأقدم في output_dir. عند load_best_model_at_end=True، يتم دائمًا الاحتفاظ بأفضل نقطة تفتيش بالإضافة إلى أحدث النقاط. على سبيل المثال، save_total_limit=5 يحتفظ بأحدث 4 نقاط بالإضافة إلى الأفضل
  • enable_jit_checkpoint (bool, اختياري، القيمة الافتراضية False) — تفعيل نقطة التفتيش الفورية عند الإرسال (Just-In-Time checkpointing) عند استلام إشارة SIGTERM لإنهاء العمل بسلاسة على الأحمال القابلة للاستحواذ (preemptible workloads). مهم: اضبط فترة الإيقاف السلس في منسّقك (orchestrator) للسماح بزمن كافٍ. في Kubernetes، اضبط terminationGracePeriodSeconds (القيمة الافتراضية 30 ثانية عادةً غير كافية). في Slurm، استخدم --signal=TERM@<seconds>. الفترة السليمة المطلوبة ≥ أطول وقت لتكرار واحد + وقت حفظ نقطة التفتيش.

التكامل مع Hugging Face Hub

  • push_to_hub (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم دفع النموذج إلى Hub في كل مرة يُحفظ فيها النموذج. إذا تم تفعيل هذا الخيار، فسيبدأ output_dir في إنشاء دليل git متزامن مع المستودع (المحدد بواسطة hub_model_id) وسيتم دفع المحتوى في كل مرة يتم فيها تشغيل الحفظ (بناءً على save_strategy الخاص بك). كما أن استدعاء save_model() سيؤدي أيضاً إلى تشغيل عملية الدفع.
  • hub_token (str، اختياري) — المفتاح المستخدم لدفع النموذج إلى Hub. سيُستخدم افتراضيًا المفتاح الموجود في مجلد الكاش الذي تم الحصول عليه عبر hf auth login.
  • hub_private_repo (bool، اختياري) — ما إذا كان سيتم جعل المستودع خاصًا. إذا كانت القيمة None (الافتراضية)، فسيكون المستودع عامًا ما لم يكن الافتراضي للمنظمة هو الخاص. يتم تجاهل هذه القيمة إذا كان المستودع موجودًا مسبقًا. عند الإبلاغ إلى Trackio مع تمكين النشر إلى Hugging Face Spaces، تحدد نفس المنطق ما إذا كان المساحة (Space) خاصًا.
  • hub_model_id (str، اختياري) — اسم المستودع الذي يجب إبقاؤه متزامنًا مع output_dir المحلي. يمكن أن يكون معرّف نموذج بسيط، وفي هذه الحالة سيتم دفع النموذج إلى نطاقك. وإلا، يجب أن يكون اسم المستودع الكامل، على سبيل المثال "user_name/model"، مما يتيح لك الدفع إلى منظمة أنت عضو فيها باستخدام "organization_name/model". سيكون الافتراضي user_name/output_dir_name حيث يكون output_dir_name هو اسم output_dir.
  • hub_strategy (str أو HubStrategy, اختياري, الافتراضي هو "every_save") — يحدد ما الذي يجب دفعه إلى Hub ومتى. الخيارات:
    • "end": الدفع فقط في نهاية التدريب
    • "every_save": الدفع عند كل حفظ (غير متزامن حتى لا يعيق التدريب)
    • "checkpoint": يشبه "every_save" مع إضافة دفع أحدث نقطة تفتيش إلى مجلد الفرع "last-checkpoint" لسهولة الاستئناف
    • "all_checkpoints": دفع جميع نقاط التفتيش كما تظهر
  • hub_always_push (bool، اختياري، القيمة الافتراضية False) — ما لم تكن هذه القيمة True، سيتخطى Trainer دفع نقطة التفتيش إذا لم يكتمل الدفع السابق.
  • hub_revision (str, اختياري) — الإصدار (revision) الذي سيتم استخدامه عند الدفع إلى Hub. يمكن أن يكون اسم فرع، أو وسم، أو تجزئة (hash) لالتزام.

أفضل تتبع للنماذج

  • load_best_model_at_end (bool، اختياري، القيمة الافتراضية False) — تحميل أفضل نقطة تحقق في نهاية التدريب. يتطلب ضبط eval_strategy. عند التفعيل، يتم دائمًا حفظ أفضل نقطة تحقق (انظر save_total_limit). عندما تكون القيمة `True`، يجب أن يتطابق `save_strategy` مع `eval_strategy` (ما لم تكن قيمة `save_strategy` هي `"best"`)، وإذا كان استخدام `"steps"`، فإن `save_steps` يجب أن يكون مضاعفًا لـ `eval_steps`.
  • metric_for_best_model (str, اختياري) — المقياس المستخدم لمقارنة النماذج عند load_best_model_at_end=True. يجب أن يكون اسم مقياس يعيده التقييم، مع أو بدون البادئة "eval_". القيمة الافتراضية هي "loss". إذا قمت بتعيين هذا، فستكون القيمة الافتراضية لـ greater_is_better هي True ما لم ينتهِ الاسم بـ "loss". أمثلة: "accuracy"، "f1"، "eval_bleu".
  • greater_is_better (bool, اختياري) — ما إذا كانت القيم الأعلى للمقياس أفضل. القيمة الافتراضية مبنية على metric_for_best_model: True إذا لم ينتهِ اسم المقياس بـ "loss"، وإلا False.

استئناف التدريب

  • ignore_data_skip (bool، اختياري، القيمة الافتراضية False) — عند استئناف التدريب، يتخطى هذا الخيار التقدّم السريع عبر مجموعة البيانات للوصول إلى الحالة السابقة. إذا كانت القيمة True، يبدأ التدريب من بداية مجموعة البيانات (استئناف أسرع لكن النتائج لن تتطابق مع التدريب المقطوع). إذا كانت القيمة False، يتخطى البيانات التي تم رؤيتها (استئناف أبطأ لكن استكمال دقيق).
  • restore_callback_states_from_checkpoint (bool، اختياري، القيمة الافتراضية False) — استعادة حالات الاستدعاءات (callbacks) من نقطة التفتيش عند الاستئناف. إذا كانت القيمة True، فسيتم تجاوز الاستدعاءات (callbacks) الممرّرة إلى Trainer إذا كانت موجودة في نقطة التفتيش.

قابلية التكرار

  • full_determinism (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، يتم استدعاء enable_full_determinism() بدلاً من set_seed() لضمان الحصول على نتائج قابلة للتكرار في التدريب الموزّع. ملاحظة مهمة: سيؤثر هذا سلباً على الأداء، لذا استخدمه فقط لأغراض تصحيح الأخطاء.
  • seed (int، اختياري، القيمة الافتراضية 42) — بذرة عشوائية سيتم ضبطها في بداية التدريب. لضمان قابلية إعادة الإنتاج عبر التشغيلات، استخدم دالة ~Trainer.model_init لإنشاء النموذج إذا كانت بعض معاميره مهيأة عشوائيًا.
  • data_seed (int, اختياري) — البذرة العشوائية المستخدمة مع عينات البيانات. إذا لم يتم ضبطها، فستستخدم مولدات الأرقام العشوائية لعينات البيانات نفس البذرة الخاصة بـ seed. يمكن استخدام هذا لضمان قابلية إعادة إنتاج عينات البيانات، بشكل مستقل عن بذرة النموذج.

إعدادات العتاد

  • use_cpu (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم استخدام وحدة المعالجة المركزية (CPU) أم لا. إذا تم ضبطها على False، فسيتم استخدام جهاز/واجهة الخلفية المتاحة من torch.

إعدادات Accelerate

  • accelerator_config (str, dict, أو AcceleratorConfig, اختياري) — إعدادات تكامل Accelerate الداخلي. يمكن أن تكون: مسار إلى ملف إعدادات بصيغة JSON: "accelerator_config.json" قاموس يحتوي على خيارات الإعدادات كائن من نوع AcceleratorConfig الخيارات الرئيسية: split_batches (bool، القيمة الافتراضية False): ما إذا كان سيتم تقسيم الدفعات عبر الأجهزة. إذا كانت True، فإن حجم الدفعة الفعلي يكون متساوياً على جميع الأجهزة (يجب أن يكون المجموع قابلاً للقسمة على num_processes). إذا كانت False، يحصل كل جهاز على حجم الدفعة المحدد. dispatch_batches (bool): إذا كانت True، يقوم العملية الرئيسية فقط بتكرار dataloader وإرسال الدفعات إلى الأجهزة. القيمة الافتراضية True لـ IterableDataset، وFalse في الحالات الأخرى. even_batches (bool، القيمة الافتراضية True): تكرار العينات من بداية مجموعة البيانات لضمان حصول جميع العمال على أحجام دفعات متساوية. use_seedable_sampler (bool، القيمة الافتراضية True): استخدام عينة عشوائية قابلة للتبذير بالكامل من أجل قابلية التكرار. use_configured_state (bool، القيمة الافتراضية False): استخدام AcceleratorState/PartialState مُهيّأ مسبقاً بدلاً من إنشاء واحد جديد. قد يسبب مشاكل في ضبط المعلمات الفائقة.
    • مسار ملف الإعدادات بصيغة JSON: "accelerator_config.json"
    • قاموس بخيارات الإعداد
    • مثال من AcceleratorConfig الخيارات الرئيسية:
    • split_batches (bool، القيمة الافتراضية False): ما إذا كان سيتم تقسيم الدفعات عبر الأجهزة. إذا كانت True، فإن حجم الدفعة الفعلي يكون متساوياً على جميع الأجهزة (يجب أن يكون المجموع قابلاً للقسمة على num_processes). إذا كانت False، يحصل كل جهاز على حجم الدفعة المحدد.
    • dispatch_batches (bool): إذا كانت القيمة True، فإن العملية الرئيسية فقط تتصفح dataloader وتوزّع الدفعات على الأجهزة. القيمة الافتراضية هي True في حالة IterableDataset، وFalse في الحالات الأخرى.
    • even_batches (bool، القيمة الافتراضية True): يُكرّر العينات من بداية مجموعة البيانات لضمان حصول جميع العمال على أحجام دفعات متساوية.
    • use_seedable_sampler (bool، القيمة الافتراضية True): استخدام مُعيّن عشوائي قابل للتبذير بالكامل من أجل قابلية التكرار.
    • use_configured_state (bool، القيمة الافتراضية False): استخدام حالة AcceleratorState/PartialState مُهيّأة مسبقًا بدلاً من إنشاء حالة جديدة. قد يسبب ذلك مشاكل في ضبط المعلمات الفائقة.
  • parallelism_config (ParallelismConfig، اختياري) — إعدادات التوازي لجلسة التدريب. يتطلب Accelerate 1.10.1

Dataloader

  • dataloader_drop_last (bool، اختياري، القيمة الافتراضية False) — هل يتم إسقاط الدفعة الأخيرة غير المكتملة (إذا لم يكن طول مجموعة البيانات قابلاً للقسمة على حجم الدفعة) أم لا.
  • dataloader_num_workers (int, اختياري، القيمة الافتراضية 0) — عدد العمليات الفرعية المستخدمة لتحميل البيانات (PyTorch فقط). القيمة 0 تعني أن البيانات ستُحمَّل في العملية الرئيسية.
  • dataloader_pin_memory (bool، اختياري، القيمة الافتراضية True) — هل تريد تثبيت الذاكرة في محمّلات البيانات أم لا. ستكون القيمة الافتراضية True.
  • dataloader_persistent_workers (bool، اختياري، القيمة الافتراضية False) — إذا كانت القيمة True، فلن يُغلق مُحمِّل البيانات عمليات العمال بعد استهلاك مجموعة البيانات مرة واحدة. هذا يسمح بإبقاء كائنات Dataset الخاصة بالعمال نشطة. قد يسرّع التدريب بشكل محتمل، لكنه سيزيد من استهلاك ذاكرة RAM. ستكون القيمة الافتراضية False.
  • dataloader_prefetch_factor (int, اختياري) — عدد الدفعات التي يتم تحميلها مسبقًا بواسطة كل عامل. قيمة 2 تعني أن إجمالي عدد الدفعات المحمّلة مسبقًا عبر جميع العمال سيكون 2 * num_workers.
  • dataloader_multiprocessing_context (str، اختياري) — طريقة بدء التشغيل متعددة العمليات المستخدمة لعمال تحميل البيانات ("fork" أو "spawn" أو "forkserver"). الافتراضي هو طريقة بدء التشغيل الافتراضية في PyTorch، باستثناء حالة MPS عندما يكون dataloader_num_workers > 1، حيث تكون القيمة الافتراضية "fork". استخدم "spawn" عند البث من مصادر لا تكون كائناتها آمنة للاستنساخ (مثل HDFS عبر pyarrow). عند استخدام "spawn"، يجب أن تكون أي دالة collate_fn مخصصة أو كود مجموعة بيانات قابلًا للاستيراد على مستوى الوحدة (بدون دوال lambda أو closures).
  • dataloader_in_order (bool، اختياري، القيمة الافتراضية True) — إذا كانت True، فإن مُحمِّل البيانات يُخرج الدفعات بالترتيب الذي تم فيه إرسال العمال. اضبطها على False لإخراج الدفعات فور جاهزيتها، مما قد يقلل من زمن التأخير النهائي لأحمال العمل التدفّقية الخاصة بـIterableDataset. يتطلب PyTorch >= 2.6.
  • remove_unused_columns (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم حذف الأعمدة التي لا يستخدمها دالة الأمامية للنموذج تلقائيًا أم لا.
  • label_names (list[str]، اختياري) — قائمة المفاتيح في قاموس المدخلات الخاص بك التي تتوافق مع التسميات. سيتم افتراضياً اعتماد قائمة أسماء المعاملات التي يقبلها النموذج والتي تحتوي على كلمة “label”، ما لم يكن النموذج المستخدم من نوع XxxForQuestionAnswering، وفي هذه الحالة ستشمل القائمة أيضاً مفاتيح ["start_positions", "end_positions"]. يجب عليك تحديد label_names فقط إذا كنت تستخدم أسماء تسميات مخصصة، أو إذا كان forward الخاص بنموذجك يستهلك عدة تينسورات للتسميات (على سبيل المثال، في الإجابة الاستخراجية على الأسئلة).
  • train_sampling_strategy (str, اختياري, الافتراضي هو "random") — المُعيّن (Sampler) المستخدم لـ DataLoader الخاص بالتدريب. القيم الممكنة هي:
    • "random": يستخدم RandomSampler (الافتراضي).
    • "sequential": يستخدم SequentialSampler.
    • "group_by_length": يستخدم LengthGroupedSampler لتجميع العينات ذات الطول المتقارب معًا (لتقليل الحشو وزيادة الكفاءة).
    • "batch_rebalance": يستخدم BatchRebalanceSampler لموازنة تكلفة الرموز المُكمّلة عبر الأجهزة وخطوات تراكم التدرّجات داخل كل دفعة فعّالة، مما يقلّل من هدر التكميم والذروة في الذاكرة مقارنةً بـ"group_by_length". حاليًا، يُدعم هذا الخيار فقط للتدريب بالتوازي على مستوى البيانات (فإن التوازي على مستوى المكوّنات غير مدعوم بعد).

    ملاحظة: عند استخدام IterableDataset، يتم تجاهل هذا الحُجّة.

  • length_column_name (str, اختياري، القيمة الافتراضية "length") — اسم العمود الخاص بالطول المحسوب مسبقاً. إذا كان العمود موجوداً، فسيستخدم التجميع حسب الطول هذه القيم بدلاً من حسابها عند بدء التدريب. يتم تجاهله ما لم يكن train_sampling_strategy هو "group_by_length" أو "batch_rebalance" وكان مجموعة البيانات مثلاً من Dataset.

DDP (DistributedDataParallel)

  • ddp_find_unused_parameters (bool، اختياري) — عند استخدام التدريب الموزّع، قيمة العلم find_unused_parameters المُمرّرة إلى DistributedDataParallel. ستكون القيمة الافتراضية False إذا تم استخدام نقطة التفتيش للتدرّجات، وإلا فستكون True.
  • ddp_bucket_cap_mb (int، اختياري) — عند استخدام التدريب الموزّع، قيمة العلم bucket_cap_mb المُمرَّر إلى DistributedDataParallel.
  • ddp_broadcast_buffers (bool، اختياري) — عند استخدام التدريب الموزّع، قيمة العلم broadcast_buffers المُمرّرة إلى DistributedDataParallel. ستكون القيمة الافتراضية False إذا تم استخدام نقطة التفتيش للتدرّجات، وإلا فستكون True.
  • ddp_static_graph (bool، اختياري) — عند استخدام التدريب الموزّع، قيمة العلم static_graph المُمرَّر إلى DistributedDataParallel.
  • ddp_backend (str, اختياري) — الواجهة الخلفية المستخدمة للتدريب الموزّع. يجب أن تكون واحدة من "nccl"، "mpi"، "xccl"، "gloo"، "hccl".
  • ddp_timeout (int، اختياري، القيمة الافتراضية 1800) — مهلة الاستجابة لاستدعاءات torch.distributed.init_process_group، وتُستخدم لتجنّب انتهاء مهلة اتصال وحدات معالجة الرسوميات (GPU) عند تنفيذ عمليات بطيئة في التشغيل الموزّع. يُرجى الرجوع إلى توثيق PyTorch لمزيد من المعلومات.

FSDP (التوازي الكامل للبيانات المجزأة)

  • fsdp (bool، اختياري، القيمة الافتراضية None) — تفعيل PyTorch Fully Sharded Data Parallel (FSDP) للتدريب الموزّع. مرّر True لتفعيل FSDP.
  • fsdp_config (str or dict, optional) — Configuration settings for when fsdp is enabled. Pass a path to a JSON config file, such as fsdp_config.json, or an already-loaded dict.

    المفاتيح المدعومة:

    • الإصدار (int، اختياري، الافتراضي 2): إصدار FSDP الذي سيتم استخدامه (2 لـ FSDP2، و1 لـ FSDP1 القديم).
    • reshard_after_forward (bool, اختياري، القيمة الافتراضية True): ما إذا كان يجب إعادة تجزئة المعاملات بعد عملية الانتقال الأمامي. اضبطها على False للحفاظ على تجميع المعاملات بين عمليتي الانتقال الأمامي والعكسي، مما يتجنب إعادة التجميع الشامل (re-all-gather)، ويستخدم ذاكرة ذروة أعلى.
    • cpu_offload (bool، اختياري، القيمة الافتراضية False): تحويل المعاملات والتدرجات إلى وحدة المعالجة المركزية (CPU) عند عدم استخدامها لتوفير ذاكرة وحدة معالجة الرسوميات (GPU).
    • activation_checkpointing (bool, اختياري، القيمة الافتراضية False): اضبطه على True لتقليل الذاكرة عن طريق إعادة حساب التفعيلات أثناء عملية الرجوع الخلفي. عند استخدام FSDP، يُفضَّل استخدام هذا بدلاً من معامل التدريب activation_checkpointing، الذي يُدخل عملية all-gather زائدة عن الحاجة في عملية الرجوع الخلفي.
    • cpu_ram_efficient_loading (bool, اختياري، القيمة الافتراضية False): اضبطه على True لتحميل نقطة الفحص المُدرَّبة مسبقًا على العملية الأولى فقط. تبدأ العمليات الأخرى بأوزان فارغة وتستقبل الأوزان عبر البث.
    • state_dict_type (str، اختياري، القيمة الافتراضية "FULL_STATE_DICT"): تنسيق نقطة التفتيش: "FULL_STATE_DICT" (ملف واحد متوافق مع HF) أو "SHARDED_STATE_DICT" (ملف واحد لكل rank، أسرع للنماذج الكبيرة).
    • auto_wrap_policy (str, اختياري، الافتراضي "TRANSFORMER_BASED_WRAP"): سياسة التغليف التلقائي المستخدمة. اختر "TRANSFORMER_BASED_WRAP" أو "SIZE_BASED_WRAP" أو "NO_WRAP".
    • transformer_layer_cls_to_wrap (list[str]، اختياري): أسماء فئات طبقات Transformer (حساسة لحالة الأحرف) التي يجب تغليفها، مثل LlamaDecoderLayer. عادةً ما يكون هذا غير ضروري: إذ يعتمد سياسة التغليف على _no_split_modules الخاص بالنموذج، والذي يغطي معظم نماذج transformers.
    • min_num_params (int, اختياري، القيمة الافتراضية 0): الحد الأدنى لعدد المعاملات في كل وحدة للتغليف التلقائي القائم على الحجم (يُستخدم مع auto_wrap_policy="SIZE_BASED_WRAP").
    • xla (bool، اختياري، القيمة الافتراضية False): ما إذا كان سيتم استخدام تدريب PyTorch/XLA بالتوازي الكامل لبيانات FSDP. تجريبي.
    • xla_fsdp_settings (dict, اختياري): قاموس بمعاملات تغليف XLA FSDP. للحصول على قائمة كاملة بالخيارات، راجع مصدر XLA FSDP.
    • xla_fsdp_grad_ckpt (bool، اختياري، القيمة الافتراضية False): اضبطه على True لاستخدام نقطة التفتيش التدرّجية على كل طبقة مغلّفة بـ XLA FSDP متداخلة. يتطلب xla=True وسياسة تغليف تلقائية (min_num_params أو transformer_layer_cls_to_wrap).

DeepSpeed

  • deepspeed (str أو dict, اختياري) — تفعيل DeepSpeed التكامل. القيمة إما:
    • مسار ملف إعدادات DeepSpeed بصيغة JSON: "ds_config.json"
    • تم تحميل الإعدادات كقاموس

      إذا كنت تستخدم تهيئة ZeRO، فقم بإنشاء نموذجك بعد تهيئة TrainingArguments، وإلا فلن يتم تطبيق ZeRO.

التصحيح والتحليل (تجريبي)

  • debug (str أو قائمة من DebugOption, اختياري, الافتراضي هو "") — تفعيل ميزة أو أكثر من ميزات التصحيح. هذه ميزة تجريبية. الخيارات الممكنة هي:
    • “underflow_overflow”: يكشف عن تجاوز الحدود في مدخلات/مخرجات النموذج ويبلّغ عن آخر الإطارات التي أدت إلى
    • “tpu_metrics_debug”: طباعة مقاييس التصحيح على TPU
  • skip_memory_metrics (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم تخطي إضافة تقارير ملفّس الذاكرة إلى المقاييس. يتم تخطي هذا الإعداد افتراضيًا لأنه يُبطئ سرعة التدريب والتقييم.

أعلام السكربت الخارجي (غير مستخدمة بواسطة Trainer)

  • do_train (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تشغيل التدريب أم لا. لا يستخدم هذا الحُجُج مباشرةً بواسطة Trainer، بل يُقصد استخدامه من قِبل سكربتات التدريب/التقييم الخاصة بك.
  • do_eval (bool, اختياري) — ما إذا كان سيتم تشغيل التقييم على مجموعة التحقق أم لا. سيُضبط على True إذا كان eval_strategy مختلفًا عن "no". لا يستخدم هذا الحجة مباشرةً بواسطة Trainer، بل يُقصد استخدامه في سكربتات التدريب/التقييم الخاصة بك.
  • do_predict (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تشغيل التنبؤات على مجموعة الاختبار أم لا. لا يستخدم هذا الحجة مباشرةً بواسطة Trainer، بل يُقصد استخدامه من قِبل سكربتات التدريب/التقييم الخاصة بك.
  • resume_from_checkpoint (str, اختياري) — مسار مجلد يحتوي على نقطة تفتيش صالحة لنموذجك. لا يستخدم هذا الحُجُج مباشرةً بواسطة Trainer، بل يُقصد استخدامه من قِبل سكربتات التدريب/التقييم الخاصة بك.

فئة التهيئة للتحكم في جميع جوانب تدريب النموذج باستخدام Trainer. تُوحّد TrainingArguments جميع المعاملات الفائقة وإعدادات التحسين وتفضيلات التسجيل وخيارات البنية التحتية اللازمة للتدريب.

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

get_process_log_level

< >

( )

يعيد مستوى التسجيل (log level) المستخدم اعتمادًا على ما إذا كانت هذه العملية هي العملية الرئيسية للعقدة 0، أو العملية الرئيسية لعقدة غير صفرية، أو عملية غير رئيسية.

تكون قيمة مستوى التسجيل للعملية الرئيسية افتراضياً هي مستوى التسجيل المُعيَّن (logging.WARNING إذا لم تقم بأي شيء) ما لم يتم تجاوزها بواسطة معامل log_level.

تكون قيمة مستوى التسجيل الافتراضية لعمليات النسخ logging.WARNING ما لم يتم تجاوزها بواسطة الحجة log_level_replica.

يتم اتخاذ القرار بين إعدادات العملية الرئيسية وإعدادات عملية النسخ بناءً على القيمة المُعادة من should_log.

get_warmup_steps

< >

( num_training_steps: int )

الحصول على عدد الخطوات المستخدمة للتسخين الخطي.

main_process_first

< >

( local = Truedesc = 'work' )

المعاملات

  • local (bool، اختياري، القيمة الافتراضية True) — إذا كانت True فإن "أول" تعني عملية الرتبة 0 لكل عقدة، وإذا كانت False فإن "أول" تعني عملية الرتبة 0 للعقدة الرتبة 0. في بيئة متعددة العقد مع نظام ملفات مشترك، من المرجح أن ترغب في استخدام local=False بحيث تقوم عملية العقدة الأولى الرئيسية فقط بالمعالجة. أما إذا لم يكن نظام الملفات مشتركاً، فستحتاج عملية كل عقدة رئيسية إلى القيام بالمعالجة، وهو السلوك الافتراضي.
  • desc (str، اختياري، القيمة الافتراضية "work") — وصف للعمل يُستخدم في سجلات التصحيح

مدير سياق لبيئة torch distributed حيث يحتاج المرء إلى تنفيذ شيء ما على العملية الرئيسية، مع حجب النسخ المكررة، وعند الانتهاء من ذلك يُطلق سراح النسخ المكررة.

من بين هذه الاستخدامات، ميزة map في datasets، والتي يجب تشغيلها مرة واحدة على العملية الرئيسية لتكون فعّالة، حيث تُحفظ نسخة مخبأة من النتائج عند اكتمالها، ثم تُحمَّل تلقائيًا بواسطة النسخ.

set_dataloader

< >

( train_batch_size: int = 8eval_batch_size: int = 8drop_last: bool = Falsenum_workers: int = 0pin_memory: bool = Truepersistent_workers: bool = Falseprefetch_factor: int | None = Nonemultiprocessing_context: str | None = Nonein_order: bool = Trueauto_find_batch_size: bool = Falseignore_data_skip: bool = Falsesampler_seed: int | None = None )

المعاملات

  • drop_last (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب حذف الدفعة الأخيرة غير المكتملة (إذا لم يكن طول مجموعة البيانات قابلاً للقسمة على حجم الدفعة) أم لا.
  • num_workers (int، اختياري، القيمة الافتراضية 0) — عدد العمليات الفرعية المستخدمة لتحميل البيانات (PyTorch فقط). القيمة 0 تعني أن البيانات ستُحمَّل في العملية الرئيسية.
  • pin_memory (bool، اختياري، القيمة الافتراضية True) — ما إذا كنت تريد تثبيت الذاكرة في محمّلات البيانات أم لا. ستكون القيمة الافتراضية True.
  • persistent_workers (bool, اختياري، القيمة الافتراضية False) — إذا كانت القيمة True، فلن يُغلق مُحمِّل البيانات عمليات العمال بعد استهلاك مجموعة البيانات مرة واحدة. وهذا يسمح بإبقاء كائنات Dataset الخاصة بالعمال نشطة. قد يسرّع التدريب بشكل محتمل، لكنه سيزيد من استهلاك ذاكرة RAM. ستكون القيمة الافتراضية False.
  • prefetch_factor (int، اختياري) — عدد الدفعات التي يتم تحميلها مسبقًا بواسطة كل عامل. قيمة 2 تعني أن إجمالي عدد الدفعات المحمّلة مسبقًا عبر جميع العمال سيكون 2 * num_workers.
  • multiprocessing_context (str, اختياري) — طريقة بدء تعدد العمليات المستخدمة لعمال تحميل البيانات ("fork" أو "spawn" أو "forkserver"). الافتراضي هو طريقة البدء الافتراضية في PyTorch. استخدم "spawn" عند البث من مصادر لا تكون كائناتها آمنة للاستنساخ (مثل HDFS عبر pyarrow). عند استخدام "spawn"، يجب أن يكون أي collate_fn مخصص أو كود مجموعة بيانات قابلاً للاستيراد على مستوى الوحدة (بدون دوال lambda أو closures).
  • in_order (bool، اختياري، القيمة الافتراضية True) — إذا كانت True، فإن مُحمِّل البيانات يُخرج الدفعات بالترتيب الذي تم فيه إرسال العمال. اضبطها على False لإخراج الدفعات فور جاهزيتها، مما قد يقلل من زمن التأخير النهائي لأحمال العمل التدفّقية الخاصة بـIterableDataset. يتطلب PyTorch >= 2.6.
  • auto_find_batch_size (bool، اختياري، القيمة الافتراضية False) — هل يتم تحديد حجم الدفعة الذي يتناسب مع الذاكرة تلقائيًا من خلال التلاشي الأسي، لتجنب أخطاء نفاد ذاكرة CUDA. يتطلب تثبيت accelerate (pip install accelerate)
  • ignore_data_skip (bool، اختياري، القيمة الافتراضية False) — عند استئناف التدريب، ما إذا كان سيتم تخطي الفترات والدفعات أم لا، لجعل تحميل البيانات في نفس المرحلة كما كانت في التدريب السابق. إذا تم ضبطه على True، فسيبدأ التدريب بشكل أسرع (لأن خطوة التخطي هذه قد تستغرق وقتاً طويلاً) لكن لن تعطي نفس النتائج التي كان من المفترض أن ينتجها التدريب المقطوع.
  • sampler_seed (int, اختياري) — البذرة العشوائية المستخدمة مع عينات البيانات. إذا لم يتم ضبطها، فستستخدم مولدات الأرقام العشوائية لعينة البيانات نفس البذرة الخاصة بـ self.seed. يمكن استخدام هذا لضمان قابلية إعادة إنتاج عينة البيانات، بشكل مستقل عن بذرة النموذج.

طريقة تجمع جميع الحُجج المرتبطة بإنشاء محمّلي البيانات.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_dataloader(train_batch_size=16, eval_batch_size=64)
>>> args.per_device_train_batch_size
16

set_evaluate

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'no'steps: int = 500batch_size: int = 8accumulation_steps: int | None = Nonedelay: float | None = Noneloss_only: bool = False )

المعاملات

  • strategy (str أو IntervalStrategy, اختياري, الافتراضي هو "no") — استراتيجية التقييم المعتمدة أثناء التدريب. القيم الممكنة هي:
    • "no": لا يتم إجراء أي تقييم أثناء التدريب.
    • "steps": يتم إجراء التقييم (وسُجّل) كل steps.
    • "epoch": يتم إجراء التقييم في نهاية كل حقبة.

    تعيين strategy مختلف عن "no" سيضبط self.do_eval على True.

  • steps (int، اختياري، القيمة الافتراضية 500) — عدد خطوات التحديث بين تقييمين إذا كان strategy="steps".
  • batch_size (int اختياري، القيمة الافتراضية 8) — حجم الدفعة لكل جهاز (GPU/TPU core/CPU…) المستخدم للتقييم.
  • accumulation_steps (int, اختياري) — عدد خطوات التنبؤ التي يتم فيها تجميع الموترات الناتجة قبل نقل النتائج إلى وحدة المعالجة المركزية. إذا لم يتم ضبطه، يتم تجميع التنبؤات بالكامل على وحدة معالجة الرسوميات/وحدة معالجة TPU قبل نقلها إلى وحدة المعالجة المركزية (أسرع لكن يتطلب ذاكرة أكبر).
  • delay (float, اختياري) — عدد الفترات أو الخطوات التي يجب الانتظار قبل إجراء أول تقييم، وذلك اعتمادًا على eval_strategy.
  • loss_only (bool، اختياري، القيمة الافتراضية False) — يتجاهل جميع المخرجات باستثناء الخسارة.

طريقة تجمع جميع الحُجج المرتبطة بالتقييم.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_evaluate(strategy="steps", steps=100)
>>> args.eval_steps
100

set_logging

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'steps'steps: int = 500report_to: str | list[str] = 'none'level: str = 'passive'first_step: bool = Falsenan_inf_filter: bool = Falseon_each_node: bool = Falsereplica_level: str = 'passive' )

المعاملات

  • strategy (str أو IntervalStrategy, اختياري, الافتراضي هو "steps") — استراتيجية التسجيل المعتمدة أثناء التدريب. القيم الممكنة هي:
    • "no": لا يتم تسجيل أي سجلات أثناء التدريب.
    • "epoch": يتم التسجيل في نهاية كل حقبة.
    • "steps": يتم التسجيل كل logging_steps.
  • steps (int، اختياري، القيمة الافتراضية 500) — عدد خطوات التحديث بين سجلّين إذا كان strategy="steps".
  • level (str، اختياري، القيمة الافتراضية "passive") — مستوى تسجيل السجلات (log level) المستخدم في العملية الرئيسية. الخيارات الممكنة هي مستويات التسجيل كنصوص: "debug"، "info"، "warning"، "error" و"critical"، بالإضافة إلى مستوى "passive" الذي لا يضبط أي شيء ويترك للتطبيق ضبط المستوى.
  • report_to (str أو list[str]، اختياري، القيمة الافتراضية "none") — قائمة التكاملات التي سيتم الإبلاغ عن النتائج والسجلات إليها. المنصات المدعومة هي "azure_ml"، "clearml"، "codecarbon"، "comet_ml"، "dagshub"، "dvclive"، "flyte"، "mlflow"، "swanlab"، "tensorboard"، "trackio" و"wandb". استخدم "all" للإبلاغ إلى جميع التكاملات المثبّتة، و"none" لعدم استخدام أي تكاملات.
  • first_step (bool، اختياري، الافتراضي False) — ما إذا كان سيتم تسجيل وتقييم الخطوة العالمية الأولى global_step أم لا.
  • nan_inf_filter (bool, اختياري, الافتراضي هو True) — ما إذا كان سيتم تصفية nan و inf في الخسائر الخاصة بالتسجيل. إذا تم ضبطه على True فإن خسارة كل خطوة تكون nan أو inf تُصفّى، ويُعتمد بدلاً منها متوسط الخسارة في نافذة التسجيل الحالية. لا يؤثر nan_inf_filter إلا على تسجيل قيم الخسارة، ولا يغيّر طريقة حساب التدرّج أو تطبيقه على النموذج.

    nan_inf_filter يؤثر فقط على تسجيل قيم الخسارة، ولا يغيّر طريقة حساب التدرّج أو تطبيقه على النموذج.

  • on_each_node (bool، اختياري، القيمة الافتراضية True) — في التدريب الموزّع متعدد العقد، ما إذا كان يجب تسجيل السجلات باستخدام log_level مرة واحدة لكل عقدة، أم على العقدة الرئيسية فقط.
  • replica_level (str، اختياري، القيمة الافتراضية "passive") — مستوى التسجيل (log level) المستخدم على النسخ. نفس الخيارات المتاحة لـ log_level

طريقة تجمع جميع الحُجج المرتبطة بالتسجيل.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_logging(strategy="steps", steps=100)
>>> args.logging_steps
100

set_lr_scheduler

< >

( name: str | transformers.trainer_utils.SchedulerType = 'linear'num_epochs: float = 3.0max_steps: int = -1warmup_steps: float = 0 )

المعاملات

  • name (str أو SchedulerType، اختياري، القيمة الافتراضية "linear") — نوع المجدول (scheduler) المراد استخدامه. راجع توثيق SchedulerType لمعرفة جميع القيم الممكنة.
  • num_epochs(float, اختياري، القيمة الافتراضية 3.0) — إجمالي عدد فترات التدريب (epochs) التي سيتم تنفيذها (إذا لم تكن قيمة صحيحة، فسيتم تنفيذ الجزء العشري كنسبة مئوية من الفترة الأخيرة قبل إيقاف التدريب).
  • max_steps (int, اختياري، القيمة الافتراضية -1) — إذا تم تعيينه إلى رقم موجب، فهو يمثل العدد الإجمالي لخطوات التدريب التي يجب تنفيذها. يتجاوز num_train_epochs. بالنسبة إلى مجموعة بيانات محدودة، يتم تكرار التدريب عبر مجموعة البيانات (إذا استُنفد كل البيانات) حتى يتم الوصول إلى max_steps. يجب تعيينه إلى قيمة موجبة عندما لا تنفّذ مجموعة بيانات التدريب __len__ (مثل مجموعة بيانات التدفق)، لأن العدد الإجمالي للخطوات لا يمكن استنتاجه في هذه الحالة، وهو مطلوب لتحديد حد حلقة التدريب وإعداد جدولة معدل التعلم.
  • warmup_steps (float، اختياري، القيمة الافتراضية 0) — عدد الخطوات المستخدمة للتسخين الخطي من 0 إلى learning_rate. يجب أن يكون عددًا صحيحًا أو عددًا عشريًا ضمن المدى [0,1). إذا كان أقل من 1، فسيُفسَّر كنسبة من الخطوات المستخدمة للتسخين الخطي من 0 إلى learning_rate.

طريقة تجمع جميع الحُجج المرتبطة بجدول جدولة معدل التعلم ومعاملاته الفائقة.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_lr_scheduler(name="cosine", warmup_steps=0.05)
>>> args.warmup_steps
0.05

set_optimizer

< >

( name: str | transformers.training_args.OptimizerNames = 'adamw_torch'learning_rate: float = 5e-05weight_decay: float = 0beta1: float = 0.9beta2: float = 0.999epsilon: float = 1e-08args: str | None = None )

المعاملات

  • name (str أو training_args.OptimizerNames، اختياري، القيمة الافتراضية "adamw_torch") — المُحسِّن (optimizer) المستخدم: "adamw_torch"، "adamw_torch_fused"، "adamw_anyprecision" أو "adafactor".
  • learning_rate (float، اختياري، القيمة الافتراضية 5e-5) — معدل التعلم الأولي.
  • weight_decay (float، اختياري، القيمة الافتراضية 0) — مقدار تآكل الوزن المطبَّق (إذا لم يكن صفراً) على جميع الطبقات باستثناء أوزان الانحياز وLayerNorm.
  • beta1 (float, اختياري، القيمة الافتراضية 0.9) — معامل الضبط beta1 لمُحسِّن adam أو أي من صيغه.
  • beta2 (float، اختياري، القيمة الافتراضية 0.999) — معامل الضبط beta2 لخوارزمية adam أو متغيراتها.
  • epsilon (float، اختياري، القيمة الافتراضية 1e-8) — معامل epsilon للمُحسِّن adam أو متغيراته.
  • args (str، اختياري) — حجج اختيارية تُمرَّر إلى AnyPrecisionAdamW (لا فائدة منها إلا عند optim="adamw_anyprecision").

طريقة تجمع جميع الحُجج المرتبطة بمُحسِّن التدريب (optimizer) ومعاملاته الفائقة.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_optimizer(name="adamw_torch", beta1=0.8)
>>> args.optim
'adamw_torch'

set_push_to_hub

< >

( model_id: strstrategy: str | transformers.trainer_utils.HubStrategy = 'every_save'token: str | None = Noneprivate_repo: bool | None = Nonealways_push: bool = Falserevision: str | None = None )

المعاملات

  • model_id (str) — اسم المستودع الذي يجب إبقاؤه متزامنًا مع output_dir المحلي. يمكن أن يكون معرّف نموذج بسيط، وفي هذه الحالة سيتم دفع النموذج إلى نطاقك. وإلا، فيجب أن يكون اسم المستودع الكامل، على سبيل المثال "user_name/model"، مما يتيح لك الدفع إلى منظمة أنت عضو فيها باستخدام "organization_name/model".
  • strategy (str أو HubStrategy, اختياري, الافتراضي هو "every_save") — يحدد نطاق ما يتم دفعه إلى Hub ومتى. القيم الممكنة هي:
    • "end": يقوم بدفع النموذج، وتكوينه، وفئة المعالجة (processing_class) مثل مُجزّئ الرموز (tokenizer) (إذا تم تمريرها إلى Trainer)، ومسودة بطاقة النموذج عند استدعاء طريقة save_model().
    • "every_save": يقوم بدفع النموذج، وتكوينه، وفئة المعالجة (مثل مُجزّئ الرموز، إذا تم تمريرها إلى Trainer)، ومسودة بطاقة النموذج، في كل مرة يتم فيها حفظ النموذج. تكون عمليات الدفع غير متزامنة حتى لا تعيق التدريب، وفي حال كانت عمليات الحفظ متكررة جداً، لا يُحاول الدفع الجديد إلا بعد اكتمال الدفع السابق. يتم تنفيذ دفع أخير بالنموذج النهائي في نهاية التدريب.
    • "checkpoint": يشبه "every_save" لكن يتم أيضًا دفع أحدث نقطة تفتيش في مجلد فرعي باسم last-checkpoint، مما يتيح لك استئناف التدريب بسهولة باستخدام trainer.train(resume_from_checkpoint="last-checkpoint").
    • "all_checkpoints": يشبه "checkpoint" لكن جميع نقاط التفتيش تُدفع كما تظهر في مجلد الإخراج (لذا ستحصل على مجلد نقطة تفتيش واحد لكل مجلد في مستودعك النهائي)
  • token (str، اختياري) — الرمز الذي يُستخدم لدفع النموذج إلى Hub. سيُستخدم افتراضيًا الرمز الموجود في مجلد الكاش الذي تم الحصول عليه عبر hf auth login.
  • private_repo (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب جعل المستودع خاصاً. إذا كانت القيمة None (الافتراضية)، فسيكون المستودع عاماً ما لم تكن القيمة الافتراضية للمنظمة هي الخاص. يتم تجاهل هذه القيمة إذا كان المستودع موجوداً مسبقاً.
  • always_push (bool، اختياري، القيمة الافتراضية False) — ما لم تكن هذه القيمة True، فسيُرجئ Trainer دفع نقطة التفتيش إذا لم تكتمل عملية الدفع السابقة.
  • revision (str, اختياري) — الإصدار (revision) الذي سيتم استخدامه عند الدفع إلى Hub. يمكن أن يكون اسم فرع، أو وسم (tag)، أو تجزئة (hash) لالتزام (commit).

طريقة تجمع جميع الحُجج المرتبطة بمزامنة نقاط التفتيش مع Hub.

عند استدعاء هذه الطريقة، سيُضبط self.push_to_hub على True، مما يعني أن output_dir سيبدأ بمجلد git متزامن مع المستودع (المحدد بواسطة model_id)، وسيتم دفع المحتوى في كل مرة يتم فيها تشغيل حفظ (بناءً على self.save_strategy). كما أن استدعاء save_model() سيُشغّل عملية الدفع أيضاً.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_push_to_hub("me/awesome-model")
>>> args.hub_model_id
'me/awesome-model'

set_save

< >

( strategy: str | transformers.trainer_utils.IntervalStrategy = 'steps'steps: int = 500total_limit: int | None = Noneon_each_node: bool = False )

المعاملات

  • strategy (str أو IntervalStrategy, اختياري, الافتراضي هو "steps") — استراتيجية حفظ نقاط التفتيش المعتمدة أثناء التدريب. القيم الممكنة هي:
    • "no": لا يتم حفظ أي شيء أثناء التدريب.
    • "epoch": يتم الحفظ في نهاية كل حقبة.
    • "steps": يتم الحفظ كل save_steps.
  • steps (int، اختياري، القيمة الافتراضية 500) — عدد خطوات التحديث قبل حفظ نقطتي تفتيش إذا كان strategy="steps".
  • total_limit (int، اختياري) — إذا تم تمرير قيمة، فسيتم تحديد إجمالي عدد نقاط التفتيش. يحذف نقاط التفتيش الأقدم في output_dir.
  • on_each_node (bool, اختياري, الافتراضي هو False) — عند تنفيذ التدريب الموزّع متعدد العقد، ما إذا كان يجب حفظ النماذج والنقاط المرجعية على كل عقدة، أم على العقدة الرئيسية فقط. لا ينبغي تفعيل هذا الخيار عندما تستخدم العقد المختلفة نفس التخزين، لأن الملفات ستُحفظ بنفس الأسماء على كل عقدة.

    يجب عدم تفعيل هذا الخيار عندما تستخدم العقد المختلفة نفس التخزين، لأن الملفات ستُحفظ بأسماء متطابقة لكل عقدة.

طريقة تجمع جميع الحُجج المرتبطة بحفظ نقاط التفتيش.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_save(strategy="steps", steps=100)
>>> args.save_steps
100

set_testing

< >

( batch_size: int = 8loss_only: bool = False )

المعاملات

  • batch_size (int اختياري، القيمة الافتراضية 8) — حجم الدفعة لكل جهاز (GPU/TPU core/CPU…) المستخدم للاختبار.
  • loss_only (bool، اختياري، القيمة الافتراضية False) — يتجاهل جميع المخرجات باستثناء الخسارة.

طريقة تجمع جميع الحجج الأساسية المرتبطة باختبار على مجموعة بيانات محجوزة.

ستؤدي استدعاء هذه الطريقة إلى تعيين self.do_predict تلقائيًا إلى True.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_testing(batch_size=32)
>>> args.per_device_eval_batch_size
32

set_training

< >

( learning_rate: float = 5e-05batch_size: int = 8weight_decay: float = 0num_epochs: float = 3max_steps: int = -1gradient_accumulation_steps: int = 1seed: int = 42activation_checkpointing: bool = Falsegradient_checkpointing: bool | None = None )

المعاملات

  • learning_rate (float، اختياري، القيمة الافتراضية 5e-5) — معدل التعلم الأولي لمُحسِّن التدريب.
  • batch_size (int اختياري، القيمة الافتراضية 8) — حجم الدفعة لكل جهاز (نواة GPU/TPU/CPU…) المستخدم للتدريب.
  • weight_decay (float, اختياري، القيمة الافتراضية 0) — مقدار تآكل الأوزان الذي يُطبَّق (إذا لم يكن صفراً) على جميع الطبقات باستثناء أوزان الانحياز وLayerNorm في المُحسِّن.
  • num_epochs (float، اختياري، القيمة الافتراضية 3.0) — إجمالي عدد فترات التدريب (epochs) التي سيتم تنفيذها (إذا لم تكن القيمة عددًا صحيحًا، فسيتم تنفيذ الجزء العشري كنسبة مئوية من الفترة الأخيرة قبل إيقاف التدريب).
  • max_steps (int, اختياري، القيمة الافتراضية -1) — إذا تم تعيينه إلى رقم موجب، فهو يمثل العدد الإجمالي لخطوات التدريب التي يجب تنفيذها. يتجاوز num_train_epochs. بالنسبة إلى مجموعة بيانات محدودة، يتم تكرار التدريب عبر مجموعة البيانات (إذا استُنفد كل البيانات) حتى يتم الوصول إلى max_steps. يجب تعيينه إلى قيمة موجبة عندما لا تنفّذ مجموعة بيانات التدريب __len__ (مثل مجموعة بيانات التدفق)، لأن العدد الإجمالي للخطوات لا يمكن استنتاجه في هذه الحالة، وهو مطلوب لتحديد حد حلقة التدريب وإعداد جدولة معدل التعلم.
  • gradient_accumulation_steps (int, اختياري, الافتراضي 1) — عدد خطوات التحديث لتجميع التدرجات قبل تنفيذ مسار الرجوع/التحديث.

    عند استخدام تراكم التدرجات، يُحتسب كل خطوة كخطوة واحدة تتضمن المرور العكسي. لذلك، ستُجرى عمليات التسجيل والتقييم والحفظ كل gradient_accumulation_steps * xxx_step من أمثلة التدريب.

  • seed (int، اختياري، القيمة الافتراضية 42) — بذرة عشوائية سيتم ضبطها في بداية التدريب. لضمان قابلية إعادة الإنتاج عبر التشغيلات، استخدم الدالة ~Trainer.model_init لإنشاء النموذج إذا كانت بعض معاميره مهيأة عشوائيًا.
  • activation_checkpointing (bool، اختياري، القيمة الافتراضية False) — إذا كانت القيمة True، فسيتم استخدام فحص التفعيل (activation checkpointing) لتوفير الذاكرة على حساب إبطاء عملية الرجوع الخلفي (backward pass).
  • gradient_checkpointing (bool، اختياري) — اسم مستعار غير مستخدم لـ activation_checkpointing، وسيتم إزالته في الإصدار v6.

طريقة تجمع جميع الحجج الأساسية المرتبطة بالتدريب.

ستؤدي استدعاء هذه الطريقة إلى تعيين self.do_train تلقائيًا إلى True.

مثال:

>>> from transformers import TrainingArguments

>>> args = TrainingArguments("working_dir")
>>> args = args.set_training(learning_rate=1e-4, batch_size=32)
>>> args.learning_rate
1e-4

to_dict

< >

( )

يسلسل هذه النسخة مع استبدال Enum بقيمها (لدعم التسلسل بصيغة JSON). كما يُعمّي على قيم الرموز عن طريق إزالة قيمها.

to_json_string

< >

( )

يسلسل هذه النسخة إلى نص JSON.

to_sanitized_dict

< >

( )

التسلسل المُطهَّر للاستخدام مع hparams في TensorBoard

Seq2SeqTrainingArguments

فئة transformers.Seq2SeqTrainingArguments

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 5e-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 = Falsefp16: 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 | None = Nonegradient_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 = 500logging_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 = <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: typing.Any | 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 = -1sortish_sampler: bool = Falsepredict_with_generate: bool = Falsegeneration_max_length: int | None = Nonegeneration_num_beams: int | None = Nonegeneration_config: str | pathlib.Path | transformers.generation.configuration_utils.GenerationConfig | None = None )

المعاملات

  • output_dir (str، اختياري، القيمة الافتراضية "trainer_output") — مجلد الإخراج الذي سيتم فيه كتابة تنبؤات النموذج ونقاط التفتيش.

مدة التدريب وحجم الدفعة

  • per_device_train_batch_size (int، اختياري، القيمة الافتراضية 8) — حجم الدفعة لكل جهاز. يُحسب حجم الدفعة الكلي على النحو التالي: per_device_train_batch_size * number_of_devices في إعدادات متعددة GPUs أو موزعة.
  • num_train_epochs(float, اختياري، القيمة الافتراضية 3.0) — إجمالي عدد فترات التدريب (epochs) التي يجب تنفيذها (إذا لم تكن قيمة صحيحة، فسيتم تنفيذ الجزء العشري كنسبة مئوية من الفترة الأخيرة قبل إيقاف التدريب).
  • max_steps (int، اختياري، القيمة الافتراضية -1) — يتجاوز num_train_epochs. إذا تم ضبطه على رقم موجب، فهو يمثل العدد الإجمالي لخطوات التدريب التي يجب تنفيذها. بالنسبة إلى مجموعة بيانات محدودة، يتم تكرار التدريب عبر مجموعة البيانات (إذا استُنفد كل البيانات) حتى يتم الوصول إلى max_steps. يجب ضبطه على قيمة موجبة عندما لا تنفّذ مجموعة بيانات التدريب __len__ (مثل مجموعة بيانات البث)، لأن العدد الإجمالي للخطوات لا يمكن استنتاجه في هذه الحالة، وهو مطلوب لتحديد حد حلقة التدريب وإعداد مجدول معدل التعلم.

معدل التعلم والمجدول

  • learning_rate (float، اختياري، القيمة الافتراضية 5e-5) — معدل التعلم الأولي لمُحسِّن التدريب. عادةً ما يكون هذا هو معدل التعلم الأقصى عند استخدام مُجدوِل مع فترة إحماء.
  • lr_scheduler_type (str أو SchedulerType, اختياري, الافتراضي هو "linear") — نوع جدولة معدل التعلم المستخدم. راجع SchedulerType لمعرفة جميع القيم الممكنة. الخيارات الشائعة:
  • lr_scheduler_kwargs (dict أو str، اختياري، القيمة الافتراضية None) — الحجج الإضافية الخاصة بـ lr_scheduler. راجع توثيق كل مُجدول لمعرفة القيم الممكنة.
  • warmup_steps (int أو float, اختياري, الافتراضي 0) — عدد الخطوات لدفء خطي من 0 إلى learning_rate. يساعد الدفء في استقرار التدريب في المرحلة الأولية. يمكن أن يكون:
    • عدد صحيح: عدد خطوات الإحماء الدقيق
    • عدد عشري ضمن المدى [0, 1): يُفسَّر كنسبة من إجمالي خطوات التدريب

المُحسِّن

  • optim (str أو training_args.OptimizerNames, اختياري, الافتراضي هو "adamw_torch" (لـ torch>=2.8 "adamw_torch_fused")) — المُحسِّن (Optimizer) المستخدم. الخيارات الشائعة:
    • "adamw_torch": AdamW في PyTorch (الافتراضي الموصى به)
    • "adamw_torch_fused": نواة AdamW المدمجة
    • "adamw_hf": تنفيذ AdamW من HuggingFace
    • "sgd": هبوط التدرج العشوائي مع الزخم
    • "adafactor": مُحسِّن فعّال من حيث الذاكرة للنماذج الكبيرة
    • "adamw_8bit": AdamW بدقة 8 بت (يتطلب bitsandbytes) راجع OptimizerNames للحصول على القائمة الكاملة.
  • optim_args (str, اختياري) — حجج اختيارية تُمرَّر إلى المُحسِّنات مثل AnyPrecisionAdamW وAdEMAMix وGaLore.
  • weight_decay (float، اختياري، القيمة الافتراضية 0) — معامل اضمحلال الوزن الذي يطبّقه المُحسِّن (وليس دالة الخسارة). يضيف تنظيم L2 لمنع الإفراط في التخصيص من خلال معاقبة الأوزان الكبيرة. يُستثنى تلقائيًا من معاملات الانحياز وLayerNorm. القيم النموذجية: 0.01 (قياسي)، 0.1 (تنظيم أقوى)، 0.0 (بدون تنظيم).
  • adam_beta1 (float, اختياري، القيمة الافتراضية 0.9) — معدل الاضمحلال الأسي لتقديرات اللحظة الأولى (الزخم) في المُحسِّنات القائمة على Adam. يتحكم في مقدار سجل التدرجات الذي يجب الاحتفاظ به.
  • adam_beta2 (float, اختياري، القيمة الافتراضية 0.999) — معدل الاضمحلال الأسي لتقديرات العزوم الثانية (التباين) في المُحسِّنات القائمة على Adam. يتحكم في تحجيم معدل التعلم التكيفي.
  • adam_epsilon (float, اختياري، القيمة الافتراضية 1e-8) — قيمة إيبسلون للاستقرار العددي في المُحسِّنات القائمة على Adam. تمنع القسمة على الصفر في مقام قاعدة التحديث.
  • optim_target_modules (Union[str, list[str]]، اختياري) — وحدات الهدف التي سيتم تحسينها، أي أسماء الوحدات التي ترغب في تدريبها. يُستخدم حاليًا لخوارزمية GaLore وخوارزمية APOLLO. راجع تنفيذ GaLore وتنفيذ APOLLO لمزيد من التفاصيل. يجب التأكد من تمرير مُحسِّن GaLore أو APOLLO صالح، مثل أحد ما يلي: “apollo_adamw” و“galore_adamw” و“galore_adamw_8bit” و“galore_adafactor”، والتأكد من أن وحدات الهدف هي وحدات nn.Linear فقط.

التنظيم واستقرار التدريب

  • gradient_accumulation_steps (int, اختياري, الافتراضي 1) — عدد خطوات التحديث لتجميع التدرجات قبل تنفيذ مسار التراجع/التحديث. يحاكي أحجام دفعات أكبر دون استهلاك ذاكرة إضافية. حجم الدفعة الفعّال = per_device_train_batch_size × num_devices × gradient_accumulation_steps.

    عند استخدام تراكم التدرجات، يُحتسب "خطوة" واحدة على أنها خطوة واحدة تتضمن مسارًا عكسيًا. لذلك، ستتم عمليات التسجيل والتقييم والحفظ كل gradient_accumulation_steps × xxx_step من أمثلة التدريب.

  • average_tokens_across_devices (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم أخذ متوسط الرموز عبر الأجهزة أم لا. إذا تم التفعيل، فسيتم استخدام all_reduce لمزامنة num_tokens_in_batch لحساب الدقة بدقة. المرجع: https://github.com/huggingface/transformers/issues/34242
  • max_grad_norm (float, اختياري، القيمة الافتراضية 1.0) — الحد الأقصى لطول التدرّج (Norm) لقصّ التدرّجات. يُطبَّق بعد مرور التدرّج العكسي وقبل خطوة المُحسِّن. يمنع انفجار التدرّجات عن طريق تصغير التدرّجات عندما يتجاوز طولها الكلي هذا العتبة. اضبطه على 0 لتعطيل القصّ. القيم النموذجية: 1.0 (قياسي)، 0.5 (أكثر تحفظاً)، 5.0 (أقل عدوانية).
  • label_smoothing_factor (float, اختياري، القيمة الافتراضية 0.0) — معامل تنعيم التسميات لمنع الثقة المفرطة. يستبدل الأهداف الصلبة 0/1 بأهداف ناعمة: يصبح 0 هو ε/num_labels ويصبح 1 هو 1 - ε + ε/num_labels، حيث ε = label_smoothing_factor. تعني القيمة صفرًا عدم وجود تنعيم. النطاق النموذجي: من 0.0 إلى 0.1.

التدريب بالدقة المختلطة

  • bf16 (bool، اختياري، القيمة الافتراضية False) — تفعيل تدريب الدقة المختلطة bfloat16 (BF16) يُفضَّل عمومًا على FP16 نظرًا لاستقراره العددي الأفضل وعدم الحاجة إلى تحجيم الفقد.
  • fp16 (bool، اختياري، القيمة الافتراضية False) — تفعيل التدريب بدقة مختلطة float16 (FP16). يُفضَّل استخدام BF16 بدلاً من ذلك إذا كان جهازك يدعمه.
  • bf16_full_eval (bool، اختياري، القيمة الافتراضية False) — استخدام دقة BF16 الكاملة للتقييم (وليس الدقة المختلطة فقط). أسرع ويوفر الذاكرة، لكنه قد يؤثر قليلاً على قيم المقاييس. ينطبق فقط أثناء التقييم.
  • fp16_full_eval (bool، اختياري، القيمة الافتراضية False) — استخدام دقة FP16 الكاملة للتقييم (وليس مجرد دقة مختلطة). أسرع ويوفر الذاكرة، لكنه قد يؤثر قليلاً على قيم المقاييس. ينطبق فقط أثناء التقييم.
  • tf32 (bool، اختياري) — تفعيل وضع TensorFloat-32 (TF32) على وحدات معالجة الرسوميات من نوع Ampere والأحدث. يستخدم TF32 دقة بمقدار 19 بت للضرب المصفوفي (بدلاً من 23 بت في FP32)، مما يوفر تسريعًا يصل إلى 8 أضعاف مع فقدان دقة ضئيل. تعتمد القيمة الافتراضية على إصدار PyTorch. راجع وثائق TF32.

التحقق من التفعيل

  • activation_checkpointing (bool, اختياري، القيمة الافتراضية False) — تفعيل فحص التفعيل لتبادل الحساب مع الذاكرة. يقلل من استهلاك الذاكرة عن طريق مسح التفعيلات أثناء المرور الأمامي وإعادة حسابها أثناء المرور الخلفي. يتيح تدريب نماذج أكبر أو أحجام دفعات أكبر مقابل تكلفة تدريب أبطأ بنسبة ~20%.
  • activation_checkpointing_kwargs (dict، اختياري، القيمة الافتراضية None) — حجج الكلمات المفتاحية التي تُمرَّر إلى activation_checkpointing_enable(). every_n_layers يُنشئ نقاط فحص (checkpoints) لكل طبقة مُفكِّكة (decoder) رقمها مضاعف لـ n بدلاً من جميع الطبقات؛ 1 هو السلوك المعتاد الشامل أو الباطل، والقيم الأكبر تُعيد بعض الذاكرة إلى السرعة. offload يحتفظ بالتفعيلات المحفوظة في ذاكرة مضيف مثبّتة (pinned host memory)، مما يُحرر layers x sequence x hidden بايت من ذاكرة الجهاز ويجعل الخطوة أبطأ. أي مفتاح آخر يُمرَّر إلى torch.utils.checkpoint.checkpoint.
  • gradient_checkpointing (bool، اختياري) — اسم مستعار غير مستخدم لـ activation_checkpointing، وسيتم إزالته في الإصدار v6.
  • gradient_checkpointing_kwargs (dict، اختياري) — اسم مستعار غير مستحسن لـ activation_checkpointing_kwargs، وسيتم إزالته في الإصدار v6.

التجميع

  • torch_compile (bool، اختياري، القيمة الافتراضية False) — تجميع النموذج باستخدام torch.compile() في PyTorch 2.0 لتسريع التدريب. يمكن أن يوفر تسريعًا بنسبة 20-50% دون أي تغييرات في الكود. يستخدم إعدادات التجميع الافتراضية ما لم يتم تحديد torch_compile_backend أو torch_compile_mode.
  • torch_compile_backend (str، اختياري) — الخلفية (Backend) الخاصة بـ torch.compile(). إذا تم ضبطه، يتم تفعيل torch_compile تلقائيًا. تشمل الخيارات "inductor" (الافتراضي)، "aot_eager"، "cudagraphs". تختلف الخلفيات حسب إصدار PyTorch - راجع توثيق PyTorch لمعرفة الخيارات المتاحة.
  • torch_compile_mode (str, اختياري) — وضع التجميع لـ torch.compile(). إذا تم ضبطه، يتم تفعيل torch_compile تلقائيًا. الخيارات: "default"، "reduce-overhead" (لتقليل الحمل الإضافي على Python)، "max-autotune" (تحسين عدواني، مع وقت تجميع أطول).

النوى

  • use_liger_kernel (bool، اختياري، القيمة الافتراضية False) — تفعيل تحسينات Liger Kernel. يزيد من الإنتاجية عبر وحدات معالجة الرسومات المتعددة بنسبة ~20% ويقلل من استهلاك الذاكرة بنسبة ~60%. يعمل مع Flash Attention وFSDP وDeepSpeed. يدعم حاليًا نماذج Llama وMistral وMixtral وGemma.
  • liger_kernel_config (Optional[dict], اختياري) — إعدادات Liger Kernel. تُمرَّر كـ kwargs إلى _apply_liger_kernel_to_instance(). تشمل الخيارات عادةً: "rope"، "swiglu"، "cross_entropy"، "fused_linear_cross_entropy"، "rms_norm". إذا كانت None، يتم استخدام الإعدادات الافتراضية.

تحسينات إضافية

  • use_cache (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تفعيل ذاكرة التخزين المؤقت للنموذج أم لا. في حالة التدريب، عادةً ما لا تكون هذه الخاصية مطلوبة باستثناء بعض طرق PEFT التي تستخدم past_key_values.
  • neftune_noise_alpha (Optional[float]) — إذا لم تكن None، فسيتم تفعيل تضمينات ضوضاء NEFTune. يمكن أن يحسّن هذا أداء النموذج بشكل كبير في الضبط الدقيق التعليمي. اطّلع على الورقة الأصلية و الكود الأصلي. يدعم PreTrainedModel من transformers وكذلك PeftModel من peft. استخدمت الورقة الأصلية قيمًا في النطاق [5.0, 15.0].
  • torch_empty_cache_steps (int, اختياري) — عدد الخطوات التي يجب انتظارها قبل استدعاء torch.<device>.empty_cache(). إذا تُرك غير مضبوط أو تم ضبطه على None، فلن يتم تفريغ ذاكرة التخزين المؤقت. يمكن أن يساعد ذلك في تجنب أخطاء نفاد ذاكرة CUDA عن طريق خفض ذروة استخدام ذاكرة VRAM، مقابل تكلفة تقارب 10% من الأداء الأبطأ.
  • auto_find_batch_size (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تحديد حجم دفعة التدريب الذي يتناسب مع الذاكرة تلقائيًا من خلال التلاشي الأسي، لتجنب أخطاء نفاد ذاكرة CUDA. لا يتم تعديل حجم دفعة التقييم.

تسجيل ومراقبة التدريب

  • logging_strategy (str أو IntervalStrategy, اختياري, الافتراضي هو "steps") — استراتيجية التسجيل المعتمدة أثناء التدريب. القيم الممكنة هي:
    • "no": لا يتم تسجيل أي سجلات أثناء التدريب.
    • "epoch": يتم التسجيل في نهاية كل حقبة.
    • "steps": يتم التسجيل كل logging_steps.
  • logging_steps (int أو float، اختياري، القيمة الافتراضية 500) — عدد خطوات التحديث بين سجلّين إذا كان logging_strategy="steps". يجب أن يكون عددًا صحيحًا أو عددًا عشريًا ضمن النطاق [0,1). إذا كان أقل من 1، فسيُفسَّر كنسبة من إجمالي خطوات التدريب.
  • logging_first_step (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تسجيل الخطوة الأولى global_step أم لا.
  • log_on_each_node (bool، اختياري، القيمة الافتراضية True) — في التدريب الموزّع متعدد العقد، ما إذا كان سيتم التسجيل باستخدام log_level مرة واحدة لكل عقدة، أم على العقدة الرئيسية فقط.
  • logging_nan_inf_filter (bool، اختياري، القيمة الافتراضية True) — تصفية قيم NaN و Inf في الخسائر عند التسجيل. إذا كانت True، يتم استبدال خسائر التدريب التي تكون NaN/Inf بمتوسط الخسائر الصالحة الأخيرة، ويُستثنى الدُفعات التي تحتوي على NaN/Inf (مثل الدُفعات التي لا تحتوي على رموز تسميات) من حساب خسارة التقييم. لا يؤثر ذلك على حساب التدرجات، بل على التسجيل فقط.
  • include_num_input_tokens_seen (Optional[Union[str, bool]]، اختياري، القيمة الافتراضية “no”) — ما إذا كان سيتم تتبع عدد رموز الإدخال التي تم رؤيتها. يجب أن تكون واحدة من [“all”, “non_padding”, “no”] أو قيمة منطقية تُخضع إلى “all” أو “no”. قد يكون أبطأ في التدريب الموزّع لأن عمليات الجمع (gather) يجب أن تُستدعى.

التسجيل

  • log_level (str، اختياري، القيمة الافتراضية passive) — مستوى التسجيل للعملية الرئيسية. الخيارات: "debug"، "info"، "warning"، "error"، "critical"، أو "passive" (لا يغيّر مستوى تسجيل Transformers الحالي، والذي تكون قيمته الافتراضية "warning")
  • log_level_replica (str، اختياري، القيمة الافتراضية "warning") — مستوى التسجيل لعمليات النسخ في التدريب الموزّع. نفس الخيارات المتاحة في log_level.
  • disable_tqdm (bool, اختياري) — تعطيل أشرطة تقدم tqdm. القيمة الافتراضية هي True إذا كان log_level على مستوى warning أو أدنى، وإلا فهي False.

تكامل تتبع التجارب

  • report_to (str أو list[str]، اختياري، القيمة الافتراضية "none") — قائمة التكاملات التي سيتم الإبلاغ عن النتائج والسجلات إليها. المنصات المدعومة هي "azure_ml"، "clearml"، "codecarbon"، "comet_ml"، "dagshub"، "dvclive"، "flyte"، "mlflow"، "swanlab"، "tensorboard"، "trackio" و"wandb". استخدم "all" للإبلاغ إلى جميع التكاملات المثبتة، و"none" لعدم استخدام أي تكاملات.
  • run_name (str, اختياري) — وصف للتشغيل. يُستخدم عادةً لتسجيل trackio، wandb، mlflow، comet و swanlab.
  • project (str، اختياري، القيمة الافتراضية "huggingface") — اسم المشروع المستخدم للتسجيل. حاليًا، يُستخدم فقط بواسطة Trackio.
  • trackio_space_id (str أو None، اختياري، القيمة الافتراضية None) — معرف مساحة Hugging Face التي تُستخدم للتسجيل المباشر عبر Trackio باستخدام مساحة مبنية على Gradio. يجب أن يكون اسمًا كاملًا للمساحة على غرار 'username/reponame' أو 'orgname/reponame'، أو مجرد 'reponame' (تُنشأ المساحة في نطاق المستخدم المسجّل حاليًا). إذا كانت القيمة None، تُسجَّل المقاييس في مجلد محلي فقط (بدون مساحة على Hub). تتمتع مساحة Gradio تلك بصلاحية القراءة والكتابة إلى Bucket الخاص بـ Trackio، وهو ما تريده أثناء استمرار التدريب—على سبيل المثال عند استئناف تشغيل جزئي أو تجميع السجلات من عدة أجهزة. ستكون المساحة عامة ما لم تضبط hub_private_repo=True أو كان الافتراضي في مؤسستك هو إنشاء مساحات خاصة.
  • trackio_bucket_id (str أو None، اختياري، القيمة الافتراضية None) — معرف Bucket اختياري على Hugging Face خاص بـ Trackio. إذا لم يُضبط، فسيُشتقّ Trackio معرّفًا تلقائيًا. يُستخدم مع مساحة Gradio (trackio_space_id) وعند نشر مساحة ثابتة (عندما لا تكون trackio_static_space_id قيمة False).
  • trackio_static_space_id (str أو False أو None، اختياري، القيمة الافتراضية هي None) — معرف مساحة Hugging Face الذي سيتم استخدامه للمساحة الثابتة التي تُنشأ بعد اكتمال التدريب. يجب أن يكون اسمًا كاملاً للمساحة على غرار 'username/reponame' أو 'orgname/reponame'، أو مجرد 'reponame' (تُنشأ المساحة في مساحة المستخدم المسجّل حاليًا). إذا كانت القيمة False، فلن يتم إنشاء مساحة ثابتة. إذا كانت القيمة None، وتم دفع النموذج إلى Hub، فسيتم إنشاء مساحة ثابتة باسم افتراضي وسيتم ربطها من بطاقة النموذج. ستكون المساحة عامة ما لم تضبط hub_private_repo=True أو كان الإعداد الافتراضي لمنظمتك هو إنشاء مساحات خاصة.

التقييم

  • eval_strategy (str أو IntervalStrategy, اختياري, الافتراضي هو "no") — متى يتم تشغيل التقييم. الخيارات:
    • "no": لا يتم إجراء أي تقييم أثناء التدريب
    • "steps": التقييم كل eval_steps
    • "epoch": التقييم في نهاية كل حقبة
  • eval_steps (int أو float، اختياري) — عدد خطوات التحديث بين تقييمين إذا كان eval_strategy="steps". إذا لم يتم ضبطه، فسيُستخدم نفس القيمة الخاصة بـ logging_steps افتراضيًا. يجب أن يكون عددًا صحيحًا أو عددًا عشريًا ضمن المدى [0,1). إذا كان أقل من 1، سيُفسَّر كنسبة من إجمالي خطوات التدريب.
  • eval_delay (float, اختياري) — عدد الفترات أو الخطوات التي يجب انتظارها قبل إجراء أول تقييم، وذلك اعتمادًا على eval_strategy.
  • per_device_eval_batch_size (int، اختياري، القيمة الافتراضية 8) — حجم الدفعة لكل نواة تسريع/وحدة معالجة مركزية على الجهاز للتقييم.
  • prediction_loss_only (bool، اختياري، القيمة الافتراضية False) — عند إجراء التقييم وتوليد التنبؤات، يُرجع الخسارة فقط.
  • eval_on_start (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب تنفيذ خطوة تقييم (فحص صحة) قبل التدريب للتأكد من أن خطوات التحقق تعمل بشكل صحيح.
  • eval_do_concat_batches (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب دمج المدخلات/الخسائر/التسميات/التنبؤات بشكل تكراري عبر الدفعات. إذا كانت القيمة False، فسيتم تخزينها بدلاً من ذلك كقوائم، مع إبقاء كل دفعة منفصلة.
  • eval_use_gather_object (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب تشغيل تجميع الكائنات بشكل تكراري من جميع الأجهزة ضمن قائمة/مجموعة/قاموس متداخل من الكائنات. يجب تفعيل هذا الخيار فقط إذا لم يكن المستخدمون يعيدون مجرد متجهات (tensors)، كما أن PyTorch يوصي صراحةً بعدم تفعيله. يكون هذا الخيار مفيداً عندما تكون بنية التسميات غير قياسية، كما هو الحال في مهام الرؤية الحاسوبية.
  • eval_accumulation_steps (int، اختياري) — عدد خطوات التنبؤ التي يتم فيها تجميع تensors المخرجات، قبل نقل النتائج إلى وحدة المعالجة المركزية (CPU). إذا لم يتم ضبطه، فسيتم تجميع التنبؤات بالكامل على مُسرِّع الجهاز قبل نقلها إلى وحدة المعالجة المركزية (CPU) (أسرع لكن يتطلب ذاكرة أكبر).

حساب المقاييس

  • include_for_metrics (list[str], اختياري, الافتراضي هو []) — تضمين بيانات إضافية في دالة compute_metrics إذا كانت مطلوبة لحساب المقاييس. الخيارات الممكنة للإضافة إلى قائمة include_for_metrics :
    • "inputs": بيانات الإدخال المُمرَّرة إلى النموذج، والمُعدّة لحساب المقاييس المعتمدة على الإدخال.
    • "loss": قيم الخسارة المحسوبة أثناء التقييم، والمخصصة لحساب المقاييس المعتمدة على الخسارة.
  • batch_eval_metrics (bool، اختياري، القيمة الافتراضية False) — إذا تم ضبطه على True، فستقوم عملية التقييم باستدعاء compute_metrics في نهاية كل دفعة لتراكم الإحصاءات بدلاً من حفظ جميع قيم التقييم (logits) في الذاكرة. عند ضبطه على True، يجب عليك تمرير دالة compute_metrics تقبل حجة منطقية compute_result، والتي عند تمرير True إليها، ستُطلق الإحصاءات الإجمالية النهائية من الإحصاءات الإجمالية على مستوى الدفعة التي تراكمها على مجموعة التقييم.

التحقق من النقاط الحرجة والحفظ

  • save_only_model (bool، اختياري، القيمة الافتراضية False) — احفظ أوزان النموذج فقط، دون حالة المُحسِّن/المُجدوِل/حالة المولّد العشوائي. يقلّل هذا بشكل كبير من حجم نقطة التفتيش، لكنه يمنع استئناف التدريب من نقطة التفتيش. استخدمه عندما تحتاج إلى النموذج المدرَّب للاستدلال فقط، وليس للتدريب المستمر. لا يمكنك تحميل النموذج باستخدام from_pretrained إلا إذا كانت هذه الخانة مضبوطة على True.
  • save_strategy (str أو SaveStrategy, اختياري, الافتراضي هو "steps") — استراتيجية حفظ نقاط التفتيش المعتمدة أثناء التدريب. القيم الممكنة هي:
    • "no": لا يتم حفظ أي شيء أثناء التدريب.
    • "epoch": يتم الحفظ في نهاية كل حقبة.
    • "steps": يتم الحفظ كل save_steps.
    • "best": يتم الحفظ كلما تم تحقيق best_metric جديد.
  • save_steps (int أو float، اختياري، القيمة الافتراضية 500) — عدد خطوات التحديث قبل حفظ نقطتي تفتيش إذا كان save_strategy="steps". يجب أن يكون عددًا صحيحًا أو عددًا عشريًا ضمن المدى [0,1). إذا كان أقل من 1، فسيُفسَّر كنسبة من إجمالي خطوات التدريب.
  • save_on_each_node (bool، اختياري، القيمة الافتراضية False) — عند تنفيذ التدريب الموزّع متعدد العقد، يحدد ما إذا كان سيتم حفظ النماذج والنقاط المرجعية على كل عقدة، أم على العقدة الرئيسية فقط. يجب عدم تفعيل هذا الخيار عندما تستخدم العقد المختلفة نفس التخزين، لأن الملفات ستُحفظ بأسماء متطابقة على كل عقدة.
  • save_total_limit (int, اختياري) — الحد الأقصى لعدد نقاط التفتيش التي يجب الاحتفاظ بها. يحذف نقاط التفتيش الأقدم في output_dir. عند load_best_model_at_end=True، يتم دائمًا الاحتفاظ بأفضل نقطة تفتيش بالإضافة إلى أحدث النقاط. على سبيل المثال، save_total_limit=5 يحتفظ بأحدث 4 نقاط بالإضافة إلى الأفضل
  • enable_jit_checkpoint (bool, اختياري، القيمة الافتراضية False) — تفعيل نقطة التفتيش الفورية عند الإرسال (Just-In-Time checkpointing) عند استلام إشارة SIGTERM لإنهاء العمل بسلاسة على الأحمال القابلة للاستحواذ (preemptible workloads). مهم: اضبط فترة الإيقاف السلس في منسّقك (orchestrator) للسماح بزمن كافٍ. في Kubernetes، اضبط terminationGracePeriodSeconds (القيمة الافتراضية 30 ثانية عادةً غير كافية). في Slurm، استخدم --signal=TERM@<seconds>. الفترة السليمة المطلوبة ≥ أطول وقت لتكرار واحد + وقت حفظ نقطة التفتيش.

التكامل مع Hugging Face Hub

  • push_to_hub (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم دفع النموذج إلى Hub في كل مرة يُحفظ فيها النموذج. إذا تم تفعيل هذا الخيار، فسيبدأ output_dir في إنشاء دليل git متزامن مع المستودع (المحدد بواسطة hub_model_id) وسيتم دفع المحتوى في كل مرة يتم فيها تشغيل الحفظ (بناءً على save_strategy الخاص بك). كما أن استدعاء save_model() سيؤدي أيضاً إلى تشغيل عملية الدفع.
  • hub_token (str، اختياري) — المفتاح المستخدم لدفع النموذج إلى Hub. سيُستخدم افتراضيًا المفتاح الموجود في مجلد الكاش الذي تم الحصول عليه عبر hf auth login.
  • hub_private_repo (bool، اختياري) — ما إذا كان سيتم جعل المستودع خاصًا. إذا كانت القيمة None (الافتراضية)، فسيكون المستودع عامًا ما لم يكن الافتراضي للمنظمة هو الخاص. يتم تجاهل هذه القيمة إذا كان المستودع موجودًا مسبقًا. عند الإبلاغ إلى Trackio مع تمكين النشر إلى Hugging Face Spaces، تحدد نفس المنطق ما إذا كان المساحة (Space) خاصًا.
  • hub_model_id (str، اختياري) — اسم المستودع الذي يجب إبقاؤه متزامنًا مع output_dir المحلي. يمكن أن يكون معرّف نموذج بسيط، وفي هذه الحالة سيتم دفع النموذج إلى نطاقك. وإلا، يجب أن يكون اسم المستودع الكامل، على سبيل المثال "user_name/model"، مما يتيح لك الدفع إلى منظمة أنت عضو فيها باستخدام "organization_name/model". سيكون الافتراضي user_name/output_dir_name حيث يكون output_dir_name هو اسم output_dir.
  • hub_strategy (str أو HubStrategy, اختياري, الافتراضي هو "every_save") — يحدد ما الذي يجب دفعه إلى Hub ومتى. الخيارات:
    • "end": الدفع فقط في نهاية التدريب
    • "every_save": الدفع عند كل حفظ (غير متزامن حتى لا يعيق التدريب)
    • "checkpoint": يشبه "every_save" مع إضافة دفع أحدث نقطة تفتيش إلى مجلد الفرع "last-checkpoint" لسهولة الاستئناف
    • "all_checkpoints": دفع جميع نقاط التفتيش كما تظهر
  • hub_always_push (bool، اختياري، القيمة الافتراضية False) — ما لم تكن هذه القيمة True، سيتخطى Trainer دفع نقطة التفتيش إذا لم يكتمل الدفع السابق.
  • hub_revision (str, اختياري) — الإصدار (revision) الذي سيتم استخدامه عند الدفع إلى Hub. يمكن أن يكون اسم فرع، أو وسم، أو تجزئة (hash) لالتزام.

أفضل تتبع للنماذج

  • load_best_model_at_end (bool، اختياري، القيمة الافتراضية False) — تحميل أفضل نقطة تحقق في نهاية التدريب. يتطلب ضبط eval_strategy. عند التفعيل، يتم دائمًا حفظ أفضل نقطة تحقق (انظر save_total_limit). عندما تكون القيمة `True`، يجب أن يتطابق `save_strategy` مع `eval_strategy` (ما لم تكن قيمة `save_strategy` هي `"best"`)، وإذا كان استخدام `"steps"`، فإن `save_steps` يجب أن يكون مضاعفًا لـ `eval_steps`.
  • metric_for_best_model (str, اختياري) — المقياس المستخدم لمقارنة النماذج عند load_best_model_at_end=True. يجب أن يكون اسم مقياس يعيده التقييم، مع أو بدون البادئة "eval_". القيمة الافتراضية هي "loss". إذا قمت بتعيين هذا، فستكون القيمة الافتراضية لـ greater_is_better هي True ما لم ينتهِ الاسم بـ "loss". أمثلة: "accuracy"، "f1"، "eval_bleu".
  • greater_is_better (bool, اختياري) — ما إذا كانت القيم الأعلى للمقياس أفضل. القيمة الافتراضية مبنية على metric_for_best_model: True إذا لم ينتهِ اسم المقياس بـ "loss"، وإلا False.

استئناف التدريب

  • ignore_data_skip (bool، اختياري، القيمة الافتراضية False) — عند استئناف التدريب، يتخطى هذا الخيار التقدّم السريع عبر مجموعة البيانات للوصول إلى الحالة السابقة. إذا كانت القيمة True، يبدأ التدريب من بداية مجموعة البيانات (استئناف أسرع لكن النتائج لن تتطابق مع التدريب المقطوع). إذا كانت القيمة False، يتخطى البيانات التي تم رؤيتها (استئناف أبطأ لكن استكمال دقيق).
  • restore_callback_states_from_checkpoint (bool، اختياري، القيمة الافتراضية False) — استعادة حالات الاستدعاءات (callbacks) من نقطة التفتيش عند الاستئناف. إذا كانت القيمة True، فسيتم تجاوز الاستدعاءات (callbacks) الممرّرة إلى Trainer إذا كانت موجودة في نقطة التفتيش.

قابلية التكرار

  • full_determinism (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، يتم استدعاء enable_full_determinism() بدلاً من set_seed() لضمان الحصول على نتائج قابلة للتكرار في التدريب الموزّع. ملاحظة مهمة: سيؤثر هذا سلباً على الأداء، لذا استخدمه فقط لأغراض تصحيح الأخطاء.
  • seed (int، اختياري، القيمة الافتراضية 42) — بذرة عشوائية سيتم ضبطها في بداية التدريب. لضمان قابلية إعادة الإنتاج عبر التشغيلات، استخدم دالة ~Trainer.model_init لإنشاء النموذج إذا كانت بعض معاميره مهيأة عشوائيًا.
  • data_seed (int, اختياري) — البذرة العشوائية المستخدمة مع عينات البيانات. إذا لم يتم ضبطها، فستستخدم مولدات الأرقام العشوائية لعينات البيانات نفس البذرة الخاصة بـ seed. يمكن استخدام هذا لضمان قابلية إعادة إنتاج عينات البيانات، بشكل مستقل عن بذرة النموذج.

إعدادات العتاد

  • use_cpu (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم استخدام وحدة المعالجة المركزية (CPU) أم لا. إذا تم ضبطها على False، فسيتم استخدام جهاز/واجهة الخلفية المتاحة من torch.

إعدادات Accelerate

  • accelerator_config (str, dict, أو AcceleratorConfig, اختياري) — إعدادات تكامل Accelerate الداخلي. يمكن أن تكون: مسار إلى ملف إعدادات بصيغة JSON: "accelerator_config.json" قاموس يحتوي على خيارات الإعدادات كائن من نوع AcceleratorConfig الخيارات الرئيسية: split_batches (bool، القيمة الافتراضية False): ما إذا كان سيتم تقسيم الدفعات عبر الأجهزة. إذا كانت True، فإن حجم الدفعة الفعلي يكون متساوياً على جميع الأجهزة (يجب أن يكون المجموع قابلاً للقسمة على num_processes). إذا كانت False، يحصل كل جهاز على حجم الدفعة المحدد. dispatch_batches (bool): إذا كانت True، يقوم العملية الرئيسية فقط بتكرار dataloader وإرسال الدفعات إلى الأجهزة. القيمة الافتراضية True لـ IterableDataset، وFalse في الحالات الأخرى. even_batches (bool، القيمة الافتراضية True): تكرار العينات من بداية مجموعة البيانات لضمان حصول جميع العمال على أحجام دفعات متساوية. use_seedable_sampler (bool، القيمة الافتراضية True): استخدام عينة عشوائية قابلة للتبذير بالكامل من أجل قابلية التكرار. use_configured_state (bool، القيمة الافتراضية False): استخدام AcceleratorState/PartialState مُهيّأ مسبقاً بدلاً من إنشاء واحد جديد. قد يسبب مشاكل في ضبط المعلمات الفائقة.
    • مسار ملف الإعدادات بصيغة JSON: "accelerator_config.json"
    • قاموس بخيارات الإعداد
    • مثال من AcceleratorConfig الخيارات الرئيسية:
    • split_batches (bool، القيمة الافتراضية False): ما إذا كان سيتم تقسيم الدفعات عبر الأجهزة. إذا كانت True، فإن حجم الدفعة الفعلي يكون متساوياً على جميع الأجهزة (يجب أن يكون المجموع قابلاً للقسمة على num_processes). إذا كانت False، يحصل كل جهاز على حجم الدفعة المحدد.
    • dispatch_batches (bool): إذا كانت القيمة True، فإن العملية الرئيسية فقط تتصفح dataloader وتوزّع الدفعات على الأجهزة. القيمة الافتراضية هي True في حالة IterableDataset، وFalse في الحالات الأخرى.
    • even_batches (bool، القيمة الافتراضية True): يُكرّر العينات من بداية مجموعة البيانات لضمان حصول جميع العمال على أحجام دفعات متساوية.
    • use_seedable_sampler (bool، القيمة الافتراضية True): استخدام مُعيّن عشوائي قابل للتبذير بالكامل من أجل قابلية التكرار.
    • use_configured_state (bool، القيمة الافتراضية False): استخدام حالة AcceleratorState/PartialState مُهيّأة مسبقًا بدلاً من إنشاء حالة جديدة. قد يسبب ذلك مشاكل في ضبط المعلمات الفائقة.
  • parallelism_config (ParallelismConfig، اختياري) — إعدادات التوازي لجلسة التدريب. يتطلب Accelerate 1.10.1

Dataloader

  • dataloader_drop_last (bool، اختياري، القيمة الافتراضية False) — هل يتم إسقاط الدفعة الأخيرة غير المكتملة (إذا لم يكن طول مجموعة البيانات قابلاً للقسمة على حجم الدفعة) أم لا.
  • dataloader_num_workers (int, اختياري، القيمة الافتراضية 0) — عدد العمليات الفرعية المستخدمة لتحميل البيانات (PyTorch فقط). القيمة 0 تعني أن البيانات ستُحمَّل في العملية الرئيسية.
  • dataloader_pin_memory (bool، اختياري، القيمة الافتراضية True) — هل تريد تثبيت الذاكرة في محمّلات البيانات أم لا. ستكون القيمة الافتراضية True.
  • dataloader_persistent_workers (bool، اختياري، القيمة الافتراضية False) — إذا كانت القيمة True، فلن يُغلق مُحمِّل البيانات عمليات العمال بعد استهلاك مجموعة البيانات مرة واحدة. هذا يسمح بإبقاء كائنات Dataset الخاصة بالعمال نشطة. قد يسرّع التدريب بشكل محتمل، لكنه سيزيد من استهلاك ذاكرة RAM. ستكون القيمة الافتراضية False.
  • dataloader_prefetch_factor (int, اختياري) — عدد الدفعات التي يتم تحميلها مسبقًا بواسطة كل عامل. قيمة 2 تعني أن إجمالي عدد الدفعات المحمّلة مسبقًا عبر جميع العمال سيكون 2 * num_workers.
  • dataloader_multiprocessing_context (str، اختياري) — طريقة بدء التشغيل متعددة العمليات المستخدمة لعمال تحميل البيانات ("fork" أو "spawn" أو "forkserver"). الافتراضي هو طريقة بدء التشغيل الافتراضية في PyTorch، باستثناء حالة MPS عندما يكون dataloader_num_workers > 1، حيث تكون القيمة الافتراضية "fork". استخدم "spawn" عند البث من مصادر لا تكون كائناتها آمنة للاستنساخ (مثل HDFS عبر pyarrow). عند استخدام "spawn"، يجب أن تكون أي دالة collate_fn مخصصة أو كود مجموعة بيانات قابلًا للاستيراد على مستوى الوحدة (بدون دوال lambda أو closures).
  • dataloader_in_order (bool، اختياري، القيمة الافتراضية True) — إذا كانت True، فإن مُحمِّل البيانات يُخرج الدفعات بالترتيب الذي تم فيه إرسال العمال. اضبطها على False لإخراج الدفعات فور جاهزيتها، مما قد يقلل من زمن التأخير النهائي لأحمال العمل التدفّقية الخاصة بـIterableDataset. يتطلب PyTorch >= 2.6.
  • remove_unused_columns (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم حذف الأعمدة التي لا يستخدمها دالة الأمامية للنموذج تلقائيًا أم لا.
  • label_names (list[str]، اختياري) — قائمة المفاتيح في قاموس المدخلات الخاص بك التي تتوافق مع التسميات. سيتم افتراضياً اعتماد قائمة أسماء المعاملات التي يقبلها النموذج والتي تحتوي على كلمة “label”، ما لم يكن النموذج المستخدم من نوع XxxForQuestionAnswering، وفي هذه الحالة ستشمل القائمة أيضاً مفاتيح ["start_positions", "end_positions"]. يجب عليك تحديد label_names فقط إذا كنت تستخدم أسماء تسميات مخصصة، أو إذا كان forward الخاص بنموذجك يستهلك عدة تينسورات للتسميات (على سبيل المثال، في الإجابة الاستخراجية على الأسئلة).
  • train_sampling_strategy (str, اختياري, الافتراضي هو "random") — المُعيّن (Sampler) المستخدم لـ DataLoader الخاص بالتدريب. القيم الممكنة هي:
    • "random": يستخدم RandomSampler (الافتراضي).
    • "sequential": يستخدم SequentialSampler.
    • "group_by_length": يستخدم LengthGroupedSampler لتجميع العينات ذات الطول المتقارب معًا (لتقليل الحشو وزيادة الكفاءة).
    • "batch_rebalance": يستخدم BatchRebalanceSampler لموازنة تكلفة الرموز المُكمّلة عبر الأجهزة وخطوات تراكم التدرّجات داخل كل دفعة فعّالة، مما يقلّل من هدر التكميم والذروة في الذاكرة مقارنةً بـ"group_by_length". حاليًا، يُدعم هذا الخيار فقط للتدريب بالتوازي على مستوى البيانات (فإن التوازي على مستوى المكوّنات غير مدعوم بعد).

    ملاحظة: عند استخدام IterableDataset، يتم تجاهل هذا الحُجّة.

  • length_column_name (str, اختياري، القيمة الافتراضية "length") — اسم العمود الخاص بالطول المحسوب مسبقاً. إذا كان العمود موجوداً، فسيستخدم التجميع حسب الطول هذه القيم بدلاً من حسابها عند بدء التدريب. يتم تجاهله ما لم يكن train_sampling_strategy هو "group_by_length" أو "batch_rebalance" وكان مجموعة البيانات مثلاً من Dataset.

DDP (DistributedDataParallel)

  • ddp_find_unused_parameters (bool، اختياري) — عند استخدام التدريب الموزّع، قيمة العلم find_unused_parameters المُمرّرة إلى DistributedDataParallel. ستكون القيمة الافتراضية False إذا تم استخدام نقطة التفتيش للتدرّجات، وإلا فستكون True.
  • ddp_bucket_cap_mb (int، اختياري) — عند استخدام التدريب الموزّع، قيمة العلم bucket_cap_mb المُمرَّر إلى DistributedDataParallel.
  • ddp_broadcast_buffers (bool، اختياري) — عند استخدام التدريب الموزّع، قيمة العلم broadcast_buffers المُمرّرة إلى DistributedDataParallel. ستكون القيمة الافتراضية False إذا تم استخدام نقطة التفتيش للتدرّجات، وإلا فستكون True.
  • ddp_static_graph (bool، اختياري) — عند استخدام التدريب الموزّع، قيمة العلم static_graph المُمرَّر إلى DistributedDataParallel.
  • ddp_backend (str, اختياري) — الواجهة الخلفية المستخدمة للتدريب الموزّع. يجب أن تكون واحدة من "nccl"، "mpi"، "xccl"، "gloo"، "hccl".
  • ddp_timeout (int، اختياري، القيمة الافتراضية 1800) — مهلة الاستجابة لاستدعاءات torch.distributed.init_process_group، وتُستخدم لتجنّب انتهاء مهلة اتصال وحدات معالجة الرسوميات (GPU) عند تنفيذ عمليات بطيئة في التشغيل الموزّع. يُرجى الرجوع إلى توثيق PyTorch لمزيد من المعلومات.

FSDP (التوازي الكامل للبيانات المجزأة)

  • fsdp (bool، اختياري، القيمة الافتراضية None) — تفعيل PyTorch Fully Sharded Data Parallel (FSDP) للتدريب الموزّع. مرّر True لتفعيل FSDP.
  • fsdp_config (str or dict, optional) — Configuration settings for when fsdp is enabled. Pass a path to a JSON config file, such as fsdp_config.json, or an already-loaded dict.

    المفاتيح المدعومة:

    • الإصدار (int، اختياري، الافتراضي 2): إصدار FSDP الذي سيتم استخدامه (2 لـ FSDP2، و1 لـ FSDP1 القديم).
    • reshard_after_forward (bool, اختياري، القيمة الافتراضية True): ما إذا كان يجب إعادة تجزئة المعاملات بعد عملية الانتقال الأمامي. اضبطها على False للحفاظ على تجميع المعاملات بين عمليتي الانتقال الأمامي والعكسي، مما يتجنب إعادة التجميع الشامل (re-all-gather)، ويستخدم ذاكرة ذروة أعلى.
    • cpu_offload (bool، اختياري، القيمة الافتراضية False): تحويل المعاملات والتدرجات إلى وحدة المعالجة المركزية (CPU) عند عدم استخدامها لتوفير ذاكرة وحدة معالجة الرسوميات (GPU).
    • activation_checkpointing (bool, اختياري، القيمة الافتراضية False): اضبطه على True لتقليل الذاكرة عن طريق إعادة حساب التفعيلات أثناء عملية الرجوع الخلفي. عند استخدام FSDP، يُفضَّل استخدام هذا بدلاً من معامل التدريب activation_checkpointing، الذي يُدخل عملية all-gather زائدة عن الحاجة في عملية الرجوع الخلفي.
    • cpu_ram_efficient_loading (bool, اختياري، القيمة الافتراضية False): اضبطه على True لتحميل نقطة الفحص المُدرَّبة مسبقًا على العملية الأولى فقط. تبدأ العمليات الأخرى بأوزان فارغة وتستقبل الأوزان عبر البث.
    • state_dict_type (str، اختياري، القيمة الافتراضية "FULL_STATE_DICT"): تنسيق نقطة التفتيش: "FULL_STATE_DICT" (ملف واحد متوافق مع HF) أو "SHARDED_STATE_DICT" (ملف واحد لكل rank، أسرع للنماذج الكبيرة).
    • auto_wrap_policy (str, اختياري، الافتراضي "TRANSFORMER_BASED_WRAP"): سياسة التغليف التلقائي المستخدمة. اختر "TRANSFORMER_BASED_WRAP" أو "SIZE_BASED_WRAP" أو "NO_WRAP".
    • transformer_layer_cls_to_wrap (list[str]، اختياري): أسماء فئات طبقات Transformer (حساسة لحالة الأحرف) التي يجب تغليفها، مثل LlamaDecoderLayer. عادةً ما يكون هذا غير ضروري: إذ يعتمد سياسة التغليف على _no_split_modules الخاص بالنموذج، والذي يغطي معظم نماذج transformers.
    • min_num_params (int, اختياري، القيمة الافتراضية 0): الحد الأدنى لعدد المعاملات في كل وحدة للتغليف التلقائي القائم على الحجم (يُستخدم مع auto_wrap_policy="SIZE_BASED_WRAP").
    • xla (bool، اختياري، القيمة الافتراضية False): ما إذا كان سيتم استخدام تدريب PyTorch/XLA بالتوازي الكامل لبيانات FSDP. تجريبي.
    • xla_fsdp_settings (dict, اختياري): قاموس بمعاملات تغليف XLA FSDP. للحصول على قائمة كاملة بالخيارات، راجع مصدر XLA FSDP.
    • xla_fsdp_grad_ckpt (bool، اختياري، القيمة الافتراضية False): اضبطه على True لاستخدام نقطة التفتيش التدرّجية على كل طبقة مغلّفة بـ XLA FSDP متداخلة. يتطلب xla=True وسياسة تغليف تلقائية (min_num_params أو transformer_layer_cls_to_wrap).

DeepSpeed

  • deepspeed (str أو dict, اختياري) — تفعيل DeepSpeed التكامل. القيمة إما:
    • مسار ملف إعدادات DeepSpeed بصيغة JSON: "ds_config.json"
    • تم تحميل الإعدادات كقاموس

      إذا كنت تستخدم تهيئة ZeRO، فقم بإنشاء نموذجك بعد تهيئة TrainingArguments، وإلا فلن يتم تطبيق ZeRO.

التصحيح والتحليل (تجريبي)

  • debug (str أو قائمة من DebugOption, اختياري, الافتراضي هو "") — تفعيل ميزة أو أكثر من ميزات التصحيح. هذه ميزة تجريبية. الخيارات الممكنة هي:
    • “underflow_overflow”: يكشف عن تجاوز الحدود في مدخلات/مخرجات النموذج ويبلّغ عن آخر الإطارات التي أدت إلى
    • “tpu_metrics_debug”: طباعة مقاييس التصحيح على TPU
  • skip_memory_metrics (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم تخطي إضافة تقارير ملفّس الذاكرة إلى المقاييس. يتم تخطي هذا الإعداد افتراضيًا لأنه يُبطئ سرعة التدريب والتقييم.

أعلام السكربت الخارجي (غير مستخدمة بواسطة Trainer)

  • do_train (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تشغيل التدريب أم لا. لا يستخدم هذا الحُجُج مباشرةً بواسطة Trainer، بل يُقصد استخدامه من قِبل سكربتات التدريب/التقييم الخاصة بك.
  • do_eval (bool, اختياري) — ما إذا كان سيتم تشغيل التقييم على مجموعة التحقق أم لا. سيُضبط على True إذا كان eval_strategy مختلفًا عن "no". لا يستخدم هذا الحجة مباشرةً بواسطة Trainer، بل يُقصد استخدامه في سكربتات التدريب/التقييم الخاصة بك.
  • do_predict (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تشغيل التنبؤات على مجموعة الاختبار أم لا. لا يستخدم هذا الحجة مباشرةً بواسطة Trainer، بل يُقصد استخدامه من قِبل سكربتات التدريب/التقييم الخاصة بك.
  • resume_from_checkpoint (str, اختياري) — مسار مجلد يحتوي على نقطة تفتيش صالحة لنموذجك. لا يستخدم هذا الحُجُج مباشرةً بواسطة Trainer، بل يُقصد استخدامه من قِبل سكربتات التدريب/التقييم الخاصة بك.
  • sortish_sampler (bool, اختياري, الافتراضي هو False) — هل نستخدم sortish sampler أم لا. هذا ممكن فقط إذا كانت مجموعات البيانات الأساسية من نوع Seq2SeqDataset حاليًا، لكن سيصبح متاحًا بشكل عام في المستقبل القريب.

    يُرتّب المدخلات وفقاً لطولها بهدف تقليل حجم الحشو، مع إضافة قدر بسيط من العشوائية لمجموعة التدريب.

  • predict_with_generate (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم استخدام generate لحساب مقاييس التوليد (ROUGE، BLEU).
  • generation_max_length (int, اختياري) — قيمة max_length المستخدمة في كل حلقة تقييم عند تعيين predict_with_generate=True. ستكون القيمة الافتراضية هي قيمة max_length في إعدادات النموذج.
  • generation_num_beams (int, اختياري) — قيمة num_beams المستخدمة في كل حلقة تقييم عند تعيين predict_with_generate=True. ستكون القيمة الافتراضية هي قيمة num_beams في إعدادات النموذج.
  • generation_config (str أو Path أو GenerationConfig, اختياري) — يتيح تحميل GenerationConfig من from_pretrained طريقة. يمكن أن يكون:
    • سلسلة نصية، وهي معرّف النموذج لإعدادات نموذج مُدرَّب مسبقًا مستضاف داخل مستودع نموذج على huggingface.co.
    • مسار إلى مجلد يحتوي على ملف إعدادات تم حفظه باستخدام طريقة save_pretrained()، على سبيل المثال ./my_model_directory/.
    • كائن GenerationConfig.

فئة التهيئة للتحكم في جميع جوانب تدريب النموذج باستخدام Trainer. تُوحّد TrainingArguments جميع المعاملات الفائقة وإعدادات التحسين وتفضيلات التسجيل وخيارات البنية التحتية اللازمة للتدريب.

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

to_dict

< >

( )

يسلسل هذه النسخة مع استبدال Enum بقيمها وGenerationConfig بقواميس (لدعم التسلسل بصيغة JSON). كما يُعمّي على قيم الرموز (tokens) عن طريق إزالة قيمها.

Update on GitHub

←مُجزِّئ DeepSpeed→