Uwzględniaj duże pliki w żądaniach multimodalnych i zarządzaj plikami za pomocą Cloud Storage dla Firebase

Dostępne tylko wtedy, gdy jako dostawcę interfejsu API używasz Vertex AI Gemini API.

Podczas wywoływania Vertex AI Gemini API z aplikacji za pomocą pakietu Firebase AI Logic SDK możesz poprosić model Gemini o wygenerowanie tekstu na podstawie danych wejściowych w różnych formatach, takich jak obrazy, pliki PDF, filmy i dźwięk.

W przypadku części wejściowych, które nie są tekstem (np. plików multimedialnych), możesz opcjonalnie użyć znaku Cloud Storage for Firebase, aby dołączyć pliki do żądania. Oto najważniejsze informacje o tej funkcji:

  • Możesz używać Cloud Storage for Firebase w przypadku dowolnego żądania multimodalnego (np. generowania tekstu i czatu), jeśli korzystasz z Vertex AI Gemini API. Przykłady w tym przewodniku pokazują podstawowe dane wejściowe w postaci tekstu i obrazu.

  • W danych wejściowych żądania określasz typ MIME pliku i jego Cloud Storage for Firebaseadres URL (który zawsze zaczyna się od gs://). Są to metadane automatycznie przypisywane do każdego pliku przesłanego do zasobnika Cloud Storage.

  • Musisz użyć obsługiwanego typu pliku i adresu URL.


Z tego przewodnika dowiesz się, jak skonfigurować Cloud Storage for Firebase, przesłać plik do zasobnika Cloud Storage for Firebase z aplikacji, a następnie uwzględnić typ MIME pliku i adres URL Cloud Storage for Firebase w żądaniu multimodalnym wysyłanym do Gemini API.

Chcesz zobaczyć przykłady kodu? A może masz już skonfigurowane Cloud Storage for Firebase i chcesz zacząć używać go w przypadku zapytań multimodalnych?

Przejdź do przykładów kodu

Dlaczego warto korzystać z Cloud Storage for Firebase w aplikacji?

Cloud Storage for Firebase korzysta z tej samej szybkiej, bezpiecznej i skalowalnej infrastruktury co Google Cloud Storage do przechowywania obiektów binarnych i plików, a jego pakiety SDK klienta są specjalnie zaprojektowane dla aplikacji mobilnych i internetowych.

W przypadku pakietów SDK Firebase AI Logic maksymalny rozmiar żądania wynosi 20 MB. Jeśli żądanie jest zbyt duże, otrzymasz błąd HTTP 413. Jeśli rozmiar pliku spowoduje, że łączny rozmiar żądania przekroczy 20 MB, użyj Cloud Storage for Firebaseadresu URL, aby uwzględnić plik w żądaniu multimodalnym. Jeśli jednak plik jest mały, możesz go często przekazywać bezpośrednio jako dane wbudowane (pamiętaj jednak, że plik przekazywany jako dane wbudowane jest kodowany w formacie base64 w trakcie przesyłania, co zwiększa rozmiar żądania).

Oto dodatkowe korzyści z używania Cloud Storage for Firebase:

  • Użytkownicy mogą przesyłać obrazy bezpośrednio z aplikacji do zasobnika Cloud Storage for Firebase, a następnie możesz uwzględniać te obrazy w promptach multimodalnych, podając tylko typ MIME pliku i jego Cloud Storage for FirebaseURL (który jest identyfikatorem pliku).

  • Możesz zaoszczędzić czas i przepustowość użytkowników, którzy muszą przesyłać obrazy, zwłaszcza jeśli mają słabe lub niestabilne połączenie sieciowe.

    • Jeśli przesyłanie lub pobieranie pliku zostanie przerwane, SDK automatycznie wznowią operację w miejscu, w którym została przerwana.Cloud Storage for Firebase
    • Ten sam przesłany plik może być używany wielokrotnie bez konieczności ponownego przesyłania go przez użytkownika za każdym razem, gdy jest potrzebny w aplikacji (np. w nowym żądaniu multimodalnym).
  • Możesz ograniczyć dostęp użytkowników do plików przechowywanych w usłudze Cloud Storage for Firebase, korzystając z Firebase Security Rules, które umożliwiają przesyłanie, pobieranie i usuwanie plików tylko autoryzowanym użytkownikom.

  • Dostęp do plików w zasobniku możesz uzyskać z Firebase lub z Google Cloud, co daje Ci możliwość przetwarzania po stronie serwera, np. filtrowania obrazów lub transkodowania filmów za pomocą interfejsów Google Cloud Storage API.

Jakie typy plików i adresów URL są obsługiwane?

Jeśli chcesz używać adresów URL Cloud Storage for Firebase z pakietami SDK Firebase AI Logic, musisz spełnić te wymagania dotyczące plików i adresów URL:

  • Plik musi spełniać wymagania dotyczące plików wejściowych w przypadku żądań multimodalnych. Obejmuje to wymagania dotyczące typu MIME i rozmiaru pliku.

  • Plik musi być przechowywany w zasobniku Cloud Storage for Firebase (co oznacza, że zasobnik jest dostępny dla usług Firebase, takich jak Firebase Security Rules). Jeśli możesz wyświetlić zasobnik w Firebase konsoli, oznacza to, że jest to zasobnik Cloud Storage for Firebase.

  • Cloud Storage for Firebase Zasobnik musi znajdować się w tym samym projekcie Firebase, w którym zarejestrowano aplikację.

  • Adres URL pliku Cloud Storage for Firebase musi zaczynać się od gs://, czyli tak, jak wszystkie adresy URL Google Cloud Storage.

  • Adres URL pliku nie może być adresem „przeglądarki” (np. adresem URL obrazu znalezionego w internecie).

Firebase Security Rules zasobnika musi też zezwalać na odpowiedni dostęp do pliku. Przykład:

  • Jeśli masz reguły publiczne, każdy użytkownik lub klient może uzyskać dostęp do pliku.

  • Jeśli masz zaawansowane reguły (zdecydowanie zalecane), Firebase sprawdzi, czy zalogowany użytkownik lub klient ma wystarczający dostęp do pliku, zanim zezwoli na wykonanie połączenia z podanym adresem URL.

Używanie adresów URL Cloud Storage for Firebase w usłudze Firebase AI Logic

Dostępne tylko wtedy, gdy jako dostawcę interfejsu API używasz Vertex AI Gemini API.

Krok 1. Skonfiguruj Cloud Storage for Firebase

Szczegółowe instrukcje konfigurowania Cloud Storage for Firebase znajdziesz w przewodniku dla początkujących:iOS+ | Android | Internet | Flutter | Unity

Oto ogólne zadania, które musisz wykonać:

  1. Utwórz lub zaimportuj zasobnik Cloud Storage for Firebase w projekcie Firebase.

  2. Zastosuj Firebase Security Rules do tego zasobnika. Rules pomagać w zabezpieczaniu plików przez ograniczanie dostępu do autoryzowanych użytkowników;

  3. Dodaj do aplikacji bibliotekę klienta Cloud Storage for Firebase.

    Pamiętaj, że możesz pominąć to zadanie, ale wtedy musisz zawsze wyraźnie uwzględniać w swoich żądaniach typ MIME i wartości adresów URL.

Krok 2. Prześlij plik do zasobnika

W Cloud Storage dokumentacji znajdziesz wszystkie sposoby przesyłania plików do zasobnika. Możesz na przykład przesyłać pliki lokalne z urządzenia użytkownika, takie jak zdjęcia i filmy z aparatu. Więcej informacji:iOS+ | Android | Internet | Flutter | Unity

Gdy przesyłasz plik do zasobnika, Cloud Storage automatycznie stosuje do niego te 2 informacje: Te wartości musisz uwzględnić w żądaniu (jak pokazano w następnym kroku tego przewodnika).

  • Typ MIME: typ nośnika pliku (np. image/png). Podczas przesyłania automatycznie spróbujemy wykryć typ MIME i zastosować te metadane do obiektu w zasobniku. Podczas przesyłania możesz jednak opcjonalnie określić typ MIME.

  • Cloud Storage for Firebase URL: unikalny identyfikator pliku. Adres URL musi zaczynać się od gs://.

Krok 3. W żądaniu multimodalnym podaj typ MIME i adres URL pliku.

Gdy plik zostanie zapisany w zasobniku, możesz uwzględnić w żądaniu jego typ MIME i adres URL. Pamiętaj, że w tych przykładach pokazano niestrumieniowe generateContent żądanie, ale możesz też używać adresów URL ze strumieniowaniem i czatem.

Aby dołączyć plik do prośby, możesz użyć jednej z tych opcji:

Opcja 1. Uwzględnij typ MIME i adres URL za pomocą odwołania do usługi Storage

Zanim wypróbujesz ten przykład, zapoznaj się z przewodnikiem dla początkujących dotyczącym pakietów SDK Firebase AI Logic.

Użyj tej opcji, jeśli plik został właśnie przesłany do zasobnika i chcesz go natychmiast uwzględnić w żądaniu (za pomocą odwołania do Storage). Wywołanie wymaga zarówno typu MIME, jak i adresu 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

W przypadku Kotlina metody w tym pakiecie SDK są funkcjami zawieszającymi i muszą być wywoływane w zakresie 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

W przypadku języka Java metody w tym pakiecie SDK zwracają wartość 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.");

Opcja 2. Jawne podanie typu MIME i adresu URL

Zanim wypróbujesz ten przykład, zapoznaj się z przewodnikiem dla początkujących dotyczącym pakietów SDK Firebase AI Logic.

Użyj tej opcji, jeśli znasz wartości typu MIME i Cloud Storage for Firebase adresu URL i chcesz je wyraźnie uwzględnić w żądaniu multimodalnym. Wywołanie wymaga zarówno typu MIME, jak i adresu 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

W przypadku Kotlina metody w tym pakiecie SDK są funkcjami zawieszającymi i muszą być wywoływane w zakresie 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

W przypadku języka Java metody w tym pakiecie SDK zwracają wartość 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.");