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

لماذا تم تغيير الاسم من "Vertex AI in Firebase" إلى "Firebase AI Logic"؟

في عام 2024، أطلقنا مجموعة من حِزم تطوير البرامج (SDK) الخاصة بالعملاء في Firebase والتي يمكنها استخدام Vertex AI Gemini API، بالإضافة إلى بوابة وكيل 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).

ما هي الاختلافات بين استخدام Gemini Developer API وVertex AI Gemini API؟

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

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

² لا تتوافق Files API مع Gemini Developer API من خلال حِزم تطوير البرامج (SDK) الخاصة بـ Firebase AI Logic.

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

هل يمكنني استخدام كل من Gemini Developer API وVertex AI Gemini API؟

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

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

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

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

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

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

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

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

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

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

ما هي النماذج التي يمكن استخدامها مع حِزم تطوير البرامج (SDK)؟Firebase AI Logic

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

• Gemini Developer API

  • كلا النموذجين الأساسيين Gemini وImagen

    يُرجى العِلم أنّ Gemini Developer API (بغض النظر عن طريقة الوصول إليه) لا يتيح سوى نماذج Imagen ثابتة محدّدة.

• Vertex AI Gemini API

  • كلا النموذجين الأساسيين Gemini وImagen

• بغض النظر عن Gemini APIمقدّم الخدمة الذي اخترته

  • Firebase AI Logic لا يتيح استخدام ما يلي:

    • نماذج Gemini غير أساسية (مثل نماذج PaLM أو النماذج المعدَّلة أو النماذج المستندة إلى Gemma)

    • طُرز Imagen أو imagen-3.0-capability-001 الأقدم

ما يجب فعله عند إيقاف النماذج نهائيًا

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

مكان العثور على تاريخ إيقاف طراز معيّن

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

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

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

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

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

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

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

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

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

تواريخ إيقاف النماذج الثابتة من 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)

كيف يمكنني ضبط حدّ السعر لكل مستخدم؟

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

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

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

ما هي الأذونات التي قد تكون مطلوبة لاستخدام حِزم تطوير البرامج (SDK) التي تتضمّن Firebase AI Logic؟

هل يستخدم Firebase AI Logic بياناتي لتدريب النماذج؟

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

هل يجب تضمين نوع 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؟ تخزين السياق مؤقتًا، والضبط الدقيق للنموذج، وإنشاء التضمينات، والاسترجاع الدلالي، والصوت الأصلي

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

• التخزين المؤقت للسياق
• ضبط نموذج
• إنشاء التضمينات
• الاسترجاع الدلالي
• الصوت الأصلي لـ "Live API"

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

بالنسبة إلى تطبيقات Swift على منصات Apple، ماذا يجب أن أفعل بشأن تغيير اسم الوحدة من FirebaseAI إلى FirebaseAILogic؟

بالنسبة إلى تطبيقات منصة Apple، بدءًا من الإصدار 12.5.0 من حزمة تطوير البرامج (SDK) لمنصة Firebase، يتم الآن توزيع Firebase AI Logic ضمن الوحدة FirebaseAILogic. لقد أجرينا هذا التغيير بطريقة لا تؤدي إلى حدوث أخطاء ومتوافقة مع الإصدارات القديمة.

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

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

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

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

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

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

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

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

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

ما هو Gemini مفتاح واجهة برمجة التطبيقات؟

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

يشير "مفتاح واجهة برمجة التطبيقات Gemini" إلى مفتاح واجهة برمجة تطبيقات يتضمّن Gemini Developer API في قائمة واجهة برمجة التطبيقات المسموح بها.

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

مزيد من المعلومات حول قيود واجهة برمجة التطبيقات لمفاتيح واجهة برمجة التطبيقات

لا تُضِف مفتاح واجهة برمجة التطبيقات Gemini إلى المصدر البرمجي لتطبيقك عند استخدام حِزم تطوير البرامج Firebase AI Logic. مزيد من المعلومات حول كيفية الحفاظ على أمان مفتاح واجهة برمجة التطبيقات Gemini

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

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

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

كيف يمكنني تغيير مفتاح واجهة برمجة التطبيقات Gemini المستخدَم لطلب بيانات من Gemini Developer API؟

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

• إذا تسرّبت المفتاح عن طريق الخطأ وأردت استبداله بمفتاح آمن جديد.

• إذا حذفت المفتاح عن طريق الخطأ يُرجى العِلم أنّه يمكنك إلغاء حذف المفتاح في غضون 30 يومًا من تاريخ الحذف.

إليك كيفية تغيير مفتاح واجهة برمجة التطبيقات Gemini الذي تستخدمه حِزم تطوير البرامج (SDK) الخاصة بـ Firebase AI Logic:

1. إذا كان مفتاح واجهة برمجة التطبيقات الذي أنشأته Firebase Gemini لا يزال موجودًا، احذفه.

   يمكنك حذف مفتاح واجهة برمجة التطبيقات هذا في لوحة واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد في وحدة تحكّم Google Cloud. اسمها هو:
   مفتاح Gemini Developer API (يتم إنشاؤه تلقائيًا بواسطة Firebase).

2. في الصفحة نفسها من وحدة تحكّم Google Cloud، أنشئ مفتاح API جديدًا. ننصحك بتسميته مثلاً:
   مفتاح Gemini Developer API لمنصة Firebase.

3. إلى مفتاح واجهة برمجة التطبيقات الجديد هذا، أضِف قيودًا على واجهة برمجة التطبيقات واختَر Generative Language API فقط.
   يُطلق على Gemini Developer API أحيانًا اسم "Generative Language API" في وحدة تحكّم Google Cloud.

   يجب عدم إضافة أي قيود على التطبيقات، وإلا لن تعمل خدمة وكيل Firebase AI Logic على النحو المتوقّع.

4. نفِّذ الأمر التالي لضبط هذا المفتاح الجديد كمفتاح واجهة برمجة التطبيقات Gemini الذي يجب أن تستخدمه خدمة الخادم الوكيل Firebase AI Logic.

   PROJECT_ID="PROJECT_ID"
   GENERATIVE_LANGUAGE_API_KEY="DEVELOPER_CREATED_GEMINI_API_KEY"
   curl \
     -X PATCH \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://firebasevertexai.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global/config" \
     -d "{\"generativeLanguageConfig\": {\"apiKey\": \"${GENERATIVE_LANGUAGE_API_KEY}\"}}"
   

   gcloud CLI

احرص على عدم إضافة مفتاح واجهة برمجة التطبيقات الجديد Gemini إلى قاعدة رموز تطبيقك. مزيد من المعلومات حول كيفية الحفاظ على أمان مفتاح واجهة برمجة التطبيقات 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؟

توضّح الأسئلة الشائعة التالية بعض أفضل الممارسات المقترَحة للحفاظ على أمان مفتاح واجهة برمجة التطبيقات Gemini.

إذا كنت تتصل بـ Gemini Developer API مباشرةً من تطبيقك على الأجهزة الجوّالة أو تطبيق الويب:

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

توفّر Firebase AI Logic خدمة وكيل تتضمّن داخليًا Gemini مفتاح واجهة برمجة التطبيقات في كل طلب إلى Gemini Developer API — في الخلفية تمامًا.

بالإضافة إلى ذلك، ننصحك بشدة بما يلي:

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

• لا تعِد استخدام مفتاح واجهة برمجة التطبيقات Gemini الذي أنشأته Firebase خارج Firebase AI Logic. إذا كنت بحاجة إلى مفتاح واجهة برمجة تطبيقات Gemini لحالة استخدام أخرى، أنشئ مفتاحًا منفصلاً.

• بشكل عام، يجب عدم تعديل مفتاح واجهة برمجة التطبيقات الذي أنشأته Firebase.Gemini يُطلق على هذا المفتاح اسم مفتاح Gemini Developer API (يتم إنشاؤه تلقائيًا بواسطة Firebase) في وحدة تحكّم Google Cloud.

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

  • يجب عدم إضافة أي قيود على التطبيقات، وإلا لن تعمل خدمة وكيل Firebase AI Logic على النحو المتوقّع.

تم اختراق مفتاح واجهة برمجة التطبيقات Gemini الخاص بي. ما هو الإجراء الواجب اتّخاذه؟

إذا تم اختراق مفتاح واجهة برمجة التطبيقات Gemini، اتّبِع التعليمات لتغيير مفتاح واجهة برمجة التطبيقات Gemini المستخدَم لطلب Gemini Developer API.

ننصحك أيضًا بمراجعة أفضل الممارسات المقترَحة للحفاظ على Gemini مفتاح واجهة برمجة التطبيقات آمنًا.

كيف يمكنني حلّ خطأ 404 هذا؟ Firebase AI Logic genai config not found

إذا كنت تحاول استخدام Gemini Developer API وتلقّيت الخطأ 404 الذي يشير إلى Firebase AI Logic genai config not found، يعني ذلك عادةً أنّ مشروعك على Firebase لا يتضمّن مفتاح Gemini صالحًا لواجهة برمجة التطبيقات لاستخدامه مع حِزم تطوير البرامج (SDK) الخاصة ببرنامج Firebase AI Logic.

في ما يلي الأسباب الأكثر احتمالاً لحدوث هذا الخطأ:

• لم يتم إعداد مشروعك على Firebase من أجل Gemini Developer API بعد.

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

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

  الحل:
  انتظِر بضع دقائق، ثم أعِد محاولة تنفيذ طلبك.

• ربما تم حذف مفتاح واجهة برمجة التطبيقات Gemini من مشروعك على Firebase.

  الإجراء المطلوب:
  تعرَّف على كيفية تغيير مفتاح واجهة برمجة التطبيقات Gemini المستخدَم من قِبل Firebase AI Logic.

كيف يمكنني حلّ خطأ 400؟ Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

إذا كنت تحاول إرسال طلب متعدد الوسائط باستخدام عنوان URL، قد يظهر لك الخطأ 400 التالي:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.Cloud Storage for Firebase

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

في ما يلي الحلّ البديل لإصلاح مشروعك وتوفير وكلاء الخدمة هؤلاء بشكل صحيح حتى تتمكّن من البدء في تضمين عناوين URL الخاصة بـ Cloud Storage for Firebase في طلباتك المتعدّدة الوسائط. يجب أن تكون مالكًا للمشروع، وعليك إكمال هذه المجموعة من المهام مرة واحدة فقط لكل مشروع.

1. الوصول والمصادقة باستخدام gcloud CLI
   أسهل طريقة لإجراء ذلك هي من Cloud Shell. يمكنك الاطّلاع على مزيد من المعلومات في Google Cloud المستندات.

2. إذا طُلب منك ذلك، اتّبِع التعليمات المعروضة في الجهاز لتنفيذ gcloud CLI على مشروعك في Firebase.

   ستحتاج إلى معرّف مشروع Firebase، ويمكنك العثور عليه في أعلى صفحة settings إعدادات المشروع في وحدة تحكّم Firebase.

3. وفِّر وكلاء الخدمة المطلوبين في مشروعك من خلال تنفيذ الأمر التالي:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
   

4. انتظِر بضع دقائق للتأكّد من توفير وكلاء الخدمة، ثم أعِد محاولة إرسال طلبك المتعدد الوسائط الذي يتضمّن عنوان URL الخاص بـ Cloud Storage for Firebase.

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

كيف يمكنني حلّ خطأ 400؟ API key not valid. Please pass a valid API key.

إذا تلقّيت الخطأ 400 الذي يشير إلى API key not valid. Please pass a valid API key.، يعني ذلك عادةً أنّ مفتاح واجهة برمجة التطبيقات في ملف/عنصر إعدادات Firebase غير متوفّر أو لم يتم إعداده لاستخدامه مع تطبيقك و/أو مشروعك على Firebase.

تأكَّد من أنّ مفتاح واجهة برمجة التطبيقات المُدرَج في ملف/عنصر إعدادات Firebase يتطابق مع مفتاح واجهة برمجة التطبيقات لتطبيقك. يمكنك عرض جميع مفاتيح واجهة برمجة التطبيقات في لوحة واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد في وحدة تحكّم Google Cloud.

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

كيف يمكنني حلّ خطأ 403 هذا؟ Requests to this API firebasevertexai.googleapis.com ... are blocked.

إذا تلقّيت الخطأ 403 الذي يظهر فيه Requests to this API firebasevertexai.googleapis.com ... are blocked.، يعني ذلك عادةً أنّ مفتاح واجهة برمجة التطبيقات في إعدادات Firebase في تطبيقك يتضمّن قيودًا تمنعه من طلب واجهة برمجة التطبيقات المطلوبة.

لحلّ هذه المشكلة، عليك تعديل القيود المفروضة على مفتاح واجهة برمجة التطبيقات في Google Cloud console لتضمين واجهة برمجة التطبيقات المطلوبة. بالنسبة إلى Firebase AI Logic، عليك التأكّد من تضمين Firebase AI Logic API (firebasevertexai.googleapis.com) في قائمة واجهات برمجة التطبيقات المحدّدة التي يمكن طلب بياناتها باستخدام مفتاح واجهة برمجة التطبيقات.

اتبع هذه الخطوات:

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

2. اختَر مفتاح واجهة برمجة التطبيقات الذي تم إعداد تطبيقك لاستخدامه (على سبيل المثال، "مفتاح iOS" لتطبيق iOS).

3. في صفحة تعديل مفتاح واجهة برمجة التطبيقات، ابحث عن قسم القيود المفروضة على واجهة برمجة التطبيقات.

4. تأكَّد من تحديد الخيار مفتاح الحظر. إذا لم يكن كذلك، يعني هذا أنّ مفتاحك غير مقيّد، ومن غير المرجّح أن يكون هذا هو مصدر الخطأ.

5. في القائمة المنسدلة واجهات برمجة التطبيقات المحدّدة، ابحث عن واجهة برمجة التطبيقات Firebase AI Logic وحدِّدها لإضافتها إلى قائمة واجهات برمجة التطبيقات المحدّدة التي يمكن طلبها باستخدام مفتاح واجهة برمجة التطبيقات.

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

   قد يستغرق تطبيق التغييرات مدة تصل إلى خمس دقائق.

كيف يمكنني حلّ خطأ 403 هذا؟ PERMISSION_DENIED: The caller does not have permission.

إذا تلقّيت الخطأ 403 الذي يشير إلى PERMISSION_DENIED: The caller does not have permission.، يعني ذلك عادةً أنّ مفتاح واجهة برمجة التطبيقات في ملف/عنصر إعدادات Firebase يخصّ مشروع Firebase مختلفًا.

تأكَّد من أنّ مفتاح واجهة برمجة التطبيقات المُدرَج في ملف/عنصر إعدادات Firebase يتطابق مع مفتاح واجهة برمجة التطبيقات لتطبيقك. يمكنك عرض جميع مفاتيح واجهة برمجة التطبيقات في لوحة واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد في وحدة تحكّم Google Cloud.

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

كيف يمكنني حلّ الخطأ 404 الذي يشير إلى النموذج "was not found or your project does not have access to it"؟

على سبيل المثال: "Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version."

هناك سببان مختلفان قد يؤديان إلى ظهور خطأ من هذا النوع.

• اسم الطراز غير صالح

  • السبب: اسم الطراز الذي قدّمته ليس اسم طراز صالحًا.

  • الحلّ: تحقَّق من اسم الطراز وإصداره مقارنةً بقائمة جميع الطرازات المتوافقة والمتوفّرة. احرص على التحقّق من الشرائح وترتيبها في اسم النموذج. على سبيل المثال:

    • اسم طراز "الموز الصغير" هو gemini-2.5-flash-image (ليس gemini-2.5-flash-image-generation).
    • إصدار المعاينة من Gemini 3 هو gemini-3-pro-preview (ليس gemini-3.0-pro-preview).

• موقع جغرافي غير صالح (ينطبق ذلك فقط في حال استخدام مقدّم خدمة Vertex AI Gemini API ونموذج معاينة)

  • السبب: أنت تستخدم إصدار معاينة من نموذج (مثل gemini-3-pro-preview)، ولم تحدّد الموقع الجغرافي global.

    إذا كنت تستخدم Vertex AI Gemini API، لن تتوفّر جميع نماذج Gemini 2.5 وGemini 3 والإصدارات التجريبية الأحدث التي تم طرحها بعد يونيو 2025 إلا في الموقع الجغرافي global (بما في ذلك الإصدار التجريبي من "nano banana"). ومع ذلك، بما أنّ القيمة التلقائية لـ Firebase AI Logic هي الموقع الجغرافي us-central1، عليك تحديد الموقع الجغرافي global بشكل صريح عند تهيئة خدمة الخلفية Vertex AI Gemini API في الرمز البرمجي عند استخدام نماذج المعاينة هذه.

  • الحلّ: عند بدء خدمة Vertex AI Gemini API، حدِّد الموقع الجغرافي global. مزيد من المعلومات حول كيفية تحديد الموقع الجغرافي الذي يمكن الوصول إلى النموذج منه (بما في ذلك مقتطفات الرموز)

• موقع جغرافي غير صالح (ينطبق ذلك فقط في حال استخدام موفّر خدمة Vertex AI Gemini API)

  • السبب: أنت تستخدم نموذجًا غير متاح في الموقع الجغرافي الذي تحاول الوصول إليه منه.

    إذا كنت تستخدم Vertex AI Gemini API، لا تتوفّر بعض النماذج إلا في مواقع جغرافية محدّدة. على سبيل المثال (ولكن ليس على سبيل الحصر):

    • طُرز Imagen غير متاحة في الموقع الجغرافي global.
    • لا تتوفّر نماذج Gemini Live API (مثل gemini-2.0-flash-live-preview-04-09) إلا في الموقع الجغرافي us-central1.
    • تتوفّر نماذج Gemini 2.5 (مثل gemini-2.5-pro) فقط في الموقع الجغرافي global والمواقع الجغرافية في الولايات المتحدة وبعض المواقع الجغرافية في أوروبا (وفي بعض الأحيان في مواقع جغرافية أخرى إذا كان مشروعك يتضمّن خيارات خاصة).

  • الحلّ: عند بدء خدمة Vertex AI Gemini API، احرص على تحديد موقع جغرافي متوافق مع النموذج الذي تستخدمه. مزيد من المعلومات حول كيفية تحديد الموقع الجغرافي الذي يمكن من خلاله الوصول إلى النموذج (بما في ذلك مقتطفات الرموز) والمواقع الجغرافية التي تتوفّر فيها النماذج

    يُرجى العِلم أنّ Firebase AI Logic يتم ضبطه تلقائيًا على الموقع الجغرافي us-central1.