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

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

كان اسم

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

لوحات البيانات الخاصة بالحالة

• Firebase AI Logic

• Gemini Developer API

• ‫Vertex AI Gemini API (Vertex Gemini API وVertex Imagen API)

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

لماذا تم تغيير الاسم من "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" بشكل عام بغض النظر عن طريقة الوصول إليهما:

	Gemini Developer API	Vertex AI Gemini API
الأسعار	متوفّرة في كلّ من خطة أسعار Spark بدون تكلفة وخطة أسعار Blaze بنظام الدفع حسب الاستخدام^1	يتطلّب دائمًا خطة أسعار Blaze للدفع حسب الاستخدام^1 (عند استخدامه مع Firebase AI Logic)
حدود المعدّل (الحصة)	الحدود القصوى الصريحة لمعدّل الزيارات	تستخدم حصة ديناميكية مشتركة (DSQ) يشاركها كل من يستخدم هذا النموذج في تلك المنطقة. تتوفّر سرعة معالجة البيانات المتوفّرة (PT).
تحديد الموقع الجغرافي الذي يمكن الوصول إلى النموذج منه	غير متوافق مع واجهة برمجة التطبيقات	متوافق مع واجهة برمجة التطبيقات
إتاحة عناوين URL الخاصة بـ Cloud Storage	غير متوافق مع واجهة برمجة التطبيقات ^2	الملفات العامة والملفات المحمية بواسطة Firebase Security Rules
التوافق مع عناوين URL على YouTube وعناوين URL في المتصفح	عناوين URL الخاصة بفيديوهات YouTube فقط	عناوين URL على YouTube وعناوين URL في المتصفح

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

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

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

الميزة	Gemini Developer API	Vertex AI Gemini API
توفُّر Gemini	متوافق	متوافق
توفُّر Imagen	متوافق	متوافق
التوافق مع طُرز Veo	غير متاحة بعد	غير متاحة بعد
دعم Gemini Live API	متاحة (على Android وFlutter والويب وUnity فقط)	متاحة (على Android وFlutter والويب وUnity فقط)
الدمج مع Firebase App Check	متوافق	متوافق
متوافق مع Firebase Remote Config	متوافق	متوافق
إتاحة تتبُّع استخدام الذكاء الاصطناعي في وحدة تحكّم Firebase	متوافق	متوافق

ملاحظة: عند استخدام Firebase AI Logic، لا تتوفّر بعد الإمكانات التالية: تخزين السياق مؤقتًا، تنفيذ الرموز البرمجية، ضبط النموذج بدقة، إنشاء التضمينات، استرجاع المعلومات الدلالية، وبعض الميزات المتقدّمة في نماذج Imagen.

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

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

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

ملاحظة مهمة: إذا كان مشروعك يستند إلى خطة التسعير Blaze بنظام الدفع حسب الاستخدام (وهي خطة مطلوبة لاستخدام Vertex AI Gemini API والعديد من المنتجات الأخرى في منظومة Google Cloud وFirebase)، يُرجى العلم أنّ جميع طلبات البيانات إلى Gemini Developer API تخضع لنظام الدفع حسب الاستخدام.

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

اختيار موفّر Gemini API لعرض المحتوى الخاص بالموفّر Gemini Developer API Vertex AI Gemini API

لاستخدام حِزم تطوير البرامج (SDK) مع Firebase AI Logic، يجب تفعيل واجهتَي برمجة التطبيقات التاليتَين في مشروعك:Gemini 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 الثابتَين).

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

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

عليك تعديل اسم النموذج الذي يستخدمه تطبيقك قبل تاريخ إيقافه نهائيًا، وإلا ستتعذّر معالجة أي طلبات إلى هذا النموذج وسيظهر الخطأ 404. يمكنك ضبط اسم النموذج وإصداره المستخدَمَين في أي طلبات عند إنشاء مثيل GenerativeModel أو LiveModel أو ImagenModel أثناء عملية التهيئة.

يمكنك الاطّلاع على الطُرز المتوافقة حاليًا وأسماء الطُرز.

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

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

باستخدام Remote Config، يمكنك تغيير النموذج وإصدار النموذج المستخدَمَين في تطبيقك بشكل ديناميكي وعن بُعد بدون طرح إصدار جديد من تطبيقك. وستبدأ أي إصدارات من تطبيقك تم طرحها سابقًا (وتم ضبطها لاستخدام Remote Config) في استخدام النموذج الجديد واسم النموذج على الفور.

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

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

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

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

الإجراء	أذونات "إدارة الهوية وإمكانية الوصول" المطلوبة	أدوار "إدارة الهوية وإمكانية الوصول" التي تتضمّن الأذونات المطلوبة تلقائيًا
الترقية إلى خطة الدفع حسب الاستخدام (Blaze)	firebase.billingPlans.update resourcemanager.projects.createBillingAssignment resourcemanager.projects.deleteBillingAssignment	المالك
تفعيل واجهات برمجة التطبيقات في المشروع	serviceusage.services.enable	محرّر المالك
إنشاء تطبيق Firebase	firebase.clients.create	مشرف Firebase محرِّر مالك

هل يستخدم 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:

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

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

Gemini الأسئلة الشائعة حول مفتاح واجهة برمجة التطبيقات

لا تنطبق هذه الأسئلة الشائعة إلا إذا كنت تستخدم Gemini Developer API.

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

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

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

ملاحظة: يُطلق على Gemini Developer API أحيانًا اسم "Generative Language API" في وحدة تحكّم Google Cloud.

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

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

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

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

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

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

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

كيف يمكنني تغيير مفتاح واجهة برمجة التطبيقات 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 فقط.
   يُطلق على "Generative Language API" أحيانًا اسم Gemini Developer 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 لطرح الأسئلة والحصول على إرشادات عند استخدام مفاتيح واجهة برمجة التطبيقات.

هل يمكنني استخدام "مفتاح واجهة برمجة التطبيقات في 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 لا يتضمّن مفتاح واجهة برمجة تطبيقات صالحًا لاستخدامه مع حِزم تطوير البرامج (SDK) الخاصة ببرنامج Firebase AI Logic.Gemini

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

• لم يتم إعداد مشروعك على 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 Cloud Storage for Firebase ، قد يظهر لك الخطأ 400 التالي:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

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

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

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

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

   ستحتاج إلى معرّف مشروع Firebase، ويمكنك العثور عليه في أعلى صفحة إعدادات المشروع في وحدة تحكّم 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 لتضمين واجهة برمجة التطبيقات المطلوبة. بالنسبة إلى Firebase AI Logic، عليك التأكّد من تضمين Firebase AI Logic API (firebasevertexai.googleapis.com) في قائمة واجهات برمجة التطبيقات المحدّدة التي يمكن طلب بياناتها باستخدام مفتاح واجهة برمجة التطبيقات.

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

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

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

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

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

   ملاحظة: إذا كان لديك مفتاح واجهة برمجة تطبيقات بدون قيود، ننصحك بشدة بتطبيق "قيود واجهة برمجة التطبيقات" على مفتاح واجهة برمجة التطبيقات في Firebase.

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

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

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

ملاحظة: تستخدم واجهات برمجة التطبيقات المرتبطة بمنصة Firebase مفاتيح واجهة برمجة التطبيقات فقط من أجل تحديد مشروع Firebase أو التطبيق، وليس من أجل منح الإذن بطلب البيانات من واجهة برمجة التطبيقات (كما تسمح بعض واجهات برمجة التطبيقات الأخرى). يتم التعامل مع تفويض واجهات برمجة التطبيقات ذات الصلة بمنصة Firebase بشكل منفصل عن مفتاح واجهة برمجة التطبيقات، إما من خلال أذونات Google Cloud لإدارة الهوية وإمكانية الوصول (IAM) أو Firebase Security Rules أو Firebase App Check. مزيد من المعلومات حول مفاتيح واجهة برمجة التطبيقات في Firebase

كيف يمكنني حلّ الخطأ 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-2.5-flash-image-preview was not found or your project does not have access to it. Please ensure you are using a valid model version."

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

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

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

  • الحلّ: تحقَّق من اسم الطراز وإصداره مقارنةً بقائمة جميع الطرازات المتوافقة والمتوفّرة. احرص على التحقّق من الأقسام وترتيبها في اسم النموذج. على سبيل المثال، اسم الطراز "nano banana" هو gemini-2.5-flash-image-preview غير gemini-2.5-flash-preview-image-generation.

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

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

    إذا كنت تستخدم Vertex AI Gemini API، ستتوفّر جميع نماذج Gemini 2.5 والإصدارات التجريبية الأحدث التي تم إصدارها بعد يونيو 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.

تقديم ملاحظات حول تجربتك مع Firebase AI Logic