Disponibile solo quando utilizzi Vertex AI Gemini API come provider 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 testuali dell'input (come i file multimediali), puoi utilizzare facoltativamente Cloud Storage for Firebase per includere i file nella richiesta. A livello generale, ecco cosa devi sapere di questa funzionalità:
Puoi utilizzare Cloud Storage for Firebase con qualsiasi richiesta multimodale (come la generazione di testo e la chat) se utilizzi Vertex AI Gemini API. Gli esempi in questa guida mostrano un input di base di testo e immagine.
Nell'input della richiesta, specifichi il tipo MIME del file e il relativo URL Cloud Storage for Firebase (che inizia sempre con
gs://
). Questi valori sono metadati assegnati automaticamente a qualsiasi file caricato in un bucket Cloud Storage.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 poi includere il tipo MIME e l'URL Cloud Storage for Firebase del file nella tua richiesta multimodale all'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 veloce, sicura e scalabile di Google Cloud Storage per archiviare blob e file e i suoi SDK client sono creati appositamente per le app mobile e web.
Per gli SDK Firebase AI Logic, la dimensione massima della richiesta è 20 MB. Se una richiesta è troppo grande, viene visualizzato un errore HTTP 413. Se le dimensioni di un file faranno superare i 20 MB alla dimensione totale della richiesta, utilizza un URL Cloud Storage for Firebase per includere il file nella richiesta multimodale. Tuttavia, se un file è piccolo, spesso puoi passarlo direttamente come dati incorporati (tieni presente, però, che un file fornito come dati incorporati viene codificato in base64 durante il transito, il che aumenta le dimensioni della richiesta).
Ecco alcuni vantaggi aggiuntivi dell'utilizzo di Cloud Storage for Firebase:
Puoi consentire agli utenti finali di caricare immagini direttamente dalla tua app in un bucket Cloud Storage for Firebase e 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 riavviano automaticamente l'operazione dal punto in cui è stata interrotta.
- 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 consentono solo a un utente autorizzato di caricare, scaricare o eliminare file.
Puoi accedere ai file nel bucket da Firebase o da Google Cloud, il che ti offre la flessibilità di eseguire l'elaborazione lato server, ad esempio il filtro 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 quali 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 riesci a visualizzare il bucket nella console Firebase, allora è un bucket Cloud Storage for Firebase.
Il bucket Cloud Storage for Firebase deve trovarsi nello stesso progetto Firebase in cui hai registrato l'app.
L'URL Cloud Storage for Firebase del file deve iniziare con
gs://
, ovvero il modo in cui vengono creati tutti gli URL Google Cloud Storage.L'URL del file non può essere un URL "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.
Se hai regole solide (vivamente consigliate), Firebase verificherà che l'utente o il client che ha eseguito l'accesso disponga di un 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 quando utilizzi Vertex AI Gemini API come provider API. |
Passaggio 1: configura Cloud Storage for Firebase
Puoi trovare istruzioni dettagliate per la configurazione di Cloud Storage for Firebase nella guida introduttiva: iOS+ | Android | Web | Flutter | Unity
Ecco le attività di alto livello che dovrai 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 di tipo MIME e URL nelle tue 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+ | Android | Web | Flutter | Unity
Quando carichi un file in un bucket, Cloud Storage applica automaticamente le seguenti due informazioni al file. Dovrai includere questi valori nella richiesta (come mostrato nel passaggio successivo di questa guida).
Tipo MIME: il tipo di media del file (ad esempio,
image/png
). Durante il caricamento, proveremo a rilevare automaticamente il tipo MIME e ad applicare i metadati all'oggetto nel bucket. Tuttavia, puoi specificare facoltativamente 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 memorizzato un file in un bucket, puoi includere il relativo tipo MIME e URL
in una richiesta. Tieni presente che questi esempi mostrano una richiesta generateContent
non di 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 Storage
Opzione 2: includi esplicitamente il tipo MIME e l'URL
Opzione 1: includi il tipo MIME e l'URL utilizzando un riferimento Storage
Prima di provare questo esempio, assicurati di aver completato la guida introduttiva per gli Firebase AI LogicSDK. |
Utilizza questa opzione se hai appena caricato il file nel bucket e vuoi includerlo immediatamente (tramite un riferimento 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 di sospensione e devono essere chiamati da un ambito di 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 esplicitamente il tipo MIME e l'URL
Prima di provare questo esempio, assicurati di aver completato la guida introduttiva per gli Firebase AI LogicSDK. |
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 di sospensione e devono essere chiamati da un ambito di 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.");