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

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

• python-genai
• js-genai
• go-genai

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

          # 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.
        

        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.
      

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

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

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

لقد رصدنا ثغرة أمنية قد تكون أدّت إلى إتاحة بعض مفاتيح واجهة برمجة التطبيقات للجميع. لحماية بياناتك ومنع الوصول غير المصرَّح به إليها، حظرنا بشكل استباقي إمكانية وصول هذه المفاتيح المعروفة التي تم تسريبها إلى 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، ما يساعد في منع إساءة استخدام التكلفة وبيانات تطبيقك.
• يمكنك الاطّلاع على حالة مفاتيح واجهة برمجة التطبيقات ضمن Google AI Studio، وسنعمل على إعلامك بشكل استباقي في حال رصدنا أي تسريب لمفاتيح واجهة برمجة التطبيقات لاتّخاذ إجراء فوري.

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

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

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

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

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

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

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

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