تضمين الملفات الكبيرة في الطلبات المتعدّدة الوسائط وإدارة الملفات باستخدام 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://) في إدخال الطلب. هذه القيم هي data الوصفية التي يتمّ تعيينها تلقائيًا لأيّ ملف يتمّ تحميله إلى حزمة Cloud Storage .

• يجب استخدام نوع ملف وعنوان URL متوافقَين.

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

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

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

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

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

• يمكنك حظر وصول المستخدم النهائي إلى الملفات المخزّنة في Cloud Storage for Firebase باستخدام Firebase Security Rules، التي لا تسمح إلا لمستخدم مفوَّض بتحميل الملفات أو تنزيلها أو حذفها.

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

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

في ما يلي متطلبات الملفات وعناوين URL عند استخدام Cloud Storage for Firebase عناوين URL مع حِزم تطوير البرامج (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 الخاص به في طلب باستخدام حزمة Vertex AI in Firebase SDK. يجب عدم استخدام هذه الأنواع من القواعد إلا للبدء وأثناء إنشاء النماذج الأوّلية (ما لم يكن من المفترض أن تكون الملفات بالفعل ملفات يمكن الوصول إليها علنًا).

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

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

iOS والإصدارات الأحدث Android الويب Flutter

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

يمكنك العثور على تعليمات تفصيلية حول إعداد واستخدام "Cloud Storage for Firebase" في دليل البدء الخاص به.

الانتقال إلى Cloud Storage for Firebase دليل البدء

في ما يلي المهام الأساسية التي عليك تنفيذها:

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

   إذا كان لديك حزمة Cloud Storage في مشروع Google Cloud تريد استخدامها مع Vertex AI in Firebase، يمكنك السماح لخدمات Firebase (بما في ذلك Vertex AI in Firebase) بالوصول إليها من خلال "استيراد" الحزمة إلى Firebase.

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

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

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

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

في مستندات Cloud Storage for Firebase، يمكنك التعرّف على كل الخطوات المختلفة التي يجب اتّباعها لتحميل الملفات إلى حزمة Cloud Storage for Firebase. على سبيل المثال، يمكنك تحميل ملفات محلية من جهاز المستخدم النهائي، مثل الصور والفيديوهات من الكاميرا.

عند تحميل ملف إلى حزمة، تطبِّق 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 لا يتم بثه، ولكن يمكنك أيضًا استخدام عناوين URL للسمة Cloud Storage for Firebase مع البث والمحادثة.

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

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

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

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

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

// Upload an image file using Cloud Storage for Firebase.
val storageRef = Firebase.storage.reference.child("images/image.jpg")
val fileUri = Uri.fromFile(File("image.jpg"))
try {
    val taskSnapshot = storageRef.putFile(fileUri).await()
    // Get the MIME type and Cloud Storage for Firebase file path.
    val mimeType = taskSnapshot.metadata?.contentType
    val bucket = taskSnapshot.metadata?.bucket
    val filePath = taskSnapshot.metadata?.path

    if (mimeType != null && bucket != null) {
        // Construct a URL in the required format.
        val storageUrl = "gs://$bucket/$filePath"
        // Construct a prompt that includes text, the MIME type, and the URL.
        val prompt = content {
            fileData(mimeType = mimeType, uri = storageUrl)
            text("What's in this picture?")
        }
        // To generate text output, call generateContent with the prompt.
        val response = generativeModel.generateContent(prompt)
        println(response.text)
    }
} catch (e: StorageException) {
    // An error occurred while uploading the file.
} catch (e: GoogleGenerativeAIException) {
    // An error occurred while generating text.
}

// Upload an image file using Cloud Storage for Firebase.
StorageReference storage = FirebaseStorage.getInstance().getReference("images/image.jpg");
Uri fileUri = Uri.fromFile(new File("images/image.jpg"));

storage.putFile(fileUri).addOnSuccessListener(taskSnapshot -> {
    // Get the MIME type and Cloud Storage for Firebase file path.
    String mimeType = taskSnapshot.getMetadata().getContentType();
    String bucket = taskSnapshot.getMetadata().getBucket();
    String filePath = taskSnapshot.getMetadata().getPath();

    if (mimeType != null && bucket != null) {
        // Construct a URL in the required format.
        String storageUrl = "gs://" + bucket + "/" + filePath;
        // Create a prompt that includes text, the MIME type, and the URL.
        Content prompt = new Content.Builder()
                .addFileData(storageUrl, mimeType)
                .addText("What's in this picture?")
                .build();

        // To generate text output, call generateContent with the prompt.
        GenerativeModelFutures modelFutures = GenerativeModelFutures.from(model);
        ListenableFuture<GenerateContentResponse> response = modelFutures.generateContent(prompt);
        Futures.addCallback(response, new FutureCallback<>() {
            @Override
            public void onSuccess(GenerateContentResponse result) {
                String resultText = result.getText();
                System.out.println(resultText);
            }

            @Override
            public void onFailure(@NonNull Throwable t) {
                t.printStackTrace();
            }
        }, executor);
    }
}).addOnFailureListener(e -> {
    // An error occurred while uploading the file.
    e.printStackTrace();
});

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

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

// Construct a prompt that explicitly includes the MIME type and Cloud Storage for Firebase URL values.
val prompt = content {
    fileData(mimeType = "image/jpeg", uri = "gs://bucket-name/path/image.jpg")
    text("What's in this picture?")
}
// To generate text output, call generateContent with the prompt.
val response = generativeModel.generateContent(prompt)
println(response.text)

// Construct a prompt that explicitly includes the MIME type and Cloud Storage for Firebase URL values.
Content prompt = new Content.Builder()
        .addFilePart("gs://bucket-name/path/image.jpg", "image/jpeg")
        .addText("What's in this picture?")
        .build();

// To generate text output, call generateContent with the prompt
GenerativeModelFutures modelFutures = GenerativeModelFutures.from(model);
ListenableFuture<GenerateContentResponse> response = modelFutures.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(@NonNull Throwable t) {
        t.printStackTrace();
    }
}, executor);