Includi file di grandi dimensioni nelle richieste multimodali e gestisci i file utilizzando Cloud Storage for Firebase

Quando chiami Gemini API dalla tua app utilizzando un SDK Vertex AI in Firebase, puoi chiedere al modello Gemini di generare del testo in base a un input multimodale. I prompt multimodali possono includere più modalità (o tipi di input), come testo, immagini, PDF, video e audio.

Per le parti non di testo dell'input (ad esempio i file multimediali), se vuoi puoi utilizzare Cloud Storage for Firebase per includere i file nella richiesta. Ecco alcune informazioni generali su questa funzionalità:

  • Puoi utilizzare Cloud Storage for Firebase con qualsiasi richiesta multimodale (ad esempio la generazione di testo e la chat). Gli esempi in questa guida mostrano un input di base di testo e immagine.

  • Devi specificare il tipo MIME del file e il relativo URL Cloud Storage for Firebase (che inizia sempre con gs://) nell'input della richiesta. Questi valori sono metadati assegnati automaticamente a qualsiasi file caricato in un Cloud Storage separato.

  • Devi utilizzare un tipo di file e un URL supportati.


Questa guida alla soluzione descrive come configurare Cloud Storage for Firebase, caricare un file in un bucket Cloud Storage for Firebase dalla tua app e includere il tipo MIME e l'URL Cloud Storage for Firebase del file nella richiesta multimodale al Gemini API.

Vuoi vedere gli esempi di codice? Oppure hai già configurato Cloud Storage for Firebase e vuoi iniziare a utilizzarlo con le tue richieste multimodali?

Vai agli esempi di codice

Perché utilizzare Cloud Storage for Firebase con la tua app?

Cloud Storage for Firebase utilizza la stessa infrastruttura rapida, sicura e scalabile di Google Cloud Storage per archiviare blob e file e i suoi SDK client sono progettati specificamente per app web e mobile.

Per gli SDK Vertex AI in Firebase, la dimensione massima della richiesta è 20 MB. Viene visualizzato un errore HTTP 413 se una richiesta è troppo grande. Se le dimensioni di un file fanno superare le dimensioni totali della richiesta di 20 MB, utilizza un URL Cloud Storage for Firebase per includere il file nella richiesta multimodale. Tuttavia, se un file è di piccole dimensioni, spesso puoi passarlo direttamente come dati in linea (tieni presente che un file fornito come dati in linea è codificato in base64 in transito, il che aumenta le dimensioni della richiesta).

Ecco alcuni vantaggi aggiuntivi dell'utilizzo di Cloud Storage for Firebase:

  • Puoi chiedere agli utenti finali di caricare le immagini direttamente dalla tua app in un bucket Cloud Storage for Firebase, per poi includerle nei prompt multimodali semplicemente specificando il tipo MIME del file e l'URL Cloud Storage for Firebase (che è un identificatore del file).

  • Puoi far risparmiare tempo e larghezza di banda agli utenti finali se devono fornire immagini, soprattutto se la qualità della rete è scarsa o instabile.

    • Se il caricamento o il download di un file viene interrotto, gli SDK Cloud Storage for Firebase riavvia automaticamente l'operazione esattamente da dove si era interrotto.
    • Lo stesso file caricato può essere utilizzato più volte senza che l'utente finale debba caricarlo ogni volta che è necessario nella tua app (ad esempio in una nuova richiesta multimodale).

  • Puoi limitare l'accesso degli utenti finali ai file archiviati in Cloud Storage for Firebase utilizzando Firebase Security Rules, che consente solo a un utente autorizzato di caricare, scaricare o eliminare file.

  • Puoi accedere ai file nel tuo bucket da Firebase o da Google Cloud, godendo della flessibilità di eseguire l'elaborazione lato server, ad esempio il filtraggio delle immagini o la transcodifica video, utilizzando le API Google Cloud Storage.

Quali tipi di file e URL sono supportati?

Di seguito sono riportati i requisiti per i file e gli URL quando vuoi utilizzare gli URL Cloud Storage for Firebase con gli SDK Vertex AI in Firebase:

  • Il file deve soddisfare i requisiti dei file di input per le richieste multimodali quando utilizzi gli SDK Vertex AI in Firebase. Sono inclusi requisiti come il tipo MIME e le dimensioni del file.

  • Il file deve essere archiviato in un bucket Cloud Storage for Firebase (il che significa che il bucket è accessibile ai servizi Firebase, come Firebase Security Rules). Se puoi visualizzare il bucket nella Console Firebase, si tratta di un bucket Cloud Storage for Firebase.

  • Il bucket Cloud Storage for Firebase deve trovarsi nello stesso progetto Firebase in cui hai registrato la tua app.

  • L'URL Cloud Storage for Firebase del file deve iniziare con gs://, che è il modo in cui vengono costruiti tutti gli URL Google Cloud Storage.

  • L'URL del file non può essere un URL del "browser" (ad esempio, l'URL di un'immagine che trovi su internet).

Inoltre, l'Firebase Security Rules per il bucket deve consentire l'accesso appropriato al file. Ad esempio:

  • Se hai regole pubbliche, qualsiasi utente o client può accedere al file e fornire il relativo URL in una chiamata utilizzando un SDK Vertex AI in Firebase. Questi tipi di regole devono essere utilizzati solo per iniziare e durante le prime fasi di prototipazione (a meno che i file non siano effettivamente destinati a essere completamente accessibili al pubblico).

  • Se hai regole efficaci (fortemente consigliate), Firebase verificherà che l'utente o il cliente che ha eseguito l'accesso abbia accesso sufficiente al file prima di consentire la chiamata con l'URL fornito.

Utilizzare gli URL Cloud Storage for Firebase con Vertex AI in Firebase

Passaggio 1: configura Cloud Storage for Firebase

Puoi trovare istruzioni dettagliate su come configurare e utilizzare Cloud Storage for Firebase nella corrispondente guida introduttiva.

Vai alla guida introduttiva Cloud Storage for Firebase

Ecco le attività di alto livello da svolgere:

  1. Crea un bucket Cloud Storage for Firebase nel tuo progetto Firebase.

    Se nel tuo progetto Google Cloud hai già un bucket Cloud Storage che vuoi utilizzare con Vertex AI in Firebase, puoi renderlo accessibile ai servizi Firebase (incluso Vertex AI in Firebase) "importandolo" in Firebase.

  2. Applica Firebase Security Rules a questo bucket. Firebase Security Rules ti aiutano a proteggere i tuoi file limitando l'accesso agli utenti finali autorizzati.

  3. Aggiungi la libreria client per Cloud Storage for Firebase alla tua app.

    Tieni presente che puoi saltare questa attività, ma devi sempre includere esplicitamente i valori del tipo MIME e dell'URL Cloud Storage for Firebase nelle richieste multimodali.

Passaggio 2: carica un file in un bucket

Nella documentazione Cloud Storage for Firebase puoi scoprire tutti i diversi modi per caricare file in un bucket Cloud Storage for Firebase. Ad esempio, puoi caricare file locali dal dispositivo dell'utente finale, come foto e video della fotocamera.

Quando carichi un file in un bucket, Cloud Storage applica automaticamente al file le due informazioni seguenti. Dovrai includere questi valori nella richiesta multimodale (come mostrato nel passaggio successivo di questa guida).

  • Tipo MIME: è il tipo multimediale del file (ad esempio, image/png). Cloud Storage for Firebase proverà automaticamente a rilevare il tipo MIME durante il caricamento e applicherà i metadati all'oggetto nel bucket. Tuttavia, se vuoi, puoi specificare il tipo MIME durante il caricamento.

  • URL Cloud Storage for Firebase: si tratta di un identificatore univoco del file. L'URL deve iniziare con gs://.

Passaggio 3: includi il tipo MIME e l'URL del file in una richiesta multimodale

Una volta che un file è archiviato in un bucket Cloud Storage for Firebase, puoi includere il relativo tipo MIME e l'URL Cloud Storage for Firebase in una richiesta multimodale. Tieni presente che questi esempi mostrano una richiesta generateContent non in streaming, ma puoi anche utilizzare gli URL Cloud Storage for Firebase con streaming e chat.

Per includere il file nella richiesta, puoi utilizzare una delle seguenti opzioni:

Opzione 1: includi il tipo MIME e l'URL utilizzando un riferimento a archiviazione

Utilizza questa opzione se hai appena caricato il file nel bucket e vuoi includerlo immediatamente (tramite un riferimento a Storage) nella richiesta multimodale. La chiamata richiede sia il tipo MIME sia l'URL Cloud Storage for Firebase.

Kotlin+KTX

Per Kotlin, i metodi in questo SDK sono funzioni sospese e devono essere chiamati da un ambito 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

Per Java, i metodi in questo SDK restituiscono un 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();
});

Opzione 2: includi il tipo MIME e l'URL in modo esplicito

Utilizza questa opzione se conosci i valori per il tipo MIME e l'URLCloud Storage for Firebase e vuoi includerli esplicitamente nella richiesta multimodale. La chiamata richiede sia il tipo MIME sia l'URL.

Kotlin+KTX

Per Kotlin, i metodi in questo SDK sono funzioni di sospensione e devono essere chiamati da un ambito 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

Per Java, i metodi in questo SDK restituiscono un 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);