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

لا تتوفّر هذه الميزة إلا عند استخدام Agent Platform Gemini API (formerly Vertex AI) كموفّر لواجهة برمجة التطبيقات.

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

بالنسبة إلى الأجزاء غير النصية من الإدخال (مثل ملفات الوسائط)، يمكنك استخدام Cloud Storage for Firebase بشكل اختياري لتضمين الملفات في الطلب. في ما يلي نظرة عامة على هذه الميزة:

  • يمكنك استخدام Cloud Storage for Firebase مع أي طلب متعدد الوسائط (مثل إنشاء النصوص والمحادثة) إذا كنت تستخدم Agent Platform Gemini API (formerly Vertex AI). تعرض الأمثلة في هذا الدليل إدخالاً أساسيًا للنص والصور.

  • يمكنك تحديد نوع MIME للملف وعنوان URL الخاص به على Cloud Storage for Firebase (الذي يبدأ دائمًا بـ gs://) في إدخال الطلب. هذه القيم هي بيانات وصفية يتم تخصيصها تلقائيًا لأي ملف يتم تحميله إلى حزمة Cloud Storage.

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


يصف دليل الحلول هذا كيفية إعداد Cloud Storage for Firebase، وتحميل ملف إلى حزمة 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) في Firebase AI Logic، يبلغ الحد الأقصى لحجم الطلب 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 عند استخدام عناوين URL من النوع Cloud Storage for Firebase مع حِزم تطوير البرامج (SDK) من النوع Firebase AI Logic:

  • يجب أن يستوفي الملف متطلبات ملفات الإدخال للطلبات المتعددة الوسائط. ويشمل ذلك متطلبات مثل نوع 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 الخاصة بالحزمة بالوصول المناسب إلى الملف. على سبيل المثال:

  • إذا كانت لديك قواعد عامة، يمكن لأي مستخدم أو عميل الوصول إلى الملف.

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

استخدام عناوين URL لـ Cloud Storage for Firebase مع Firebase AI Logic

لا تتوفّر هذه الميزة إلا عند استخدام Agent Platform Gemini API (formerly Vertex AI) كموفّر لواجهة برمجة التطبيقات.

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

يمكنك العثور على تعليمات مفصّلة لإعداد Cloud Storage for Firebase في دليل البدء: iOS+ | Android | الويب | Flutter | Unity

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

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

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

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

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

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

في مستندات Cloud Storage، يمكنك الاطّلاع على جميع الطرق المختلفة لتحميل الملفات إلى حزمة. على سبيل المثال، يمكنك تحميل ملفات محلية من جهاز المستخدم النهائي، مثل الصور والفيديوهات من الكاميرا. مزيد من المعلومات: iOS+ | Android | الويب | Flutter | Unity

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

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

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

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

بعد تخزين ملف في حزمة، يمكنك تضمين نوع MIME وعنوان URL الخاص به في الطلب. يُرجى العِلم أنّ هذه الأمثلة تعرض طلب generateContent غير مستند إلى البث، ولكن يمكنك أيضًا استخدام عناوين URL مع البث والمحادثة.

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

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

قبل تجربة هذا المثال، تأكَّد من إكمال دليل البدء لحِزم تطوير البرامج (SDK) في Firebase AI Logic.

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

Swift

// Upload an image file using Cloud Storage for Firebase.
let storageRef = Storage.storage().reference(withPath: "images/image.jpg")
guard let imageURL = Bundle.main.url(forResource: "image", withExtension: "jpg") else {
  fatalError("File 'image.jpg' not found in main bundle.")
}
let metadata = try await storageRef.putFileAsync(from: imageURL)

// Get the MIME type and Cloud Storage for Firebase URL.
guard let mimeType = metadata.contentType else {
  fatalError("The MIME type of the uploaded image is nil.")
}
// Construct a URL in the required format.
let storageURL = "gs://\(storageRef.bucket)/\(storageRef.fullPath)"

let prompt = "What's in this picture?"
// Construct the imagePart with the MIME type and the URL.
let imagePart = FileDataPart(uri: storageURL, mimeType: mimeType)

// To generate text output, call generateContent with the prompt and the imagePart.
let result = try await model.generateContent(prompt, imagePart)
if let text = result.text {
  print(text)
}

Kotlin

بالنسبة إلى لغة Kotlin، فإنّ الطرق في حزمة تطوير البرامج (SDK) هذه هي دوال تعليق ويجب استدعاؤها من نطاق الكوروتين.
// 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 = model.generateContent(prompt)
        println(response.text)
    }
} catch (e: StorageException) {
    // An error occurred while uploading the file.
} catch (e: GoogleGenerativeAIException) {
    // An error occurred while generating text.
}

Java

بالنسبة إلى Java، تعرض الطرق في حزمة SDK هذه ListenableFuture.
// 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();
});

Web

// Upload an image file using Cloud Storage for Firebase.
const storageRef = ref(storage, "image.jpg");
const uploadResult = await uploadBytes(storageRef, file);

// Get the MIME type and Cloud Storage for Firebase URL.
// toString() is the simplest way to construct the Cloud Storage for Firebase URL
// in the required format.
const mimeType = uploadResult.metadata.contentType;
const storageUrl = uploadResult.ref.toString();

// Construct the imagePart with the MIME type and the URL.
const imagePart = { type: "fileData", fileData: { mimeType, fileUri: storageUrl }};

// To generate text output, call generateContent with the prompt and imagePart.
const result = await model.generateContent([prompt, imagePart]);
console.log(result.response.text());

Dart

// Upload an image file using Cloud Storage for Firebase.
final storageRef = FirebaseStorage.instance.ref();
final imageRef = storageRef.child("images/image.jpg");
await imageRef.putData(data);

// Get the MIME type and Cloud Storage for Firebase file path.
final metadata = await imageRef.getMetadata();
final mimeType = metadata.contentType;
final bucket = imageRef.bucket;
final fullPath = imageRef.fullPath;

final prompt = TextPart("What's in the picture?");
// Construct a URL in the required format.
final storageUrl = 'gs://$bucket/$fullPath';
// Construct the filePart with the MIME type and the URL.
final filePart = FileData(mimeType, storageUrl);
// To generate text output, call generateContent with the text and the filePart.
final response = await model.generateContent([
  Content.multi([prompt, filePart])
]);
print(response.text);

Unity

var storageRef = FirebaseStorage.DefaultInstance.GetReference("images/image.jpg");
var metadata = await storageRef.PutFileAsync(filePathToJpg);

// Get the MIME type and Cloud Storage for Firebase URL.
var mimeType = metadata.ContentType;
// Construct a URL in the required format.
var storageURL = new Uri($"gs://{storageRef.Bucket}/{storageRef.Path}");

var prompt = ModelContent.Text("What's in this picture?");
// Construct a FileData that explicitly includes the MIME type and
// Cloud Storage for Firebase URL values.
var fileData = ModelContent.FileData(mimeType, storageURL);

// To generate text output, call GenerateContentAsync with the prompt and fileData.
var response = await model.GenerateContentAsync(new [] { prompt, fileData });
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

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

قبل تجربة هذا المثال، تأكَّد من إكمال دليل البدء لحِزم تطوير البرامج (SDK) في Firebase AI Logic.

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

Swift

let prompt = "What's in this picture?"
// Construct an imagePart that explicitly includes the MIME type and
// Cloud Storage for Firebase URL values.
let imagePart = FileDataPart(uri: "gs://bucket-name/path/image.jpg", mimeType: "image/jpeg")

// To generate text output, call generateContent with the prompt and imagePart.
let result = try await model.generateContent(prompt, imagePart)
if let text = result.text {
  print(text)
}

Kotlin

بالنسبة إلى لغة Kotlin، فإنّ الطرق في حزمة تطوير البرامج (SDK) هذه هي دوال تعليق ويجب استدعاؤها من نطاق الكوروتين.
// 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 = model.generateContent(prompt)
println(response.text)

Java

بالنسبة إلى Java، تعرض الطرق في حزمة SDK هذه ListenableFuture.
// 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);

Web

const prompt = "What's in this picture?";
// Construct an imagePart that explicitly includes the MIME type and Cloud Storage for Firebase URL values.
const imagePart = { type: "fileData", fileData: { mimeType: "image/jpeg", fileUri: "gs://bucket-name/path/image.jpg" }};

// To generate text output, call generateContent with the prompt and imagePart.
const result = await model.generateContent([prompt, imagePart]);
console.log(result.response.text());

Dart

final prompt = TextPart("What's in the picture?");
// Construct a filePart that explicitly includes the MIME type and Cloud Storage for Firebase URL values.
final filePart = FileData('image/jpeg', 'gs://bucket-name/path/image.jpg');
// To generate text output, call generateContent with the prompt and filePart.
final response = await model.generateContent([
  Content.multi([prompt, filePart])
]);
print(response.text);

Unity

var prompt = ModelContent.Text("What's in this picture?");
// Construct a FileData that explicitly includes the MIME type and
// Cloud Storage for Firebase URL values.
var fileData = ModelContent.FileData(
  mimeType: "image/jpeg",
  uri: new Uri("gs://bucket-name/path/image.jpg")
);

// To generate text output, call GenerateContentAsync with the prompt and fileData.
var response = await model.GenerateContentAsync(new [] { prompt, fileData });
UnityEngine.Debug.Log(response.Text ?? "No text in response.");