دليل تحديد المشاكل وحلّها

استخدِم هذا الدليل لمساعدتك في تشخيص المشاكل الشائعة التي تحدث عند استدعاء Gemini API وحلّها. قد تواجه مشاكل إما من خدمة الخلفية لواجهة Gemini API أو من حِزم SDK للبرامج. حِزم تطوير البرامج (SDK) الخاصة بالعملاء هي مفتوحة المصدر في المستودعات التالية:

في حال مواجهة مشاكل في مفتاح واجهة برمجة التطبيقات، تأكَّد من إعداد المفتاح بشكلٍ صحيح وفقًا لدليل إعداد مفتاح واجهة برمجة التطبيقات.

رموز الخطأ في خدمة الخلفية لواجهة Gemini API

يسرد الجدول التالي رموز الأخطاء الشائعة في الخلفية التي قد تواجهها، بالإضافة إلى توضيحات حول أسبابها وخطوات تحديد المشاكل وحلّها:

رمز HTTP الحالة الوصف مثال Solution
400 INVALID_ARGUMENT تمت صياغة نص الطلب بشكل غير صحيح. هناك خطأ إملائي أو حقل مطلوب ناقص في طلبك. راجِع مرجع واجهة برمجة التطبيقات للاطّلاع على تنسيق الطلب والأمثلة والإصدارات المتوافقة. قد يؤدي استخدام ميزات من إصدار أحدث من واجهة برمجة التطبيقات مع نقطة نهاية قديمة إلى حدوث أخطاء.
400 FAILED_PRECONDITION لا تتوفّر الطبقة المجانية من Gemini API في بلدك. يُرجى تفعيل الفوترة في مشروعك في Google AI Studio. أنت تقدّم طلبًا في منطقة لا تتوفّر فيها الطبقة المجانية، ولم تفعّل الفوترة في مشروعك على Google AI Studio. لاستخدام Gemini API، عليك إعداد خطة مدفوعة باستخدام Google AI Studio.
403 PERMISSION_DENIED لا يتضمّن مفتاح واجهة برمجة التطبيقات الأذونات المطلوبة. أنت تستخدم مفتاح API غير صحيح، أو تحاول استخدام نموذج معدَّل بدون إجراء المصادقة المناسبة. تأكَّد من ضبط مفتاح واجهة برمجة التطبيقات ومنحه إذن الوصول المناسب. وتأكَّد من إكمال عملية المصادقة بشكل صحيح لاستخدام النماذج المعدَّلة.
404 NOT_FOUND لم يتم العثور على المورد المطلوب. لم يتم العثور على ملف صورة أو صوت أو فيديو تمت الإشارة إليه في طلبك. تحقَّق مما إذا كانت جميع المَعلمات في طلبك صالحة لإصدار واجهة برمجة التطبيقات.
429 RESOURCE_EXHAUSTED تجاوزت الحد الأقصى لمعدّل الطلبات. أنت ترسل عددًا كبيرًا جدًا من الطلبات في الدقيقة باستخدام المستوى المجاني من Gemini API. تأكَّد من أنّك لم تتجاوز حدّ معدّل النموذج. طلب زيادة الحصة إذا لزم الأمر
500 INTERNAL حدث خطأ غير متوقَّع من جهة Google. سياق الإدخال طويل جدًا. يمكنك تقليل سياق الإدخال أو التبديل مؤقتًا إلى نموذج آخر (مثل التبديل من Gemini 2.5 Pro إلى Gemini 2.5 Flash) لمعرفة ما إذا كان ذلك سيحلّ المشكلة. أو الانتظار قليلاً وإعادة محاولة إجراء الطلب. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في Google AI Studio.
503 UNAVAILABLE قد تكون الخدمة محمّلة بشكل مؤقت أو معطّلة. نفدت سعة الخدمة مؤقتًا. يمكنك التبديل مؤقتًا إلى نموذج آخر (مثل Gemini 2.5 Pro إلى Gemini 2.5 Flash) ومعرفة ما إذا كان ذلك سيحلّ المشكلة. أو الانتظار قليلاً وإعادة محاولة إجراء الطلب. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في Google AI Studio.
504 DEADLINE_EXCEEDED يتعذّر على الخدمة إنهاء المعالجة في غضون الموعد النهائي. طلبك (أو سياقك) كبير جدًا بحيث لا يمكن معالجته في الوقت المناسب. اضبط قيمة "مهلة" أكبر في طلب العميل لتجنُّب هذا الخطأ.

التحقّق من طلبات البيانات من واجهة برمجة التطبيقات بحثًا عن أخطاء في مَعلمات النموذج

تأكَّد من أنّ مَعلمات النموذج تندرج ضمن القيم التالية:

مَعلمة النموذج القيم (النطاق)
عدد المرشحين من 1 إلى 8 (عدد صحيح)
درجة الحرارة ‫0.0-1.0
الحد الأقصى لعدد الرموز المميزة للناتج استخدِم صفحة النماذج لتحديد الحدّ الأقصى لعدد الرموز المميزة للنموذج الذي تستخدمه.
TopP ‫0.0-1.0

بالإضافة إلى التحقّق من قيم المَعلمات، تأكَّد من أنّك تستخدم إصدار واجهة برمجة التطبيقات الصحيح (مثل /v1 أو /v1beta) والنموذج الذي يتوافق مع الميزات التي تحتاج إليها. على سبيل المثال، إذا كانت إحدى الميزات في إصدار تجريبي، ستتوفّر فقط في إصدار واجهة برمجة التطبيقات /v1beta.

التأكّد من أنّ لديك الطراز المناسب

تأكَّد من أنّك تستخدم طرازًا متوافقًا مُدرَجًا في صفحة الطُرز.

زيادة وقت الاستجابة أو استخدام الرموز المميزة مع نماذج 2.5

إذا لاحظت زيادة في وقت الاستجابة أو استخدام الرموز المميزة مع طرازَي 2.5 Flash وPro، قد يكون ذلك بسبب تفعيل ميزة "التفكير" تلقائيًا بهدف تحسين الجودة. إذا كنت تريد إعطاء الأولوية للسرعة أو تقليل التكاليف، يمكنك تعديل ميزة "التفكير" أو إيقافها.

يُرجى الرجوع إلى صفحة التفكير للحصول على إرشادات ورمز نموذجي.

مشاكل الأمان

إذا ظهرت لك رسالة تفيد بأنّه تم حظر طلب بسبب إعدادات الأمان في طلب البيانات من واجهة برمجة التطبيقات، راجِع الطلب مع مراعاة الفلاتر التي ضبطتها في طلب البيانات من واجهة برمجة التطبيقات.

إذا ظهرت لك BlockedReason.OTHER، قد يكون الطلب أو الرد مخالفًا لبنود الخدمة أو غير متوافق معها.

مشكلة في التلاوة

إذا لاحظت أنّ النموذج يتوقف عن إنشاء المخرجات بسبب RECITATION، هذا يعني أنّ مخرجات النموذج قد تشبه بيانات معيّنة. لحلّ هذه المشكلة، حاوِل جعل الطلب أو السياق فريدًا قدر الإمكان واستخدِم درجة عشوائية أعلى.

مشكلة الرموز المميزة المتكررة

إذا ظهرت لك رموز مميّزة مكرّرة في الناتج، جرِّب الاقتراحات التالية للمساعدة في تقليلها أو إزالتها.

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

أضِف تعليمات في طلبك لتزويد النموذج بإرشادات محدّدة لإنشاء جداول Markdown. قدِّم أمثلة تتّبع هذه الإرشادات. يمكنك أيضًا محاولة تعديل درجة الحرارة. لإنشاء رمز برمجي أو ناتج منظَّم جدًا، مثل جداول Markdown، تبيّن أنّ درجات العشوائية المرتفعة تعمل بشكل أفضل (أكبر من أو يساوي 0.8).

في ما يلي مثال على مجموعة إرشادات يمكنك إضافتها إلى طلبك لمنع حدوث هذه المشكلة: 

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
الرموز المتكررة في جداول Markdown ويحدث ذلك، كما هو الحال مع الشرطات المتكررة، عندما يحاول النموذج محاذاة محتوى الجدول بصريًا. لا يُشترط أن يكون المحتوى محاذيًا في Markdown لعرضه بشكل صحيح.
  • جرِّب إضافة تعليمات مثل ما يلي إلى طلب النظام: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • جرِّب تعديل درجة الحرارة. تساعد درجات الحرارة الأعلى (>= 0.8) بشكل عام في إزالة التكرار أو الازدواجية في الناتج.
أسطر جديدة متكرّرة (\n) في الناتج المنظَّم عندما يحتوي إدخال النموذج على تسلسلات يونيكود أو تسلسلات إلغاء مثل \u أو \t، يمكن أن يؤدي ذلك إلى تكرار أسطر جديدة.
  • ابحث عن تسلسلات الهروب المحظورة واستبدلها بأحرف UTF-8 في طلبك. على سبيل المثال، يمكن أن يؤدي تسلسل الهروب \u في أمثلة JSON إلى أن يستخدم النموذج هذا التسلسل في رده أيضًا.
  • إعطاء النموذج تعليمات بشأن عمليات الإلغاء المسموح بها أضِف تعليمات النظام التالية: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
النص المتكرّر عند استخدام الناتج المنظَّم عندما يكون ترتيب الحقول في مخرجات النموذج مختلفًا عن ترتيبها في المخطط المنظَّم المحدَّد، قد يؤدي ذلك إلى تكرار النص.
  • لا تحدّد ترتيب الحقول في طلبك.
  • اجعل جميع حقول الإخراج مطلوبة.
استخدام الأدوات بشكل متكرّر يمكن أن يحدث ذلك إذا فقد النموذج سياق الأفكار السابقة و/أو إذا اضطر إلى طلب نقطة نهاية غير متاحة. اطلب من النموذج الحفاظ على الحالة ضمن عملية التفكير. أضِف ما يلي إلى نهاية تعليمات النظام: 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
النص المتكرّر الذي لا يشكّل جزءًا من الناتج المنظَّم يمكن أن يحدث ذلك إذا تعذّر على النموذج حلّ طلب معيّن.
  • إذا كانت ميزة "التفكير" مفعّلة، تجنَّب تقديم أوامر صريحة حول كيفية التفكير في مشكلة معيّنة في التعليمات. ما عليك سوى طلب الناتج النهائي.
  • جرِّب درجة حرارة أعلى من 0.8.
  • أضِف تعليمات مثل "كن موجزًا" أو "لا تكرّر نفسك" أو "قدِّم الإجابة مرة واحدة".

مفاتيح واجهة برمجة التطبيقات المحظورة أو التي لا تعمل

يوضّح هذا القسم كيفية التحقّق مما إذا كان مفتاح Gemini API محظورًا والإجراءات التي يجب اتّخاذها في حال كان محظورًا.

التعرّف على أسباب حظر المفاتيح

لقد رصدنا ثغرة أمنية قد تكون أدّت إلى إتاحة بعض مفاتيح واجهة برمجة التطبيقات للجميع. لحماية بياناتك ومنع الوصول غير المصرَّح به إليها، حظرنا بشكل استباقي إمكانية وصول هذه المفاتيح المعروفة التي تم تسريبها إلى Gemini API.

تأكيد ما إذا كانت مفاتيحك متأثرة

إذا تبيّن أنّ مفتاحك قد تم تسريبه، لن يعود بإمكانك استخدامه مع Gemini API. يمكنك استخدام Google AI Studio لمعرفة ما إذا تم حظر أي من مفاتيح واجهة برمجة التطبيقات من طلب البيانات من Gemini API وإنشاء مفاتيح جديدة. قد يظهر لك أيضًا الخطأ التالي عند محاولة استخدام هذه المفاتيح:

Your API key was reported as leaked. Please use another API key.

الإجراءات المتّخذة بشأن مفاتيح واجهة برمجة التطبيقات المحظورة

عليك إنشاء مفاتيح واجهة برمجة تطبيقات جديدة لعمليات الدمج في Gemini API باستخدام Google AI Studio. ننصحك بشدة بمراجعة ممارسات إدارة مفاتيح واجهة برمجة التطبيقات للتأكّد من الحفاظ على أمان مفاتيحك الجديدة وعدم إتاحتها للجميع.

رسوم غير متوقّعة بسبب ثغرة أمنية

إرسال طلب للحصول على دعم بشأن الفوترة يعمل فريق الفوترة على حلّ هذه المشكلة، وسنرسل إليك إشعارات بشأن آخر الأخبار في أقرب وقت ممكن.

إجراءات الأمان التي تتّخذها Google بشأن المفاتيح المسروقة

كيف ستساعدني Google في حماية حسابي من تجاوز التكلفة وإساءة الاستخدام في حال تسرّبت مفاتيح واجهة برمجة التطبيقات؟

  • نحن بصدد طرح ميزة إصدار مفاتيح API عند طلب مفتاح جديد باستخدام Google AI Studio، وسيكون هذا المفتاح مقتصرًا تلقائيًا على Google AI Studio فقط ولن يقبل مفاتيح من خدمات أخرى. سيساعد ذلك في منع أي استخدام غير مقصود لمفاتيح متعددة.
  • نعمل تلقائيًا على حظر مفاتيح واجهة برمجة التطبيقات التي تم تسريبها واستخدامها مع Gemini API، ما يساعد في منع إساءة استخدام التكلفة وبيانات تطبيقك.
  • يمكنك الاطّلاع على حالة مفاتيح واجهة برمجة التطبيقات ضمن Google AI Studio، وسنعمل على إعلامك بشكل استباقي في حال رصدنا أي تسريب لمفاتيح واجهة برمجة التطبيقات لاتّخاذ إجراء فوري.

تحسين مخرجات النموذج

للحصول على نتائج أفضل من النموذج، ننصحك بتجربة كتابة طلبات أكثر تنظيمًا. تقدّم صفحة دليل هندسة الطلبات بعض المفاهيم الأساسية والاستراتيجيات وأفضل الممارسات لمساعدتك على البدء.

التعرّف على حدود الرموز المميزة

اطّلِع على دليل الرموز المميزة للتعرّف بشكل أفضل على كيفية احتساب الرموز المميزة وحدودها.

المشاكل المعروفة

  • لا تتوافق واجهة برمجة التطبيقات إلا مع عدد من اللغات المحدّدة. قد يؤدي إرسال الطلبات بلغات غير متوافقة إلى ظهور ردود غير متوقّعة أو حتى محظورة. يمكنك الاطّلاع على اللغات المتاحة للتحديثات.

الإبلاغ عن خطأ

يمكنك الانضمام إلى المناقشة في منتدى مطوّري الذكاء الاصطناعي من Google إذا كانت لديك أسئلة.