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

استخدِم هذا الدليل لمساعدتك في تحديد المشاكل الشائعة وحلّها عند طلب بيانات من 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 لا يملك مفتاح واجهة برمجة التطبيقات الأذونات المطلوبة. أنت تستخدم مفتاح واجهة برمجة التطبيقات الخطأ، وتحاول استخدام نموذج معدَّل بدون إجراء عملية المصادقة المناسبة. تأكَّد من ضبط مفتاح واجهة برمجة التطبيقات ومنحه إذن الوصول المناسب. وتأكَّد من إجراء عملية المصادقة المناسبة لاستخدام النماذج المعدَّلة.
404 NOT_FOUND لم يتم العثور على المصدر المطلوب. لم يتم العثور على ملف صورة أو ملف صوت أو ملف فيديو تمت الإشارة إليه في طلبك. تأكَّد من أنّ جميع المَعلمات في طلبك صالحة لإصدار واجهة برمجة التطبيقات.
429 RESOURCE_EXHAUSTED تجاوزت أحد الحدود القصوى لمعدّل الطلبات في واجهة برمجة التطبيقات (عدد الطلبات في الدقيقة أو عدد الرموز المميّزة في الدقيقة أو عدد الطلبات في اليوم أو الإنفاق أو ما إلى ذلك). أنت تُرسِل عددًا كبيرًا جدًا من الطلبات، أو تستخدم عددًا كبيرًا جدًا من الرموز المميّزة، أو تتجاوز الحدود القصوى المستندة إلى الإنفاق لسجلّ الفوترة والمستوى في حسابك. تأكَّد من أنّك ضمن الحدود القصوى لمعدّل الطلبات في النموذج. انتظِر وأعِد المحاولة بعد فترة قصيرة. قلِّل معدّل طلباتك أو حجمها. اطلب زيادة الحدّ الأقصى لمعدّل الطلبات إذا لزم الأمر.
499 CANCELLED تم إلغاء العملية، وعادةً ما يكون ذلك من قِبل المتصل. أغلق العميل الاتصال قبل أن تتمكّن واجهة برمجة التطبيقات من إنهاء الرد. تأكَّد مما إذا كان العميل أو البنية الأساسية للشبكة يغلقان الاتصال قبل الأوان (على سبيل المثال، بسبب انتهاء المهلة من جهة العميل).
500 INTERNAL حدث خطأ غير متوقَّع من جانب Google. سياق الإدخال طويل جدًا. راجِع صفحة حالة Gemini API للاطّلاع على أي حوادث مستمرة. قلِّل سياق الإدخال أو بدِّل مؤقتًا إلى نموذج آخر (على سبيل المثال، من Gemini 2.5 Pro إلى Gemini 2.5 Flash) وتحقَّق مما إذا كان ذلك يحلّ المشكلة. أو انتظِر قليلاً وأعِد محاولة إرسال طلبك. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في Google AI Studio.
503 UNAVAILABLE قد تكون الخدمة غير متاحة مؤقتًا أو قد يكون هناك زيادة مؤقتة في التحميل عليها. الخدمة غير متاحة مؤقتًا بسبب عدم توفّر سعة كافية. راجِع صفحة حالة Gemini API للاطّلاع على أي حوادث مستمرة. بدِّل مؤقتًا إلى نموذج آخر (على سبيل المثال، من 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) في الناتج المنظَّم عندما يحتوي إدخال النموذج على أحرف 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 أو تساويها).
  • أضِف تعليمات مثل "كُن موجزًا" أو "لا تكرِّر نفسك" أو "قدِّم الإجابة مرة واحدة".

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

يوضّح هذا القسم كيفية التحقّق مما إذا كان مفتاح 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 إذا كانت لديك أسئلة.