يساعدك هذا الدليل في تشخيص المشكلات الشائعة وحلها في حالة في Gemini API وعلى مستوى عالٍ، قد تواجه مشاكل من خدمة الواجهة الخلفية لواجهة Gemini API أو حِزم تطوير البرامج (SDK) للعميل حزم تطوير البرامج (SDK) الخاصة بالعملاء مفتوح المصدر في المستودعات التالية:
- generative-ai-python
- generative-ai-js
- generative-ai-android
- generative-ai-swift
- generative-ai-dart
- generative-ai-go
في حال مواجهة مشاكل بشأن مفتاح واجهة برمجة التطبيقات، تأكَّد من أنّك ضبطت الإعدادات مفتاح واجهة برمجة التطبيقات بشكلٍ صحيح وفقًا لدليل إعداد مفتاح واجهة برمجة التطبيقات.
رموز الخطأ في خدمة الواجهة الخلفية في Gemini API
يسرد الجدول التالي رموز خطأ الخلفية الشائعة التي قد تواجهها، إلى مع تفسيرات لأسبابها وخطوات تحديد المشاكل وحلّها:
| رمز HTTP | الحالة | الوصف | مثال | الحلّ |
| 400 | INVALID_ARGUMENT | نص الطلب مكتوب بشكلٍ غير صحيح. | هناك خطأ إملائي أو هناك حقل مفقود من الحقول المطلوبة في طلبك. | يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات للاطّلاع على تنسيق الطلب والأمثلة والإصدارات المتوافقة. يمكن أن يؤدي استخدام ميزات من إصدار أحدث لواجهة برمجة التطبيقات مع نقطة نهاية قديمة إلى حدوث أخطاء. |
| 400 | FAILED_PRECONDITION | لا يتوفّر الإصدار المجاني من Gemini API في بلدك. يُرجى تفعيل الفوترة في مشروعك في Google AI Studio. | أنت تقدّم طلبًا في منطقة لا تتوفّر فيها الفئة المجانية، ولم تفعِّل الفوترة في مشروعك في Google AI Studio. | لاستخدام Gemini API، يجب إعداد خطة مدفوعة باستخدام Google AI Studio. |
| 403 | PERMISSION_DENIED | لا يتضمّن مفتاح واجهة برمجة التطبيقات الأذونات المطلوبة. | أنت تستخدم مفتاح واجهة برمجة تطبيقات خاطئًا، CANNOT TRANSLATE استخدام نموذج تم ضبطه بدون إجراء المصادقة الصحيحة. | تحقَّق من ضبط مفتاح واجهة برمجة التطبيقات وأنّ لديه إذن الوصول الصحيح. واحرص على إجراء المصادقة المناسبة لاستخدام نماذج مضبوطة. |
| 404 | NOT_FOUND | لم يتم العثور على المورد المطلوب. | لم يتم العثور على ملف صورة أو صوت أو فيديو مُشار إليه في طلبك. | تحقَّق مما إذا كانت جميع المَعلمات في طلبك صالحة لإصدار واجهة برمجة التطبيقات. |
| 429 | RESOURCE_EXHAUSTED | لقد تجاوزت الحد الأقصى لمعدّل الزحف. | أنت ترسل عددًا كبيرًا جدًا من الطلبات في الدقيقة من خلال المستوى المجاني من Gemini API. | تأكَّد من أنّك ضمن الحدّ الأقصى لمعدّل الزحف للنموذج. يمكنك طلب زيادة الحصة إذا لزم الأمر. |
| 500 | للاستخدام الداخلي | حدث خطأ غير متوقع من جانب Google. | سياق الإدخال طويل جدًا. | عليك تقليل سياق الإدخال أو التبديل مؤقتًا إلى نموذج آخر (مثل Gemini 1.5 Pro إلى Gemini 1.5 Flash) ومعرفة ما إذا كان يعمل بشكل سليم. أو يُرجى الانتظار قليلاً وإعادة محاولة تقديم الطلب. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في Google AI Studio. |
| 503 | UNAVAILABLE | قد تكون الخدمة متوقّفة أو تم تحميلها بشكل زائد مؤقتًا. | نفدت سعة الخدمة مؤقتًا. | يُرجى التبديل مؤقتًا إلى نموذج آخر (مثل Gemini 1.5 Pro إلى Gemini 1.5 Flash) ومعرفة ما إذا كان يعمل. أو يُرجى الانتظار قليلاً وإعادة محاولة تقديم الطلب. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في Google AI Studio. |
| 504 | DEADLINE_EXCEEDED | يتعذّر على الخدمة إنهاء عملية المعالجة قبل الموعد النهائي. | الطلب (أو السياق) كبير جدًا بحيث لا يمكن معالجته في الوقت المناسب. | ضبط "مهلة" أكبر في طلب العميل لتجنب هذا الخطأ. |
رموز أخطاء حزمة تطوير البرامج (SDK) لعميل Python
يسرد الجدول التالي السمات المشتركة خطأ في حزمة تطوير البرامج (SDK) لعميل Python الرموز التي قد تصادفها، مع تفسيرات لأسبابها:
| نوع الاستثناء/الخطأ | دورات تدريبية | الوصف |
|---|---|---|
| BlockedPromptException | google.generativeai.types.BlockedPromptException | تم حظر الطلب لأسباب تتعلق بالسلامة. |
| BrokenResponseError | google.generativeai.types.BrokenResponseError | تعذّر عرض الردود تدريجيًا. يتم إبرازه عند الوصول إلى عنصر يتطلب الاستجابة الكاملة، مثل سجلّ المحادثات. يمكنك الاطّلاع على تفاصيل الخطأ المقدّمة في تقرير تتبُّع تسلسل استدعاء الدوال البرمجية. |
| IncompleteIterationError | google.generativeai.types.IncompleteIterationError | يتم عرضه عند الوصول إلى محتوى يتطلب استجابة كاملة من واجهة برمجة التطبيقات، ولكن لم يتم تكرار استجابة البث بالكامل. يمكنك استدعاء resolve() على كائن الاستجابة لاستخدام المكرر. |
| StopCandidateException | google.generativeai.types.StopCandidateException | استجابت واجهة برمجة التطبيقات بعرض finish_reason استثنائي. يُرجى الاطّلاع على سبب تلقّي النصائح حول كيفية المتابعة. |
| PermissionDenied | google.api_core.exceptions.PermissionDenied | ليس لديك إذن للوصول إلى المورد المطلوب (مثل النموذج). |
| ResourceExhausted | google.api_core.exceptions.ResourceExhausted | تم استنفاد حصتك. يُرجى الانتظار قليلاً وإعادة المحاولة. ننصحك بإعداد عمليات إعادة المحاولة المبرمَجة لمعالجة هذه الأخطاء. |
| AlreadyExists | google.api_core.exceptions.AlreadyExists | هناك نموذج تم ضبطه يحمل المعرّف نفسه. يُرجى تحديد رقم تعريف فريد للنموذج عند ضبط نموذج جديد. |
| InvalidArgument | google.api_core.exceptions.InvalidArgument | وسيطة غير صالحة. أحد الأمثلة على ذلك هو أن الملف كبير جدًا ويتجاوز الحد الأقصى لحجم حمولة البيانات. والنوع الآخر هو توفير مفتاح واجهة برمجة تطبيقات غير صالح. |
| DefaultCredentialsError | google.auth.exceptions.DefaultCredentialsError | تعذّرت المصادقة. يُرجى التحقّق مرة أخرى من مفتاح واجهة برمجة التطبيقات وإعادة المحاولة. |
| RetryError | google.api_core.exceptions.RetryError | يمكن أن يحدث عند استخدام خادم وكيل لا يتوافق مع gRPC. يمكنك تجربة استخدام وسيلة النقل REST مع genai.configure(..., transport="rest"). |
التحقّق من طلبات البيانات من واجهة برمجة التطبيقات بحثًا عن أخطاء مَعلمات النماذج
تأكّد من أنّ مَعلمات النموذج ضمن القيم التالية:
| مَعلمة النموذج | القيم (النطاق) |
| عدد المرشحين | 1-8 (عدد صحيح) |
| درجة الحرارة | من 0.0 إلى 1.0 |
| الحد الأقصى للرموز المميزة للمخرجات |
استخدام
get_model (Python)
لتحديد الحد الأقصى لعدد الرموز بالنموذج الذي تستخدمه.
|
| TopP | من 0.0 إلى 1.0 |
بالإضافة إلى التحقق من قيم المعلمات، تأكد من استخدام
إصدار واجهة برمجة التطبيقات (على سبيل المثال، /v1 أو /v1beta) و
نموذج يدعم الميزات التي تحتاج إليها. على سبيل المثال، إذا كانت إحدى الميزات في مرحلة تجريبية
، فلن يتوفر إلا في إصدار واجهة برمجة التطبيقات /v1beta.
التحقق من استخدام النموذج الصحيح
تأكد من أنك تستخدم نموذجًا متوافقًا مدرج في صفحة النماذج.
مشاكل تتعلق بالسلامة
إذا ظهرت رسالة مطالبة تم حظرها بسبب إعداد أمان في طلب البيانات من واجهة برمجة التطبيقات، راجِع الطلب في ما يتعلق بالفلاتر التي أعددتها في طلب البيانات من واجهة برمجة التطبيقات.
إذا رأيت BlockedReason.OTHER، يعني هذا أنّ طلب البحث أو الردّ يخالف البنود.
أو ألّا تكون غير متاحة بأي شكل آخر.
مشكلة في القراءة
إذا رأيت أنّ النموذج يتوقف عن إنشاء النتائج بسبب سبب التسجيل، مما يعني أن ناتج النموذج قد يشبه بيانات معينة. لإصلاح ذلك، حاول أن تقديم طلب / سياق فريد قدر الإمكان واستخدام درجة حرارة أعلى
تحسين ناتج النموذج
للحصول على نتائج نموذج ذات جودة أعلى، ننصحك بكتابة المزيد من الطلبات المنظَّمة. تشير رسالة الأشكال البيانية تقدم صفحة مقدمة إلى تصميم الطلب وبعض المفاهيم الأساسية والاستراتيجيات وأفضل الممارسات للبدء.
إذا كان لديك مئات الأمثلة على أزواج الإدخال/الإخراج الجيدة، فيمكنك أيضًا ننصحك بضبط النموذج.
فهم حدود الرموز المميّزة
الاطّلاع على دليل الرموز المميّزة لفهم كيفية إجراء ذلك بشكل أفضل لحساب الرموز المميزة وحدودها.
المشاكل المعروفة
- لا تتيح واجهة برمجة التطبيقات سوى عدد من اللغات المحددة. إرسال الطلبات في يمكن أن ينتج عن اللغات غير المتوافقة ردود غير متوقعة أو حتى محظورة. عرض اللغات المتاحة للتحديثات.
الإبلاغ عن خطأ
انضم إلى المناقشة في منتدى مطوّري تكنولوجيات الذكاء الاصطناعي من Google إذا كانت لديك أسئلة.