خطأ Gemini ‏DEADLINE_EXCEEDED: المعنى والسبب والحل

لماذا تنتهي المهلة؟

مكوّنان يُنتجان تقريباً كل حالات DEADLINE_EXCEEDED. الأول حجم الإدخال: موجَّه ضخم أو سياق محشوّ يحتاج وقت معالجة أطول ممّا عميلك مستعد للانتظار، فتستسلم الوصلة بينما النموذج ما زال يعمل. الثاني طول التوليد: حين تطلب إجابة طويلة وتُبقي الخط مفتوحاً للاستجابة الكاملة، يتناسب الانتظار مع المخرَج، واستدعاء غير مبثوث لا سبيل له لإظهار التقدّم قبل القطع. لا أحد منهما يعني أن Gemini معطّل. يعني أن ميزانية الوقت وحجم العمل لا يتفقان.

محتوى الرد

جسم نموذجي للخطأ 504، في شكل Google القياسي:

{
  "error": {
    "code": 504,
    "message": "The service is unable to finish processing within the deadline.",
    "status": "DEADLINE_EXCEEDED"
  }
}

اعتمد على كون status هو DEADLINE_EXCEEDED لا على النص، ولا تخلطه مع أخطاء 429: هذا فشل زمني لكل طلب، لا سقف حركة.

ثلاثة حلول بالترتيب

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

# Python (google-genai)
from google import genai

# الحل 2: مهلة اخترتها عمداً (بالميلي ثانية)
client = genai.Client(http_options={"timeout": 120000})

# الحل 1: بثّ، حتى لا ينتظر شيء على الإجابة الكاملة
for chunk in client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents=long_prompt,
):
    print(chunk.text, end="")

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

قد يكون حجم الإدخال هو السبب

لا يظهر الإدخال الكبير دائماً كخطأ 504. تشير وثائق Google إلى أن السياق الذي يتعذر معالجته قد يظهر أيضاً كخطأ 500 INTERNAL، وحلّه مشابه: قلّل السياق، أو استخدم نموذجاً آخر، ثم أعد المحاولة. إذا ظهر الرمزان في مسار العمل نفسه، فضع حداً واضحاً لحجم السياق وقطّع المستندات الكبيرة. ويمكنك مراجعة مقارنة سعات السياق قبل اختيار نموذج بديل.

إذا كانت المدخلات الكبيرة جزءاً دائماً من عملك، فقارن تكلفة Gemini 3.5 Flash ذي سياق المليون توكن قبل تغيير بنية التطبيق.