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

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

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

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

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

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

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

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

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

التغييرات المطلوبة لإعادة تسمية "Vertex AI" إلى "منصة الوكلاء"

في منتصف عام 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.

  BEFORE

  // ...
  
  // 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"))
  
  // ...
  

  AFTER

  // ...
  
  // 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.

  BEFORE

  // ...
  
  // 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"))
  
  // ...
  

  AFTER

  // ...
  
  // 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.

  BEFORE

  // ...
  
  // 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).

  BEFORE

  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') });
  
  // ...
  

  AFTER

  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.
  تتوفّر هذه الميزة بدءًا من الإصدار 3.15.0 والإصدارات الأحدث من مكوّن Firebase AI Logic الإضافي لتطبيق Flutter (الإصدار 4.18.0 والإصدارات الأحدث من Firebase Flutter BoM).

  BEFORE

  // ...
  
  // 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');
  
  // ...
  

  AFTER

  // ...
  
  // 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"
  تتوفّر هذه الميزة بدءًا من الإصدار 13.15.0 من Firebase SDK لمنصة Unity.

  BEFORE

  // ...
  
  // 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"));
  
  // ...
  

  AFTER

  // ...
  
  // 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. لقد أجرينا هذا التغيير بطريقة لا تؤدي إلى حدوث أخطاء ومتوافقة مع الإصدارات السابقة.

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

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

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

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

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

إنّ تغيير اسم الوحدة إلى FirebaseAILogic لا يؤدي إلى حدوث عطل وهو متوافق مع الأنظمة القديمة في الإصدار 12 من Firebase. ومع ذلك، في Firebase 13، ستتم إزالة هذه الوحدة القديمة. انقل التبعيات وعمليات الاستيراد قبل التحديث إلى الإصدار 13 من Firebase.

ليس عليك إجراء أي تغييرات بسبب تغيير اسم هذه الوحدة، ولكننا ننصحك بإجراء ما يلي:

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

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

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

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

• Gemini Developer API (generativelanguage.googleapis.com)
• واجهة برمجة التطبيقات Firebase AI Logic (firebasevertexai.googleapis.com)

عليك تفعيل هاتين الواجهتين باستخدام وحدة تحكّم Firebase:

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

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

3. انقر للبدء باستخدام Gemini Developer API.

   يؤدي ذلك إلى بدء سير عمل موجَّه يفعّل واجهتَي برمجة التطبيقات نيابةً عنك. ستوفّر Firebase أيضًا حساب خدمة تديره Google (P4SA) من أجل تفويض استخدام Gemini API، بالإضافة إلى إضافة واجهة برمجة التطبيقات 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

الطُرز المتوقّفة نهائيًا أو التي تم إيقافها (المتوقّفة) - القائمة والطُرز البديلة

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

Gemini 2.5 الطُرز الثابتة - تواريخ إيقاف التشغيل وعمليات الاستبدال

• ‫Gemini 2.5 Pro وGemini 2.5 Flash وGemini 2.5 Flash‑Lite

  gemini-2.5-pro
gemini-2.5-flash
gemini-2.5-flash-lite
gemini-2.5-flash-image (المعروفة أيضًا باسم "Nano Banana")

  • بالنسبة إلى النماذج المخصّصة للاستخدام العام، يعتمد تاريخ الإيقاف على مقدّم خدمة Gemini API الذي اخترته:

    • Gemini Developer API (Google AI): تم إيقافها نهائيًا، ولكن لم يتم الإعلان عن تاريخ الإيقاف بعد (يمكن للمشاريع النشطة سابقًا فقط مواصلة استخدامها)
    • Agent Platform Gemini API (formerly Vertex AI): 20 أكتوبر 2026

  • بالنسبة إلى نموذج إنشاء الصور (Nano Banana)، تاريخ الإيقاف هو نفسه بغض النظر عن مقدّم خدمة Gemini API الذي اخترته: 2 أكتوبر 2026

  يُرجى العِلم أنّ نماذج "Nano Banana" الأخرى وأي نماذج Gemini Live API 2.5 ثابتة لن تتأثر.

الاستبدال: انتقِل إلى استخدام أحد أحدث نماذج Gemini (مثل gemini-4-argon أو gemini-3.8-flash أو gemini-3.1-flash-image).

نماذج Imagen الثابتة - تواريخ الإيقاف والبدائل

• سيتم إيقاف جميع نماذج Imagen في 17 أغسطس 2026 (يُرجى العِلم أنّه تم تمديد تاريخ الإيقاف النهائي من 30 يونيو 2026).

البديل: يمكنك نقل تطبيقاتك لاستخدام Gemini نماذج الصور (نماذج "Nano Banana").

نماذج Gemini 2.0 الثابتة - تواريخ الإيقاف والبدائل

• ‫Gemini 2.0 Flash وGemini 2.0 Flash‑Lite:

  ‫gemini-2.0-flash-001 (وعنوانه البديل الذي يتم تعديله تلقائيًا gemini-2.0-flash)
  gemini-2.0-flash-lite-001 (وعنوانه البديل الذي يتم تعديله تلقائيًا gemini-2.0-flash-lite)

  • ‫6 فبراير 2026: لن تكون هذه النماذج متاحة للاستخدام في المشاريع التي لم يسبق لها استخدام النموذج.

  • ‫31 مارس 2026: سيتم إيقاف هذه النماذج نهائيًا.

  يُرجى العِلم أنّ نماذج Gemini Live API 2.0 الثابتة لا تتأثر بذلك.

الاستبدال: يمكنك نقل البيانات لاستخدام أحد نماذج Gemini 3.x الجديدة (مثل gemini-3.1-flash-lite).

النماذج الثابتة من Gemini 1.5 و1.0 - تواريخ الإيقاف والبدائل

• طرازا Gemini 1.5 Pro:

  • gemini-1.5-pro-002 (وgemini-1.5-pro): 24 سبتمبر 2025
  • gemini-1.5-pro-001: ‫24 مايو 2025

• نماذج Gemini 1.5 Flash:

  • gemini-1.5-flash-002 (وgemini-1.5-flash): 24 سبتمبر 2025
  • gemini-1.5-flash-001: 24 مايو 2025

• نماذج Gemini 1.0 Pro Vision: في 21 أبريل 2025 (كان من المقرّر إيقافها في 9 أبريل 2025)

• نماذج Gemini 1.0 Pro: في 21 أبريل 2025 (كان من المقرّر سابقًا في 9 أبريل 2025)

البديل: يمكنك نقل البيانات لاستخدام أحد نماذج Gemini 3.x الجديدة (مثل gemini-3.1-flash-lite).

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

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

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

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

• في وقت الإصدار: نُدرج تاريخ الإيقاف المتوقّع لكل نموذج في عدة أماكن في مستندات مقدّم خدمة Gemini API وكذلك في مستندات Firebase (يُرجى الاطّلاع على صفحة النماذج المتوافقة).

• عند اقتراب تاريخ الإيقاف:

  • ترسل Google رسائل إلكترونية إلى أعضاء المشروع المعنيين.
  • ننشر تذكيرات بشأن عمليات الإيقاف القادمة في قنوات مختلفة:
    • ملاحظات الإصدار (راجِع المثال)
    • البانرات على مستوى الصفحة وصفحة النماذج المتوافقة والأسئلة الشائعة حول النماذج المتوقّفة نهائيًا

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

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

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

2. يُرجى تعديل اسم النموذج الذي يستخدمه تطبيقك قبل تاريخ الإيقاف النهائي، وإلا ستتعذّر أي طلبات موجَّهة إلى هذا النموذج وسيظهر الخطأ 404.

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

   • عند استخدام Firebase AI Logic، عادةً لن تحتاج إلى تعديل أي جزء من الرمز الذي يستدعي النموذج.

     يُرجى العِلم أنّه بالنسبة إلى أحدث طرازات Gemini 4.x وGemini 3.x، لا تتوفّر عدّة مَعلمات (تحديدًا درجة العشوائية، وأعلى K كلمة محتملة، وأعلى احتمال تراكمي، وعقوبة التكرار، وعقوبة الحضور، وعدد المرشحين).

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

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

يضبط 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.

فهم سبب تغيير الاسم من "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" يعبّر بدقة عن النطاق الموسّع لمنتجنا. لذلك، الاسم الجديد — Firebase AI Logic — يعكس بشكل أفضل مجموعة الخصائص المتطورة لدينا ويسمح لنا بمواصلة توسيع عروضنا في المستقبل!

يمكنك الاطّلاع على دليل نقل البيانات للتأكّد من حصولك على أحدث الميزات من 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 وفرضه على تطبيق تم إصداره بالفعل

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

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

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

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

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

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

3. فرض App Check على Firebase AI Logic

4. بالنسبة إلى التطوير المحلي عند فرض 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مفتاح واجهة برمجة تطبيقات عادية، تتولّى الآن عملية منح الإذن بالوصول إلى Gemini Developer API باستخدام حساب خدمة تديره Google (P4SA) ونوفّره لك تلقائيًا:
وكيل خدمة Firebase AI Logic (service-PROJECT_ID@gcp-sa-firebasevertexai.iam.gserviceaccount.com)Firebase AI Logic

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

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

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

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

اعتبارًا من منتصف عام 2026، لن يتم توفير مفاتيح واجهة برمجة التطبيقات Gemini العادية أو استخدامها في Firebase AI Logic. بدلاً من ذلك، يتولّى 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