# المستدعات

المستدعات (Callbacks) هي كائنات يمكنها تخصيص سلوك حلقة التدريب في [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) الخاص بـ PyTorch، حيث يمكنها فحص حالة حلقة التدريب (لأغراض الإبلاغ عن التقدم، أو التسجيل على TensorBoard أو منصات التعلم الآلي الأخرى...) واتخاذ قرارات (مثل التوقف المبكر).

تُعدّ المستدعات (Callbacks) مقاطع من الشيفرة "للقراءة فقط"، فباستثناء كائن [TrainerControl](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerControl) الذي تُرجعه، لا يمكنها تغيير أي شيء في حلقة التدريب. أما للتخصيصات التي تتطلب إجراء تغييرات في حلقة التدريب، فيجب عليك إنشاء فئة فرعية من [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) وتجاوز (override) الطرق التي تحتاجها (انظر [trainer](trainer) للحصول على أمثلة).

بشكل افتراضي، يُضبط `TrainingArguments.report_to` على `"none"`.

الفئة الرئيسية التي تنفّذ الاستدعاءات العكسية هي [TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback). تحصل على [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) المستخدمة لإنشاء [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer)، ويمكنها الوصول إلى الحالة الداخلية لذلك Trainer عبر [TrainerState](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerState)، كما يمكنها تنفيذ بعض الإجراءات على حلقة التدريب عبر [TrainerControl](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerControl).

## الاستدعاءات المتاحة[[transformers.integrations.CometCallback]]

فيما يلي قائمة بـ [TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) المتاحة في المكتبة:

#### transformers.integrations.CometCallback[[transformers.integrations.CometCallback]]

```python
transformers.integrations.CometCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1133)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يرسل السجلات إلى [Comet ML](https://www.comet.com/site/).

#### الإعداد[[transformers.integrations.CometCallback.setup]]

```python
setup(args, state, model)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1147)

قم بإعداد تكامل Comet الاختياري.

البيئة:
- **COMET_MODE** (`str`، *اختياري*، القيمة الافتراضية `get_or_create`): يتحكم في ما إذا كان سيتم إنشاء تجربة Comet جديدة وتسجيل البيانات فيها، أو إضافة البيانات إلى تجربة موجودة مسبقًا. يقبل القيم التالية:
  * `get_or_create`: يقرر تلقائيًا بناءً على ما إذا كان `COMET_EXPERIMENT_KEY` مضبوطًا، وما إذا كان هناك Experiment يحمل هذا المفتاح موجودًا بالفعل أم لا.
  * `create`: أنشئ دائمًا تجربة Comet جديدة.
  * `get`: حاول دائماً الإضافة إلى تجربة Comet موجودة مسبقاً. يتطلب تعيين `COMET_EXPERIMENT_KEY`.
- **COMET_START_ONLINE** (`bool`، *اختياري*): ما إذا كان سيتم إنشاء تجربة عبر الإنترنت أو دون اتصال.
- **COMET_PROJECT_NAME** (`str`، *اختياري*): اسم مشروع Comet للتجارب.
- **COMET_LOG_ASSETS** (`str`، *اختياري*، القيمة الافتراضية `TRUE`): تحديد ما إذا كان سيتم تسجيل أصول التدريب (نقاط التفتيش، إلخ) في Comet. يمكن أن تكون القيمة `TRUE` أو `FALSE`.

لمعرفة عدد من العناصر القابلة للتكوين في البيئة، راجع [هنا](https://www.comet.com/docs/v2/guides/experiment-management/configure-sdk/#explore-comet-configuration-options).

#### transformers.DefaultFlowCallback[[transformers.DefaultFlowCallback]]

```python
transformers.DefaultFlowCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L563)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يتعامل مع التدفق الافتراضي لحلقة التدريب الخاصة بالسجلات والتقييم والنقاط المحفوظة.

#### transformers.PrinterCallback[[transformers.PrinterCallback]]

```python
transformers.PrinterCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L698)

A bare [TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) that just prints the logs.

#### transformers.ProgressCallback[[transformers.ProgressCallback]]

```python
transformers.ProgressCallback(max_str_len: int = 100)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L624)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يعرض تقدم التدريب أو التقييم. يمكنك تعديل `max_str_len` للتحكم في طول النصوص التي يتم اقتطاعها عند التسجيل.

#### transformers.EarlyStoppingCallback[[transformers.EarlyStoppingCallback]]

```python
transformers.EarlyStoppingCallback(early_stopping_patience: int = 1, early_stopping_threshold: float | None = 0.0)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L711)

**المعاملات:**

early_stopping_patience (`int`) : يُستخدم مع `metric_for_best_model` لإيقاف التدريب عندما تتدهور المقاييس المحددة لعدد `early_stopping_patience` من استدعاءات التقييم.

early_stopping_threshold(`float`, *اختياري*) : يُستخدم مع TrainingArguments `metric_for_best_model` و`early_stopping_patience` لتحديد مقدار التحسّن المطلوب في المقياس المحدد لكي تتحقق شروط التوقف المبكر.

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يتعامل مع التوقف المبكر.

يعتمد هذا الاستدعاء على وظيفة *load_best_model_at_end* في معامل [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) لضبط best_metric في [TrainerState](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerState). لاحظ أنه إذا اختلف معامل [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) الخاص بـ *save_steps* عن *eval_steps*، فلن يحدث التوقف المبكر حتى خطوة الحفظ التالية.

#### transformers.integrations.TensorBoardCallback[[transformers.integrations.TensorBoardCallback]]

```python
transformers.integrations.TensorBoardCallback(tb_writer = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L577)

**المعاملات:**

tb_writer (`SummaryWriter`، *اختياري*) : الكاتِب الذي سيتم استخدامه. سيتم إنشاء كائن واحد إذا لم يتم تعيينه.

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يرسل السجلات إلى [TensorBoard](https://www.tensorflow.org/tensorboard).

البيئة:
- **TENSORBOARD_LOGGING_DIR** (`str`، *اختياري*، القيمة الافتراضية `None`): المجلد الذي تُسجَّل فيه النتائج. القيمة الافتراضية هي os.path.join(args.output_dir, default_logdir())

#### transformers.integrations.TrackioCallback[[transformers.integrations.TrackioCallback]]

```python
transformers.integrations.TrackioCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L935)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يسجّل المقاييس في Trackio.

#### الإعداد[[transformers.integrations.TrackioCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L969)

قم بإعداد تكامل Trackio الاختياري.

لتخصيص الإعداد، يمكنك أيضاً تعيين `project` و`trackio_space_id` و`trackio_bucket_id` و`trackio_static_space_id` و`hub_private_repo` في [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments).

#### transformers.integrations.WandbCallback[[transformers.integrations.WandbCallback]]

```python
transformers.integrations.WandbCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L695)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يسجّل المقاييس والوسائط ونقاط التفتيش للنموذج في [Weight and Biases](https://www.wandb.com/).

#### الإعداد[[transformers.integrations.WandbCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L711)

قم بإعداد تكامل Weights & Biases (*wandb*) الاختياري.

يمكن إنشاء فئة فرعية من هذه الفئة وتجاوز هذه الطريقة لتخصيص الإعداد عند الحاجة. تجد مزيدًا من المعلومات [هنا](https://docs.wandb.ai/guides/integrations/huggingface). كما يمكنك تجاوز متغيرات البيئة التالية:

البيئة:
- **WANDB_LOG_MODEL** (`str`، *اختياري*، القيمة الافتراضية `"false"`): ما إذا كان سيتم تسجيل النموذج والنقاط المحفوظة (checkpoints) أثناء التدريب. يمكن أن تكون القيمة `"end"` أو `"checkpoint"` أو `"false"`. إذا تم ضبطها على `"end"`، فسيتم رفع النموذج في نهاية التدريب. إذا تم ضبطها على `"checkpoint"`، فسيتم رفع النقطة المحفوظة كل `args.save_steps` خطوة. إذا تم ضبطها على `"false"`، فلن يتم رفع النموذج. استخدمها مع `load_best_model_at_end()` لرفع أفضل نموذج.
- **WANDB_WATCH** (`str`، *اختياري*، القيمة الافتراضية `"false"`): يمكن أن تكون `"gradients"` أو `"all"` أو `"parameters"` أو `"false"`. اضبطها على `"all"` لتسجيل التدرجات والبارامترات.
- **WANDB_PROJECT** (`str`، *اختياري*، القيمة الافتراضية `"huggingface"`): اضبط هذا على نص مخصص لتخزين النتائج في مشروع مختلف.

#### transformers.integrations.MLflowCallback[[transformers.integrations.MLflowCallback]]

```python
transformers.integrations.MLflowCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1286)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يرسل السجلات إلى [MLflow](https://www.mlflow.org/). يمكن تعطيله عن طريق تعيين متغير البيئة `DISABLE_MLFLOW_INTEGRATION = TRUE`.

#### الإعداد[[transformers.integrations.MLflowCallback.setup]]

```python
setup(args, state, model)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1305)

قم بإعداد تكامل MLflow الاختياري.

البيئة:
- **HF_MLFLOW_LOG_ARTIFACTS** (`str`، *اختياري*): ما إذا كان سيتم استخدام آلية `.log_artifact()` في MLflow لتسجيل المخرجات. لا يكون هذا الخيار منطقيًا إلا عند التسجيل على خادم بعيد، مثل s3 أو GCS. إذا تم ضبطه على `True` أو *1*، فسيتم نسخ كل نقطة تحقق محفوظة عند كل عملية حفظ في `output_dir` الخاصة بـ [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) إلى تخزين المخرجات المحلي أو البعيد. استخدام هذه الخاصية دون تخزين بعيد سيؤدي فقط إلى نسخ الملفات إلى موقع المخرجات الخاص بك.
- **MLFLOW_TRACKING_URI** (`str`، *اختياري*): ما إذا كان سيتم تخزين التشغيلات في مسار محدد أو على خادم بعيد. غير مُعيَّن افتراضيًا، مما يؤدي إلى تخطي تعيين URI للتتبع بالكامل.
- **MLFLOW_EXPERIMENT_NAME** (`str`، *اختياري*، القيمة الافتراضية `None`): يحدد ما إذا كان سيتم استخدام اسم تجربة MLflow لإطلاق التشغيل. القيمة الافتراضية هي `None` والتي تشير إلى تجربة `Default` في MLflow. وإلا، فهي اسم حساس لحالة الأحرف للتجربة التي سيتم تفعيلها. إذا لم توجد تجربة بهذا الاسم، يتم إنشاء تجربة جديدة بهذا الاسم.
- **MLFLOW_TAGS** (`str`, *اختياري*): نص يمثل تصريفاً لقاموس أزواج مفتاح/قيمة ليتم إضافتها كوسوم إلى تشغيل MLflow. مثال: `os.environ['MLFLOW_TAGS']='{"release.candidate": "RC1", "release.version": "2.2.0"}'`.
- **MLFLOW_NESTED_RUN** (`str`، *اختياري*): ما إذا كان سيتم استخدام عمليات MLflow المتداخلة. إذا تم ضبطه على `True` أو *1*، فسيتم إنشاء عملية متداخلة داخل العملية الحالية.
- **MLFLOW_RUN_ID** (`str`، *اختياري*): يتيح إعادة الارتباط بتشغيل قائم، وهو أمر مفيد عند استئناف التدريب من نقطة تفتيش. عند تعيين متغير البيئة `MLFLOW_RUN_ID`، تحاول `start_run` استئناف التشغيل ذي معرّف التشغيل المحدد، وتُتجاهل المعاملات الأخرى.
- **MLFLOW_FLATTEN_PARAMS** (`str`، *اختياري*، القيمة الافتراضية `False`): ما إذا كان سيتم تسطيح قاموس المعاملات قبل التسجيل.
- **MLFLOW_MAX_LOG_PARAMS** (`int`، *اختياري*): تحديد الحد الأقصى لعدد المعلمات التي سيتم تسجيلها في التشغيل.

#### transformers.integrations.AzureMLCallback[[transformers.integrations.AzureMLCallback]]

```python
transformers.integrations.AzureMLCallback(azureml_run = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1263)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يرسل السجلات إلى [AzureML](https://pypi.org/project/azureml-sdk/).

#### transformers.integrations.CodeCarbonCallback[[transformers.integrations.CodeCarbonCallback]]

```python
transformers.integrations.CodeCarbonCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1809)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يتتبع انبعاثات ثاني أكسيد الكربون الناتجة عن التدريب.

#### transformers.integrations.ClearMLCallback[[transformers.integrations.ClearMLCallback]]

```python
transformers.integrations.ClearMLCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1843)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يرسل السجلات إلى [ClearML](https://clear.ml/).

البيئة:
- **CLEARML_PROJECT** (`str`، *اختياري*، القيمة الافتراضية `HuggingFace Transformers`): اسم مشروع ClearML.
- **CLEARML_TASK** (`str`، *اختياري*، الافتراضي `Trainer`): اسم مهمة ClearML.
- **CLEARML_LOG_MODEL** (`bool`، *اختياري*، القيمة الافتراضية `False`): ما إذا كان سيتم تسجيل النماذج كعناصر أثناء التدريب.

#### transformers.integrations.DagsHubCallback[[transformers.integrations.DagsHubCallback]]

```python
transformers.integrations.DagsHubCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1467)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يسجّل إلى [DagsHub](https://dagshub.com/). يوسّع `MLflowCallback`

#### الإعداد[[transformers.integrations.DagsHubCallback.setup]]

```python
setup(*args, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L1481)

قم بإعداد تكامل تسجيل DagsHub.

البيئة:
- **HF_DAGSHUB_LOG_ARTIFACTS** (`str`، *اختياري*): ما إذا كان سيتم حفظ بيانات التجربة ونماذجها. القيمة الافتراضية هي `False`.

#### transformers.integrations.FlyteCallback[[transformers.integrations.FlyteCallback]]

```python
transformers.integrations.FlyteCallback(save_log_history: bool = True, sync_checkpoints: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2094)

**المعاملات:**

save_log_history (`bool`، *اختياري*، القيمة الافتراضية `True`) : عند ضبطه على True، تُحفظ سجلات التدريب على شكل Flyte Deck.

sync_checkpoints (`bool`، *اختياري*، القيمة الافتراضية `True`) : عند ضبطه على True، تتم مزامنة نقاط التفتيش مع Flyte ويمكن استخدامها لاستئناف التدريب في حال حدوث انقطاع.

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يرسل السجلات إلى [Flyte](https://flyte.org/). ملاحظة: لا يعمل هذا الاستدعاء الخلفي إلا داخل مهمة Flyte.

مثال:

```python
# Note: This example skips over some setup steps for brevity.
from flytekit import current_context, task

@task
def train_hf_transformer():
    cp = current_context().checkpoint
    trainer = Trainer(..., callbacks=[FlyteCallback()])
    output = trainer.train(resume_from_checkpoint=cp.restore())
```

#### transformers.integrations.KubeflowCallback[[transformers.integrations.KubeflowCallback]]

```python
transformers.integrations.KubeflowCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2436)

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يُبلّغ عن تقدّم التدريب إلى [Kubeflow Trainer](https://github.com/kubeflow/trainer).

This callback is automatically registered when training inside a Kubeflow TrainJob with the `TrainJobRuntimeStatus` feature gate enabled. The Kubeflow controller injects the required environment variables into the training pod.

**متغيرات البيئة (المحقونة بواسطة المتحكم):**

- `KUBEFLOW_TRAINER_SERVER_URL`: نقطة نهاية HTTPS لتحديثات الحالة
- `KUBEFLOW_TRAINER_SERVER_CA_CERT`: مسار شهادة CA للتحقق من TLS
- `KUBEFLOW_TRAINER_SERVER_TOKEN`: مسار رمز حساب الخدمة للمصادقة

**المعلومات المُبلَّغ عنها:**

- نسبة التقدم (0-100%)
- الوقت المتبقي المقدر (بالثواني)
- مقاييس التدريب (الخسارة، learning_rate، إلخ)

**الميزات:**

- التحكم التلقائي في معدل التحديث (حد أقصى 1 تحديث كل 5 ثوانٍ) لتجنب إجهاد وحدة التحكم
- التخزين المؤقت للرموز (٥ دقائق) لتقليل عمليات الإدخال والإخراج للملفات
- يُبلّغ عن التقدم في التدريب الموزّع فقط المرتبة 0
- الفشل الصامت - لن تُسبّب مشاكل الشبكة انقطاعاً في التدريب

يمكن تعطيله عن طريق تعيين متغير البيئة `DISABLE_KUBEFLOW_INTEGRATION=TRUE`.

#### transformers.integrations.DVCLiveCallback[[transformers.integrations.DVCLiveCallback]]

```python
transformers.integrations.DVCLiveCallback(live: typing.Any | None = None, log_model: typing.Union[typing.Literal['all'], bool, NoneType] = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2157)

**المعاملات:**

live (`dvclive.Live`، *اختياري*، القيمة الافتراضية `None`) : كائن Live اختياري. إذا كانت القيمة None، فسيتم إنشاء كائن جديد باستخدام **kwargs.

log_model (Union[Literal["all"], bool], *اختياري*، القيمة الافتراضية `None`) : ما إذا كان سيتم استخدام `dvclive.Live.log_artifact()` لتسجيل نقاط التفتيش التي ينشئها [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer). إذا تم ضبطه على `True`، يُسجَّل نقطة التفتيش النهائية في نهاية التدريب. إذا تم ضبطه على `"all"`، يُسجَّل مجلد `output_dir` الخاص بـ [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) بالكامل عند كل نقطة تفتيش.

[TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) يرسل السجلات إلى [DVCLive](https://www.dvc.org/doc/dvclive).

استخدم متغيرات البيئة أدناه في `setup` لإعداد التكامل. لتخصيص هذا الاستدعاء الخلفي بما يتجاوز تلك متغيرات البيئة، راجع [هنا](https://dvc.org/doc/dvclive/ml-frameworks/huggingface).

#### الإعداد[[transformers.integrations.DVCLiveCallback.setup]]

```python
setup(args, state, model)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2198)

قم بإعداد تكامل DVCLive الاختياري. لتخصيص هذا الاستدعاء الخلفي بما يتجاوز متغيرات البيئة أدناه، راجع [هنا](https://dvc.org/doc/dvclive/ml-frameworks/huggingface).

البيئة:
- **HF_DVCLIVE_LOG_MODEL** (`str`، *اختياري*): ما إذا كان سيتم استخدام `dvclive.Live.log_artifact()` لتسجيل نقاط التفتيش التي ينشئها [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer). إذا تم ضبطه على `True` أو *1*، يتم تسجيل نقطة التفتيش النهائية في نهاية التدريب. إذا تم ضبطه على `all`، يتم تسجيل مجلد `output_dir` الخاص بـ [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) بالكامل عند كل نقطة تفتيش.

#### transformers.integrations.SwanLabCallback[[transformers.integrations.SwanLabCallback]]

```python
transformers.integrations.SwanLabCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2262)

A [TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) that logs metrics, media, model checkpoints to [SwanLab](https://swanlab.cn/).

#### الإعداد[[transformers.integrations.SwanLabCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/integration_utils.py#L2276)

قم بإعداد تكامل SwanLab (*swanlab*) الاختياري.

يمكن إنشاء فئة فرعية من هذه الفئة وتجاوز هذه الطريقة لتخصيص الإعداد عند الحاجة. تجد مزيدًا من المعلومات [هنا](https://docs.swanlab.cn/guide_cloud/integration/integration-huggingface-transformers.html).

يمكنك أيضًا تجاوز متغيرات البيئة التالية. تجد مزيدًا من المعلومات حول متغيرات البيئة [هنا](https://docs.swanlab.cn/en/api/environment-variable.html#environment-variables)

البيئة:
- **SWANLAB_API_KEY** (`str`، *اختياري*، القيمة الافتراضية `None`): مفتاح واجهة برمجة التطبيقات السحابية. أثناء تسجيل الدخول، يتم التحقق من متغير البيئة هذا أولاً. إذا لم يكن موجوداً، يتحقق النظام مما إذا كان المستخدم مسجلاً بالفعل. وإذا لم يكن كذلك، يبدأ عملية تسجيل الدخول.

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

- **SWANLAB_PROJECT** (`str`، *اختياري*، القيمة الافتراضية `None`): اضبط هذا على نص مخصص لتخزين النتائج في مشروع مختلف. إذا لم يُحدد، فسيتم استخدام اسم المجلد الحالي قيد التشغيل.

- **SWANLAB_LOG_DIR** (`str`، *اختياري*، القيمة الافتراضية `swanlog`): تحدد هذه المتغيّرة البيئية مسار تخزين ملفات السجلات عند التشغيل في الوضع المحلي. افتراضيًا، تُحفظ السجلات في مجلد باسم swanlog ضمن المجلد العامل.

- **SWANLAB_MODE** (`Literal["local", "cloud", "disabled"]`، *اختياري*، القيمة الافتراضية `cloud`): وضع تحليل SwanLab، والذي يتضمن استدعاءات مسجّلة من قِبل المشغّل. حالياً، هناك ثلاثة أوضاع: local وcloud وdisabled. ملاحظة: حساس لحالة الأحرف. تجد مزيداً من المعلومات [هنا](https://docs.swanlab.cn/en/api/py-init.html#swanlab-init)

- **SWANLAB_LOG_MODEL** (`str`، *اختياري*، القيمة الافتراضية `None`): لا يدعم SwanLab حاليًا وظيفة وضع الحفظ. ستكون هذه الميزة متاحة في إصدار مستقبلي

- **SWANLAB_WEB_HOST** (`str`، *اختياري*، القيمة الافتراضية `None`): عنوان الويب لبيئة SwanLab السحابية للإصدار الخاص (وهو مجاني)

- **SWANLAB_API_HOST** (`str`، *اختياري*، القيمة الافتراضية `None`): عنوان واجهة برمجة التطبيقات (API) لبيئة SwanLab السحابية للنسخة الخاصة (وهي مجانية)

- **SWANLAB_RUN_ID** (`str`، *اختياري*، القيمة الافتراضية `None`): معرّف التجربة لاستئناف تشغيل سابق. يُستخدم مع `SWANLAB_RESUME` لمواصلة تجربة قائمة.

- **SWANLAB_RESUME** (`str`، *اختياري*، القيمة الافتراضية `None`): وضع الاستئناف (`"must"`، `"allow"`، `"never"`). تكون القيمة الافتراضية `"allow"` عند استخدام `resume_from_checkpoint`.

## TrainerCallback[[transformers.TrainerCallback]]

#### transformers.TrainerCallback[[transformers.TrainerCallback]]

```python
transformers.TrainerCallback()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L295)

**المعاملات:**

args ([TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments)) : حُجج التدريب المستخدمة لإنشاء [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer).

state ([TrainerState](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerState)) : الحالة الحالية لـ [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer).

control ([TrainerControl](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerControl)) : الكائن الذي يُعاد إلى [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) ويمكن استخدامه لاتخاذ بعض القرارات.

model ([PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel) أو `torch.nn.Module`) : النموذج قيد التدريب.

processing_class ([`PreTrainedTokenizer` أو `BaseImageProcessor` أو `ProcessorMixin` أو `FeatureExtractionMixin`]) : فئة المعالجة المستخدمة لتشفير البيانات. يمكن أن تكون مُشفِّرًا (tokenizer) أو مُعالِجًا (processor) أو مُعالِج صور (image processor) أو مستخرج ميزات (feature extractor).

optimizer (`torch.optim.Optimizer`) : المُحسِّن المستخدم في خطوات التدريب.

lr_scheduler (`torch.optim.lr_scheduler.LambdaLR`) : الجدولة المستخدمة لضبط معدل التعلم.

train_dataloader (`torch.utils.data.DataLoader`، *اختياري*) : مُحمِّل البيانات الحالي المستخدم للتدريب.

eval_dataloader (`torch.utils.data.DataLoader`، *اختياري*) : مُحمِّل البيانات الحالي المستخدم للتقييم.

metrics (`dict[str, float]`) : المقاييس التي تم حسابها في مرحلة التقييم الأخيرة. لا يمكن الوصول إليها إلا في الحدث `on_evaluate`.

logs  (`dict[str, float]`) : القيم المراد تسجيلها.  لا يمكن الوصول إليها إلا في الحدث `on_log`.

فئة مخصصة للكائنات التي تفحص حالة حلقة التدريب عند بعض الأحداث وتتخذ بعض القرارات. عند كل من هذه الأحداث، تكون الحُجج التالية متاحة:

يُعدّ كائن `control` الكائن الوحيد الذي يمكن تغييره بواسطة الاستدعاء العكسي، وفي هذه الحالة يجب أن يعيد الحدث الذي يُجري التغيير النسخة المعدّلة.

الحجج `args` و`state` و`control` هي حجج موضعية لجميع الأحداث، بينما تُجمَّع جميع الحجج الأخرى في `kwargs`. يمكنك فكّ حزم ما تحتاجه منها في توقيع الحدث باستخدامها. كمثال، راجع كود [PrinterCallback](/docs/transformers/main/ar/main_classes/callback#transformers.PrinterCallback) البسيط.

مثال:

```python
class PrinterCallback(TrainerCallback):
    def on_log(self, args, state, control, logs=None, **kwargs):
        _ = logs.pop("total_flos", None)
        if state.is_local_process_zero:
            print(logs)
```

#### on_epoch_begin[[transformers.TrainerCallback.on_epoch_begin]]

```python
on_epoch_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L361)

حدث يُستدعى في بداية حقبة.

#### on_epoch_end[[transformers.TrainerCallback.on_epoch_end]]

```python
on_epoch_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L366)

حدث يُستدعى في نهاية حقبة.

#### on_evaluate[[transformers.TrainerCallback.on_evaluate]]

```python
on_evaluate(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L398)

حدث يُستدعى بعد مرحلة التقييم.

#### on_init_end[[transformers.TrainerCallback.on_init_end]]

```python
on_init_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L346)

حدث يُستدعى في نهاية تهيئة [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer).

#### on_log[[transformers.TrainerCallback.on_log]]

```python
on_log(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L413)

حدث يُستدعى بعد تسجيل السجلات الأخيرة.

#### on_optimizer_step[[transformers.TrainerCallback.on_optimizer_step]]

```python
on_optimizer_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L382)

حدث يُستدعى بعد خطوة المُحسِّن وقبل تصفير التدرّجات. مفيد لمراقبة التدرّجات.

#### on_pre_optimizer_step[[transformers.TrainerCallback.on_pre_optimizer_step]]

```python
on_pre_optimizer_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L377)

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

#### on_predict[[transformers.TrainerCallback.on_predict]]

```python
on_predict(args: TrainingArguments, state: TrainerState, control: TrainerControl, metrics, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L403)

حدث يُستدعى بعد تنبؤ ناجح.

#### on_prediction_step[[transformers.TrainerCallback.on_prediction_step]]

```python
on_prediction_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L418)

حدث يُستدعى بعد خطوة التنبؤ.

#### on_push_begin[[transformers.TrainerCallback.on_push_begin]]

```python
on_push_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L423)

Event called before pushing the model to the hub, at the beginning of Trainer.push_to_hub and Trainer._push_from_checkpoint.

#### on_save[[transformers.TrainerCallback.on_save]]

```python
on_save(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L408)

حدث يُستدعى بعد حفظ نقطة التفتيش.

#### on_step_begin[[transformers.TrainerCallback.on_step_begin]]

```python
on_step_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L371)

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

#### on_step_end[[transformers.TrainerCallback.on_step_end]]

```python
on_step_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L392)

حدث يُستدعى في نهاية خطوة تدريب. عند استخدام تراكم التدرجات، قد تتطلب خطوة تدريب واحدة عدة مدخلات.

#### on_substep_end[[transformers.TrainerCallback.on_substep_end]]

```python
on_substep_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L387)

حدث يُستدعى في نهاية خطوة فرعية أثناء تراكم التدرجات.

#### on_train_begin[[transformers.TrainerCallback.on_train_begin]]

```python
on_train_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L351)

حدث يُستدعى في بداية التدريب.

#### on_train_end[[transformers.TrainerCallback.on_train_end]]

```python
on_train_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L356)

حدث يُستدعى في نهاية التدريب.

فيما يلي مثال على كيفية تسجيل استجابة مخصصة مع [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) في PyTorch:

```python
class MyCallback(TrainerCallback):
    "A callback that prints a message at the beginning of training"

    def on_train_begin(self, args, state, control, **kwargs):
        print("Starting training")

trainer = Trainer(
    model,
    args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    callbacks=[MyCallback],  # We can either pass the callback class this way or an instance of it (MyCallback())
)
```

طريقة أخرى لتسجيل مستدع هي استدعاء `trainer.add_callback()` على النحو التالي:

```python
trainer = Trainer(...)
trainer.add_callback(MyCallback)
# Alternatively, we can pass an instance of the callback class
trainer.add_callback(MyCallback())
```

## TrainerState[[transformers.TrainerState]]

#### transformers.TrainerState[[transformers.TrainerState]]

```python
transformers.TrainerState(epoch: float = 0, global_step: int = 0, max_steps: int = 0, logging_steps: int = 500, eval_steps: int = 500, save_steps: int = 500, train_batch_size: int | None = None, num_train_epochs: int = 0, num_input_tokens_seen: int = 0, total_flos: float = 0, log_history: list = None, best_metric: float | None = None, best_global_step: int | None = None, best_model_checkpoint: str | None = None, is_local_process_zero: bool = True, is_world_process_zero: bool = True, is_hyper_param_search: bool = False, trial_name: str | None = None, trial_params: dict[str, str | float | int | bool] | None = None, stateful_callbacks: list['TrainerCallback'] | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L35)

**المعاملات:**

epoch (`float`، *اختياري*) : يُضبط فقط أثناء التدريب، ويمثل الحقبة التي يتواجد فيها التدريب (حيث يمثل الجزء الكسري نسبة إتمام الحقبة الحالية).

global_step (`int`، *اختياري*، القيمة الافتراضية 0) : أثناء التدريب، يمثل عدد خطوات التحديث المكتملة.

max_steps (`int`، *اختياري*، القيمة الافتراضية 0) : عدد خطوات التحديث التي يجب تنفيذها خلال التدريب الحالي.

logging_steps (`int`، *اختياري*، القيمة الافتراضية 500) : تسجيل كل X خطوات تحديث

eval_steps (`int`، *اختياري*) : تشغيل التقييم كل X خطوات.

save_steps (`int`، *اختياري*، القيمة الافتراضية 500) : حفظ نقطة تفتيش كل X خطوات تحديث.

train_batch_size (`int`، *اختياري*) : حجم الدفعة (batch size) الخاص بمحمّل بيانات التدريب. لا يُطلب إلا عند استخدام `auto_find_batch_size`.

num_input_tokens_seen (`int`، *اختياري*، القيمة الافتراضية 0) : عند تتبع رموز المدخلات، عدد الرموز التي شوهدت أثناء التدريب (عدد رموز المدخلات، وليس عدد رموز التنبؤ).

total_flos (`float`، *اختياري*، القيمة الافتراضية 0) : إجمالي عدد العمليات العائمة التي نفذها النموذج منذ بداية التدريب (تُخزَّن كأرقام عائمة لتجنب تجاوز الحد الأقصى).

log_history (`list[dict[str, float]]`، *اختياري*) : قائمة السجلات التي تم إنشاؤها منذ بداية التدريب.

best_metric (`float`، *اختياري*) : عند تتبع أفضل نموذج، قيمة أفضل مقياس تم العثور عليه حتى الآن.

best_global_step (`int`، *اختياري*) : عند تتبع أفضل نموذج، الخطوة التي تم فيها رصد أفضل مقياس. يُستخدم لضبط `best_model_checkpoint`.

best_model_checkpoint (`str`، *اختياري*) : عند تتبع أفضل نموذج، قيمة اسم نقطة التفتيش (checkpoint) لأفضل نموذج تم العثور عليه حتى الآن.

is_local_process_zero (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان هذا العملية هي العملية الرئيسية المحلية (على سبيل المثال، على جهاز واحد إذا كان التدريب يتم بطريقة موزعة على عدة أجهزة).

is_world_process_zero (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كانت هذه العملية هي العملية الرئيسية العامة (عند التدريب بطريقة موزعة على عدة أجهزة، لن تكون `True` إلا لعملية واحدة).

is_hyper_param_search (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كنا في مرحلة البحث عن المعلمات الفائقة باستخدام Trainer.hyperparameter_search. سيؤثر هذا على طريقة تسجيل البيانات في TensorBoard.

stateful_callbacks (`list[StatefulTrainerCallback]`، *اختياري*) : المراجعات (Callbacks) المرتبطة بـ `Trainer` والتي يجب حفظ حالاتها أو استعادتها. يجب أن تنفّذ المراجعات ذات الصلة دالة `state` ودالة `from_state`.

فئة تحتوي على الحالة الداخلية لـ [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) التي سيتم حفظها مع النموذج والمُحسِّن عند إنشاء نقاط التفتيش، وتُمرَّر إلى [TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback).

في هذه الفئة بأكملها، يُفهم أن الخطوة الواحدة تعني خطوة تحديث واحدة. عند استخدام تراكم التدرجات، قد تتطلب خطوة التحديث الواحدة عدة تمريرات أمامية وخلفية: إذا استخدمت `gradient_accumulation_steps=n`، فإن خطوة التحديث الواحدة تتطلب المرور عبر *n* دفعات.

#### compute_steps[[transformers.TrainerState.compute_steps]]

```python
compute_steps(args, max_steps)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L156)

يُحسب القيمة المطلقة ويخزّنها لخطوات التسجيل والتقييم والحفظ، بناءً على ما إذا كانت نسبةً أم لا.

#### init_training_references[[transformers.TrainerState.init_training_references]]

```python
init_training_references(trainer, max_steps, num_train_epochs, trial)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L169)

يخزّن المراجع الأولية للتدريب المطلوبة في `self`

#### load_from_json[[transformers.TrainerState.load_from_json]]

```python
load_from_json(json_path: str)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L149)

أنشئ مثيلًا من محتوى `json_path`.

#### save_to_json[[transformers.TrainerState.save_to_json]]

```python
save_to_json(json_path: str)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L143)

احفظ محتوى هذه الكائن في صيغة JSON داخل `json_path`.

## TrainerControl[[transformers.TrainerControl]]

#### transformers.TrainerControl[[transformers.TrainerControl]]

```python
transformers.TrainerControl(should_training_stop: bool = False, should_epoch_stop: bool = False, should_save: bool = False, should_evaluate: bool = False, should_log: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L234)

**المعاملات:**

should_training_stop (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب مقاطعة التدريب أم لا. إذا كانت `True`، فلن تُعاد ضبط هذه المتغيّرة إلى `False`. سيتوقف التدريب ببساطة.

should_epoch_stop (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان ينبغي مقاطعة الحقبة الحالية أم لا. إذا كانت `True`، فسيتم إعادة تعيين هذا المتغير إلى `False` في بداية الحقبة التالية.

should_save (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب حفظ النموذج في هذه الخطوة أم لا. إذا كانت القيمة `True`، فسيتم إعادة تعيين هذا المتغير إلى `False` في بداية الخطوة التالية.

should_evaluate (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب تقييم النموذج في هذه الخطوة أم لا. إذا كانت القيمة `True`، فسيتم إعادة تعيين هذا المتغير إلى `False` في بداية الخطوة التالية.

should_log (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب الإبلاغ عن السجلات في هذه الخطوة أم لا. إذا كانت `True`، فسيتم إعادة تعيين هذا المتغير إلى `False` في بداية الخطوة التالية.

فئة تتولى تدفق التحكم في [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer). تُستخدم هذه الفئة بواسطة [TrainerCallback](/docs/transformers/main/ar/main_classes/callback#transformers.TrainerCallback) لتفعيل بعض المفاتيح في حلقة التدريب.