Disponibile solo se utilizzi Vertex AI Gemini API come fornitore di API. |
Quando chiami Vertex AI Gemini API dalla tua app utilizzando un SDK Firebase AI Logic, puoi chiedere a un modello Gemini di generare testo in base a un input multimodale, come 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à:
Se utilizzi Cloud Storage for Firebase, puoi usare Cloud Storage for Firebase con qualsiasi richiesta multimodale (ad esempio la generazione di testo e la chat).Vertex AI Gemini API Gli esempi riportati in questa guida mostrano un input di testo e immagini di base.
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?
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 mobile e web.
Per gli SDK Firebase AI Logic, 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 però che un file fornito come dati in linea viene 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, come 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 Firebase AI Logic:
Il file deve soddisfare i requisiti dei file di input per le richieste multimodali. 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 trovata 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 cliente può accedere al file.
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 Firebase AI Logic
Disponibile solo se utilizzi Vertex AI Gemini API come fornitore di API. |
Passaggio 1: configura Cloud Storage for Firebase
Puoi trovare istruzioni dettagliate per la configurazione di Cloud Storage for Firebase nella sua guida introduttiva: iOS+ | Android | Web | Flutter | Unity
Ecco le attività di alto livello da svolgere:
Crea o importa un bucket Cloud Storage for Firebase nel tuo progetto Firebase.
Applica Firebase Security Rules a questo bucket. Rules ti aiutano a proteggere i tuoi file limitando l'accesso agli utenti finali autorizzati.
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 nelle richieste.
Passaggio 2: carica un file in un bucket
Nella documentazione di Cloud Storage puoi scoprire tutti i diversi modi per caricare file in un bucket. Ad esempio, puoi caricare file locali dal dispositivo dell'utente finale, come foto e video dalla fotocamera. Scopri di più: iOS e versioni successive | Android | Web | Flutter | Unity
Quando carichi un file in un bucket, Cloud Storage applica automaticamente al file le due seguenti informazioni. Dovrai includere questi valori nella richiesta (come mostrato nel passaggio successivo di questa guida).
Tipo MIME: si tratta del tipo di media del file (ad esempio
image/png
). Proveremo automaticamente a rilevare il tipo MIME durante il caricamento e ad applicare questi 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 archiviato un file in un bucket, puoi includerne il tipo MIME e l'URL
in una richiesta. Tieni presente che questi esempi mostrano una richiesta generateContent
non in streaming, ma puoi anche utilizzare URL 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
Prima di provare questo esempio, assicurati di aver completato la guida introduttiva agli SDK Firebase AI Logic. |
Utilizza questa opzione se hai appena caricato il file nel bucket e vuoi includerlo immediatamente (tramite un riferimento a Storage) nella richiesta. La chiamata richiede sia il tipo MIME sia l'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
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 unListenableFuture
.
// 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.");
Opzione 2: includi il tipo MIME e l'URL in modo esplicito
Prima di provare questo esempio, assicurati di aver completato la guida introduttiva agli SDK Firebase AI Logic. |
Utilizza questa opzione se conosci i valori per il tipo MIME e l'URL Cloud Storage for Firebase e vuoi includerli esplicitamente nella richiesta multimodale. La chiamata richiede sia il tipo MIME sia l'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
Per Kotlin, i metodi in questo SDK sono funzioni sospese 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 unListenableFuture
.
// 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.");