# المستدعات

يتداخل [TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) مع أحداث التدريب المحددة (بدء الحقبة، التقييم، نهاية التدريب) لتعديل حالة التدريب أو التحكم في تدفق التنفيذ. استخدم الاستدعاءات (callbacks) لتسجيل المقاييس في متتبعات التجارب مثل Trackio، أو تخصيص توقيت حفظ النماذج وإجراء التقييم، أو إضافة سلوك مخصص آخر. يمكنك تجميع عدة استدعاءات معًا لدمج الميزات.

لا يمكن للـ Callbacks تعديل حلقة التدريب نفسها، مثل المرور الأمامي. لتغيير ما يحسبه [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer)، [أنشئ فئة فرعية](./trainer_customize) لطرقه بدلاً من ذلك.

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

```md
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](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) وأعد كتابة واحدة أو أكثر من طرق الأحداث الموضحة في المخطط أعلاه. يوضح المثال أدناه ثلاثة خطافات:

- يطبع `on_epoch_begin` الحقبة الحالية من [TrainerState](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerState) (قيمة حيّة) ومعدل التعلم من [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) (قيمة ثابتة).
- تقرأ `on_step_end` معدل التعلم الحالي من lr_scheduler (المُمرَّر عبر `**kwargs`) وتضبط `should_evaluate` على [TrainerControl](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerControl) (راجع [TrainerControl](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerControl) للحصول على قائمة كاملة بأهداف التحكم) لتفعيل التقييم عندما ينخفض عن العتبة.
- يطبع `on_train_end` أفضل مقياس والخطوة التي حدث فيها.

```python
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](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) في الحجة `callbacks`. يمكنك أيضاً تمرير عدة استدعاءات عكسية كقائمة.

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

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

تتضمن مكتبة Transformers عدة استدعاءات مدمجة (callbacks) نشطة افتراضيًا. كما توفر [استدعاءات مدمجة إضافية](./main_classes/callback) تسجّل البيانات على منصات مثل [Trackio](https://huggingface.co/docs/trackio/en/index).

### DefaultFlowCallback

يدير [DefaultFlowCallback](/docs/transformers/main/ar/main_classes/callback#transformers.DefaultFlowCallback) الجدول الافتراضي للتسجيل والتقييم وحفظ نقاط التوقف بناءً على قيم `logging_strategy` و`eval_strategy` و`save_strategy` في [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments). عند الخطوة أو الحقبة المناسبة، يضبط الأعلام المقابلة في `control` (أي `should_log` و`should_evaluate` و`should_save`). كما يضبط `should_training_stop` عندما يصل `global_step` إلى `max_steps`.

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

### ProgressCallback وPrinterCallback

يختار [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) تلقائيًا بين هذين المستدعين (callbacks) بناءً على حقل [disable_tqdm](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments.disable_tqdm) في [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments).

- يُستخدم [ProgressCallback](/docs/transformers/main/ar/main_classes/callback#transformers.ProgressCallback) افتراضيًا. يعرض شريط تقدم tqdm أثناء التدريب، وشريطًا منفصلًا أثناء التقييم أو التنبؤ، ويُطبع أحدث المقاييس عند كل حدث `on_log`. أثناء التدريب الموزّع، يعمل على العملية الرئيسية فقط لتجنّب تكرار المخرجات.
- يُستخدم [PrinterCallback](/docs/transformers/main/ar/main_classes/callback#transformers.PrinterCallback) عند تعيين `disable_tqdm=True`. يقوم بطباعة قاموس السجلات إلى stdout في كل حدث `on_log` دون شريط تقدّم.

يمكنك أيضًا استبدالها يدويًا باستخدام [remove_callback()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.remove_callback) و[add_callback()](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer.add_callback).

```py
from transformers import PrinterCallback

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

### EarlyStoppingCallback

يوقف [EarlyStoppingCallback](/docs/transformers/main/ar/main_classes/callback#transformers.EarlyStoppingCallback) التدريب عندما يتوقف مقياس التقييم عن التحسن. بعد كل تقييم، يتحقق مما إذا كان المقياس قد تحسن بمقدار أكبر من `early_stopping_threshold`. إذا لم يتحسن المقياس خلال `early_stopping_patience` تقييمًا متتاليًا، يتوقف التدريب.

يتطلب [EarlyStoppingCallback](/docs/transformers/main/ar/main_classes/callback#transformers.EarlyStoppingCallback) حجّتين من نوع [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments):

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

```py
from transformers import EarlyStoppingCallback

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

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

- اطّلع على جميع [المستدعات المدمجة](./main_classes/callback) المتاحة لتسجيل البيانات في متتبّعات التجارب.
- يتناول دليل [إعادة تصنيف دوال Trainer](./trainer_customize) تجاوز دوال [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) عندما تحتاج إلى تغيير ما يحسبه حلقة التدريب.