تضمين الملفات الكبيرة في الطلبات المتعدّدة الوسائط وإدارة الملفات باستخدام Cloud Storage for Firebase

عند الاتصال بالرقم Gemini API من تطبيقك باستخدام حزمة تطوير البرامج (SDK) Vertex AI in 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 in Firebase، يبلغ الحد الأقصى لحجم الطلب 20 ميغابايت. إذا كان الطلب كبيرًا جدًا، تظهر لك رسالة خطأ HTTP 413. إذا كان حجم الملف اجعل إجمالي حجم الطلب يتجاوز 20 ميغابايت، ثم استخدم Cloud Storage for Firebase عنوان URL لتضمين الملف في طلبك متعدد الوسائط. ومع ذلك، إذا كان الملف صغيرًا، يمكنك غالبًا تمريره مباشرةً كبيانات مضمّنة (يُرجى العلم أنّ الملف المقدَّم كبيانات مضمّنة تم ترميزه إلى base64 في النقل العام، مما يزيد من حجم الطلب).

في ما يلي بعض المزايا الإضافية لاستخدام "Cloud Storage for Firebase":

  • يمكنك السماح للمستخدمين النهائيين بتحميل الصور مباشرةً من تطبيقك إلى Cloud Storage for Firebase، وبعد ذلك يمكنك تضمين هذه الصور في الطلبات متعددة الوسائط فقط من خلال تحديد نوع MIME للملف Cloud Storage for Firebase عنوان URL (وهو معرِّف للملف).

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

    • في حال توقُّف عملية تحميل أو تنزيل ملف، تعمل Cloud Storage for Firebase تعمل حِزم SDK على إعادة تشغيل العملية تلقائيًا من حيث توقفت.
    • يمكن استخدام الملف نفسه عدة مرات بدون حساب المستخدم النهائي. الاضطرار إلى تحميل الملف نفسه في كل مرة مطلوبة في تطبيقك (كما هو الحال في طلب جديد متعدد الوسائط).
  • يمكنك حظر وصول المستخدم النهائي إلى الملفات المخزَّنة في Cloud Storage for Firebase باستخدام Firebase Security Rules، التي تتيح للمستخدم المصرّح له فقط تحميل الملفات أو تنزيلها أو حذفها.

  • يمكنك الوصول إلى الملفات في الحزمة من Firebase أو من Google Cloud. مما يمنحك المرونة لإجراء معالجة من جهة الخادم، مثل معالجة الصور الفلترة أو تحويل ترميز الفيديو باستخدام واجهات برمجة التطبيقات Google Cloud Storage.

ما هي أنواع الملفات وعناوين URL المتوافقة؟

في ما يلي متطلبات الملفات وعناوين URL عندما تريد استخدام عنوانا URL (Cloud Storage for Firebase) يتضمّنان حِزم تطوير البرامج (SDK) Vertex AI in Firebase:

  • يجب أن يستوفي الملف متطلبات ملفات الإدخال للطلبات المتعددة الوسائط عند استخدام حِزم تطوير البرامج (SDK) Vertex AI in Firebase يشمل ذلك المتطلّبات مثل نوع MIME وحجم الملف.

  • يجب تخزين الملف في حزمة Cloud Storage for Firebase. (ما يعني أنّه يمكن لخدمات Firebase، مثل Firebase Security Rules، الوصول إلى الحزمة) إذا كان بإمكانك الاطّلاع على الحزمة في وحدة تحكُّم Firebase يكون بالتالي مجموعة Cloud Storage for Firebase.

  • يجب أن تكون حزمة Cloud Storage for Firebase ضمن مشروع Firebase نفسه في الذي سجّلت فيه تطبيقك

  • يجب أن يبدأ عنوان URL للملف Cloud Storage for Firebase بـ gs://، وهو الطريقة التي يتم بها إنشاء جميع عناوين URL Google Cloud Storage.

  • لا يمكن أن يكون عنوان URL للملف "متصفحًا" عنوان URL (على سبيل المثال، عنوان URL لصورة التي تعثر عليها على الإنترنت).

بالإضافة إلى ذلك، يجب أن تتيح السمة Firebase Security Rules الخاصة بحزمتك. الوصول المناسب إلى الملف. على سبيل المثال:

  • إذا كانت لديك قواعد عامة، ثم يمكن لأي مستخدم أو عميل الوصول إلى الملف وتقديم عنوان URL له في مكالمة باستخدام حزمة تطوير البرامج (SDK) Vertex AI in Firebase يجب استخدام هذه الأنواع من القواعد فقط البدء وأثناء إنشاء النماذج الأوّلية المبكرة (ما لم تكن الملفات مخصصة بالفعل يمكن الوصول إليها بشكل كامل).

  • إذا كانت لديك قواعد فعّالة (ننصح بذلك بشدة)، سيتحقّق Firebase بعد ذلك من وصول المستخدم الذي سجّل الدخول أو العميل لديه أذونات كافية للوصول إلى الملف قبل السماح بانتقال المكالمة. باستخدام عنوان URL المقدم.

استخدام Cloud Storage for Firebase من عناوين URL مع Vertex AI in Firebase

الخطوة 1: إعداد Cloud Storage for Firebase

إليك المهام عالية المستوى التي ستحتاج إلى القيام بها:

  1. أنشِئ حزمة Cloud Storage for Firebase في مشروعك على Firebase.

  2. طبِّق Firebase Security Rules على هذه الحزمة. مساعدتك من Firebase Security Rules تأمين ملفاتك عن طريق تقييد الوصول إلى المستخدمين النهائيين المصرّح لهم.

  3. أضف مكتبة برامج Cloud Storage for Firebase إلى تطبيقك.

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

الخطوة 2: تحميل ملف إلى حزمة

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

  • نوع MIME: هذا هو نوع وسائط الملف (على سبيل المثال، image/png). سيحاول Cloud Storage for Firebase تلقائيًا رصد نوع MIME أثناء التحميل وتطبيق تلك البيانات الوصفية على العنصر في الحزمة ومع ذلك، يمكنك تحديد نوع MIME أثناء التحميل اختياريًا.

  • عنوان URL لـ Cloud Storage for Firebase: هو معرّف فريد للملف. يجب أن يبدأ عنوان URL بـ gs://.

الخطوة 3: تضمين نوع MIME للملف وعنوان URL في طلب متعدد الوسائط

بعد تخزين ملف في حزمة Cloud Storage for Firebase، يمكنك تنفيذ ما يلي: تضمين نوع MIME وعنوان URL لـ Cloud Storage for Firebase في طلب متعدد الوسائط. يُرجى العلم أنّ هذه الأمثلة تعرض طلب generateContent لا يتم بثه، ولكن يمكنك يمكنهم أيضًا استخدام Cloud Storage for Firebase عناوين URL مع ميزة البث والمحادثة.

لتضمين الملف في الطلب، يمكنك استخدام أي من الخيارَين التاليَين:

الخيار 1: تضمين نوع MIME وعنوان URL باستخدام مرجع مساحة تخزين

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

الخيار 2: تضمين نوع MIME وعنوان URL بشكل صريح

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