Visualizza su ai.google.dev | Esegui in Google Colab | Visualizza il codice sorgente su GitHub |
L'API Gemini supporta i prompt con dati di testo, immagine, audio e video, noti anche come prompt multimodali, il che significa che puoi includere questi tipi di file multimediali nei tuoi prompt. Per file di piccole dimensioni, puoi puntare il modello Gemini direttamente a un file locale. Carica i file di dimensioni maggiori con l'API File prima di includerli nei prompt.
L'API File ti consente di archiviare fino a 20 GB di file per progetto e ogni file non ha una dimensione superiore a 2 GB. I file rimangono archiviati per 48 ore e sono accessibili con la chiave API per la generazione entro questo periodo di tempo e non possono essere scaricati dall'API. L'API Files è disponibile senza costi in tutte le regioni in cui è disponibile l'API Gemini.
L'API File gestisce gli input che possono essere utilizzati per generare contenuti con model.generateContent
o model.streamGenerateContent
. Per informazioni sui formati di file validi (tipi MIME) e sui modelli supportati, consulta Formati di file supportati.
Questa guida mostra come utilizzare l'API File per caricare file multimediali e includerli in una chiamata GenerateContent
all'API Gemini. Per ulteriori informazioni, consulta gli
esempi
di codice.
Prima di iniziare: configura il progetto e la chiave API
Prima di chiamare l'API Gemini (o la relativa API File), devi impostare il progetto e configurare la chiave API.
Prompt con immagini
In questo tutorial, caricherai un'immagine di esempio utilizzando l'API File e la utilizzerai per generare contenuti.
Carica un file immagine
Per informazioni su come caricare il tuo file, consulta la sezione Appendice.
Prepara un'immagine di esempio da caricare:
curl -o image.jpg https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg
Carica il file utilizzando
media.upload
in modo da potervi accedere con altre chiamate API:sample_file = genai.upload_file(path="image.jpg", display_name="Sample drawing") print(f"Uploaded file '{sample_file.display_name}' as: {sample_file.uri}")
response
mostra che l'immagine caricata viene archiviata con l'elemento display_name
specificato e ha un uri
per fare riferimento al file nelle chiamate API Gemini. Utilizza response
per monitorare il modo in cui i file caricati vengono mappati agli URI.
A seconda del caso d'uso, puoi archiviare gli URI in strutture, ad esempio dict
o un database.
recupera i metadati del file immagine
Dopo aver caricato il file, puoi verificare che l'API abbia archiviato il file
e ottenere i relativi metadati chiamando files.get
tramite l'SDK.
Questo metodo ti consente di ottenere i metadati per un file caricato associato al progetto Google Cloud collegato alla tua chiave API. Solo i valori name
(e, di conseguenza,
uri
) sono univoci. Utilizza display_name
per identificare i file solo se
gestisci personalmente l'univocità.
file = genai.get_file(name=sample_file.name)
print(f"Retrieved file '{file.display_name}' as: {sample_file.uri}")
Genera contenuti utilizzando il file immagine caricato
Dopo aver caricato l'immagine, puoi effettuare richieste GenerateContent
che fanno riferimento a uri
nella risposta (dal caricamento del file o dalla ricezione diretta dei metadati del file).
In questo esempio, crei un prompt che inizia con del testo seguito dal riferimento URI del file caricato:
# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")
response = model.generate_content([sample_file, "Describe the image with a creative description."])
Markdown(">" + response.text)
Eliminare il file immagine
I file vengono eliminati automaticamente dopo 48 ore. Puoi anche eliminarli manualmente utilizzando files.delete
tramite l'SDK.
genai.delete_file(sample_file.name)
print(f'Deleted {sample_file.display_name}.')
Prompt con video
In questo tutorial, carichi un video di esempio utilizzando l'API File e quindi lo utilizzerai per generare contenuti.
Carica un file video
L'API Gemini accetta direttamente i formati file video. Questo esempio usa il cortometraggio "Big Buck Bunny".
"Big Buck Bunny" è (c) copyright 2008, Mergeer Foundation / www.bigbuckbunny.org e concesso in licenza ai sensi della licenza Creative Commons Attribution 3.0.
Per informazioni su come caricare il tuo file, consulta la sezione Appendice.
Prepara il file video di esempio per il caricamento:
wget https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4
Carica il file utilizzando
media.upload
in modo da potervi accedere con altre chiamate API:video_file_name = "BigBuckBunny_320x180.mp4" print(f"Uploading file...") video_file = genai.upload_file(path=video_file_name) print(f"Completed upload: {video_file.uri}")
Verificare lo stato di caricamento del file video
Verifica che l'API abbia caricato correttamente il file video chiamando il metodo files.get
tramite l'SDK.
I file video hanno un campo State
dell'API File. Quando un video viene caricato, sarà nello stato PROCESSING
fino a quando non sarà pronto per l'inferenza. Per l'inferenza del modello possono essere utilizzati
solo ACTIVE
file.
import time
while video_file.state.name == "PROCESSING":
print('.', end='')
time.sleep(10)
video_file = genai.get_file(video_file.name)
if video_file.state.name == "FAILED":
raise ValueError(video_file.state.name)
Ottieni i metadati del file video
Puoi recuperare i metadati del file video caricato in qualsiasi momento chiamando il metodo files.get
tramite l'SDK.
Questo metodo ti consente di ottenere i metadati per un file caricato associato al progetto Google Cloud collegato alla tua chiave API. Solo i valori name
(e, di conseguenza,
uri
) sono univoci. Utilizza display_name
per identificare i file solo se
gestisci personalmente l'univocità.
file = genai.get_file(name=video_file.name)
print(f"Retrieved file '{file.display_name}' as: {video_file.uri}")
Genera contenuti utilizzando il file video caricato
Dopo aver caricato il video, puoi effettuare richieste GenerateContent
che fanno riferimento al valore uri
nella risposta (dal caricamento del file o dalla ricezione diretta dei metadati del file).
Assicurati di aver verificato lo stato di caricamento del file video (sezione sopra) prima di eseguire l'inferenza sul video.
# Create the prompt.
prompt = "Describe this video."
# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")
# Make the LLM request.
print("Making LLM inference request...")
response = model.generate_content([video_file, prompt],
request_options={"timeout": 600})
print(response.text)
Eliminare il file video
I file vengono eliminati automaticamente dopo 48 ore. Puoi anche eliminarli manualmente utilizzando files.delete
tramite l'SDK.
genai.delete_file(file_response.name)
print(f'Deleted file {file_response.uri}')
Formati di file supportati
I modelli Gemini supportano i prompt con più formati file. Questa sezione illustra le considerazioni sull'utilizzo di formati multimediali generici per i prompt, in particolare file di immagine, audio, video e di testo normale. Puoi utilizzare i file multimediali per la richiesta solo con versioni specifiche del modello, come mostrato nella tabella seguente.
Modello | Immagini | Audio | Video | Testo normale |
---|---|---|---|---|
Gemini 1.5 Pro (release 008 e successive) | ✔ (file immagine massimo 3600) | ✔ | ✔ | ✔ |
Formati dell'immagine
Puoi utilizzare i dati immagine per i prompt con i modelli Gemini 1.5. Quando utilizzi immagini per i prompt, queste sono soggette alle limitazioni e ai requisiti seguenti:
- Le immagini devono essere in uno dei seguenti tipi MIME di dati immagine:
- PNG - immagine/png
- JPEG: immagine/jpeg
- WEBP - immagine/webp
- HEIC - immagine/heic
- HEIF - immagine/heif
- Massimo 3600 immagini per i modelli Gemini 1.5.
- Non ci sono limiti specifici al numero di pixel in un'immagine; tuttavia, le immagini più grandi vengono ridimensionate per adattarsi a una risoluzione massima di 3072 x 3072 mantenendo le proporzioni originali.
Formati audio
Puoi utilizzare i dati audio per i prompt con i modelli Gemini 1.5. Quando utilizzi l'audio per i prompt, questi sono soggetti alle limitazioni e ai requisiti seguenti:
- I dati audio sono supportati nel seguente formato audio comune tipi MIME:
- WAV: audio/wav
- MP3: audio/mp3
- AIFF - audio/aiff
- AAC: audio/aac
- OGG Vorbis - audio/ogg
- FLAC: audio/flac
- La durata massima supportata dei dati audio in un singolo prompt è 9,5 ore.
- I file audio vengono ricampionati a una risoluzione dati di 16 Kbps e più canali audio vengono combinati in un unico canale.
- Non esiste un limite specifico al numero di file audio in un singolo prompt; tuttavia, la durata totale combinata di tutti i file audio in un singolo prompt non può superare le 9,5 ore.
Formati video
Puoi utilizzare i dati video per i prompt con i modelli Gemini 1.5.
I dati video sono supportati nel seguente formato video comune tipi MIME:
- video/mp4
- video/mpeg
- video/mov
- video/avi
- video/x-flv
- video/mpg
- video/webm
- video/wmv
- video/3Gpp
Il servizio File API campiona i video in immagini a 1 frame al secondo (f/s) e può essere soggetto a modifiche per fornire la migliore qualità di inferenza. Le singole immagini occupano 258 token indipendentemente da risoluzione e qualità.
Formati di testo normale
L'API File supporta il caricamento di file di testo normale con i seguenti tipi MIME:
- testo/normale
- text/html
- text/css
- text/javascript
- application/x-javascript
- text/x-typescript
- application/x-typescript
- testo/csv
- testo/markdown
- text/x-python
- application/x-python-code
- application/json
- text/xml
- applicazione/rtf
- testo/rtf
Per i file di testo normale con un tipo MIME non presente nell'elenco, puoi provare a specificare manualmente uno dei tipi MIME precedenti.
Appendice: caricamento di file su Colab
Questo blocco note utilizza l'API File con i file scaricati da internet. Se esegui questa operazione in Colab e vuoi utilizzare i tuoi file, devi prima caricarli nell'istanza Colab.
Innanzitutto, fai clic su File nella barra laterale a sinistra, poi sul pulsante Carica:
Successivamente, devi caricare il file nell'API File. Nel modulo per la cella di codice riportata di seguito, inserisci il nome del file caricato e fornisci un nome visualizzato appropriato per il file, quindi esegui la cella.
my_filename = "gemini_logo.png" # @param {type:"string"}
my_file_display_name = "Gemini Logo" # @param {type:"string"}
my_file = genai.upload_file(path=my_filename,
display_name=my_file_display_name)
print(f"Uploaded file '{my_file.display_name}' as: {my_file.uri}")