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

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

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

رموز الخطأ

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

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

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

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

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

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

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

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

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

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

التحقّق من توفّر الطراز المناسب

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

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

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

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

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

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

مشاكل متعلّقة بالسلامة

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

إذا ظهرت لك 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 إذا كانت لديك أسئلة.