Richiesta di file multimediali


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.

  1. Prepara un'immagine di esempio da caricare:

      curl -o image.jpg https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg

  2. 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.

  1. Prepara il file video di esempio per il caricamento:

    wget https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4

  2. 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}")