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

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

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

رموز الخطأ

للحصول على مرجع كامل لجميع رموز الأخطاء، بما في ذلك رموز حالة HTTP ورموز حظر الإنشاء ورموز أخطاء المحتوى، يُرجى الاطّلاع على صفحة أخطاء واجهة برمجة التطبيقات.

استراتيجية إعادة المحاولة

إذا تلقّيت خطأ يشير إلى أنّه عليك إعادة محاولة طلبك (مثل 429 RESOURCE_EXHAUSTED أو 503 UNAVAILABLE)، ننصحك بتنفيذ استراتيجية التراجع الأسي. وهذا يعني الانتظار لفترة قصيرة قبل إعادة المحاولة الأولى، ثم زيادة وقت الانتظار تدريجيًا بين المحاولات اللاحقة.

تتضمّن حِزم SDK الرسمية للعملاء في Gemini API، مثل Python SDK، منطق إعادة المحاولة التلقائي مع تراجع أسي تلقائيًا لمعالجة الأخطاء المؤقتة، مثل المهلات ومشاكل الشبكة وحدود المعدّل (رمزا الحالة 429 و5xx). على سبيل المثال، تعيد حزمة تطوير البرامج (SDK) في Python تلقائيًا محاولة معالجة الأخطاء المؤقتة حتى أربع مرات مع تأخير أولي يبلغ ثانية واحدة تقريبًا وتأخير أقصى يبلغ 60 ثانية.

إذا كنت تُجري طلبات مباشرة من REST API أو تخصّص منطق إعادة المحاولة، اتّبِع أفضل الممارسات التالية لزيادة احتمالية نجاح الطلب وتجنُّب إرباك الخدمة:

  • استخدام استراتيجية الانتظار الأسي: انتظِر لفترة قصيرة قبل المحاولة الأولى (على سبيل المثال، ثانية واحدة)، ثم زِد مدة التأخير بشكل أسي (على سبيل المثال، ثانيتان، 4 ثوانٍ، 8 ثوانٍ).
  • إضافة تفاوت زمني: يمكنك إضافة "تفاوت زمني" عشوائي إلى التأخير للمساعدة في منع جميع العملاء من إعادة المحاولة في الوقت نفسه.
  • إعادة المحاولة عند حدوث أخطاء معيّنة: أعِد المحاولة فقط عند حدوث أخطاء عابرة (مثل 429 أو 408 أو 5xx). لا تُعِد المحاولة عند حدوث أخطاء من جهة العميل (مثل 400 أو 402 أو 403) لأنّها تشير إلى مشاكل مثل مفاتيح واجهة برمجة التطبيقات غير الصالحة أو نفاد رصيد الدفع المُسبق أو البنية غير الصالحة.
  • ضبط الحد الأقصى لعدد المحاولات: حدِّد الحد الأقصى لعدد المحاولات لمنع التكرار اللانهائي.

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

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

مَعلمة النموذج القيم (النطاق)
عدد المرشحين ‫1-8 (عدد صحيح، غير متاح في Gemini 3 و4)
درجة الحرارة ‫0.0-1.0 (يتم تجاهلها في Gemini 3.6 والإصدارات الأحدث وGemini 4، ويجب إبقاؤها على الإعداد التلقائي في إصدارات Gemini 3 السابقة)
أقصى عدد لرموز الناتج المميّزة استخدِم صفحة النماذج لتحديد الحد الأقصى لعدد الرموز المميّزة للنموذج الذي تستخدمه.
TopP ‫0.0-1.0 (يتم تجاهلها في Gemini 3.6 والإصدارات الأحدث وGemini 4، ويجب إبقاؤها على الإعداد التلقائي في إصدارات Gemini 3 السابقة)

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

التحقّق من أنّ لديك الطراز الصحيح

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

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

غالبًا ما يحدث تأخير أطول أو استخدام أكبر للرموز المميّزة لأنّ ميزة "المفكّر" تكون مفعّلة تلقائيًا في نماذج Gemini 3.x. تستخدم نماذج Gemini 2.5 المتوقفة نهائيًا أيضًا ميزة "المفكّر" التلقائية.

تُنشئ نماذج التفكير رموزًا مميّزة للاستدلال الداخلي من أجل تحسين الجودة. تؤدي عملية الاستدلال هذه إلى زيادة وقت الاستجابة وإجمالي استهلاك الرموز المميّزة.

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

للاطّلاع على تفاصيل الإعداد وعينات التعليمات البرمجية، يُرجى مراجعة دليل التفكير.

مشاكل متعلقة بالأمان

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

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

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

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

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

إذا ظهرت رموز مميّزة متكرّرة في النتائج، جرِّب الاقتراحات التالية للمساعدة في تقليلها أو التخلّص منها. لا تنطبق تعديلات درجة الحرارة إلا على النماذج السابقة التي تتيح استخدام مَعلمات أخذ العينات. بالنسبة إلى نموذجَي Gemini 3 وGemini 4، يمكنك استخدام الحلول البديلة للطلبات وتعليمات النظام بدلاً من ذلك.

الوصف السبب الحل البديل المقترَح
الواصلات المتكررة في جداول 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) في الناتج المنظَّم عندما يحتوي إدخال النموذج على ترميز Unicode أو تسلسلات إلغاء مثل \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.
  • أضِف تعليمات مثل "يُرجى الإيجاز" أو "لا تكرّر نفسك" أو "قدِّم الإجابة مرة واحدة".

المشروع محظور أو غير متاح

إذا كانت طلبات البيانات من واجهة برمجة التطبيقات تعرض الخطأ 403 PERMISSION_DENIED ("تم رفض وصول مشروعك") أو إذا كانت حالة مشروعك تظهر على أنّها محدودة أو الطبقة المجانية غير متاحة أو يجب الدفع أو غير متاحة في Google AI Studio، يُرجى الاطّلاع على أي من الأقسام التالية ينطبق على مشروعك:

عدم توفّر المستوى المجاني من Gemini API

لا تكون بعض المشاريع أو الحسابات على Google Cloud مؤهَّلة لاستخدام المستوى المجاني من Gemini API. إذا تم حظر مشروعك من استخدام المستوى المجاني:

  • لن يؤدي إنشاء مفتاح جديد لواجهة برمجة التطبيقات في المشروع نفسه إلى حلّ الخطأ. تقيّم Google الأهلية على مستوى مشروع Google Cloud.
  • لاستخدام Gemini API مع هذا المشروع، عليك الترقية إلى المستوى المدفوع من خلال ربط حساب فوترة نشط على Cloud.
  • ملاحظة: لا تؤدي ترقية مشروع إلى الفئة المدفوعة إلى فتح حصة الفئة المجانية. تُحصّل Google رسوم استخدام المستوى المدفوع وفقًا لأسعار Gemini API، أو تخصمها من أرصدة Google Cloud المؤهَّلة.

يجب الدفع من خلال حساب الفوترة على Cloud

إذا كان مشروعك مرتبطًا بحساب فوترة على Cloud ويظهر مطلوب الدفع (أو يعرض 403 PERMISSION_DENIED مع الإشارة إلى رصيد مستحق):

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

إذا كانت حالة الخطأ 403 PERMISSION_DENIED تشير إلى أنّه تم الإبلاغ عن تسرُّب مفتاح واجهة برمجة التطبيقات أو حظره:

  • انتقِل إلى صفحة مفاتيح واجهة برمجة التطبيقات في AI Studio لإنشاء مفتاح جديد وتعديل بيانات اعتماد تطبيقك.
  • لا تضمِّن أبدًا مفاتيح واجهة برمجة التطبيقات مباشرةً في الرموز البرمجية من جهة العميل أو المستودعات المتاحة للجميع.

تعليق المشروع أو حساب الفوترة بسبب انتهاك السياسات

إذا علّقت Google مشروعك على Google Cloud أو حساب الفوترة على Cloud بسبب انتهاك السياسة، يُرجى التحقّق من عنوان البريد الإلكتروني المرتبط. يُرجى الانتقال إلى Google Cloud Console لمراجعة أي إشعارات تعليق واتّباع إرشادات تعليق المشاريع.

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

يوضّح هذا القسم كيفية التحقّق مما إذا كان مفتاح 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 في تأمين حسابي من تجاوز التكلفة وإساءة الاستخدام في حال تسرُّب مفاتيح واجهة برمجة التطبيقات؟

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

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

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

فهم حدود الرموز المميّزة

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

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

  • تتيح واجهة برمجة التطبيقات عددًا من اللغات المحدّدة فقط. قد يؤدي إرسال الطلبات بلغات غير متاحة إلى الحصول على ردود غير متوقعة أو حتى محظورة. يُرجى الاطّلاع على صفحات تفاصيل الطراز لمعرفة آخر المعلومات.

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

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