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

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

عند استدعاء Vertex AI Gemini API من تطبيقك باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Firebase AI Logic، يمكنك الطلب من أحد نماذج 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) الخاصة بالعملاء مصمَّمة خصيصًا للتطبيقات المتوافقة مع الأجهزة الجوّالة وتطبيقات الويب.

بالنسبة إلى حِزم تطوير البرامج (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 مع حِزم Firebase AI Logic SDK:

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

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

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

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

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

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

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

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

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

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

في مستندات Cloud Storage، يمكنك التعرّف على جميع الطرق المختلفة لتحميل الملفات إلى حزمة. على سبيل المثال، يمكنك تحميل ملفات محلية من جهاز المستخدم النهائي، مثل الصور والفيديوهات من الكاميرا. مزيد من المعلومات: iOS+‎ | Android | الويب | 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) هذه عبارة عن دوال معلّقة ويجب استدعاؤها من نطاق روتين فرعي.
// 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.
}

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) هذه عبارة عن دوال معلّقة ويجب استدعاؤها من نطاق روتين فرعي.
// 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)

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.");