عند طلب واجهة برمجة تطبيقات Gemini من تطبيقك باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Vertex AI for Firebase، يمكنك أن تطلب من نموذج Gemini إنشاء نص استنادًا إلى إدخال متعدد الوسائط. ويمكن أن تتضمّن الطلبات المتعدّدة الوسائط طُرقًا متعدّدة (أو أنواعًا من الإدخالات)، مثل النص مع الصور وملفات PDF والفيديوهات والصوت.
بالنسبة إلى الأجزاء غير النصية من الإدخال (مثل ملفات الوسائط)، يمكنك اختياريًا استخدام Cloud Storage for Firebase لتضمين الملفات في الطلب. على مستوى عالٍ، إليك ما تحتاج إلى معرفته عن هذه الميزة:
يمكنك استخدام Cloud Storage for Firebase مع أي طلب متعدد الوسائط (مثل إنشاء النص والدردشة). تُظهر الأمثلة الواردة في هذا الدليل إدخالاً أساسيًا للنص والصورة.
عليك تحديد نوع MIME للملف وعنوان URL الخاص بخدمة Cloud Storage for Firebase (والذي يبدأ دائمًا بـ
gs://) في إدخال الطلب. وهذه القيم هي بيانات وصفية يتم تعيينها تلقائيًا لأي ملف يتم تحميله إلى حزمة Cloud Storage.وعليك استخدام نوع ملف وعنوان URL متوافقَين.
يصف دليل الحلول هذا كيفية إعداد Cloud Storage for Firebase في Google Cloud، وتحميل ملف إلى حزمة Cloud Storage for Firebase من تطبيقك، ثم تضمين نوع MIME للملف وعنوان URL لخدمة Cloud Storage for Firebase في طلبك المتعدّد الوسائط إلى Gemini API.
هل تريد الاطّلاع على أمثلة الرمز؟ أو هل سبق لك إعداد Cloud Storage for Firebase وكنت جاهزًا لبدء استخدامه مع الطلبات المتعدّدة الوسائط؟
لماذا تستخدم Cloud Storage for Firebase مع تطبيقك؟
تستخدم خدمة Cloud Storage for Firebase البنية الأساسية السريعة والأمان وقابلية التطور نفسها التي تستخدمها Google Cloud Storage لتخزين العناصر الثنائية الكبيرة والملفات، كما تم تصميم حزم تطوير البرامج (SDK) للعملاء خصّيصًا لتطبيقات الأجهزة الجوّالة وتطبيقات الويب.
بالنسبة إلى حِزم تطوير برامج (SDK) Vertex AI for Firebase، يبلغ الحد الأقصى لحجم الطلب 20 ميغابايت. سيظهر لك الخطأ HTTP 413 إذا كان الطلب كبيرًا جدًا. إذا كان حجم الملف سيتجاوز إجمالي حجم الطلب 20 ميغابايت، استخدِم عنوان URL الخاص بـ Cloud Storage for Firebase لتضمين الملف في طلبك المتعدّد الوسائط. إذا كان الملف صغيرًا، يمكنك غالبًا تمريره مباشرةً كبيانات مضمّنة (مع ذلك، يُرجى العلم بأنّ أي ملف يتم تقديمه كبيانات مضمّنة يتم ترميزه باستخدام base64 في النقل، ما يزيد من حجم الطلب).
في ما يلي بعض المزايا الإضافية لاستخدام Cloud Storage for Firebase:
يمكنك أن تطلب من المستخدمين النهائيين تحميل الصور من تطبيقك مباشرةً إلى حزمة Cloud Storage for Firebase، وبعد ذلك يمكنك تضمين هذه الصور في الطلبات المتعدّدة الوسائط فقط من خلال تحديد نوع MIME للملف وعنوان URL للتخزين في السحابة الإلكترونية لبرنامج Firebase (وهو معرّف للملف).
يمكنك توفير الوقت ومعدل نقل البيانات للمستخدمين النهائيين إذا كانوا بحاجة إلى تقديم صور، خاصةً إذا كانت جودة الشبكة رديئة أو غير مستقرة.
- في حال مقاطعة تحميل أو تنزيل ملفّ، ستُعيد حِزم SDK في Cloud Storage for Firebase إعادة تشغيل العملية تلقائيًا من حيث توقّفت.
- يمكن استخدام الملف نفسه الذي تم تحميله عدة مرات بدون أن يضطر المستخدم النهائي إلى تحميل الملف نفسه في كل مرة يكون مطلوبًا فيها في تطبيقك (كما هو الحال في طلب جديد متعدد الوسائط).
يمكنك تقييد وصول المستخدم النهائي إلى الملفات المخزنة في Cloud Storage for Firebase باستخدام قواعد أمان Firebase، التي تسمح للمستخدم المصرَّح له فقط بتحميل الملفات أو تنزيلها أو حذفها.
يمكنك الوصول إلى الملفات في الحزمة من Firebase أو من Google Cloud، ما يمنحك المرونة في إجراء معالجة من جهة الخادم مثل فلترة الصور أو تحويل ترميز الفيديو باستخدام واجهات برمجة تطبيقات Google Cloud Storage.
ما هي أنواع الملفات وعناوين URL المتوافقة؟
في ما يلي متطلبات الملفات وعناوين URL إذا أردت استخدام ميزة "التخزين في السحابة الإلكترونية" لعناوين URL لمنصة Firebase مع حِزم تطوير البرامج (SDK) الخاصة بأداة Vertex AI for Firebase:
يجب أن يستوفي الملف متطلبات ملفات الإدخال للطلبات المتعددة الوسائط عند استخدام حِزم تطوير البرامج (SDK) الخاصة بأداة Vertex AI for Firebase. ويتضمن ذلك متطلبات مثل نوع MIME وحجم الملف.
يجب تخزين الملف في حزمة Cloud Storage for Firebase (يعني ذلك أنّه يمكن لخدمات Firebase الوصول إلى الحزمة، مثل "قواعد أمان Firebase"). إذا كان بإمكانك عرض الحزمة في وحدة تحكُّم Firebase، ستكون حزمة Cloud Storage for Firebase.
يجب أن تكون حزمة Cloud Storage for Firebase ضِمن مشروع Firebase نفسه الذي سجّلت تطبيقك فيه.
يجب أن يبدأ عنوان URL الخاص بخدمة Cloud Storage for Firebase للملف بـ
gs://، وهي الطريقة التي يتم بها إنشاء جميع عناوين URL على Google Cloud Storage.لا يمكن أن يكون عنوان URL للملف عنوان URL لـ "متصفّح" (على سبيل المثال، عنوان URL لصورة تعثر عليها على الإنترنت).
بالإضافة إلى ذلك، يجب أن تسمح قواعد أمان Firebase الخاصة بالحزمة بالوصول المناسب إلى الملف. على سبيل المثال:
إذا كانت لديك قواعد متاحة للجميع، يمكن لأي مستخدم أو عميل الوصول إلى الملف وتقديم عنوان URL الخاص به في مكالمة باستخدام حزمة تطوير البرامج (SDK) لميزة Vertex AI for Firebase. يجب استخدام هذه الأنواع من القواعد فقط للبدء وأثناء إنشاء النماذج الأوّلية في وقت مبكر (إلا إذا كانت الملفات الغرض منها في الواقع أن تكون ملفات متاحة للجميع بالكامل).
إذا كانت لديك قواعد متينة (ننصح بها بشدة)، سيتحقق Firebase من أنّ المستخدم أو العميل الذي سجّل الدخول لديه إمكانية الوصول الكافية إلى الملف قبل السماح بوصول المكالمة إلى عنوان URL المقدّم.
استخدام Cloud Storage لعناوين URL على Firebase من خلال Vertex AI for Firebase
الخطوة 1: إعداد Cloud Storage لمنصة Firebase
فيما يلي المهام عالية المستوى التي سيتعين عليك القيام بها:
أنشِئ حزمة Cloud Storage for Firebase في مشروعك على Firebase.
طبِّق قواعد أمان Firebase على هذه الحزمة. تساعدك "قواعد أمان Firebase" في تأمين ملفاتك من خلال حظر الوصول إليها على المستخدمين النهائيين المصرّح لهم.
أضِف مكتبة العملاء الخاصة بخدمة Cloud Storage for Firebase إلى تطبيقك.
يمكنك تخطّي هذه المَهمّة، ولكن عليك دائمًا تضمين قيم النوع MIME وCloud Storage for Firebase بشكل صريح في الطلبات المتعدّدة الوسائط.
الخطوة 2: تحميل ملف إلى حزمة
عند تحميل ملف إلى حزمة، تطبّق Cloud Storage تلقائيًا المعلومات التالية على الملف. يجب تضمين هذه القيم في الطلب متعدد الوسائط (كما هو موضّح في الخطوة التالية من هذا الدليل).
نوع MIME: هذا هو نوع وسائط الملف (على سبيل المثال،
image/png). ستحاول خدمة Cloud Storage لمنصة Firebase رصد نوع MIME تلقائيًا أثناء التحميل وتطبيق البيانات الوصفية على العنصر في الحزمة. ومع ذلك، يمكنك اختياريًا تحديد نوع MIME أثناء التحميل.عنوان URL لخدمة Cloud Storage لمنصّة Firebase: هو معرّف فريد للملف. يجب أن يبدأ عنوان URL بـ
gs://.
الخطوة 3: تضمين نوع MIME وعنوان URL للملف في طلب متعدد الوسائط
بعد توفُّر ملف مخزَّن في حزمة Cloud Storage for Firebase، يمكنك تضمين نوع MIME وعنوان URL لخدمة Cloud Storage for Firebase في طلب متعدد الوسائط.
تجدر الإشارة إلى أنّ هذه الأمثلة تعرض طلب generateContent لا يتم بثّه، ولكن يمكنك أيضًا استخدام Cloud Storage لعناوين URL لمنصة Firebase مع البث والمحادثة.
لتضمين الملف في الطلب، يمكنك استخدام أحد الخيارَين التاليَين:
الخيار 1: تضمين نوع MIME وعنوان URL باستخدام مرجع مساحة التخزين
الخيار 2: تضمين نوع MIME وعنوان URL بشكل صريح
الخيار 1: تضمين نوع MIME وعنوان URL باستخدام مرجع مساحة التخزين
استخدِم هذا الخيار إذا كنت قد حمّلت الملف إلى الحزمة للتو، وتريد تضمين الملف فورًا (عبر مرجع مساحة تخزين) في الطلب متعدد الوسائط. يتطلب الاستدعاء كلاً من نوع MIME وعنوان URL لخدمة Cloud Storage لمنصة Firebase.
الخيار 2: تضمين نوع MIME وعنوان URL بشكل صريح
استخدِم هذا الخيار إذا كنت تعرف قيم النوع MIME وعنوان URL للتخزين في السحابة الإلكترونية لبرنامج Firebase، وكنت تريد تضمينها صراحةً في الطلب المتعدّد الوسائط. تتطلّب المكالمة كلاً من نوع MIME وعنوان URL.