Gemini 3.7 Flash إلى 3.8 Flash: دليل ترحيل API

أطلقت جوجل نموذج Gemini 3.8 Flash في 2 سبتمبر 2026، بعد ثلاثة أسابيع من إطلاق 3.7 Flash، بنفس سعر الإطلاق وبنفس السرعة تقريبًا. معرّف النموذج هو gemini-3.8-flash، بدون لاحقة معاينة، وتصفه بطاقة النموذج بأنه "مبني على Gemini 3.7 Flash". لذلك تتوقع معظم الفرق تبديلاً بسيطًا بسطر واحد. بالنسبة لطلب دردشة عادي، هذا صحيح. أما بالنسبة لأي شيء يضبط معلمات التفكير، أو يضبط أخذ العينات، أو يشغل حلقة أدوات، فهناك تسعة أمور للتحقق منها، واثنان منها يعيدان أخطاء لم تكن موجودة في 3.7 Flash مطلقًا.

هذا الدليل هو قائمة التحقق تلك، مبنيًا على صفحة جوجل "ما الجديد في Gemini 3.8 Flash" ودليل مطوري Gemini 3. لكل عنصر جزء "قبل" و"بعد" لكلا شكلي الـ API: واجهة برمجة تطبيقات التفاعلات (Interactions API)، التي تتعامل معها جوجل الآن كمسار أساسي، ونقطة نهاية generateContent القديمة التي لا يزال معظم كود 3.7 Flash يستخدمها. يمكن لصق كل جزء في Apidog وإرساله مقابل نقطة النهاية المباشرة قبل أن يلامس بيئة الإنتاج. إذا كنت تريد نظرة عامة على النموذج أولاً، فابدأ بـ ما هو Gemini 3.8 Flash.

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

ماذا يتغير وماذا لا يتغير

مصدر صفوف الأسعار: صفحة تسعير واجهة برمجة تطبيقات Gemini من Google Gemini API pricing page، حيث صفوف 3.6 و 3.7 و 3.8 Flash متطابقة.

الخطوة 0: قرر ما إذا كنت ستنتقل على الإطلاق

لا شيء يجبر على الترحيل. يذكر منشور إطلاق جوجل أن "Gemini 3.7 Flash لا يزال مدعومًا بالكامل"، ولم يتم نشر تاريخ إيقاف الدعم. تسعير الرمز الواحد لم يتغير، لذا فإن فرق التكلفة الوحيد هو الاستخدام. قدرت Artificial Analysis أن 3.8 Flash في مستوى التفكير العالي يستخدم حوالي 48 ألف رمز مخرج لكل مهمة على مؤشرهم، بزيادة 30% عن 3.7 Flash، مما رفع تكلفة المهمة من $0.40 إلى $0.58 بنفس المعدلات. ارتفع مؤشرهم من 56 إلى 59، وارتفعت دقة استخدام الأدوات في τ³-Banking بمقدار 12 نقطة لتصل إلى 45%.

لذا، المقايضة هي قدرة أكبر لكل مهمة مقابل المزيد من الرموز لكل مهمة. إذا كان عبء عملك قصيرًا، أو حساسًا للكمون، أو كان يمر بالفعل بتقييماته على 3.7 Flash، فيمكنك البقاء كما أنت. يتضمن مقارنة 3.8 Flash مقابل 3.7 Flash الكاملة مصفوفة قرار حسب عبء العمل. إذا كنت ستنتقل، فاستمر في القراءة.

الخطوة 1: تبديل معرّف النموذج في كلا الشكلين

واجهة برمجة تطبيقات التفاعلات (Interactions API) (واجهة برمجة تطبيقات جوجل الأساسية لـ Gemini 3.x):

{"model": "gemini-3.7-flash", "input": "..."}
{"model": "gemini-3.8-flash", "input": "..."}

نقطة النهاية القديمة generateContent (لا تزال مدعومة، ولا يوجد تاريخ إيقاف):

POST /v1beta/models/gemini-3.7-flash:generateContent
POST /v1beta/models/gemini-3.8-flash:generateContent

مجموعة تطوير برامج بايثون (Python SDK)، كلا المسارين:

client.interactions.create(model="gemini-3.8-flash", input=..., generation_config={"thinking_level": "medium"})
client.models.generate_content(model="gemini-3.8-flash", contents=..., config=types.GenerateContentConfig(thinking_config=types.ThinkingConfig(thinking_level="low")))

إذا لم تستخدم واجهة برمجة تطبيقات التفاعلات (Interactions API) من قبل، فإن دليل API الخاص بـ 3.8 Flash يغطي كلا الشكلين بالكامل؛ بينما يغطي دليل API الخاص بـ 3.7 Flash الأقدم فقط generateContent، وهذا هو السبب في أن هذا الدليل يعرض كلا الشكلين.

قائمة التحقق من الترحيل ذات التسعة بنود

تعامل مع هذه البنود بالترتيب. البنود من 1 إلى 4 هي تغييرات في التكوين تظهر على الفور. تؤثر البنود 5 و 6 على حلقات الأدوات وحالة الدورات المتعددة. البنود من 7 إلى 9 هي تغييرات في التخطيط والوسائط لن تكتشفها إلا في الاختبار.

1. تعيين thinking_level: "minimal" إلى "low"

هذا هو البند الذي يتعطل أولاً. يقبل 3.8 Flash القيم low و medium و high. إرسال minimal يعيد خطأ تحقق. الإعداد الافتراضي عند عدم إرسال أي شيء هو medium. نموذج Gemini 3 Pro يضبط افتراضيًا على high، لذا لا تنسخ تكوين Pro وتفترض أنه يتطابق.

قبل (3.7 Flash، التفاعلات):

{"generation_config": {"thinking_level": "minimal"}}

بعد (3.8 Flash):

{"generation_config": {"thinking_level": "low"}}

الشكل القديم، بعد:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

يصف توثيق التفكير من جوجل low كإعداد للكمون و medium كإعداد افتراضي للكود المعقد والعمل الوكالي. المستوى الذي يجب استخدامه لكل مسار هو مقال بذاته؛ لأغراض الترحيل، low هو البديل المباشر لـ minimal.

2. إزالة temperature و top_p و top_k

إرشادات جوجل لكل نموذج Gemini 3 هي الإبقاء على درجة الحرارة (temperature) عند قيمتها الافتراضية 1.0. قد يؤدي خفضها إلى "حدوث حلقات أو تدهور في الأداء". تحمل العديد من تكوينات 3.7 Flash قيمة temperature: 0.2 المتبقية من الأجيال السابقة. احذف مفاتيح أخذ العينات بدلاً من ضبطها.

قبل:

{"generationConfig": {"temperature": 0.2, "topP": 0.9, "topK": 40}}

بعد:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "medium"}}}

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

3. استبدال thinking_budget بـ thinking_level

كان thinking_budget عبارة عن حد أقصى للرموز الرقمية. thinking_level هو تعداد سلسلة (string enum). لا يوجد تعيين حسابي بينهما، لذا اختر المستوى حسب الغرض: مسارات الكمون تحصل على low، والمسارات الافتراضية تحصل على medium، والمسارات المتعددة الخطوات الأكثر صعوبة تحصل على high.

قبل:

{"generationConfig": {"thinkingConfig": {"thinkingBudget": 4096}}}

بعد:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

لا تزال رموز التفكير تُحاسب كرموز إخراج ويتم الإبلاغ عنها في usageMetadata.thoughtsTokenCount، لذا ينتقل التحكم في التكلفة من حد أقصى صارم إلى اختيار مستوى بالإضافة إلى تأكيد في اختباراتك (انظر قسم الانحدار أدناه).

4. إزالة candidate_count

نماذج Gemini 3 والإصدارات الأحدث لا تدعم مرشحين متعددين. احذف المفتاح، واحذف أي كود يستدعي candidates[1] أو ما بعدها.

قبل:

{"generationConfig": {"candidateCount": 2}}

بعد:

{"generationConfig": {}}

إذا قمت بأخذ عينات من عدة مرشحين لاختيار الأفضل، فإن البديل في 3.8 Flash هو مستوى تفكير أعلى، والذي يقوم بالتحقق داخل استجابة واحدة.

5. وضع call_id و name على كل نتيجة دالة

هذا هو الانقطاع الصعب الثاني. في 3.8 Flash، يجب أن تحمل كل نتيجة دالة ترسلها مرة أخرى كلاً من id الاستدعاء و name الدالة. ينص دليل جوجل لـ Gemini 3 على "التأكد من أن جميع كائنات FunctionResponse تتضمن call_id و name". الكود الذي كان يعيد الاسم فقط سيفشل في دور نتيجة الأداة.

Interactions API، بعد:

{
  "previous_interaction_id": "<id from the function_call step>",
  "input": [{
    "type": "function_result",
    "name": "get_weather",
    "call_id": "<id from the function_call step>",
    "result": [{"type": "text", "text": "{\"temp_c\": 24}"}]
  }]
}

تمنحك خطوة function_call للنموذج id و name و arguments؛ انسخ الأولين مباشرة. في الشكل القديم، يحمل جزء functionResponse نفس القيمة في حقل يسمى id (مطابقًا لـ id في جزء functionCall للنموذج) جنبًا إلى جنب مع name و response. يحتوي مرجع استدعاء الدالة من Google على الأمثلة الكنسية، ودليل استدعاء الدالة في 3.8 Flash يشرح حلقة الدورين الكاملة، بما في ذلك سبب قيام 3.8 Flash باستدعاء الأدوات مرات أكثر لكل مهمة مما فعله 3.7 Flash.

6. إعادة توقيعات التفكير (thought signatures) تمامًا كما تم استلامها

تلحق نماذج Gemini 3 توقيعات التفكير بأجزاء الاستجابة. عند بناء الدور التالي بنفسك، أعد كل جزء دون تغيير، بما في ذلك التوقيعات، لجميع أنواع الأجزاء، وليس فقط النصوص. يؤدي إزالة أو إعادة تسلسلها إلى تدهور استمرارية النموذج في الخطوة التالية.

تلغي واجهة برمجة تطبيقات التفاعلات (Interactions API) هذا العمل عندما تسمح للخادم بالاحتفاظ بالحالة: مرر previous_interaction_id وتحتفظ Google بالسجل. إذا قمت بتعيين store: false لاستدعاء لا يعتمد على الحالة، فإنك تمتلك السجل مرة أخرى ويجب عليك إرسال كتل التفكير والتوقيعات بنفسك. في generateContent القديمة، أنت تمتلك السجل دائمًا، لذا راجع أي كود يعيد بناء contents من نسخة مختصرة من الاستجابة الأخيرة.

7. تخصيص المزيد من الرموز لكل مسار

هذا البند لا يحتوي على خطأ يمكن اكتشافه، ولهذا السبب يتم تجاهله. يمثل رقم +30% من رموز الإخراج من Artificial Analysis متوسطًا عبر مؤشرهم في مستوى التفكير العالي. صياغة Google الخاصة هي أن النموذج "يمكنه استخدام المزيد من الرموز في المهام الأطول والأكثر تعقيدًا، حسب التصميم" وأن الاستخدام يرتفع "خاصة عند مستويات الجهد الأعلى".

• نقاط النهاية الحساسة للكمون: low. قدرت AA 0.8 دقيقة لكل مهمة عند مستوى منخفض مقابل 2.5 دقيقة عند مستوى عالٍ، و $0.24 لكل مهمة مقابل $0.58.
• المسارات الافتراضية: medium، بحوالي $0.41 لكل مهمة على نفس المؤشر.
• حلقات الوكيل: توقع المزيد من دورات استدعاء الأدوات لكل مهمة، لذا حدد الحلقة بعدد الدورات، وليس فقط بالرموز.

راجع أيضًا سقف الرموز المخرجة البالغ 65,536. قد يعمل طلب 3.7 Flash الذي أعاد 40 ألف رمز مع التفكير الآن أقرب إلى الحد الأقصى. إذا كنت تقوم بنمذجة الفاتورة، فإن تحليل تسعير 3.8 Flash يعمل على أرقام كل مهمة في المستويات الثلاثة.

8. اختبار media_resolution_high على ملفات PDF مقابل الفيديو

يقبل 3.8 Flash مدخلات نصية، وصورية، وفيديو، وصوتية، وملفات PDF. يغير إعداد دقة الوسائط عدد الرموز التي يستهلكها كل مدخل وسائط، وتختلف التكلفة حسب نوع الوسائط، لذا فإن نفس الإعداد الذي يكون رخيصًا على صفحة PDF يمكن أن يكون مكلفًا على فيديو طويل. لا تنقل إعداد دقة عالية عالميًا من 3.7 Flash دون قياس. أرسل ملف PDF تمثيليًا واحدًا وفيديو تمثيليًا واحدًا بكل دقة وقارن usageMetadata.promptTokenCount بينهما.

9. إسقاط أي استدعاءات لتجزئة الصور

تجزئة الصور غير مدعومة في نماذج Gemini 3. إذا كانت عملية سابقة من عصر 3.7 Flash لا تزال توجه التجزئة عبر نموذج Gemini أقدم، فإن هذا المسار منفصل عن هذا الترحيل؛ إذا طلب طلب من 3.8 Flash أقنعة تجزئة، فتوقع أن يفشل بدلاً من إرجاع مخرج قابل للاستخدام. توليد الصور، وتوليد الصوت، وواجهة برمجة التطبيقات المباشرة (Live API) غير مدعومة أيضًا على 3.8 Flash، وفقًا لصفحة النموذج.

بناء خطة الانحدار في Apidog

يتطلب الترحيل الذي يحتوي على تغييرين جذريين وتحول في استخدام الرموز مقارنة قابلة للتكرار، وليس مجرد استدعاء واحد بـ curl. إليك الإعداد الذي نستخدمه في Apidog، والذي يعمل لأن Apidog هو عميل API ومدير اختبار: يرسل الطلبات، ويتحقق من الاستجابات، ويجدول التشغيل. لا يقوم بتشغيل النموذج.

البيئة والمتغيرات. أنشئ بيئة Gemini مع GEMINI_API_KEY مخزنة كمتغير سري ومتغير MODEL. استخدم {{MODEL}} في عنوان URL لطلب generateContent وفي حقل model لطلب Interactions، بحيث يتم تشغيل نفس الطلب المحفوظ مقابل أي من النموذجين.

الطلبات الذهبية (Golden prompts). احفظ من 10 إلى 20 طلبًا تمثل مساراتك الحقيقية: دورة دردشة قصيرة، استخراج مخرج مهيكل، استدعاء دالة من دورين باستخدام أداة وهمية، مدخل PDF واحد، ومدخل فيديو واحد. كل منها هو طلب واحد في سيناريو اختبار.

التأكيدات (Assertions). أضف ثلاثة لكل طلب:

• الحالة هي 200، ويتطابق نص الاستجابة مع مخطط JSON. بالنسبة لمسارات المخرجات المهيكلة، تأكد من الحقول التي تقوم بتحليلها لاحقًا.
• يبقى usageMetadata.thoughtsTokenCount أقل من سقف تحدده لكل مسار (على سبيل المثال، 8,000 في مسار low). هذا هو الحارس الذي يلتقط تكوينًا عاد بصمت إلى medium.
• يبقى usageMetadata.totalTokenCount أقل من ميزانية المسار من البند 7.

جنباً إلى جنب (Side by side). كرر السيناريو، اضبط MODEL على gemini-3.7-flash في أحدهما وعلى gemini-3.8-flash في الآخر، وشغل كلاهما. تظهر تقارير اختبار Apidog النجاح/الفشل لكل تأكيد ونصوص الاستجابات، بحيث يكون فرق الرموز لكل طلب مرئيًا في عرض واحد بدلاً من إعادة بنائه من السجلات. لسيناريو استدعاء الدالة، أضف تأكيدًا بأن call_id الذي أعدته يساوي id من function_call للخطوة السابقة.

جدولتها. حول سيناريو 3.8 Flash إلى تشغيل مجدول بحيث يتم فحص حدود الرموز يوميًا خلال فترة النشر. يغطي دليل اختبارات API المجدولة الإعداد. إذا كنت تفضل المتابعة في التطبيق، حمل Apidog واستورد أجزاء curl أعلاه.

التراجع: الاحتفاظ بـ 3.7 Flash خلف علامة تكوين

بما أن 3.7 Flash لا يزال مدعومًا بالكامل ويشارك 3.8 Flash في السعر، فإن التراجع رخيص: احتفظ بمعرف النموذج في التكوين بدلاً من الكود.

{"gemini_model": "gemini-3.8-flash", "gemini_fallback_model": "gemini-3.7-flash"}

ثلاث قواعد تجعل العلم آمنًا:

• حافظ على شكل الطلب المهاجر على كلا النموذجين. البنود من 1 إلى 6 (لا minimal، لا مفاتيح أخذ عينات، thinking_level وليس thinking_budget، لا candidate_count، call_id + name، التوقيعات محفوظة) كلها صالحة أيضًا على 3.7 Flash، لذا فإن تبديل العلم لا يحتاج أبدًا إلى مسار كود ثانٍ.
• انشر لكل مسار. اقلب مسارات الكمون منخفضة المستوى أولاً، نظرًا لأن فرق الرموز فيها هو الأصغر؛ اقلب حلقات الوكيل أخيرًا، بعد أن يكون سيناريو المقارنة قد مر لبضعة أيام.
• راقب الرموز، وليس الأخطاء فقط. من المرجح أن يكون محفز التراجع في 3.8 Flash انحدارًا في التكلفة أو الكمون بدلاً من خطأ 4xx، لذا قم بتوصيل تأكيدات سقف الرموز بنظام التنبيه الخاص بك.

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

هل يكلف Gemini 3.8 Flash أكثر من 3.7 Flash؟ ليس لكل رمز. كلاهما بسعر $0.75 للإدخال / $3.75 للإخراج لكل مليون رمز حتى 31 ديسمبر 2026، ويرتفع كلاهما إلى $1.50 / $7.50 في 1 يناير 2027. لكل مهمة، يستخدم 3.8 Flash رموزًا أكثر حسب التصميم؛ قدرت Artificial Analysis حوالي 30% رموز إخراج إضافية على مؤشرها في مستوى التفكير العالي.

ماذا يحدث إذا تركت thinking_level: "minimal" كما هي؟ سيفشل الطلب بخطأ تحقق في 3.8 Flash. استبدله بـ low. يشرح دليل مستويات التفكير ما يفعله كل مستوى متبقي وكيفية قياس الفرق.

هل يجب علي الانتقال إلى Interactions API لاستخدام 3.8 Flash؟ لا. يوصف generateContent بأنه قديم ولكنه يظل مدعومًا بالكامل بدون تاريخ إيقاف، ويعمل 3.8 Flash عليه. تضيف Interactions API حالة محادثة من جانب الخادم عبر previous_interaction_id، مما يلغي مسك سجل توقيعات التفكير في البند 6.

هل سيتم إيقاف دعم 3.7 Flash؟ تقول جوجل إنه "يبقى مدعومًا بالكامل" ولم تنشر تاريخ إيقاف. هذا ما يجعل التراجع باستخدام علامة التكوين ممكنًا.

هل يمكنني الاحتفاظ بنفس درجة الحرارة التي قمت بضبطها لـ 3.7 Flash؟ نصيحة جوجل لجميع نماذج Gemini 3 هي ترك درجة الحرارة عند 1.0. إذا كنت قد تجاوزتها بالفعل في 3.7 Flash، فإن هذا الترحيل هو الوقت المناسب لإزالتها والتحقق من تقييماتك؛ المخرجات المهيكلة هي المسار المدعوم للأشكال الحاسمة.

الشحن على مراحل

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