# أدوات Trainer

تُدرج هذه الصفحة جميع دوال الأداة المستخدمة في [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer).

لا تُفيد معظم تلك العناصر إلا إذا كنت تدرس كود Trainer في المكتبة.

## أدوات[[transformers.EvalPrediction]]

#### transformers.EvalPrediction[[transformers.EvalPrediction]]

```python
transformers.EvalPrediction(predictions: numpy.ndarray | tuple[numpy.ndarray], label_ids: numpy.ndarray | tuple[numpy.ndarray], inputs: numpy.ndarray | tuple[numpy.ndarray] | None = None, losses: numpy.ndarray | tuple[numpy.ndarray] | None = None)
```

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

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

predictions (`np.ndarray`) : تنبؤات النموذج.

label_ids (`np.ndarray`) : الأهداف المراد مطابقتها.

inputs (`np.ndarray`، *اختياري*) : بيانات الإدخال المُمرَّرة إلى النموذج.

losses (`np.ndarray`، *اختياري*) : قيم الخسارة المحسوبة أثناء التقييم.

مخرجات التقييم (تحتوي دائمًا على التسميات)، لاستخدامها في حساب المقاييس.

#### transformers.IntervalStrategy[[transformers.IntervalStrategy]]

```python
transformers.IntervalStrategy(value, names = None, module = None, qualname = None, type = None, start = 1, boundary = None)
```

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

#### transformers.enable_full_determinism[[transformers.enable_full_determinism]]

```python
transformers.enable_full_determinism(seed: int, warn_only: bool = False)
```

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

دالة مساعدة لضمان سلوك قابل للتكرار أثناء التدريب الموزّع. راجع https://pytorch.org/docs/stable/notes/randomness.html للحصول على معلومات حول PyTorch

#### transformers.set_seed[[transformers.set_seed]]

```python
transformers.set_seed(seed: int, deterministic: bool = False)
```

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

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

seed (`int`) : البذرة التي يجب تعيينها.

deterministic (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب استخدام الخوارزميات الحتمية حيثما توفرت. قد يؤدي ذلك إلى إبطاء التدريب.

دالة مساعدة لضمان سلوك قابل للتكرار من خلال تعيين البذرة في `random` و`numpy` و`torch` (إذا كانت مثبتة).

#### transformers.torch_distributed_zero_first[[transformers.torch_distributed_zero_first]]

```python
transformers.torch_distributed_zero_first(local_rank: int)
```

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

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

local_rank (`int`) : رتبة العملية المحلية.

مُزيِّن لجعل جميع العمليات في التدريب الموزّع تنتظر كل local_master لتنفيذ شيء ما.

## التفاصيل الداخلية للمكالمات[[transformers.trainer_callback.CallbackHandler]]

#### transformers.trainer_callback.CallbackHandler[[transformers.trainer_callback.CallbackHandler]]

```python
transformers.trainer_callback.CallbackHandler(callbacks, model, processing_class, optimizer, lr_scheduler)
```

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

فئة داخلية تستدعي قائمة المراجعات (callbacks) بالترتيب فقط.

## محلل حجة Trainer[[transformers.HfArgumentParser]]

#### transformers.HfArgumentParser[[transformers.HfArgumentParser]]

```python
transformers.HfArgumentParser(dataclass_types: typing.Union[transformers.hf_argparser.DataClassType, collections.abc.Iterable[transformers.hf_argparser.DataClassType], NoneType] = None, **kwargs)
```

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

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

dataclass_types (`DataClassType` أو `Iterable[DataClassType]`، *اختياري*) : نوع dataclass، أو قائمة بأنواع dataclass التي سنقوم بـ"ملء" أمثلتها بالقيم المُحلَّلة.

kwargs (`dict[str, Any]`، *اختياري*) : يُمرَّر إلى `argparse.ArgumentParser()` بالطريقة المعتادة.

تستخدم هذه الفئة الفرعية من `argparse.ArgumentParser` تلميحات الأنواع على فئات البيانات (dataclasses) لتوليد الحجج.

صُمِّم هذا الصنف ليتوافق بشكل جيد مع argparse الأصلي. على وجه التحديد، يمكنك إضافة المزيد من الحُجج (غير المدعومة بواسطة dataclass) إلى المُحلِّل بعد التهيئة، وستحصل على المخرجات بعد التحليل كفضاء أسماء إضافي. اختياري: لإنشاء مجموعات حُجج فرعية، استخدم خاصية `_argument_group_name` في dataclass.

#### parse_args_into_dataclasses[[transformers.HfArgumentParser.parse_args_into_dataclasses]]

```python
parse_args_into_dataclasses(args = None, return_remaining_strings = False, look_for_args_file = True, args_filename = None, args_file_flag = None)
```

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

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

args : قائمة من السلاسل النصية التي سيتم تحليلها. القيمة الافتراضية مأخوذة من sys.argv. (نفس argparse.ArgumentParser)

return_remaining_strings : إذا كانت القيمة صحيحة، فسيتم أيضًا إرجاع قائمة بسلاسل الحروف المتبقية.

look_for_args_file : إذا كانت القيمة صحيحة، فسيبحث عن ملف ".args" يحمل الاسم الأساسي نفسه لسكربت نقطة الدخول الخاص بهذه العملية، وسيضيف محتواه المحتمل إلى معاملات سطر الأوامر.

args_filename : إذا لم تكن القيمة None، فسيتم استخدام هذا الملف بدلاً من ملف ".args" المحدد في الحجة السابقة.

args_file_flag : إذا لم تكن القيمة None، فسيتم البحث عن ملف في معاملات سطر الأوامر المحددة بواسطة هذا العلم. يمكن تحديد العلم عدة مرات، ويُحدَّد الأولوية بناءً على الترتيب (يُعتدّ بالآخر).

**يعيد:** `Tuple consisting of`

- أمثلة dataclass بنفس الترتيب الذي تم تمريرها به إلى المُهيِّئ.
- إذا كان ذلك ينطبق، فمساحة أسماء إضافية لمزيد من الحُجج (غير المدعومة بواسطة dataclass) التي أُضيفت إلى المُحلِّل بعد التهيئة.
- القائمة المحتملة لسلاسل الحجة المتبقية. (نفس argparse.ArgumentParser.parse_known_args)

تحليل حُجج سطر الأوامر إلى كائنات من أنواع dataclass المحددة.

يعتمد هذا على `ArgumentParser.parse_known_args` الخاص بـ argparse. راجع التوثيق في: docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args

#### parse_dict[[transformers.HfArgumentParser.parse_dict]]

```python
parse_dict(args: dict, allow_extra_keys: bool = False)
```

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

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

args (`dict`) : قاموس يحتوي على قيم الإعداد

allow_extra_keys (`bool`، *اختياري*، القيمة الافتراضية `False`) : القيمة الافتراضية هي False. إذا كانت False، فسيتم رفع استثناء إذا احتوت القاموس على مفاتيح غير محللة.

**يعيد:** `Tuple consisting of`

- أمثلة dataclass بنفس الترتيب الذي تم تمريرها به إلى المُهيِّئ.

طريقة مساعدة بديلة لا تستخدم `argparse` إطلاقاً، بل تعتمد على قاموس (dict) وملء أنواع dataclass.

#### parse_json_file[[transformers.HfArgumentParser.parse_json_file]]

```python
parse_json_file(json_file: str | os.PathLike, allow_extra_keys: bool = False)
```

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

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

json_file (`str` أو `os.PathLike`) : اسم ملف json الذي سيتم تحليله

allow_extra_keys (`bool`، *اختياري*، القيمة الافتراضية `False`) : القيمة الافتراضية هي False. إذا كانت False، فسيتم رفع استثناء إذا احتوى ملف json على مفاتيح غير مُحلَّلة.

**يعيد:** `Tuple consisting of`

- أمثلة dataclass بنفس الترتيب الذي تم تمريرها به إلى المُهيِّئ.

طريقة مساعدة بديلة لا تستخدم `argparse` إطلاقاً، بل تقوم بدلاً من ذلك بتحميل ملف json وملء أنواع dataclass.

#### parse_yaml_file[[transformers.HfArgumentParser.parse_yaml_file]]

```python
parse_yaml_file(yaml_file: str | os.PathLike, allow_extra_keys: bool = False)
```

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

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

yaml_file (`str` أو `os.PathLike`) : اسم ملف yaml الذي سيتم تحليله

allow_extra_keys (`bool`، *اختياري*، القيمة الافتراضية `False`) : القيمة الافتراضية هي False. إذا كانت False، فسيتم رفع استثناء إذا احتوى ملف json على مفاتيح غير مُحلَّلة.

**يعيد:** `Tuple consisting of`

- أمثلة dataclass بنفس الترتيب الذي تم تمريرها به إلى المُهيِّئ.

طريقة مساعدة بديلة لا تستخدم `argparse` إطلاقاً، بل تقوم بدلاً من ذلك بتحميل ملف yaml وملء أنواع dataclass.

## أدوات التصحيح[[transformers.debug_utils.DebugUnderflowOverflow]]

#### transformers.debug_utils.DebugUnderflowOverflow[[transformers.debug_utils.DebugUnderflowOverflow]]

```python
transformers.debug_utils.DebugUnderflowOverflow(model, max_frames_to_save = 21, trace_batch_nums = None, abort_after_batch_num = None)
```

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

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

model (`nn.Module`) : النموذج المراد تصحيحه.

max_frames_to_save (`int`, *اختياري*، القيمة الافتراضية 21) : عدد الإطارات التي يجب تسجيلها من الماضي

trace_batch_nums(`list[int]`، *اختياري*، الافتراضي `[]`) : أرقام الدفعات المراد تتبّعها (يُعطّل اكتشاف الدور)

abort_after_batch_num  (`int``, *اختياري*) : ما إذا كان يجب إنهاء العملية بعد اكتمال رقم دفعة معين

تساعد هذه الفئة في التصحيح على اكتشاف وفهم المكان الذي تبدأ فيه أوزان النموذج وتفعيلاته في أن تصبح كبيرة جداً أو صغيرة جداً، والأهم من ذلك العناصر التي تكون قيمتها `nan` أو `inf`.

هناك وضعان للعمل:

1. كشف عن نقص/فائض التدفق (افتراضي)
2. تتبع الحد الأدنى/الحد الأقصى المطلق للدفعة المحددة دون كشف

الوضع 1: كشف عن/تجاوز الحدود

لتفعيل كشف النقص/الزيادة، قم بتهيئة الكائن مع النموذج:

```python
debug_overflow = DebugUnderflowOverflow(model)
```

ثم قم بتشغيل التدريب بشكل طبيعي، وإذا تم اكتشاف `nan` أو `inf` في عنصر واحد على الأقل من عناصر الأوزان أو المدخلات أو المخرجات، فسيقوم هذا الوحدة بإلقاء استثناء وطباعة `max_frames_to_save` إطارًا تؤدي إلى هذا الحدث، مع الإبلاغ في كل إطار عن

1. اسم الوحدة الكامل بالإضافة إلى اسم الفئة التي تم تنفيذ `forward` الخاصة بها
2. القيمة الدنيا والعليا المطلقة لجميع العناصر في أوزان كل وحدة، والمدخلات والمخرجات

على سبيل المثال، فيما يلي الترويسة والأطر الأخيرة في تقرير الكشف الخاص بتشغيل `google/mt5-small` في fp16

الدقة المختلطة:

```
Detected inf/nan during batch_number=0
Last 21 forward frames:
abs min  abs max  metadata
[...]
                  encoder.block.2.layer.1.DenseReluDense.wi_0 Linear
2.17e-07 4.50e+00 weight
1.79e-06 4.65e+00 input[0]
2.68e-06 3.70e+01 output
                  encoder.block.2.layer.1.DenseReluDense.wi_1 Linear
8.08e-07 2.66e+01 weight
1.79e-06 4.65e+00 input[0]
1.27e-04 2.37e+02 output
                  encoder.block.2.layer.1.DenseReluDense.wo Linear
1.01e-06 6.44e+00 weight
0.00e+00 9.74e+03 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.DenseReluDense T5DenseGatedGeluDense
1.79e-06 4.65e+00 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.dropout Dropout
3.18e-04 6.27e+04 input[0]
0.00e+00      inf output
```

يمكنك أن ترى هنا أن `T5DenseGatedGeluDense.forward` نتج عنه تنشيطات مخرجات، كان أقصى قيمة مطلقة لها حوالي 62.7 ألف، وهو قريب جداً من الحد الأقصى لـ fp16 البالغ 64 ألف. في الإطار التالي لدينا `Dropout` الذي يعيد تطبيع الأوزان بعد أن صفر بعض العناصر، مما يدفع أقصى قيمة مطلقة إلى أكثر من 64 ألف، فنحصل على تجاوز.

كما ترون، فإن الإطارات السابقة هي التي نحتاج إلى فحصها عندما تبدأ الأرقام في الوصول إلى قيم كبيرة جداً بالنسبة لأرقام fp16.

يتم تنفيذ التتبع في خطاف أمامي (forward hook) يُستدعى فور اكتمال `forward`.

بشكل افتراضي، يتم طباعة آخر 21 إطارًا. يمكنك تغيير الإعداد الافتراضي لتلبية احتياجاتك. على سبيل المثال:

```python
debug_overflow = DebugUnderflowOverflow(model, max_frames_to_save=100)
```

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

الوضع 2. تتبع الحد الأدنى/الحد الأقصى المطلق للدفعات المحددة دون اكتشاف

الوضع الثاني للعمل هو التتبع لكل دفعة مع تعطيل ميزة اكتشاف النقص/الزيادة.

لنفترض أنك تريد مراقبة القيم الدنيا والعليا المطلقة لجميع مكوّنات كل استدعاء لـ `forward` لـ

المجموعة المعطاة، وتنفيذ ذلك فقط للمجموعتين 1 و 3. ثم تقوم بإنشاء هذا الصنف على النحو التالي:

```python
debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3])
```

والآن سيتم تتبع الدفعتين الكاملتين 1 و 3 باستخدام نفس التنسيق الموضح أعلاه. تُرقَّم الدفعات بدءًا من الصفر.

يُفيدك هذا إذا كنتَ على دراية بأن البرنامج يبدأ في العمل بشكل غير صحيح بعد رقم دفعة معين، مما يتيح لك التقدّم السريع مباشرةً إلى تلك المنطقة.

الإيقاف المبكر:

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

```python
debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3], abort_after_batch_num=3)
```

تكون هذه الميزة مفيدة بشكل رئيسي في وضع التتبع، لكن يمكنك استخدامها في أي وضع.

**الأداء**:

بما أن هذا الوحدة تقيس `min`/``max` المطلقة لكل وزن في النموذج في كل تمريرة أمامية، فإنها ستبطئ عملية التدريب. لذا، تذكّر بإيقاف تشغيلها بمجرد تلبية احتياجات التصحيح.