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

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

عند استدعاء Vertex AI Gemini API من تطبيقك باستخدام Firebase AI Logic SDK، يمكنك الطلب من نموذج Gemini إنشاء نص استنادًا إلى إدخال متعدد الوسائط، مثل الصور وملفات PDF والفيديو والمحتوى الصوتي.

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

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

  • يمكنك تحديد نوع 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 للعملاء خصيصًا لتطبيقات الأجهزة الجوّالة وتطبيقات الويب.

بالنسبة إلى حِزم Firebase AI Logic SDK، يبلغ الحد الأقصى لحجم الطلب 20 ميغابايت. يظهر الخطأ HTTP 413 إذا كان الطلب كبيرًا جدًا. إذا كان حجم الملف سيؤدي إلى تجاوز إجمالي حجم الطلب 20 ميغابايت، استخدِم Cloud Storage for Firebase عنوان URL لتضمين الملف في طلبك المتعدد الوسائط. ومع ذلك، إذا كان الملف صغيرًا، يمكنك غالبًا تمريره مباشرةً كبيانات مضمّنة (يُرجى العِلم أنّ الملف المقدَّم كبيانات مضمّنة يتم ترميزه إلى base64 أثناء النقل، ما يزيد من حجم الطلب).

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

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

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

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

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

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

في ما يلي متطلبات الملفات وعناوين URL عند استخدام Cloud Storage for Firebase عناوين URL مع Firebase AI Logic حِزم SDK:

  • يجب أن يستوفي الملف الـ متطلبات ملفات الإدخال للطلبات المتعددة الوسائط. ويشمل ذلك متطلبات مثل نوع MIME وحجم الملف.

  • يجب تخزين الملف في حاوية Cloud Storage for Firebase(ما يعني أنّ الحاوية يمكن الوصول إليها من خدمات Firebase، مثل Firebase Security Rules).إذا كان بإمكانك الاطّلاع على حاويتك في Firebase console،فهذا يعني أنّها حاوية 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

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

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

يمكنك الاطّلاع على تعليمات مفصّلة حول إعداد Cloud Storage for Firebase في دليل البدء: iOS+ | Android | Web | 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 | Web | Flutter | Unity

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

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

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

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

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

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

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

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

استخدِم هذا الخيار إذا حمّلت الملف للتو إلى الحاوية وأردت تضمين الملف على الفور (عبر مرجع في 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 هذه دوالاً معلّقة ويجب استدعاؤها من نطاق Coroutine.
// 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 = { 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 بشكلٍ صريح

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

استخدِم هذا الخيار إذا كنت تعرف قيم نوع 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 هذه دوالاً معلّقة ويجب استدعاؤها من نطاق Coroutine.
// 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 = { 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.");