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

السبب الأول: الملف الذي أشرت إليه اختفى

يعطي توثيق استكشاف الأخطاء لدى Google سبباً رسمياً واحداً للخطأ 404: الطلب أشار إلى ملف ليس موجوداً. وهذا يشمل الوسائط التي ترفقها بالمرجع بدل التضمين المباشر، أي الصور والصوت والفيديو. المراجع المرفوعة لا تعيش إلى الأبد؛ قد تنتهي صلاحيتها أو تُحذف، ولا شيء ينبّهك حين يختفي أحدها بهدوء. يبقى كودك يقدّم مقبضاً لمورد توقّف عن الوجود في مكان ما بين الرفع وهذا الاستدعاء.

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

السبب الثاني: النموذج تقاعد

السبب الثاني أكبر من طلبك: خط النموذج بأكمله أُطفئ. ثلاثة تواريخ موثَّقة تهمّ حتى يونيو 2026. النموذج gemini-3-pro-preview ميّت منذ 9 مارس 2026. وعائلة gemini-2.0-flash أُغلقت في 1 يونيو 2026. وأما gemini-2.5-pro مع gemini-2.5-flash فيحملان تاريخ 16 أكتوبر 2026، الذي ينشره Google بصفته أبكر إيقاف ممكن لا وعداً بوقت إضافي. سجلّ إيقاف 2.5 Pro ومتتبّع النماذج يحفظان الجدول الزمني الكامل.

للترقية ثمن، حرفياً. البديلان هما gemini-3.5-flash وgemini-3.1-pro-preview، وكلاهما أغلى ممّا يحلّ محلّه. على مسار Flash، يقفز الإدخال من 0.30$ إلى 1.50$ لكل مليون توكن (أي ×5) بينما يتسلّق الإخراج من 2.50$ إلى 9.00$. وعلى مسار Pro، يصبح 1.25$/10$ هو 2$/12$. تغيير إعداد من سطر واحد قد يضاعف فاتورة، فخطّط للميزانية قبل أن تشحن الانتقال.

الاستجابة

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

{
  "error": {
    "code": 404,
    "message": "The requested resource wasn't found.",
    "status": "NOT_FOUND"
  }
}

تفرّع على حقل status؛ يبقى NOT_FOUND ثابتاً بينما قد ينحرف نص الرسالة. لاحظ ما لا يخبرك به الجسم أبداً: أيّ السببين أصبت. التقويم يخبرك عادةً. خطأ 404 يبدأ صباح تاريخ إيقاف منشور هو تقاعد، لا خلل ملف.

الحل في الكود

لحالة الملف، غلّف الاستدعاء بحيث يُطلِق المرجع القديم إعادة رفع واحدة وإعادة محاولة واحدة بدل حلقة انهيار:

# Python (google-genai): أعد الرفع حين يُرجع مرجع ملف خطأ 404
from google import genai
from google.genai import errors

client = genai.Client()

def ask_about(path, prompt, model="gemini-3.5-flash"):
    ref = client.files.upload(file=path)
    try:
        return client.models.generate_content(model=model, contents=[ref, prompt])
    except errors.APIError as e:
        if e.code != 404:
            raise
        ref = client.files.upload(file=path)   # مقبض قديم: حدّثه
        return client.models.generate_content(model=model, contents=[ref, prompt])

لحالة التقاعد، تغيير الكود بأكمله هو سطر إعداد واحد:

# config.yaml
-  model: gemini-2.5-flash
+  model: gemini-3.5-flash

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