عند طلب Gemini API من تطبيقك باستخدام Vertex AI in Firebase SDK، يمكنك توجيه نموذج 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 من تطبيقك، ثم تضمين نوع ملف MIME وعنوان URL لCloud Storage for Firebase في طلبك المتعدّد الوسائط المرسَل إلى Gemini API.
هل تريد الاطّلاع على أمثلة الرموز؟ هل سبق لك إعداد Cloud Storage for Firebase وأصبحت مستعدًا لبدء استخدامه مع طلباتك باستخدام وسائط متعددة؟
الانتقال إلى أمثلة الرموز البرمجية
ما هي مزايا استخدام Cloud Storage for Firebase مع تطبيقك؟
يستخدم Cloud Storage for Firebase البنية الأساسية نفسها السريعة والآمنة والقابلة للتوسّع التي يستخدمها Google Cloud Storage لتخزين ملفات البيانات غير القابلة للتعديل والملفات، وحِزم تطوير البرامج (SDK) للعملاء مصمّمة خصيصًا للتطبيقات المتوافقة مع الأجهزة الجوّالة والمواقع الإلكترونية.
بالنسبة إلى حِزم Vertex AI in Firebase SDK، يبلغ الحد الأقصى لحجم الطلب 20 ميغابايت. يظهر لك خطأ HTTP 413 إذا كان الطلب كبيرًا جدًا. إذا كان حجم ملف معيّن يؤدي إلى زيادة حجم الطلب الإجمالي إلى أكثر من 20 ميغابايت، استخدِم عنوان URL بعنوان Cloud Storage for Firebase لتضمين الملف في طلبك المتعدّد الوسائط. ومع ذلك، إذا كان الملف صغيرًا، يمكنك غالبًا تمريره مباشرةً كبيانات مضمّنة (يُرجى العلم أنّ الملف المقدَّم كبيانات مضمّنة يتم ترميزه إلى base64 أثناء نقله، ما يزيد من حجم الطلب).
في ما يلي بعض المزايا الإضافية لاستخدام Cloud Storage for Firebase:
يمكنك أن تطلب من المستخدمين النهائيين تحميل الصور مباشرةً من تطبيقك إلى حزمة Cloud Storage for Firebase، ثم يمكنك تضمين هذه الصور في طلباتك المتعدّدة الوسائط من خلال تحديد نوع MIME للملف وعنوان URL الخاص بملف Cloud Storage for Firebase (وهو معرّف للملف).
يمكنك توفير الوقت وعرض النطاق للمستخدمين النهائيين إذا احتاجوا إلى تقديم صور، خاصةً إذا كانت جودة الشبكة لديهم متقلبة أو منخفضة.
- في حال انقطاع عملية تحميل أو تنزيل ملف، ستعيد حِزم Cloud Storage for Firebase SDK التشغيل تلقائيًا من حيث توقفت.
- يمكن استخدام الملف الذي تم تحميله نفسه عدة مرات بدون أن يحتاج المستخدم النهائي إلى تحميل الملف نفسه في كل مرة يكون مطلوبًا فيها في تطبيقك (مثل ملف طلب متعدد الوسائط جديد).
يمكنك حظر وصول المستخدم النهائي إلى الملفات المخزّنة في 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
الخطوة 1: إعداد Cloud Storage for Firebase
يمكنك العثور على تعليمات مفصّلة لإعداد Cloud Storage for Firebase في دليل البدء: iOS والإصدارات الأحدث | Android | الويب | Flutter
في ما يلي المهام الأساسية التي عليك تنفيذها:
أنشئ حزمة Cloud Storage for Firebase أو استورِدها في مشروعك على Firebase.
طبِّق Firebase Security Rules على هذه المجموعة. Rules مساعدتك في تأمين ملفاتك من خلال تقييد الوصول إلى المستخدمين النهائيين المعتمَدين
أضِف مكتبة البرامج لنظام التشغيل Cloud Storage for Firebase إلى تطبيقك.
يُرجى العِلم أنّه يمكنك تخطّي هذه المهمة، ولكن عليك بعد ذلك دائمًا تضمين نوع MIME وقيم عنوان URL في طلباتك بشكل صريح.
الخطوة 2: تحميل ملف إلى حزمة
في مستندات Cloud Storage، يمكنك الاطّلاع على كل الخطوات المختلفة لتحميل الملفات إلى حزمة تخزين. على سبيل المثال، يمكنك تحميل ملفات محلية من جهاز المستخدم النهائي، مثل الصور والفيديوهات من الكاميرا. اطّلِع على مزيد من المعلومات: iOS والإصدارات الأحدث | Android | الويب | Flutter
عند تحميل ملف إلى حزمة، تطبِّق Cloud Storage تلقائيًا المعلومتَين التاليتَين على الملف. ستحتاج إلى تضمين هذه القيم في الطلب (كما هو موضّح في الخطوة التالية من هذا الدليل).
نوع MIME: هو نوع الوسائط للملف (على سبيل المثال،
image/png
). سنحاول تلقائيًا رصد نوع MIME أثناء التحميل وتطبيق هذه القيمة الوصفية على العنصر في الحزمة. ومع ذلك، يمكنك اختياريًا تحديد نوع MIME أثناء التحميل.عنوان URL لـ Cloud Storage for Firebase: هو معرّف فريد للملف. يجب أن يبدأ عنوان URL بـ
gs://
.
الخطوة 3: تضمين نوع MIME للملف وعنوان URL الخاص به في طلب متعدد الوسائط
بعد تخزين ملف في حزمة، يمكنك تضمين نوع MIME وعنوان URL
في طلب. يُرجى العلم أنّ هذه الأمثلة تعرض طلب generateContent
غير مخصّص للبث، ولكن يمكنك أيضًا استخدام عناوين URL مع البث والمحادثة.
لتضمين الملف في الطلب، يمكنك استخدام أحد الخيارَين التاليَين:
الخيار 2: تضمين نوع MIME وعنوان URL بشكل صريح
الخيار 1: تضمين نوع MIME وعنوان URL باستخدام مرجع مساحة تخزين
استخدِم هذا الخيار إذا كنت قد حمّلت الملف للتو إلى الحزمة وأردت تضمين الملف على الفور (من خلال مرجع في "مساحة التخزين") في الطلب. يتطلّب الطلب نوع 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 = 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);
الخيار 2: تضمين نوع MIME وعنوان URL بشكل صريح
استخدِم هذا الخيار إذا كنت تعرف قيم نوع 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 = 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);