| Доступно только при использовании Agent Platform Gemini API (formerly Vertex AI) в качестве поставщика API. |
При вызове Agent Platform Gemini API (formerly Vertex AI) из приложения с помощью Firebase AI Logic SDK вы можете попросить модель Gemini сгенерировать текст на основе мультимодальных входных данных, таких как изображения, PDF-файлы, видео и аудио.
Для нетекстовых частей входных данных (например, медиафайлов) можно использовать параметр Cloud Storage for Firebase, чтобы включить файлы в запрос. Вот что вам нужно знать об этой функции:
Вы можете использовать Cloud Storage for Firebase с любым мультимодальным запросом (например, с генерацией текста и чатом), если вы используете Agent Platform Gemini API (formerly Vertex AI). В примерах в этом руководстве показан простой запрос с текстом и изображением.
В запросе нужно указать MIME-тип файла и его Cloud Storage for Firebase URL (который всегда начинается с
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 МБ, используйте Cloud Storage for Firebase URL, чтобы включить файл в мультимодальный запрос. Однако, если файл небольшой, его можно передать непосредственно как встроенные данные (обратите внимание, что файл, предоставленный как встроенные данные, кодируется в base64 при передаче, что увеличивает размер запроса).
Вот ещё несколько преимуществ использования Cloud Storage for Firebase:
Конечные пользователи могут загружать изображения прямо из вашего приложения в корзину Cloud Storage for Firebase, а вы можете включать эти изображения в мультимодальные запросы, просто указав MIME-тип файла и Cloud Storage for Firebase URL (идентификатор файла).
Вы можете сэкономить время и трафик конечных пользователей, если им нужно предоставить изображения, особенно если у них плохое или нестабильное подключение к сети.
- Если загрузка или скачивание файла прерывается, Cloud Storage for FirebaseSDK автоматически возобновляют операцию с того места, где она была остановлена.
- Один и тот же загруженный файл можно использовать несколько раз, не загружая его каждый раз, когда он нужен в приложении (например, в новом мультимодальном запросе).
Вы можете ограничить доступ конечных пользователей к файлам, хранящимся в Cloud Storage for Firebase, с помощью Firebase Security Rules, которые позволяют только авторизованным пользователям загружать, скачивать или удалять файлы.
Вы можете получить доступ к файлам в корзине из Firebase или Google Cloud, чтобы выполнять обработку на стороне сервера, например фильтрацию изображений или перекодирование видео, с помощью API Google Cloud Storage.
Какие типы файлов и URL поддерживаются?
Ниже приведены требования к файлам и URL, которые необходимо соблюдать при использовании Cloud Storage for FirebaseURL с 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
| Доступно только при использовании Agent Platform Gemini API (formerly Vertex AI) в качестве поставщика API. |
Шаг 1. Настройте Cloud Storage for Firebase
Подробные инструкции по настройке Cloud Storage for Firebase приведены в руководстве по началу работы:iOS+ | Android | Веб | Flutter | Unity.
Вот что вам нужно будет сделать:
Создайте или импортируйте сегмент Cloud Storage for Firebase в проекте Firebase.
Примените к этому сегменту правило Firebase Security Rules. Security Rules помогут вам защитить файлы, ограничив доступ к ним для авторизованных конечных пользователей.
Добавьте в приложение клиентскую библиотеку для 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, используя ссылку на хранилище
Вариант 2. Явное указание MIME-типа и URL
Вариант 1. Укажите тип MIME и URL с помощью ссылки на хранилище
| Прежде чем использовать этот пример, убедитесь, что вы выполнили инструкции из руководства по началу работы с Firebase AI Logic SDK. |
Этот вариант подходит, если вы только что загрузили файл в сегмент и хотите сразу же включить его в запрос (через ссылку на хранилище). Для вызова требуются 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 = { 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 = 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.");