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

Доступно только при использовании API Vertex AI Gemini в качестве поставщика API.

При вызове API Vertex AI Gemini из вашего приложения с помощью 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 в ваш мультимодальный запрос к API Gemini .

Хотите увидеть примеры кода? Или вы уже настроили Cloud Storage for Firebase и готовы начать использовать его с вашими мультимодальными запросами?

Перейти к примерам кода

Зачем использовать Cloud Storage for Firebase в вашем приложении?

Cloud Storage for Firebase использует ту же быструю, безопасную и масштабируемую инфраструктуру, что и Google Cloud Storage для хранения больших двоичных объектов и файлов, а его клиентские SDK созданы специально для мобильных и веб-приложений.

Для Firebase AI Logic 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 (который является идентификатором файла).

  • Вы можете сэкономить время и пропускную способность своих конечных пользователей, если им необходимо предоставить изображения, особенно если у них плохое или нестабильное качество сети.

    • Если загрузка или скачивание файла прерывается, SDK Cloud Storage for Firebase автоматически возобновляет операцию с того места, где она была прервана.
    • Один и тот же загруженный файл можно использовать несколько раз, и конечному пользователю не придется загружать один и тот же файл каждый раз, когда он понадобится в вашем приложении (например, в новом мультимодальном запросе).
  • Вы можете ограничить доступ конечного пользователя к файлам, хранящимся в Cloud Storage for Firebase с помощью Firebase Security Rules , которые разрешают только авторизованному пользователю загружать, скачивать или удалять файлы.

  • Вы можете получить доступ к файлам в вашем хранилище из Firebase или из Google Cloud , что дает вам возможность выполнять обработку на стороне сервера, например фильтрацию изображений или перекодирование видео, с использованием API-интерфейсов Google Cloud Storage .

Какие типы файлов и 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-адресом.

Используйте Cloud Storage for Firebase с Firebase AI Logic

Доступно только при использовании API 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 к этому контейнеру. 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 с использованием ссылки на хранилище

Прежде чем приступить к работе с этим примером, убедитесь, что вы ознакомились с руководством по началу работы с Firebase AI Logic SDK .

Используйте эту опцию, если вы только что загрузили файл в бакет и хотите немедленно включить файл (через ссылку на хранилище) в запрос. Для вызова требуется как тип MIME, так и URL-адрес Cloud Storage for Firebase .

Быстрый

// 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);

Единство

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.

Быстрый

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

Единство

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