استخدِم هذا الدليل لمساعدتك في تشخيص المشاكل الشائعة التي تحدث عند استدعاء Gemini API وحلّها. قد تواجه مشاكل من خدمة Gemini API الخلفية أو حِزم SDK للعملاء. إنّ حِزم SDK المخصّصة للعملاء مفتوحة المصدر في المستودعات التالية:
إذا واجهت مشاكل في مفتاح واجهة برمجة التطبيقات، تأكَّد من أنّك أعددت مفتاح واجهة برمجة التطبيقات بشكلٍ صحيح وفقًا لدليل إعداد مفتاح واجهة برمجة التطبيقات.
رموز خطأ خدمة 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 | لا يتضمّن مفتاح واجهة برمجة التطبيقات الأذونات المطلوبة. | استخدام مفتاح واجهة برمجة التطبيقات غير الصحيح محاولة استخدام نموذج معدّل بدون إجراء مصادقة صحيحة | تأكَّد من ضبط مفتاح واجهة برمجة التطبيقات ومن أنّه يتضمّن إذن الوصول الصحيح. واحرص على إجراء المصادقة المناسبة لاستخدام النماذج المحسّنة. |
| 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 | يتعذّر على الخدمة إكمال المعالجة في غضون الموعد النهائي. | الطلب (أو السياق) كبير جدًا ولا يمكن معالجته في الوقت المناسب. | اضبط مهلة أكبر في طلب العميل لتجنُّب هذا الخطأ. |
التحقّق من طلبات البيانات من واجهة برمجة التطبيقات بحثًا عن أخطاء في مَعلمات النماذج
تأكَّد من أنّ مَعلمات النموذج ضمن القيم التالية:
| مَعلمة النموذج | القيم (النطاق) |
| عدد المرشحين | من 1 إلى 8 (عدد صحيح) |
| درجة الحرارة | 0.0-1.0 |
| الحد الأقصى لعدد الرموز المميّزة للإخراج |
استخدِم get_model (Python)
لتحديد الحد الأقصى لعدد الرموز المميّزة للنموذج الذي تستخدمه.
|
| TopP | 0.0-1.0 |
بالإضافة إلى التحقّق من قيم المَعلمات، تأكَّد من استخدام
إصدار واجهة برمجة التطبيقات الصحيح (مثلاً، /v1 أو /v1beta) وأحد
الطرازات التي تتيح الميزات التي تحتاج إليها. على سبيل المثال، إذا كانت إحدى الميزات في مرحلة الإصدار التمهيدي، لن تتوفّر إلا في الإصدار /v1beta من واجهة برمجة التطبيقات.
التأكّد من استخدام الطراز الصحيح
تأكَّد من استخدام طراز متوافق مُدرَج في صفحة الطُرز.
مشاكل السلامة
إذا ظهرت لك رسالة تفيد بأنّه تم حظر طلب بسبب إعدادات أمان في طلبك إلى واجهة برمجة التطبيقات، راجِع الطلب في ما يتعلق بالفلاتر التي ضبطتها في طلبك إلى واجهة برمجة التطبيقات.
إذا ظهرت لك القيمة BlockedReason.OTHER، قد يعني ذلك أنّ الطلب أو الاستجابة ينتهكان بنود
الخدمة أو أنّهما غير متوافقَين.
مشكلة في القراءة
إذا توقّف النموذج عن إنشاء النتائج بسبب السبب "القراءة"، يعني ذلك أنّه قد تشبه نتيجة النموذج بيانات معيّنة. لحلّ هذه المشكلة، حاوِل جعل الطلب أو السياق فريدَين قدر الإمكان واستخدِم درجة حرارة أعلى.
تحسين مخرجات النموذج
للحصول على نتائج ذات جودة أعلى من النماذج، استكشِف كتابة طلبات أكثر تنظيمًا. تقدّم صفحة دليل هندسة الطلبات بعض المفاهيم الأساسية والاستراتيجيات وأفضل الممارسات لمساعدتك في البدء.
إذا كانت لديك مئات الأمثلة على أزواج الإدخال/الإخراج الجيدة، يمكنك أيضًا التفكير في ضبط النموذج.
فهم حدود الرموز المميّزة
اطّلِع على دليل الرموز المميّزة للتعرّف بشكل أفضل على كيفية عدّ الرموز المميّزة وحدودها.
المشاكل المعروفة
- لا تتيح واجهة برمجة التطبيقات سوى عدد محدّد من اللغات. قد يؤدي إرسال طلبات باللغة غير المتوافقة إلى ظهور ردود غير متوقّعة أو حتى محظورة. اطّلِع على اللغات المتاحة للاطّلاع على التحديثات.
الإبلاغ عن خطأ
إذا كانت لديك أسئلة، يمكنك الانضمام إلى المناقشة في منتدى مطوّري تكنولوجيات الذكاء الاصطناعي من Google.