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

استخدِم هذا الدليل لمساعدتك في تشخيص المشاكل الشائعة التي تحدث عند استدعاء 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.