الأسئلة الشائعة وتحديد المشاكل وحلّها

الاختلافات بين استخدام Gemini Developer API وAgent Platform Gemini API (formerly Vertex AI)

يسرد الجدول التالي الاختلافات المهمة بين مقدِّمَي خدمة "Gemini API" بشكل عام بغض النظر عن كيفية الوصول إليهما:

^‫1 يختلف سعر الدفع حسب الاستخدام بين مقدّمي واجهة برمجة التطبيقات (يمكنك الاطّلاع على مزيد من المعلومات في المستندات الخاصة بكل منهما).

^‫2 لا تتوفّر واجهة Files API لـ Gemini Developer API من خلال حِزم تطوير البرامج (SDK) في Firebase AI Logic.

يعرض الجدول التالي مدى توفّر الميزات التي يتم السؤال عنها بشكل شائع لمقدّمي خدمات "Gemini API". ينطبق هذا الجدول تحديدًا عند استخدام Firebase AI Logic حزم تطوير البرامج (SDK) للعملاء.

كيفية استخدام كل من Gemini Developer API وAgent Platform Gemini API (formerly Vertex AI)

يمكنك تفعيل كلا مقدِّمَي خدمة Gemini API في مشروع Firebase، ويمكنك استخدام كلتا واجهتَي برمجة التطبيقات في تطبيقك.

للتبديل بين مقدّمي واجهة برمجة التطبيقات في الرمز البرمجي، ما عليك سوى التأكّد من ضبط خدمة الخلفية بشكل مناسب في الرمز البرمجي.

واجهات برمجة التطبيقات المطلوبة وكيفية تفعيلها

لاستخدام حِزم تطوير البرامج (SDK) الخاصة بـ Firebase AI Logic مع Agent Platform Gemini API (formerly Vertex AI)، يجب تفعيل واجهتَي برمجة التطبيقات التاليتَين في مشروعك:

• واجهة برمجة التطبيقات Agent Platform (aiplatform.googleapis.com)
• واجهة برمجة التطبيقات Firebase AI Logic (firebasevertexai.googleapis.com)

يمكنك تفعيل واجهات برمجة التطبيقات هذه باستخدام أحد الخيارَين التاليَين:

• الخيار 1 (يُنصح به): فعِّل واجهات برمجة التطبيقات ببضع نقرات في وحدة تحكّم Firebase:

  1. في وحدة تحكّم Firebase، انتقِل إلى صفحة خدمات الذكاء الاصطناعي > Firebase AI Logic.

  2. انقر على البدء.

  3. انقر للبدء في استخدام Agent Platform Gemini API (formerly Vertex AI).

     يؤدي ذلك إلى بدء سير عمل موجَّه يفعّل واجهتَي برمجة التطبيقات نيابةً عنك. ستوفّر Firebase أيضًا حساب خدمة مُدارًا من Google (P4SA) للسماح باستخدام Gemini API، بالإضافة إلى إضافة واجهة برمجة تطبيقات Firebase AI Logic إلى القائمة المسموح بها لمفتاح واجهة برمجة تطبيقات Firebase.

• الخيار 2 (يدوي، لا يُنصح به): فعِّل واجهات برمجة التطبيقات في وحدة تحكّم Google Cloud:

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

  2. أضِف واجهة برمجة تطبيقات Firebase AI Logic إلى القائمة المسموح بها لمفتاح واجهة برمجة تطبيقات Firebase.

كيفية إيقاف واجهات برمجة التطبيقات في مشروع Firebase

بالنسبة إلى "Firebase AI Logic"، نحاول تسهيل عملية إعداد مشروع Firebase الخاص بك قدر الإمكان لاستخدام مقدّم خدمة "Gemini API" الذي اخترته. ويشمل ذلك تفعيل واجهات برمجة التطبيقات المطلوبة في مشروع Firebase خلال رحلات معيّنة، مثل سير العمل الإرشادي في وحدة تحكّم "Firebase".

ومع ذلك، إذا قررت عدم استخدام Firebase AI Logic أو أحد مقدّمي خدمات Gemini API، يمكنك إيقاف واجهات برمجة التطبيقات المرتبطة في مشروع Firebase.

الأذونات المطلوبة لاستخدام Firebase AI Logic

النماذج المتوافقة عند استخدام Firebase AI Logic

اطّلِع على قائمة الطُرز المتوافقة. نضيف بشكل متكرّر إمكانات جديدة إلى حِزم تطوير البرامج (SDK)، لذا يُرجى مراجعة هذه الأسئلة الشائعة للاطّلاع على التعديلات (بالإضافة إلى ملاحظات الإصدار والمدوّنات والمنشورات على شبكات التواصل الاجتماعي).

• يتيح Firebase AI Logic استخدام النماذج التالية:

  • Gemini Developer API

    • معظم النماذج الأساسية من Gemini

  • Agent Platform Gemini API (formerly Vertex AI)

    • معظم النماذج الأساسية من Gemini

• Firebase AI Logic لا يتوافق مع الطُرز التالية (بغض النظر عن مقدّم خدمة Gemini API الذي اخترته):

  • النماذج المضبوطة بدقة

  • نماذج التضمين، أو نماذج Veo، أو نماذج Lyria، أو نماذج الروبوتات، أو نماذج استخدام الكمبيوتر، Gemini أو نماذج Omni، Gemini أو نماذج Cyber

كيفية ضبط حدّ أقصى لمعدّل الإرسال لكل مستخدم

يضبط Firebase AI Logic تلقائيًا الحدّ الأقصى لعدد الطلبات لكل مستخدم على 100 طلب في الدقيقة.

إذا أردت تعديل الحدّ الأقصى لعدد الطلبات لكل مستخدم، عليك تعديل إعدادات الحصة لواجهة برمجة التطبيقات Firebase AI Logic.

مزيد من المعلومات حول حصة واجهة برمجة التطبيقات في Firebase AI Logic في تلك الصفحة، يمكنك أيضًا التعرّف على كيفية عرض حصتك وتعديلها.

كيفية تقليل وقت الاستجابة والاستخدام العالي للرموز المميّزة

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

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

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

يُرجى العِلم أنّه في معظم نماذج Gemini 3 والإصدارات الأحدث، يتم ضبط مستوى التفكير التلقائي على HIGH.

متطلبات نوع MIME للطلبات المتعددة الوسائط (مثل الصور وملفات PDF والفيديو والإدخال الصوتي)

في كل طلب متعدد الوسائط، يجب دائمًا تقديم ما يلي:

• الملف هو mimeType. يُرجى الاطّلاع على الاستثناء أدناه.

• الملف يمكنك تقديم الملف كبيانات مضمّنة أو تقديم الملف باستخدام عنوان URL الخاص به.

تعرَّف على أنواع ملفات الإدخال المتوافقة وكيفية تحديد نوع MIME والخيارَين المتاحَين لتقديم الملف في ملفات الإدخال المتوافقة والمتطلبات.

استثناء من تضمين نوع MIME في طلبك

يُستثنى من توفير نوع MIME إدخالات الصور المضمّنة للطلبات من تطبيقات Android وApple الأساسية.

توفّر حِزم تطوير البرامج (SDK) في Firebase AI Logic لمنصّتَي Android وApple طريقة مبسّطة ومتوافقة مع المنصّات للتعامل مع الصور في الطلبات، إذ يتم تحويل جميع الصور (بغض النظر عن تنسيقها) من جهة العميل إلى تنسيق JPEG بجودة %80 قبل إرسالها إلى الخادم. يعني ذلك أنّه عند تقديم الصور كبيانات مضمّنة باستخدام حِزم تطوير البرامج (SDK) لمنصّات Android وApple، لن تحتاج إلى تحديد نوع MIME في الطلب.

تظهر هذه المعالجة المبسّطة في مستندات Firebase AI Logic في الأمثلة على إرسال الصور بترميز base64 في الطلبات.

في ما يلي بعض المعلومات الإضافية الخاصة بالمنصة حول هذه الميزة:

• على أجهزة Android:

  • يمكنك الاستفادة من الطريقة المبسّطة للتعامل مع أنواع الصور الأصلية في النظام الأساسي (Bitmap) في الطلبات المتعددة الوسائط التي تحتوي على صور كبيانات مضمّنة (راجِع المثال).

  • للمزيد من التحكّم في تنسيقات الصور وعمليات التحويل، يمكنك تقديم الصور كـ InlineDataPart وتوفير نوع MIME المحدّد. على سبيل المثال:

    content { inlineData(/* PNG as byte array */, "image/png") }

• بالنسبة إلى أنظمة Apple الأساسية:

  • يمكنك الاستفادة من الطريقة المبسّطة للتعامل مع أنواع الصور الأصلية في المنصة (UIImage وNSImage وCIImage وCGImage) في الطلبات المتعددة الوسائط التي تحتوي على صور كبيانات مضمّنة (راجِع المثال).

  • للمزيد من التحكّم في تنسيقات الصور وعمليات التحويل، يمكنك تقديم الصور كـ InlineDataPart وتوفير نوع MIME المحدّد. على سبيل المثال:

    InlineDataPart(data: Data(/* PNG Data */), mimeType: "image/png")

الميزات المتقدّمة غير المتاحة بعد عند استخدام Firebase AI Logic: تحديد المصدر باستخدام صور بحث Google، وضبط النموذج بدقة، وإنشاء التضمينات، واسترجاع الدلالات

تتوفّر الميزات التالية في نماذج مختلفة ومقدّمي خدمات واجهة برمجة التطبيقات، ولكنّها لا تكون متاحة عند استخدام Firebase AI Logic:

• تحديد المصدر من خلال "صور بحث Google"
• ضبط نموذج بدقة
• إنشاء التضمينات
• استرجاع دلالي

إذا أردت إضافة هذه الميزات كطلبات ميزات أو التصويت على طلب ميزة حالي، يُرجى الانتقال إلى Firebase UserVoice.

استخدام البيانات لتدريب النماذج

يُرجى الاطّلاع على إدارة البيانات والذكاء الاصطناعي المسؤول.

النماذج المتوقّفة نهائيًا أو التي تم إيقافها (النماذج القديمة) - القائمة والبدائل

عندما تطرح Google إصدارًا ثابتًا من النموذج، نسعى جاهدين لإبقائه متاحًا لمدة 12 شهرًا على الأقل قبل إيقافه نهائيًا.

ومع ذلك، يُرجى الانتباه إلى ما يلي:

• بالنسبة إلى Agent Platform Gemini API (formerly Vertex AI)، لا تتوفّر بعض النماذج الثابتة إلا لفترة قصيرة، ما يعني أنّه قد يتم إيقافها (إيقافها نهائيًا) بعد 45 يومًا من طرح نموذج بديل.

• بالنسبة إلى Gemini Developer API، بدلاً من إيقاف نموذج معيّن، ستوجّه الخدمة الطلب تلقائيًا إلى نموذج أحدث. يتم احتساب تكلفة الطلبات المرسَلة إلى النموذج الأحدث وفقًا لأسعار هذا النموذج.

• قبل عدة أسابيع من تاريخ الإيقاف النهائي، سيتم حظر المشاريع التي لم تستخدم النموذج من قبل من بدء استخدامه.

• عند طرح إصدار ثابت لنموذج معيّن، يتم عادةً إيقاف جميع الإصدارات التجريبية والحصرية من هذا النموذج (إيقافها نهائيًا) في غضون بضعة أيام أو أسابيع (لا تدرج هذه الأسئلة الشائعة كل نموذج حصري وتجريبي سابق).

نماذج الاستخدام العام

^{1 بالنسبة إلى Agent Platform Gemini API (formerly Vertex AI)، يُعدّ هذا "نموذج توفّر على المدى القصير". يُرجى الاطّلاع على أنماط تسمية النماذج وإصداراتها}

^{سيتم أيضًا إيقاف جميع النماذج التالية المخصّصة للاستخدام العام: gemini-1.0-pro، gemini-1.0-pro-001، gemini-1.0-pro-002، gemini-1.0-pro-vision، gemini-1.0-pro-vision-001 gemini-1.5-flash-001، gemini-1.5-flash، gemini-1.5-flash-002، gemini-1.5-pro-001، gemini-1.5-pro، gemini-1.5-pro-002}

نماذج إنشاء الصور (Nano Banana وImagen)

الصوت - نماذج Live API

التغييرات المطلوبة عند إيقاف النماذج نهائيًا أو إيقافها (إيقافها نهائيًا)

أين يمكن العثور على تاريخ إيقاف النموذج؟

في ما يلي بعض الطرق التي يمكنك من خلالها العثور على تاريخ إيقاف النموذج:

• ترسل Google رسائل إلكترونية إلى أعضاء المشروع المعنيين.

• ننشر إشعارات وتذكيرات بشأن عمليات الإيقاف القادمة في قنوات مختلفة:

  • ملاحظات الإصدار (يُرجى الاطّلاع على مثال)
  • البانرات على مستوى الصفحة في المستندات وصفحة النماذج المتوافقة والأسئلة الشائعة حول النماذج المتوقفة نهائيًا

ماذا أفعل إذا كان النموذج الذي أستخدمه على وشك الإيقاف؟

يجب إجراء هذه التغييرات قبل تاريخ الإيقاف النهائي، وإلا ستتعذّر أي طلبات إلى نموذج تم إيقافه نهائيًا وسيظهر الخطأ 404.

1. ابحث عن طراز متوافق حاليًا واسم الطراز.

   ونوفّر أيضًا نماذج بديلة مقترَحة في الأسئلة الشائعة حول النماذج المتوقفة نهائيًا.

2. عدِّل اسم النموذج الذي يستخدمه تطبيقك.

   يمكنك ضبط اسم النموذج أثناء الإعداد عند إنشاء مثيل GenerativeModel أو LiveModel أو ImagenModel. يُرجى مراجعة الاقتراح المهم أدناه حول استخدام Firebase Remote Config أو نماذج الطلبات من الخادم.

3. تحقَّق مما إذا كنت بحاجة إلى تعديل أي من الرموز البرمجية.

   عادةً لا تحتاج إلى تعديل أي من الرموز البرمجية التي تستدعي النموذج. في ما يلي بعض الاستثناءات:

   • مَعلمات اختيار العينات غير المتوافقة: في أحدث نماذج Gemini 4.x وGemini 3.x، لا تتوفّر عدة مَعلمات (على وجه التحديد، درجة العشوائية، وأعلى K كلمة محتملة، وأعلى احتمال تراكمي، وعقوبة التكرار، وعقوبة الحضور، وعدد المرشحين).

   • مستوى التفكير مقابل ميزانية التفكير: بدءًا من نماذج Gemini 3.x، يجب استخدام thinkingLevel بدلاً من thinkingBudget (ولكن لا يزال thinkingBudget متاحًا للتوافق مع الأنظمة القديمة). ومع ذلك، بدءًا من طُرز Gemini 4.x، thinkingBudget غير متوافق. مزيد من المعلومات حول التفكير

   • تجربة قيمة مستوى التفكير: عند الترقية إلى جيل جديد (على سبيل المثال، من 2.5 إلى 3.8) وإذا أردت ضمان الأداء والسلوك نفسهما (على سبيل المثال، وقت الاستجابة)، ننصحك بتجربة ضبط مستوى التفكير على قيمة أقل. مزيد من المعلومات حول التفكير

4. اختبِر تطبيقك للتأكّد من أنّ الردود لا تزال على النحو المتوقّع.

التغييرات المطلوبة لإعادة تسمية "Vertex AI" إلى "Agent Platform"

في منتصف عام 2026، غيّرت Google Cloud العلامة التجارية لـ Vertex AI إلى "Gemini Enterprise Agent Platform" (أو "Agent Platform"). في منظومة Firebase المتكاملة، نشير إلى هذه الخدمة باسم "Agent Platform Gemini API".

بالنسبة إلى Google Cloud، شملت عملية تغيير العلامة التجارية ما يلي: يُرجى العِلم أنّه تم إجراء تغييرات أخرى، ولكنّها لا تنطبق على "Firebase AI Logic".

• تغيير العلامة التجارية للمنتج من "Vertex AI" إلى "Gemini Enterprise Agent Platform" (أو "Agent Platform")، والذي يتضمّن عناوين URL جديدة لوحدة تحكّم Google Cloud والمستندات.

• تغيير الاسم المعروض لواجهة برمجة التطبيقات من "Vertex AI API" إلى "Agent Platform API". يُرجى العِلم أنّ اسم الخدمة لم يتغيّر: aiplatform.googleapis.com.

• تغيير العلامة التجارية لـ "Vertex AI Studio" إلى "Agent Studio".

• لن يتم إجراء أي تغييرات على إمكانات واجهات برمجة التطبيقات الأساسية أو النماذج المتوافقة.

بالنسبة إلى حِزم تطوير البرامج (SDK) في Firebase AI Logic، أجرينا تعديلات على بنية الإعداد لخدمة الخلفية "Gemini API" والموقع الجغرافي التلقائي للوصول إلى النموذج عند استخدام هذه البنية الجديدة، وذلك لتعكس عملية تغيير العلامة التجارية.

• بناء جملة الإعداد الجديد لخدمة الخلفية "Gemini API":

  Swift

  تغيير "vertexAI" إلى "agentPlatform"

  • تتوفّر بنية agentPlatform بدءًا من الإصدار 12.17.0 من حزمة تطوير البرامج (SDK).
  • تمت إزالة بنية vertexAI في الإصدار 13.0.0 من حزمة تطوير البرامج (SDK).

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  let ai = FirebaseAI.firebaseAI(backend: .vertexAI(location: "LOCATION"))
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `agentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  let ai = FirebaseAI.firebaseAI(backend: .agentPlatform(location: "LOCATION"))
  
  // ...
  

  Kotlin

  تغيير "vertexAI" إلى "agentPlatform"

  • تتوفّر بنية agentPlatform بدءًا من الإصدار 17.15.0 من حزمة تطوير البرامج (SDK) والإصدار 34.17.0 من Firebase Android BoM.
  • تمت إزالة بنية vertexAI في الإصدار 18.0.0 من حزمة تطوير البرامج (SDK) والإصدار 35.0.0 من BoM.

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  val ai = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "LOCATION"))
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `agentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  val ai = Firebase.ai(backend = GenerativeBackend.agentPlatform(location = "LOCATION"))
  
  // ...
  

  Java

  تغيير "vertexAI" إلى "agentPlatform"

  • تتوفّر بنية agentPlatform بدءًا من الإصدار 17.15.0 من حزمة تطوير البرامج (SDK) والإصدار 34.17.0 من Firebase Android BoM.
  • تمت إزالة بنية vertexAI في الإصدار 18.0.0 من حزمة تطوير البرامج (SDK) والإصدار 35.0.0 من BoM.

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.vertexAI("LOCATION"));
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `agentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"));
  
  // ...
  

  Web

  تغيير "VertexAIBackend" إلى "AgentPlatformBackend"

  • تتوفّر بنية AgentPlatformBackend بدءًا من الإصدار 12.17.0 من حزمة تطوير البرامج (SDK) لـ Firebase JS.
  • تمت إزالة بنية VertexAIBackend في الإصدار 13.0.0 من حزمة تطوير البرامج (SDK).

  قبل

  import { getAI, getGenerativeModel, VertexAIBackend } from "firebase/ai";
  
  // ...
  
  // Initialize FirebaseApp
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `VertexAIBackend` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  const ai = getAI(firebaseApp, { backend: new VertexAIBackend('LOCATION') });
  
  // ...
  

  بعد

  import { getAI, getGenerativeModel, AgentPlatformBackend } from "firebase/ai";
  
  // ...
  
  // Initialize FirebaseApp
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `AgentPlatformBackend` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  const ai = getAI(firebaseApp, { backend: new AgentPlatformBackend('LOCATION') });
  
  // ...
  

  Dart

  تغيير "vertexAI" إلى "agentPlatform"

  • تتوفّر بنية agentPlatform بدءًا من الإصدار 3.15.0 من المكوّن الإضافي والإصدار 4.18.0 من Firebase Flutter BoM.
  • تمت إزالة بنية vertexAI في الإصدار 5.0.0 من المكوّن الإضافي والإصدار 5.0.0 والإصدارات الأحدث من قائمة المواد في Firebase Flutter.

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  final ai = await FirebaseAI.vertexAI(location: 'LOCATION');
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the `agentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  final ai = await FirebaseAI.agentPlatform(location: 'LOCATION');
  
  // ...
  

  Unity

  تغيير "VertexAI" إلى "AgentPlatform"

  • تتوفّر بنية AgentPlatform بدءًا من الإصدار 13.15.0 من Firebase SDK لنظام Unity.
  • تمت إزالة بنية VertexAI في الإصدار 14.0.0 من حزمة تطوير البرامج (SDK).

  قبل

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `VertexAI` syntax, the default location is `us-central1`, so
  // specifying a location is usually required since most models are *not* supported in `us-central1`.
  var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "LOCATION"));
  
  // ...
  

  بعد

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
  // For the `AgentPlatform` syntax, the default location is `global`, so
  // specifying a location is usually optional since most models are supported in `global`.
  var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(location: "LOCATION"));
  
  // ...
  

• الموقع الجغرافي التلقائي الجديد للوصول إلى النموذج عند استخدام بنية الإعداد الجديدة:

  عند استخدام بنية الإعداد الجديدة في Agent Platform، يتم ضبط الموقع الجغرافي تلقائيًا على global.

  تم إجراء هذا التغيير لأنّ جميع طُرز Gemini تقريبًا متوافقة مع global، ولم يعُد Google Cloud يتيح استخدام الموقع الجغرافي us-central1 للإصدارات الجديدة من معظم طُرز Gemini.

بالنسبة إلى تطبيقات Swift: التغييرات المطلوبة لنقل البيانات من FirebaseAI إلى FirebaseAILogic

بالنسبة إلى التطبيقات على منصات Apple، بدءًا من الإصدار 12.5.0 من حزمة تطوير البرامج (SDK) لمنصة Firebase، يتم توزيع Firebase AI Logic ضمن وحدة FirebaseAILogic. في الإصدار 13.0.0 من حزمة تطوير البرامج (SDK)، تمت إزالة وحدة FirebaseAI.

لماذا أجرينا هذا التغيير؟

كنا نوزّع هذه الخدمة سابقًا ضمن وحدة FirebaseAI. ومع ذلك، كان علينا إعادة تسميته إلى FirebaseAILogic للأسباب التالية:

• تجنَّب تعارض الأسماء بين الوحدة والفئة، لأنّ ذلك يؤدي إلى حدوث مشاكل في التوزيعات الثنائية.

• تتيح لنا استخدام وحدات ماكرو Swift لتطوير الميزات المستقبلية.

ماذا يجب أن تفعل إذا كنت بصدد الترقية إلى الإصدار 12.5.0 أو إصدار أحدث أو الإصدار 13.0.0 أو إصدار أحدث؟

في الإصدار 12 من Firebase (بدءًا من الإصدار 12.5.0 والإصدارات الأحدث)، لا يؤدي تغيير اسم الوحدة إلى FirebaseAILogic إلى حدوث عطل وهو متوافق مع الأنظمة القديمة، لذا يُنصح بإجراء هذه التغييرات في الإصدار 12 من Firebase. ومع ذلك، في الإصدار 13.0.0 من Firebase SDK، تمت إزالة وحدة FirebaseAI القديمة، لذا فإنّ هذه التغييرات مطلوبة عند الترقية إلى الإصدار 13 من Firebase.

1. عند اختيار تبعيات Swift PM، اختَر FirebaseAILogic (بدلاً من FirebaseAI).

2. تغيير عبارات الاستيراد إلى FirebaseAILogic (بدلاً من FirebaseAI)

فهم سبب تغيير الاسم من "Vertex AI in Firebase" إلى "Firebase AI Logic"

في عام 2024، أطلقنا مجموعة من حزم تطوير البرامج (SDK) لعملاء Firebase التي يمكنها استخدام Agent Platform Gemini API (formerly Vertex AI) بالإضافة إلى بوابة خادم وكيل Firebase لحماية واجهة برمجة التطبيقات هذه من إساءة الاستخدام وإتاحة عمليات الدمج مع منتجات Firebase الأخرى. أطلقنا على منتجنا اسم "Vertex AI في Firebase"، وكان هذا الاسم يصف بدقة حالات الاستخدام المتاحة لمنتجنا في ذلك الوقت.

ومنذ ذلك الحين، وسّعنا نطاق إمكانات منتجنا. على سبيل المثال، اعتبارًا من مايو 2025، أصبحنا نقدّم الدعم لـ Gemini Developer API، بما في ذلك إمكانية حماية Gemini Developer API من إساءة الاستخدام من خلال التكامل مع Firebase App Check.

نتيجةً لذلك، لم يعُد اسم "Vertex AI في Firebase" يعبّر بدقة عن النطاق الموسّع لمنتجنا. Thus, a new name — Firebase AI Logic — better reflects our evolving feature set and allows us to continue to expand our offerings in the future!

يمكنك الاطّلاع على دليل نقل البيانات للتأكّد من حصولك على أحدث الميزات من Firebase AI Logic (ويمكنك اختياريًا البدء في استخدام Gemini Developer API).

مطلوب تنفيذ إجراءات App Check لجميع إصدارات التطبيق

يجب فرض استخدام App Check في جميع إصدارات تطبيقك التي تستخدم Firebase AI Logic.

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

إذا نفّذت App Check في قاعدة الرموز البرمجية لتطبيقك على الفور، ستتمكّن جميع إصدارات تطبيقك من إرسال رموز مميّزة صالحة لـ App Check. يُعتبر الطلب الذي لا يرسل رمزًا مميّزًا صالحًا غير متحقق منه وسيتم حظره عند تنفيذ App Check.

إذا سبق لك طرح إصدار من تطبيقك للمستخدمين النهائيين لا يتضمّن App Check، يُرجى الاطّلاع على الأسئلة الشائعة حول كيفية تنفيذ App Check وفرضه في تطبيق تم طرحه.

تأخير التنفيذ التلقائي لسياسة "App Check" في "Firebase AI Logic"

اعتبارًا من 2 نوفمبر 2026، سيفرض Firebase تلقائيًا Firebase App Check لـ Firebase AI Logic في مشروعك على Firebase (إذا لم يتم فرضه بعد).

عند فرض استخدام App Check، سيتم حظر أي طلبات إلى Firebase AI Logic بدون رمز مميّز صالح لـ App Check. ويشمل ذلك إصدارات التطبيقات التي تم طرحها ولا تتضمّن مقدّم خدمة مصادقة الإصدار العلني.

إذا كنت قد طرحت إصدارات من التطبيق لا تتضمّن App Check، يمكنك تأجيل التنفيذ التلقائي لـ App Check مؤقتًا في Firebase AI Logic. ومع ذلك، قبل 21 يناير 2027، من الضروري العمل على تنفيذ App Check وفرضه على تطبيقاتك التي تم إصدارها بالفعل.

في ما يلي كيفية تأخير التنفيذ التلقائي لـ "App Check" في Firebase AI Logic:

1. في وحدة تحكّم Firebase، انتقِل إلى الأمان > فحص التطبيقات > علامة التبويب واجهات برمجة التطبيقات.

2. ابحث عن صف Firebase AI Logic.

3. في نهاية الصف، ابحث عن أداة اختيار التاريخ تاريخ التنفيذ: مع رمز editالتعديل.

4. اختَر التاريخ الذي تريد أن يتم فيه تنفيذ App Check تلقائيًا على Firebase AI Logic.

   آخر تاريخ ممكن هو 21 يناير 2027. بعد هذا التاريخ، لن يكون بإمكانك تأجيل التنفيذ التلقائي لسياسة App Check في Firebase AI Logic.

5. انقر على حفظ.

كيفية تنفيذ App Check وفرضه على تطبيق تم إصداره بالفعل

بالنسبة إلى إصدارات التطبيق التي لا تستخدم App Check، فإنّ الطلبات المُرسَلة إلى Firebase AI Logic من هذه الإصدارات لا تحتوي على رموز مميّزة صالحة لـ App Check وتُعتبر غير متحقق منها. سيتم حظر هذه الطلبات عند فرض سياسة App Check على Firebase AI Logic.

تساعدك التعليمات التالية في نقل تطبيقك لتتمكّن من فرض App Check بطريقة تتجنّب انقطاع الخدمة في تطبيق تم إصداره بالفعل ولا يتضمّن App Check.

1. تأخير التنفيذ التلقائي لسياسة "App Check" في "Firebase AI Logic":

   1. في وحدة تحكّم Firebase، انتقِل إلى الأمان > فحص التطبيقات > علامة التبويب واجهات برمجة التطبيقات.

   2. ابحث عن صف Firebase AI Logic.

   3. في نهاية الصف، ابحث عن أداة اختيار التاريخ تاريخ التنفيذ: مع رمز editالتعديل.

   4. اختَر التاريخ الذي تريد أن يتم فيه تنفيذ App Check تلقائيًا على Firebase AI Logic.

      آخر تاريخ ممكن هو 21 يناير 2027. بعد هذا التاريخ، لن يكون بإمكانك تأجيل التنفيذ التلقائي لسياسة App Check في Firebase AI Logic.

   5. انقر على حفظ.

2. يجب تنفيذ موفّر مصادقة الإنتاج في تطبيقك في أقرب وقت ممكن.

   • أنظمة Apple الأساسية: DeviceCheck أو App Attest أو reCAPTCHA Enterprise
   • أجهزة Android: Play Integrity أو reCAPTCHA Enterprise
   • الويب: reCAPTCHA Enterprise
   • ‫Flutter: تتوافق مع جميع مقدّمي الخدمات المذكورين أعلاه، بما في ذلك reCAPTCHA Enterprise
   • ‫Unity: يتيح استخدام جميع موفّري الخدمات المذكورين أعلاه (ستتم إتاحة استخدام reCAPTCHA Enterprise قريبًا)

3. راقِب الطلبات الواردة من تطبيقك لمساعدتك في تحديد الوقت المناسب لتطبيق App Check.

   على سبيل المثال، إذا كانت جميع الطلبات الأخيرة تقريبًا واردة من عملاء تم التحقّق منهم، عليك التفكير في فرض App Check.

4. فرض App Check لـ Firebase AI Logic

5. بالنسبة إلى التطوير المحلي عند فرض App Check، يمكنك إعداد App Check مقدّم خدمة تصحيح الأخطاء مع إبقاء App Check مفروضًا لـ Firebase AI Logic.

التعرّف على ترقيات الأمان (منتصف عام 2026) في Gemini Developer API وFirebase AI Logic

في السابق، كانت Gemini Developer API تعتمد على مفاتيح واجهة برمجة التطبيقات العادية في Gemini للسماح باستخدام Gemini Developer API (generativelanguage.googleapis.com). إذا فعّلت Firebase AI Logic واخترت استخدام Gemini Developer API، ستنشئ Firebase مفتاح واجهة برمجة تطبيقات في Gemini لك يقتصر على Gemini Developer API. تمت تسمية هذا المفتاح Gemini Developer API key (auto created by Firebase).

اعتبارًا من منتصف عام 2026، ستتم ترقية Gemini Developer API إلى بديل أكثر أمانًا يُعرف باسم "مفاتيح التفويض (المصادقة)" (وهي في الأساس حسابات خدمة). تمت ترقية "Firebase AI Logic" في الوقت نفسه. بدلاً من استخدام مفتاح واجهة برمجة تطبيقات Gemini عادي، يتولّى Firebase AI Logic الآن معالجة التفويض لـ Gemini Developer API باستخدام حساب خدمة مُدار من Google‏ (P4SA) نوفّره لك تلقائيًا:
وكيل خدمة Firebase AI Logic (service-PROJECT_ID@gcp-sa-firebasevertexai.iam.gserviceaccount.com)

بالنسبة إلى المشاريع الحالية والجديدة، إذا كنت تستخدم Gemini Developer API من خلال Firebase AI Logic، ليس عليك اتّخاذ أي إجراء للاستفادة من ترقيات الأمان هذه اعتبارًا من منتصف عام 2026.

كيفية نقل مفتاح واجهة برمجة تطبيقات Gemini إلى "مفتاح تفويض"

بالنسبة إلى المشاريع الحالية والجديدة، إذا كنت تستخدم Gemini Developer API من خلال Firebase AI Logic، ليس عليك اتّخاذ أي إجراء للاستفادة من ترقيات الأمان اعتبارًا من منتصف عام 2026 (بما في ذلك الانتقال إلى "مفتاح التفويض").

نيابةً عن مطوّرينا، يتعامل Firebase AI Logic تلقائيًا مع جميع تغييرات الأمان المطلوبة لاستيعاب عملية انتقال Gemini Developer API لطلب "مفاتيح التفويض (المصادقة)".

اعتبارًا من منتصف عام 2026، لن يعود بإمكان "Firebase AI Logic" توفير أو استخدام مفاتيح واجهة برمجة التطبيقات العادية في "Gemini". بدلاً من ذلك، يتولّى Firebase AI Logic الآن عملية التفويض لـ Gemini Developer API باستخدام حساب خدمة مُدار من Google‏ (P4SA) ننشئه لك تلقائيًا في مشروعك على Firebase:
وكيل خدمة Firebase AI Logic‏ (service-PROJECT_ID@gcp-sa-firebasevertexai.iam.gserviceaccount.com)

بناءً على هذا التغيير، يمكنك مراجعة وحذف أي مفتاح واجهة برمجة تطبيقات يحمل الاسم Gemini Developer API key (auto created by Firebase). يمكنك حذف هذا المفتاح في وحدة تحكّم Google Cloud. راجِع ما يلي قبل حذف المفتاح:

• تم إنشاء مفتاح واجهة برمجة التطبيقات "Gemini" من قِبل Firebase لغرض وحيد وهو استخدامه مع "Firebase AI Logic"، لذا من المفترض أن يكون حذفه آمنًا. ومع ذلك، قبل حذف هذا المفتاح، يجب التأكّد من عدم استخدامه عن طريق الخطأ مع أدوات أخرى يمكنها منح إذن الوصول إلى Gemini Developer API، مثل حِزم تطوير البرامج (SDK) لخادم الذكاء الاصطناعي التوليدي أو Genkit. إليك كيفية التحقّق من الاستخدام:
  1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Gemini Developer API، ثم انقر على إدارة.
  2. في علامة التبويب المقاييس، في القائمة المنسدلة بيانات الاعتماد، اختَر المفتاح باسم Gemini Developer API key (auto created by Firebase).
  3. إذا كانت الرسوم البيانية المعروضة لا تُظهر أي استخدام منذ أوائل يوليو 2026 (وهو الوقت الذي توقّف فيه "Firebase AI Logic" عن استخدام مفاتيح واجهة برمجة التطبيقات هذه)، يمكن حذف المفتاح بأمان.
     ومع ذلك، إذا كانت الرسوم البيانية تعرض الاستخدام، يعني ذلك أنّك تستخدم المفتاح مع أداة أخرى وعليك إعادة تسمية المفتاح ليكون واضحًا أنّه يتم استخدامه مع تلك الأداة (وليس مع Firebase AI Logic).
• تأكَّد من عدم حذف أي مفتاح آخر لواجهة برمجة التطبيقات يحمل اسمًا يتضمّن الجزء (auto created by Firebase).

عدم إضافة مفتاح واجهة برمجة تطبيقات Gemini إلى قاعدة الرموز البرمجية لتطبيق ويب أو تطبيق متوافق مع الأجهزة الجوّالة

عند استخدام حِزم تطوير البرامج (SDK) في Firebase AI Logic، لا تحتاج إلى مفتاح واجهة برمجة التطبيقات في Gemini للسماح باستخدام Gemini Developer API، ويجب عدم إضافة مفتاح واجهة برمجة التطبيقات في Gemini إلى قاعدة الرموز البرمجية لتطبيقك.

لا تستخدِم "مفتاح واجهة برمجة تطبيقات Firebase" كمفتاح واجهة برمجة تطبيقات Gemini

لا تستخدِم أبدًا "مفتاح واجهة برمجة تطبيقات Firebase" كمفتاح واجهة برمجة تطبيقات Gemini. ننصحك بشدة بعدم إضافة Gemini Developer API إلى القائمة المسموح بها لمفتاح واجهة برمجة التطبيقات في Firebase.

مفتاح واجهة برمجة التطبيقات في Firebase هو مفتاح واجهة برمجة التطبيقات المُدرَج في ملف إعدادات Firebase أو العنصر الذي تضيفه إلى قاعدة الرموز البرمجية لتطبيقك من أجل ربط تطبيقك بمنصة Firebase. يمكنك تضمين مفتاح واجهة برمجة التطبيقات Firebase في الرمز البرمجي عند استخدام المفتاح فقط مع واجهات برمجة التطبيقات ذات الصلة بـ Firebase (مثل Firebase AI Logic). معلومات مهمة حول مفاتيح واجهة برمجة التطبيقات Firebase

في واجهات برمجة التطبيقات والخدمات > لوحة بيانات الاعتماد في وحدة تحكّم Google Cloud، إليك شكل مفاتيح واجهة برمجة تطبيقات Firebase:

بما أنّه عليك إضافة مفتاح واجهة برمجة التطبيقات في Firebase إلى قاعدة الرموز البرمجية لتطبيقك لكي تعمل واجهات برمجة التطبيقات ذات الصلة بـ Firebase، وبما أنّه يمكن منح الإذن لـ Gemini Developer API من خلال مفتاح واجهة برمجة التطبيقات، ننصحك بشدة بعدم إضافة Gemini Developer API (المعروف باسم "Generative Language API" في وحدة تحكّم Google Cloud) إلى القائمة المسموح بها لمفتاح واجهة برمجة التطبيقات في Firebase. في حال فعلت ذلك، ستعرّض Gemini Developer API لإساءة استخدام محتملة.

كيفية الحفاظ على أمان مفتاح واجهة برمجة التطبيقات في Gemini