يمكنك الاستعانة بهذا الدليل لتشخيص وحلّ المشاكل الشائعة التي تنشأ عند الاتصال بواجهة Gemini API. إذا واجهت مشاكل في مفتاح واجهة برمجة التطبيقات، عليك التأكّد من إعداد مفتاح واجهة برمجة التطبيقات بشكل صحيح وفقًا لدليل إعداد مفتاح واجهة برمجة التطبيقات.
رموز الخطأ
يسرد الجدول التالي رموز الخطأ الشائعة التي قد تواجهها، مع شرح أسبابها وخطوات تحديد المشاكل وحلّها:
| رمز HTTP | الحالة | الوصف | الحل |
| 400 | INVALID_ARGUMENT | تم تكوين نص الطلب بشكلٍ غير صحيح. | يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات للتعرّف على تنسيق الطلب والأمثلة والإصدارات المتوافقة. قد يؤدي استخدام ميزات من إصدار أحدث من واجهة برمجة التطبيقات مع نقطة نهاية قديمة إلى حدوث أخطاء. |
| 403 | PERMISSION_DENIED | لا يتضمّن مفتاح واجهة برمجة التطبيقات الأذونات المطلوبة. | يُرجى التأكّد من ضبط مفتاح واجهة برمجة التطبيقات ومن إمكانية الوصول إليه بشكل صحيح. |
| 404 | NOT_FOUND | لم يتم العثور على المورد المطلوب. | تأكّد من أنّ جميع المَعلمات في طلبك صالحة لإصدار واجهة برمجة التطبيقات. |
| 429 | RESOURCE_EXHAUSTED | لقد تجاوزت الحدّ الأقصى المسموح به لمعدل الزيارات. | تأكَّد من أنّك ضمن الحدّ الأقصى المسموح به لمعدل النموذج. اطلب زيادة الحصة إذا لزم الأمر. |
| 500 | داخلي | حدث خطأ غير متوقع من جانب Google. | يُرجى الانتظار قليلاً وإعادة محاولة تقديم طلبك. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في "استوديو Google AI". |
| 503 | UNAVAILABLE | ربما تكون الخدمة زائدة التحميل أو متوقفة مؤقتًا. | يُرجى الانتظار قليلاً وإعادة محاولة تقديم طلبك. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في "استوديو Google AI". |
التحقّق من طلبات البيانات من واجهة برمجة التطبيقات بحثًا عن أخطاء مَعلمات النماذج
تأكَّد من أنّ مَعلمات النموذج تقع ضمن القيم التالية:
| مَعلمة النموذج | القيم (النطاق) |
| عدد المرشحين | من 1 إلى 8 (عدد صحيح) |
| درجة الحرارة | 0.0-1.0 |
| الحد الأقصى من الرموز المميّزة للإخراج |
استخدِم get_model (Python) لتحديد الحدّ الأقصى لعدد الرموز المميّزة للنموذج الذي تستخدمه.
|
| TopP | 0.0-1.0 |
وبالإضافة إلى التحقّق من قيم المَعلمات، احرص على استخدام إصدار واجهة برمجة التطبيقات الصحيح (مثل /v1 أو /v1beta)
ونموذج يتيح الميزات التي تحتاج إليها. على سبيل المثال، إذا كانت الميزة في الإصدار التجريبي،
لن تكون متاحة إلا في إصدار واجهة برمجة التطبيقات /v1beta.
التحقق من استخدام النموذج الصحيح
تأكَّد من استخدام نموذج متوافق. استخدم list_models
(Python) للحصول على جميع النماذج
المتاحة للاستخدام.
مشاكل متعلقة بالأمان
إذا تم حظر طلب بسبب أحد إعدادات الأمان في طلب البيانات من واجهة برمجة التطبيقات، راجِع الطلب في ما يتعلق بالفلاتر التي ضبطتها في طلب البيانات من واجهة برمجة التطبيقات.
إذا ظهر لك BlockedReason.OTHER، قد يكون طلب البحث أو الرد ينتهكان بنود الخدمة أو قد يكونا غير متوافقَين.
تحسين ناتج النموذج
للحصول على نتائج أفضل للنماذج، ننصحك باستكشاف كيفية كتابة المزيد من الطلبات المنظَّمة. تقدم صفحة مقدمة إلى تصميم الطلب بعض المفاهيم والاستراتيجيات الأساسية وأفضل الممارسات لمساعدتك على البدء.
إذا كان لديك مئات الأمثلة على أزواج إدخال وإخراج جيدة، يمكنك أيضًا ضبط النموذج.
فهم حدود الرموز المميّزة
يمكنك استخدام ModelService API للحصول على بيانات وصفية إضافية عن النماذج، بما في ذلك الحدود القصوى للرموز المميّزة للإدخال والإخراج.
للحصول على الرموز المميّزة المستخدمة في طلبك، استخدِم countMessageTokens لنماذج المحادثات وcountTextTokens للنماذج النصية.
المشاكل المعروفة
- دعم استوديو Google AI على الأجهزة الجوّالة: على الرغم من إمكانية فتح الموقع الإلكتروني على الأجهزة الجوّالة، إلا أنّه لم يتم تحسينه ليلائم الشاشات الصغيرة.
- لا تتوافق واجهة برمجة التطبيقات إلا مع اللغة الإنجليزية. يمكن أن يؤدي إرسال المطالبات بلغات مختلفة إلى ردود غير متوقعة أو حتى محظورة. راجِع اللغات المتاحة للاطّلاع على آخر الأخبار.
الإبلاغ عن خطأ
يمكنك الإبلاغ عن مشكلة في جيت هب لطرح الأسئلة أو إرسال طلبات الميزات أو الأخطاء.