Как добавлять большие файлы в мультимодальные запросы и управлять файлами с помощью Cloud Storage for Firebase

Доступно только при использовании 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.

Вот что вам нужно будет сделать:

  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-тип.

  • Cloud Storage for Firebase URL – уникальный идентификатор файла. URL должен начинаться с gs://.

Шаг 3. Включите MIME-тип и URL файла в мультимодальный запрос

После того как вы сохраните файл в сегменте, вы можете указать его MIME-тип и URL в запросе. Обратите внимание, что в этих примерах показан запрос generateContent без потоковой передачи, но вы также можете использовать 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.");