المستدعات

يتداخل TrainerCallback مع أحداث التدريب المحددة (بدء الحقبة، التقييم، نهاية التدريب) لتعديل حالة التدريب أو التحكم في تدفق التنفيذ. استخدم الاستدعاءات (callbacks) لتسجيل المقاييس في متتبعات التجارب مثل Trackio، أو تخصيص توقيت حفظ النماذج وإجراء التقييم، أو إضافة سلوك مخصص آخر. يمكنك تجميع عدة استدعاءات معًا لدمج الميزات.

لا يمكن للـ Callbacks تعديل حلقة التدريب نفسها، مثل تمرير الأمامي. لتغيير ما يحسبه Trainer، أنشئ فئة فرعية لطرقه بدلاً من ذلك.

يُظهر المخطط أدناه كل حدث يمكن لـ callback أن يتفاعل معه.

on_train_begin
  └─ for each epoch:
      on_epoch_begin
      └─ for each step:
          on_step_begin
          ├─ for each gradient accumulation substep:
          │   on_substep_end
          on_pre_optimizer_step   ← after gradient clipping, before optimizer.step()
          on_optimizer_step       ← after optimizer.step()
          on_step_end
          └─ (conditionally):
              on_log
              on_evaluate
              on_save
      on_epoch_end
on_train_end
on_predict / on_prediction_step
on_push_begin

إنشاء مستدعٍ

أنشئ فئة فرعية من TrainerCallback وأعد كتابة واحدة أو أكثر من طرق الأحداث الموضحة في المخطط أعلاه. يوضح المثال أدناه ثلاثة خطافات:

• يطبع on_epoch_begin الحقبة الحالية من TrainerState (قيمة حيّة) ومعدل التعلم من TrainingArguments (قيمة ثابتة).
• تقرأ on_step_end معدل التعلم الحالي من lr_scheduler (المُمرَّر عبر **kwargs) وتضبط should_evaluate على TrainerControl (راجع TrainerControl للحصول على قائمة كاملة بأهداف التحكم) لتفعيل التقييم عندما ينخفض عن العتبة.
• يطبع on_train_end أفضل مقياس والخطوة التي حدث فيها.

from transformers import TrainerCallback

class EpochLoggerCallback(TrainerCallback):
    def __init__(self, lr_eval_threshold=1e-5):
        self.lr_eval_threshold = lr_eval_threshold

    def on_epoch_begin(self, args, state, control, **kwargs):
        print(f"Starting epoch {int(state.epoch) + 1}/{state.num_train_epochs} "
              f"(lr={args.learning_rate})")

    def on_step_end(self, args, state, control, **kwargs):
        lr_scheduler = kwargs.get("lr_scheduler")
        if lr_scheduler is not None:
            current_lr = lr_scheduler.get_last_lr()[0]
            if current_lr < self.lr_eval_threshold:
                control.should_evaluate = True

    def on_train_end(self, args, state, control, **kwargs):
        print(f"Training complete! Best metric: {state.best_metric} at step {state.best_global_step}")

سجّل الاستدعاء العكسي مع Trainer في الحجة callbacks. يمكنك أيضاً تمرير عدة استدعاءات عكسية كقائمة.

trainer = Trainer(
    callbacks=[EpochLoggerCallback(lr_eval_threshold=1e-5)],
    ...,
)

المستدعات المدمجة

تتضمن مكتبة Transformers عدة استدعاءات مدمجة (callbacks) نشطة افتراضيًا. كما توفر استدعاءات مدمجة إضافية تسجّل البيانات على منصات مثل Trackio.

DefaultFlowCallback

يدير DefaultFlowCallback الجدول الافتراضي للتسجيل والتقييم وحفظ نقاط التوقف بناءً على قيم logging_strategy وeval_strategy وsave_strategy في TrainingArguments. عند الخطوة أو الحقبة المناسبة، يضبط الأعلام المقابلة في control (أي should_log وshould_evaluate وshould_save). كما يضبط should_training_stop عندما يصل global_step إلى max_steps.

إن تجاوز هذا الاستدعاء هو الطريقة الرئيسية لتخصيص متى يتم تسجيل السجلات أو التقييم أو الحفظ.

ProgressCallback وPrinterCallback

يختار Trainer تلقائيًا بين هذين المستدعين (callbacks) بناءً على حقل disable_tqdm في TrainingArguments.

• يُستخدم ProgressCallback افتراضيًا. يعرض شريط تقدم tqdm أثناء التدريب، وشريطًا منفصلًا أثناء التقييم أو التنبؤ، ويُطبع أحدث المقاييس عند كل حدث on_log. أثناء التدريب الموزّع، يعمل على العملية الرئيسية فقط لتجنّب تكرار المخرجات.
• يُستخدم PrinterCallback عند تعيين disable_tqdm=True. يقوم بطباعة قاموس السجلات إلى stdout في كل حدث on_log دون شريط تقدّم.

يمكنك أيضًا استبدالها يدويًا باستخدام remove_callback() وadd_callback().

from transformers import PrinterCallback

trainer = Trainer(...)
trainer.remove_callback(ProgressCallback)
trainer.add_callback(PrinterCallback)

EarlyStoppingCallback

يوقف EarlyStoppingCallback التدريب عندما تتوقف مقياس التقييم عن التحسن. بعد كل تقييم، يتحقق مما إذا كان المقياس قد تحسن بمقدار أكبر من early_stopping_threshold. إذا لم يتحسن المقياس خلال early_stopping_patience تقييمات متتالية، يتوقف التدريب.

يتطلب EarlyStoppingCallback حجّتين من نوع TrainingArguments:

• metric_for_best_model، وهي مقياس التقييم الذي يجب مراقبته
• eval_strategy، ما إذا كان التقييم يتم على "steps" أو "epoch"

from transformers import EarlyStoppingCallback

trainer = Trainer(
    ...,
    callbacks=[EarlyStoppingCallback(early_stopping_patience=3, early_stopping_threshold=0.001)],
)

الخطوات التالية

• اطّلع على جميع المستدعات المدمجة المتاحة لتسجيل البيانات في متتبّعات التجارب.
• يتناول دليل إعادة تصنيف دوال Trainer تجاوز دوال Trainer عندما تحتاج إلى تغيير ما يحسبه حلقة التدريب.