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

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

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

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

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

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

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

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

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

التغييرات المطلوبة لإعادة تسمية "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
  تتوفّر هذه الميزة بدءًا من الإصدار 12.17.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لمنصات Apple في Firebase.

  BEFORE

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexai` syntax, the default location is `us-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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
  متاحة بدءًا من الإصدار 17.15.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لنظام التشغيل Android من Firebase AI Logic (Firebase Android BoM الإصدار 34.17.0 أو إصدار أحدث).

  BEFORE

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `vertexAI` syntax, the default location is `us-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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
  متاحة بدءًا من الإصدار 17.15.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لنظام التشغيل Android من Firebase AI Logic (Firebase Android BoM الإصدار 34.17.0 أو إصدار أحدث).

  BEFORE

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

  Web

  تغيير VertexAIBackend إلى AgentPlatformBackend
  تتوفّر هذه الميزة بدءًا من الإصدار 12.17.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) من Firebase لنظام التشغيل JavaScript.

  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-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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 أو إصدار أحدث من حزمة تطوير البرامج (SDK) من Firebase لبرنامج Unity.

  BEFORE

  // ...
  
  // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI).
  // For the legacy `VertexAI` syntax, the default location is `us-central`, so
  // specifying a location is usually required since most models are *not* supported in `us-central`.
  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 لا يؤدي إلى حدوث أي أعطال وهو متوافق مع الإصدارات السابقة في Firebase 12. ومع ذلك، ستتم إزالة هذه الوحدة القديمة في الإصدار 13 من Firebase. انقل التبعيات وعمليات الاستيراد قبل التحديث إلى الإصدار 13 من Firebase.

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

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

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

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

لاستخدام حِزم تطوير البرامج (SDK) مع Firebase AI LogicAgent 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 أو نماذج الروبوتات أو نماذج استخدام الكمبيوتر أو نماذج GeminiOmni أو نماذج GeminiFlash 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): 16 أكتوبر 2026
    • Agent Platform Gemini API (formerly Vertex AI): 20 أكتوبر 2026

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

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

الاستبدال: يمكنك نقل البيانات لاستخدام أحد نماذج Gemini 3.x الجديدة (مثل 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 3.x نماذج، لا تتوفّر عدّة مَعلمات (تحديدًا درجة العشوائية، وأعلى K كلمة محتملة، وأعلى احتمال تراكمي، وعقوبة التكرار، وعقوبة الحضور، وعدد المرشحين).

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

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

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

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

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

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

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

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

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

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

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

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

• mimeType الملف الاطّلاع على استثناء أدناه

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

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

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

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

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

• أنشأت Firebase مفتاح واجهة برمجة التطبيقات Gemini لغرض وحيد وهو استخدامه مع 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.

مفتاح واجهة برمجة التطبيقات (API) في 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 مفتاح واجهة برمجة التطبيقات