# استكشاف الأخطاء

قد تحدث أخطاء في بعض الأحيان، لكننا هنا للمساعدة! يغطي هذا الدليل بعضًا من أكثر المشكلات شيوعًا التي واجهناها وكيفية حلها. ومع ذلك، لا يُقصد بهذا الدليل أن يكون مجموعة شاملة لكل مشكلة في 🤗 Transformers. للحصول على مزيد من المساعدة في استكشاف مشكلتك وحلها، جرّب ما يلي:

1. الطلب على المساعدة في [المنتديات](https://discuss.huggingface.co/). توجد فئات محددة يمكنك نشر سؤالك فيها، مثل [المبتدئون](https://discuss.huggingface.co/c/beginners/5) أو [🤗 Transformers](https://discuss.huggingface.co/c/transformers/9). تأكد من كتابة منشور وصفي جيد في المنتدى يتضمن بعض الأكواد القابلة للتكرار لتعظيم احتمالية حل مشكلتك!

2. أنشئ [قضية](https://github.com/huggingface/transformers/issues/new/choose) في مستودع 🤗 Transformers إذا كان الأمر يتعلق بخطأ في المكتبة. حاول تضمين أكبر قدر ممكن من المعلومات التي تصف الخطأ لمساعدتنا على تحديد المشكلة بشكل أفضل ومعرفة كيفية إصلاحها.

3. إذا كنت تستخدم إصدارًا أقدم من 🤗 Transformers، فراجع دليل [النقل](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md) نظرًا لأن بعض التغييرات المهمة قد أُدخلت بين الإصدارات.

لمزيد من التفاصيل حول استكشاف الأخطاء وإصلاحها والحصول على المساعدة، راجع [الفصل 8](https://huggingface.co/course/chapter8/1?fw=pt) من دورة Hugging Face.

## البيئات المحمية بجدران نارية

تُقيَّد بعض وحدات المعالجة الرسومية (GPU) في بيئات السحابة والشبكات الداخلية بجدران حماية تمنع الاتصالات الخارجية، مما يؤدي إلى حدوث خطأ في الاتصال. عند محاولة سكربتك تنزيل أوزان النموذج أو مجموعات البيانات، سيعلق التنزيل ثم ينتهي بوقت انتهاء الصلاحية مع الرسالة التالية:

```text
ValueError: Connection error, and we cannot find the requested files in the cached path.
Please try again or make sure your Internet connection is on.
```

في هذه الحالة، يجب أن تحاول تشغيل 🤗 Transformers في [الوضع دون اتصال](installation#offline-mode) لتجنب خطأ الاتصال.

## نفاد ذاكرة CUDA

قد يكون تدريب نماذج كبيرة تحتوي على ملايين المعلمات أمراً صعباً دون توفر العتاد المناسب. خطأ شائع قد تواجهه عندما تنفد ذاكرة وحدة معالجة الرسوميات (GPU) هو:

```text
CUDA out of memory. Tried to allocate 256.00 MiB (GPU 0; 11.17 GiB total capacity; 9.70 GiB already allocated; 179.81 MiB free; 9.85 GiB reserved in total by PyTorch)
```

إليك بعض الحلول المحتملة التي يمكنك تجربتها لتقليل استهلاك الذاكرة:

- قلّل قيمة [per_device_train_batch_size](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments.per_device_train_batch_size) في [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments).
- جرّب استخدام [gradient_accumulation_steps](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments.gradient_accumulation_steps) في [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) لزيادة حجم الدفعة الإجمالي بشكل فعال.

راجع [نظرة عامة على التحسين](optimization_overview) لمزيد من التفاصيل حول تقنيات توفير الذاكرة.

## ImportError

خطأ شائع آخر قد تواجهه، لا سيما إذا كان النموذج حديث الإصدار، هو `ImportError`:

```text
ImportError: cannot import name 'ImageGPTImageProcessor' from 'transformers' (unknown location)
```

بالنسبة لأنواع الأخطاء هذه، تأكد من أنك قمت بتثبيت أحدث إصدار من 🤗 Transformers للوصول إلى أحدث النماذج:

```bash
pip install transformers --upgrade
```

## خطأ CUDA: تم تفعيل المطالبة على جانب الجهاز

قد تواجه أحيانًا خطأً عامًا في CUDA يتعلق بخطأ في كود الجهاز.

```text
RuntimeError: CUDA error: device-side assert triggered
```

يجب أن تحاول تشغيل الكود على وحدة المعالجة المركزية (CPU) أولاً للحصول على رسالة خطأ أكثر تفصيلاً. أضف متغير البيئة التالي إلى بداية الكود للتبديل إلى وحدة المعالجة المركزية:

```py
>>> import os

>>> os.environ["CUDA_VISIBLE_DEVICES"] = ""
```

خيار آخر هو الحصول على أثر أخطاء (traceback) أدق من وحدة معالجة الرسوميات (GPU). أضف متغير البيئة التالي في بداية كودك لجعل أثر الأخطاء يشير إلى مصدر الخطأ:

```py
>>> import os

>>> os.environ["CUDA_LAUNCH_BLOCKING"] = "1"
```

## إخراج غير صحيح عند عدم إخفاء رموز الحشو

في بعض الحالات، قد تكون المخرجات `hidden_state` غير صحيحة إذا تضمنت `input_ids` رموز حشو. ولإيضاح ذلك، قم بتحميل نموذج ومُرمِّز. يمكنك الوصول إلى `pad_token_id` للنموذج لمعرفة قيمته. قد تكون `pad_token_id` بقيمة `None` لبعض النماذج، لكن يمكنك دائمًا ضبطها يدويًا.

```py
>>> from transformers import AutoModelForSequenceClassification
>>> import torch

>>> model = AutoModelForSequenceClassification.from_pretrained("google-bert/bert-base-uncased")
>>> model.config.pad_token_id
0
```

يُظهر المثال التالي المخرجات دون إخفاء رموز الحشو:

```py
>>> input_ids = torch.tensor([[7592, 2057, 2097, 2393, 9611, 2115], [7592, 0, 0, 0, 0, 0]])
>>> output = model(input_ids)
>>> print(output.logits)
tensor([[ 0.0082, -0.2307],
        [ 0.1317, -0.1683]], grad_fn=<AddmmBackward0>)
```

إليك المخرجات الفعلية للترتيب الثاني:

```py
>>> input_ids = torch.tensor([[7592]])
>>> output = model(input_ids)
>>> print(output.logits)
tensor([[-0.1008, -0.4061]], grad_fn=<AddmmBackward0>)
```

في معظم الأحيان، يجب أن تزوّد نموذجك بـ`attention_mask` لتجاهل رموز الحشو (padding) وتجنّب هذا الخطأ الصامت. الآن يطابق ناتج التسلسل الثاني ناتجه الفعلي:

بشكل افتراضي، ينشئ مُجزِّئ الرموز `attention_mask` نيابةً عنك بناءً على الإعدادات الافتراضية الخاصة بمُجزِّئ الرموز الذي تستخدمه.

```py
>>> attention_mask = torch.tensor([[1, 1, 1, 1, 1, 1], [1, 0, 0, 0, 0, 0]])
>>> output = model(input_ids, attention_mask=attention_mask)
>>> print(output.logits)
tensor([[ 0.0082, -0.2307],
        [-0.1008, -0.4061]], grad_fn=<AddmmBackward0>)
```

لا يقوم 🤗 Transformers تلقائيًا بإنشاء `attention_mask` لإخفاء رمز التعبئة إذا تم توفيره، وذلك للأسباب التالية:

- بعض النماذج لا تحتوي على رمز تعبئة.
- في بعض حالات الاستخدام، يرغب المستخدمون في أن يولي النموذج اهتمامًا لرمز الحشو.

## ValueError: فئة الإعداد XYZ غير معروفة لهذا النوع من AutoModel

بشكل عام، ننصح باستخدام فئة [AutoModel](/docs/transformers/main/ar/model_doc/auto#transformers.AutoModel) لتحميل النماذج المدربة مسبقًا. يمكن لهذه الفئة الاستدلال تلقائيًا على البنية الصحيحة وتحميلها من نقطة تحقق محددة بناءً على الإعدادات. إذا واجهت هذا الخطأ `ValueError` عند تحميل نموذج من نقطة تحقق، فهذا يعني أن فئة Auto لم تتمكن من إيجاد تطابق بين الإعدادات في نقطة التحقق المحددة ونوع النموذج الذي تحاول تحميله. في الغالب، يحدث هذا عندما لا تدعم نقطة تحقق مهمة معينة. على سبيل المثال، ستظهر لك هذه الرسالة في المثال التالي لأنه لا يوجد نموذج GPT2 مخصص للإجابة على الأسئلة:

```py
>>> from transformers import AutoProcessor, AutoModelForQuestionAnswering

>>> processor = AutoProcessor.from_pretrained("openai-community/gpt2-medium")
>>> model = AutoModelForQuestionAnswering.from_pretrained("openai-community/gpt2-medium")
ValueError: Unrecognized configuration class <class 'transformers.models.gpt2.configuration_gpt2.GPT2Config'> for this kind of AutoModel: AutoModelForQuestionAnswering.
Model type should be one of AlbertConfig, BartConfig, BertConfig, BigBirdConfig, BigBirdPegasusConfig, BloomConfig, ...
```