Esplora le funzionalità di visione con l'API Gemini

Visualizza su ai.google.dev Provare un notebook di Colab Visualizzare il notebook su GitHub

I modelli Gemini sono in grado di elaborare immagini e video, consentendo molti casi d'uso per sviluppatori di frontiera che in passato avrebbero richiesto modelli specifici per il dominio. Alcune delle funzionalità di visione di Gemini includono la possibilità di:

  • Aggiungere didascalie e rispondere a domande sulle immagini
  • Trascrivere e ragionare sui PDF, inclusi fino a 2 milioni di token
  • Descrivere, segmentare ed estrarre informazioni da video con una durata massima di 90 minuti
  • Rileva gli oggetti in un'immagine e restituisci le coordinate dei relativi riquadri di delimitazione

Gemini è stato progettato da zero per essere multimodale e continuiamo a spingere i confini di ciò che è possibile.

Input di immagini

Per un payload totale delle immagini inferiore a 20 MB, ti consigliamo di caricare immagini codificate in base64 o direttamente i file immagine archiviati localmente.

Lavorare con le immagini locali

Se utilizzi la libreria di imaging di Python (Pillow ), puoi utilizzare anche gli oggetti immagine PIL.

from google import genai
from google.genai import types

import PIL.Image

image = PIL.Image.open('/path/to/image.png')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=["What is this image?", image])

print(response.text)

Immagini con codifica Base64

Puoi caricare gli URL delle immagini pubbliche codificandoli come payload Base64. L'esempio di codice seguente mostra come eseguire questa operazione utilizzando solo gli strumenti della libreria standard:

from google import genai
from google.genai import types

import requests

image_path = "https://goo.gle/instrument-img"
image = requests.get(image_path)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What is this image?",
              types.Part.from_bytes(image.content, "image/jpeg")])

print(response.text)

Più immagini

Per visualizzare più immagini, puoi fornirle nella chiamata a generate_content. Possono essere in qualsiasi formato supportato, incluso base64 o PIL.

from google import genai
from google.genai import types

import pathlib
import PIL.Image

image_path_1 = "path/to/your/image1.jpeg"  # Replace with the actual path to your first image
image_path_2 = "path/to/your/image2.jpeg" # Replace with the actual path to your second image

image_url_1 = "https://goo.gle/instrument-img" # Replace with the actual URL to your third image

pil_image = PIL.Image.open(image_path_1)

b64_image = types.Part.from_bytes(
    pathlib.Path(image_path_2).read_bytes(), "image/jpeg")

downloaded_image = requests.get(image_url_1)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What do these images have in common?",
              pil_image, b64_image, downloaded_image])

print(response.text)

Tieni presente che queste chiamate di dati in linea non includono molte delle funzionalità disponibili tramite l'API File, ad esempio l'ottenimento dei metadati dei file, la loro elencazione o l'eliminazione.

Caricamenti di immagini di grandi dimensioni

Quando la combinazione di file e istruzioni di sistema che intendi inviare ha dimensioni superiori a 20 MB, utilizza l'API File per caricare i file.

Utilizza il metodo media.upload dell'API File per caricare un'immagine di qualsiasi dimensione.

Dopo aver caricato il file, puoi effettuare richieste GenerateContent che fanno riferimento all'URI dell'API File. Seleziona il modello generativo e fornisci un prompt di testo e l'immagine caricata.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

img_path = "/path/to/Cajun_instruments.jpg"
file_ref = client.files.upload(path=img_path)
print(f'{file_ref=}')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What can you tell me about these instruments?",
              file_ref])

print(response.text)

Compatibilità con OpenAI

Puoi accedere alle funzionalità di comprensione delle immagini di Gemini utilizzando le librerie OpenAI. In questo modo puoi integrare Gemini nei flussi di lavoro OpenAI esistenti aggiornando tre righe di codice e utilizzando la tua chiave API Gemini. Consulta l'esempio di comprensione delle immagini per il codice che mostra come inviare immagini codificate come payload Base64.

Prompt con immagini

In questo tutorial caricherai le immagini utilizzando l'API File o come dati in linea e genererai contenuti in base a queste immagini.

Dettagli tecnici (immagini)

Gemini 1.5 Pro e 1.5 Flash supportano un massimo di 3600 file immagine.

Le immagini devono essere in uno dei seguenti tipi MIME di dati delle immagini:

  • PNG - image/png
  • JPEG - image/jpeg
  • WEBP - image/webp
  • HEIC - image/heic
  • HEIF - image/heif

Token

Ecco come vengono calcolati i token per le immagini:

  • Gemini 1.0 Pro Vision: ogni immagine corrisponde a 258 token.
  • Gemini 1.5 Flash e Gemini 1.5 Pro: se entrambe le dimensioni di un'immagine sono inferiori o uguali a 384 pixel, vengono utilizzati 258 token. Se una dimensione di un'immagine è superiore a 384 pixel, l'immagine viene ritagliata in riquadri. Per ogni dimensione del riquadro viene utilizzata per impostazione predefinita la dimensione più piccola (larghezza o altezza) divisa per 1,5. Se necessario, ogni riquadro viene modificato in modo che non sia più piccolo di 256 pixel e non più grande di 768 pixel. Ogni riquadro viene quindi ridimensionato in 768 x 768 e utilizza 258 token.
  • Gemini 2.0 Flash: gli input immagine con entrambe le dimensioni <=384 pixel vengono conteggiati come 258 token. Le immagini più grandi in una o entrambe le dimensioni vengono ritagliate e ridimensionate in base alle esigenze in riquadri di 768 x 768 pixel, ciascuno conteggiato come 258 token.

Per risultati ottimali

  • Ruota le immagini con l'orientamento corretto prima del caricamento.
  • Evita immagini sfocate.
  • Se utilizzi una singola immagine, posiziona il prompt di testo dopo l'immagine.

Funzionalità

Questa sezione illustra le funzionalità di visione specifiche del modello Gemini, tra cui il rilevamento degli oggetti e le coordinate del riquadro di delimitazione.

Ottenere una casella delimitante per un oggetto

I modelli Gemini sono addestrati a restituire le coordinate del riquadro di delimitazione come larghezze o altezze relative nell'intervallo [0, 1]. Questi valori vengono poi scalati per 1000 e convertiti in numeri interi. In pratica, le coordinate rappresentano il riquadro di delimitazione su una versione dell'immagine di 1000 x 1000 pixel. Pertanto, dovrai ripristinare queste coordinate alle dimensioni dell'immagine originale per mappare con precisione i riquadri delimitanti.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

prompt = (
  "Return a bounding box for each of the objects in this image "
  "in [ymin, xmin, ymax, xmax] format.")

response = client.models.generate_content(
  model="gemini-1.5-pro",
  contents=[sample_file_1, prompt])

print(response.text)

Puoi utilizzare i riquadri di delimitazione per il rilevamento e la localizzazione degli oggetti all'interno di immagini e video. Identificando e delineando con precisione gli oggetti con le caselle delimitanti, puoi accedere a una vasta gamma di applicazioni e migliorare l'efficacia dei tuoi progetti.

Vantaggi principali

  • Semplice: integra facilmente le funzionalità di rilevamento degli oggetti nelle tue applicazioni, indipendentemente dalle tue competenze in materia di visione artificiale.
  • Personalizzabile: genera riquadri di selezione in base a istruzioni personalizzate (ad es. "Voglio vedere i riquadri di selezione di tutti gli oggetti verdi in questa immagine"), senza dover addestrare un modello personalizzato.

Dettagli tecnici

  • Input: il prompt e le immagini o gli frame video associati.
  • Output: riquadri di delimitazione nel formato [y_min, x_min, y_max, x_max]. L'angolo superior sinistro è l'origine. Gli assi x e y vanno rispettivamente in orizzontale e verticalmente. I valori delle coordinate sono normalizzati in modo da avere come intervallo 0-1000 per ogni immagine.
  • Visualizzazione: gli utenti di AI Studio vedranno le caselle delimitanti tracciate all'interno dell'UI.

Gli sviluppatori Python possono provare il notebook di comprensione spaziale 2D o il notebook sperimentale di indicazione 3D.

Normalizzare le coordinate

Il modello restituisce le coordinate del riquadro di delimitazione nel formato[y_min, x_min, y_max, x_max]. Per convertire queste coordinate normalizzate nelle coordinate in pixel dell'immagine originale:

  1. Dividi ogni coordinata di output per 1000.
  2. Moltiplica le coordinate x per la larghezza dell'immagine originale.
  3. Moltiplica le coordinate Y per l'altezza dell'immagine originale.

Per esplorare esempi più dettagliati di generazione delle coordinate dei riquadri di delimitazione e visualizzarli sulle immagini, ti invitiamo a consultare il nostro esempio di ricetta per il rilevamento degli oggetti.

Prompt con video

In questo tutorial caricherai un video utilizzando l'API File e genererai contenuti in base a queste immagini.

Dettagli tecnici (video)

Gemini 1.5 Pro e Flash supportano fino a circa un'ora di dati video.

Il video deve essere in uno dei seguenti tipi MIME di formato video:

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

Il servizio API File estrae i frame delle immagini dai video a 1 frame al secondo (FPS) e l'audio a 1 Kbps, singolo canale, aggiungendo i timestamp ogni secondo. Questi rapporti sono soggetti a modifiche in futuro per i miglioramenti dell'inferenza.

I singoli frame sono composti da 258 token e l'audio da 32 token al secondo. Con i metadati, ogni secondo di video diventa circa 300 token, il che significa che una finestra contestuale di 1 milione può contenere poco meno di un'ora di video.

Per porre domande sulle posizioni con timestamp, utilizza il formato MM:SS, dove le prime due cifre rappresentano i minuti e le ultime due rappresentano i secondi.

Per ottenere risultati ottimali:

  • Utilizza un video per prompt.
  • Se utilizzi un singolo video, inserisci il prompt di testo dopo il video.

Caricare un file video utilizzando l'API File

L'API File accetta direttamente i formati file video. Questo esempio utilizza il breve film della NASA "Jupiter's Great Red Spot Shrinks and Grows". Crediti: Goddard Space Flight Center (GSFC)/David Ladd (2018).

"La Grande Macchia Rossa di Giove si restringe e si espande" è di dominio pubblico e non mostra persone identificabili. (Linee guida per l'utilizzo di immagini e contenuti multimediali della NASA).

Per prima cosa, recupera il video breve:

wget https://storage.googleapis.com/generativeai-downloads/images/GreatRedSpot.mp4

Carica il video utilizzando l'API File e stampa l'URI.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print("Uploading file...")
video_file = client.files.upload(path="GreatRedSpot.mp4")
print(f"Completed upload: {video_file.uri}")

Verifica il caricamento del file e controlla lo stato

Verifica che l'API abbia ricevuto correttamente i file chiamando il metodo files.get.

import time

# Check whether the file is ready to be used.
while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(1)
    video_file = client.files.get(name=video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

print('Done')

Prompt con video e testo

Una volta che il video caricato è nello stato ACTIVE, puoi inviare richieste GenerateContent che specificano l'URI dell'API File per quel video. Seleziona il modello generativo e fornisci il video caricato e un prompt di testo.

from IPython.display import Markdown

# Pass the video file reference like any other media part.
response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[
        video_file,
        "Summarize this video. Then create a quiz with answer key "
        "based on the information in the video."])

# Print the response, rendering any Markdown
Markdown(response.text)

Fai riferimento ai timestamp nei contenuti

Puoi utilizzare i timestamp del tipo HH:MM:SS per fare riferimento a momenti specifici del video.

prompt = "What are the examples given at 01:05 and 01:19 supposed to show us?"

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

Trascrivere i video e fornire descrizioni visive

I modelli Gemini possono trascrivere e fornire descrizioni visive dei contenuti video elaborando sia la traccia audio sia i fotogrammi visivi. Per le descrizioni visive, il modello campiona il video a una frequenza di 1 frame al secondo. Questa frequenza di campionamento può influire sul livello di dettaglio delle descrizioni, in particolare per i video con immagini in rapida evoluzione.

prompt = (
    "Transcribe the audio from this video, giving timestamps for "
    "salient events in the video. Also provide visual descriptions.")

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

Elenco file

Puoi elencare tutti i file caricati utilizzando l'API File e i relativi URI utilizzando files.list.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print('My files:')
for f in client.files.list():
  print(" ", f'{f.name}: {f.uri}')

Elimina file

I file caricati utilizzando l'API File vengono eliminati automaticamente dopo 2 giorni. Puoi anche eliminarli manualmente utilizzando files.delete.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

# Upload a file
poem_file = client.files.upload(path="poem.txt")

# Files will auto-delete after a period.
print(poem_file.expiration_time)

# Or they can be deleted explicitly.
dr = client.files.delete(name=poem_file.name)

try:
  client.models.generate_content(
      model="gemini-2.0-flash-exp",
      contents=['Finish this poem:', poem_file])
except genai.errors.ClientError as e:
  print(e.code)  # 403
  print(e.status)  # PERMISSION_DENIED
  print(e.message)  # You do not have permission to access the File .. or it may not exist.

Passaggi successivi

Questa guida mostra come caricare file di immagini e video utilizzando l'API File e poi generare output di testo da input di immagini e video. Per saperne di più, consulta le seguenti risorse:

  • Strategie di prompt dei file: l'API Gemini supporta i prompt con dati di testo, immagini, audio e video, noti anche come prompt multimodali.
  • Istruzioni di sistema: le istruzioni di sistema ti consentono di indirizzare il comportamento del modello in base alle tue esigenze e ai tuoi casi d'uso specifici.
  • Indicazioni per la sicurezza: a volte i modelli di IA generativa producono output inaspettati, ad esempio imprecisi, biassati o offensivi. Il post-trattamento e la valutazione umana sono essenziali per limitare il rischio di danni derivanti da questi output.