خطأ 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 وسعة سياقه البالغة مليون توكن قبل أن تعيد هندسة كل شيء حول الساعة.