حل خطأ thought_signature 400 في Nano Banana 2: يجب إعادة إرسال توقيع التفكير عند تحرير الصور متعدد الجولات

ملاحظة من المؤلف: هل واجهت خطأ "Image part is missing a thought_signature" عند استخدام Nano Banana 2؟ هذا الخطأ (400) يحدث بسبب عدم إرسال "توقيع التفكير" (thought_signature) في المحادثات متعددة الجولات. يشرح هذا المقال الأسباب، حلول الإصلاح، وأمثلة برمجية.

إذا تلقيت هذا الخطأ أثناء استخدام Nano Banana 2 (gemini-3.1-flash-image-preview) لتحرير الصور:

{
  "status_code": 400,
  "error": {
    "message": "Image part is missing a thought_signature in content position 2, part position 1."
  }
}

لا داعي للقلق—هذا ليس مشكلة في أمان المحتوى أو عطلاً في المنصة، بل هو متطلب تقني للمحادثات متعددة الجولات في نماذج سلسلة Gemini 3. ببساطة: لقد أرسلت في الجولة الثانية صورة تم إنشاؤها مسبقاً، ولكن دون إرفاق thought_signature (توقيع التفكير) الخاص بتلك الصورة.

القيمة الأساسية: بعد قراءة هذا المقال، ستفهم كيفية عمل thought_signature، وستتقن 3 حلول للإصلاح، وستتعلم كيفية التعامل بشكل صحيح مع توقيع التفكير في سيناريوهات تحرير الصور متعددة الجولات.

فهم جوهر خطأ thought_signature في Nano Banana 2

ماذا يعني هذا الخطأ بالضبط؟

لنقم بتفكيك رسالة الخطأ هذه كلمة بكلمة:

الحقل	المعنى	التوضيح
status_code: 400	خطأ في معايير الطلب	ليس خطأ في الخادم، بل مشكلة في المعايير المرسلة من العميل
Image part	بيانات الصورة المضمنة في الطلب	لقد أرسلت صورة في الجولة الثانية من الطلب
missing a thought_signature	فقدان توقيع التفكير	هذه الصورة تم إنشاؤها بواسطة النموذج في الجولة السابقة، ويجب إرفاق توقيعها
content position 2, part position 1	في الرسالة الثانية من سجل المحادثة، الجزء الأول	تحديد دقيق لموقع الجزء المفقود من التوقيع

خلاصة القول: واجهة برمجة تطبيقات Gemini (Gemini API) عديمة الحالة (Stateless)، ويستخدم النموذج thought_signature (توقيع التفكير) للحفاظ على سياق الاستنتاج عبر جولات المحادثة المتعددة. عندما تبدأ جولة ثانية من طلب تحرير الصور، يجب عليك إعادة إرسال thought_signature التي أعادها النموذج في الجولة السابقة كما هي، وإلا ستتلقى خطأ 400.

لماذا تفرض سلسلة Gemini 3 استخدام thought_signature؟

المقارنة	سلسلة Gemini 2.x	سلسلة Gemini 3 (بما فيها NB2)
توقيع التفكير	اختياري في بعض السيناريوهات	إلزامي لجميع أنواع الأجزاء (parts)
صرامة التحقق	متساهلة	صارمة (الفقدان يعني خطأ 400)
نطاق التطبيق	يُستخدم بشكل رئيسي لاستدعاء الدوال	ينطبق على النصوص، الصور، واستدعاء الدوال
المعالجة التلقائية	تعالجها SDK الرسمية تلقائياً	تعالجها SDK الرسمية تلقائياً

تفرض نماذج سلسلة Gemini 3 (بما في ذلك gemini-3.1-flash الذي يعتمد عليه Nano Banana 2) استخدام توقيع التفكير للأسباب التالية:

1. استعادة حالة الاستنتاج: توقيع التفكير هو تمثيل مشفر لعملية الاستنتاج الداخلية للنموذج، مما يسمح له باستعادة "حالة التفكير" السابقة في الجولة التالية من المحادثة.
2. استمرارية تحرير الصور: بالنسبة لتحرير الصور متعدد الجولات، يحتاج النموذج إلى فهم أن "هذه الصورة هي التي أنشأتها في الخطوة السابقة" ليتمكن من تنفيذ تعليمات التحرير بشكل صحيح.
3. الأمان والاتساق: تضمن آلية التوقيع عدم التلاعب بسجل المحادثة، مما يعزز موثوقية التفاعل متعدد الجولات.

🎯 إدراك جوهري: خطأ 400 هذا لا علاقة له إطلاقاً بسياسات أمان المحتوى (IMAGE_SAFETY)، وليس مشكلة في منصة APIYI. إنه متطلب آلي طبيعي لنماذج سلسلة Gemini 3، ويجب معالجته على مستوى الكود البرمجي.

---

3 حلول لإصلاح خطأ thought_signature في Nano Banana 2

الحل 1: استخدام ميزة المحادثة (chat) في SDK الرسمية (موصى به)

إذا كنت تستخدم SDK الرسمية من Google (بواسطة Python / Node.js / Java)، فإن أسهل طريقة هي استخدام ميزة المحادثة، حيث ستقوم الـ SDK بإدارة thought_signature تلقائياً:

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

# استخدام ميزة المحادثة، حيث تقوم الـ SDK بمعالجة thought_signature تلقائياً
chat = client.chats.create(model="gemini-3.1-flash-image-preview")

# الجولة 1: توليد صورة
response1 = chat.send_message("ارسم قطة برتقالية تجلس على حافة النافذة")

# الجولة 2: تحرير الصورة (يتم إعادة إرسال التوقيع تلقائياً)
response2 = chat.send_message("اجعل القطة ترتدي قبعة عيد الميلاد")

الحل 2: استخراج وإعادة إرسال thought_signature يدوياً

إذا كنت تستخدم استدعاء HTTP مخصصاً أو عبر واجهة متوافقة مع OpenAI، فأنت بحاجة إلى معالجة التوقيع يدوياً. المنطق الأساسي هو: استخراج thought_signature من استجابة الجولة السابقة، وإرفاقه كما هو في الجزء المقابل (part) في الطلب التالي.

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

# الجولة 1: توليد صورة
response1 = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=[{"role": "user", "content": "ارسم قطة برتقالية"}]
)

# مفتاح الحل: حفظ استجابة النموذج الكاملة
# بما في ذلك بيانات الصورة و thought_signature
model_reply = response1.choices[0].message

# الجولة 2: تحرير الصورة
# تمرير استجابة النموذج الكاملة من الجولة السابقة كجزء من سجل المحادثة
response2 = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=[
        {"role": "user", "content": "ارسم قطة برتقالية"},
        model_reply,  # إعادة إرسال كاملة، تتضمن thought_signature
        {"role": "user", "content": "اجعل القطة ترتدي قبعة"}
    ]
)

الحل 3: التحول إلى طلبات الجولة الواحدة

إذا كان سيناريو عملك لا يتطلب تحرير محادثة متعدد الجولات، يمكنك إرسال طلبات منفصلة في كل مرة، لتجنب مشكلة thought_signature تماماً:

# تحرير صورة في جولة واحدة: إرسال الصورة الأصلية + تعليمات التحرير مباشرة
response = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,/9j/..."}},
            {"type": "text", "text": "اجعل هذه القطة ترتدي قبعة عيد الميلاد"}
        ]
    }]
)

🎯 توصية: للمشاريع الجديدة، يُنصح باستخدام الحل 1 (ميزة المحادثة في SDK الرسمية). أما المشاريع القائمة، فيمكن اختيار الحل 2 أو 3 بناءً على حجم التعديلات المطلوبة. عند الاستدعاء عبر APIYI (apiyi.com) لنموذج Nano Banana 2، يعمل الحلان 2 و3 بشكل طبيعي.

مفاهيم خاطئة شائعة حول thought_signature في Nano Banana 2

المفهوم الخاطئ	الحقيقة
هذه مشكلة أمان محتوى	لا. خطأ 400 يعني فشل التحقق من المعاملات، ولا علاقة له بـ IMAGE_SAFETY
هذه مشكلة في منصة API	لا. هذا متطلب تقني خاص بآلية عمل نماذج سلسلة Gemini 3
يمكنني إنشاء التوقيع بنفسي	لا. التوقيع مشفر، ويجب إعادة إرسال القيمة التي أرجعها النموذج كما هي
مطلوب فقط في استدعاءات الدوال	قد يكون مطلوباً في جميع أنواع الأجزاء (parts) في سلسلة Gemini 3
ضبط thinking: off يحل المشكلة	لا. حتى لو تم ضبط مستوى التفكير على minimal، سيظل التوقيع يُرجع ويجب إعادة إرساله

موقع thought_signature في استجابة Nano Banana 2

في بيانات استجابة Nano Banana 2، يجب الانتباه إلى نوعين خاصين من الأجزاء (parts):

صور مؤقتة (thought: true): هي صور وسيطة يتم إنشاؤها أثناء عملية استنتاج النموذج، وتُسمى thought: true. هذه بيانات مؤقتة ولا تحتاج لعرضها للمستخدم.

الصور النهائية (تحتوي على thought_signature): الصور المولدة نهائياً ستتضمن حقل thought_signature. هذا هو التوقيع الذي يجب عليك إرساله في الطلب التالي.

{
  "candidates": [{
    "content": {
      "parts": [
        {
          "inlineData": {"mimeType": "image/png", "data": "..."},
          "thought_signature": "CkYKRAo..."
        }
      ]
    }
  }]
}

🎯 تفاصيل تقنية: thought_signature عبارة عن سلسلة نصية مشفرة، يتراوح طولها عادة بين 200 و500 حرف. لا تحاول تحليلها أو تعديلها أو إنشائها بنفسك؛ أعد إرسال ما استلمته تماماً. عند الاستدعاء عبر خدمة وكيل API الخاص بـ APIYI (apiyi.com)، يكون تنسيق الاستجابة متطابقاً تماماً مع API الأصلي من جوجل.

---

قائمة التحقق من أخطاء thought_signature في Nano Banana 2

خطوات الاستكشاف السريع (4 خطوات):

1. تأكد من وجود طلبات متعددة الجولات: إذا كانت مصفوفة messages لديك تحتوي على ردود سابقة من دور model (خاصة بيانات الصور)، فهذا يعني أنك في طلب متعدد الجولات.
2. تحقق من حفظ الاستجابة الكاملة: هل تحتوي استجابة النموذج في الجولة السابقة على حقل thought_signature؟ وهل تم حفظه بالكامل؟
3. تحقق من عدم تعديل التوقيع: أثناء عملية تحويل JSON (تسلسل/إلغاء تسلسل)، هل تم اقتطاع سلسلة التوقيع أو تغيير ترميزها؟
4. تحقق من محاذاة الأجزاء (part position): رسائل الخطأ التي تحتوي على content position X, part position Y تساعدك في تحديد الجزء الذي يفتقد التوقيع بدقة.

الأسئلة الشائعة

س1: هل يظهر هذا الخطأ أيضاً عند توليد الصور في جولة واحدة؟

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

س2: كيف يتم التعامل مع الأمر عند الاستدعاء عبر واجهة متوافقة مع OpenAI؟

عند استدعاء Nano Banana 2 عبر واجهة APIYI (apiyi.com) المتوافقة مع OpenAI، يكمن السر في حفظ الكائن الكامل لرد النموذج (model) من الجولة السابقة، وإدراجه كجزء من سجل المحادثة في الطلب التالي. لا تقم بحفظ بيانات الصورة فقط وتجاهل الحقول الأخرى. إذا كانت منصتك (مثل Dify أو Cherry Studio) تدير سجل المحادثة تلقائياً، تأكد من أنها تحتفظ بـ thought_signature بشكل كامل.

س3: هل يجب إعادة إرسال الصور المؤقتة التي تحمل الوسم thought: true؟

نعم، يجب ذلك. قد يعيد Nano Banana 2 أثناء عملية الاستدلال صوراً مؤقتة موسومة بـ thought: true، وهي جزء من "عملية تفكير" النموذج. عند بناء سجل المحادثة، يجب إعادة إرسال جميع الأجزاء (parts) التي أعادها النموذج (بما في ذلك الصور المؤقتة) كما هي. الطريقة الأكثر أماناً هي إعادة إرسال كائن رد النموذج (model response) بالكامل.

---

ملخص

النقاط الجوهرية حول خطأ thought_signature 400 في Nano Banana 2:

1. ليس مشكلة أمان محتوى: هذا مطلب خاص بآلية المحادثات متعددة الجولات في سلسلة نماذج Gemini 3، ولا علاقة له بـ IMAGE_SAFETY.
2. سبب واضح: عدم إعادة إرسال thought_signature التي أعادها النموذج في الجولة السابقة كما هي عند إجراء طلبات متعددة الجولات.
3. حل المشكلة: استخدم وظيفة المحادثة (chat) في حزمة SDK الرسمية (التي تعالج الأمر تلقائياً)، أو استخرج التوقيع وأعد إرساله يدوياً، أو انتقل إلى طلبات الجولة الواحدة.

تذكر المبدأ الأساسي: لا تقم بتعديل، أو حذف، أو إنشاء thought_signature التي يعيدها النموذج بنفسك؛ أعد إرسال ما استلمته تماماً كما هو.

إذا كنت بحاجة لاستدعاء Nano Banana 2 عبر منصة طرف ثالث، نوصي باستخدام APIYI (apiyi.com)، حيث يتطابق تنسيق الاستجابة تماماً مع واجهة برمجة تطبيقات جوجل الأصلية، بتكلفة 0.05 دولار لكل استدعاء، وبدون قيود على التزامن.

📚 المراجع

1. وثائق Google الرسمية لـ Thought Signatures: شرح مفصل لآلية توقيع التفكير (Thought Signatures).

   • الرابط: ai.google.dev/gemini-api/docs/thought-signatures
   • الوصف: الوثائق الرسمية، تتضمن مبدأ العمل، سلوك النموذج، وطريقة المعالجة عبر SDK.

2. دليل مطوري Google Gemini 3: الميزات الجديدة في سلسلة Gemini 3.

   • الرابط: ai.google.dev/gemini-api/docs/gemini-3
   • الوصف: توضيح لمتطلبات التوقيع الإلزامية والميزات الجديدة في سلسلة Gemini 3.

3. وثائق توليد الصور من Google: أفضل الممارسات لتوليد الصور باستخدام Nano Banana.

   • الرابط: ai.google.dev/gemini-api/docs/image-generation
   • الوصف: نصائح حول استخدام thought_signature في عمليات تحرير الصور متعددة الجولات.

4. وثائق Google Cloud Vertex AI: شرح توقيع التفكير على مستوى المؤسسات.

   • الرابط: docs.google.com/vertex-ai/generative-ai/docs/thought-signatures
   • الوصف: طرق معالجة وتكوين التوقيع في بيئة Vertex AI.

---

المؤلف: فريق APIYI التقني
النقاش التقني: نرحب بمشاركتكم لتجاربكم في تنفيذ التحرير متعدد الجولات باستخدام Nano Banana 2 في قسم التعليقات، ولمزيد من المعلومات يمكنكم زيارة مركز توثيق APIYI عبر الرابط docs.apiyi.com