Vision-Funktionen mit der Gemini API entdecken

Auf ai.google.dev ansehen Colab-Notebook testen Notebook auf GitHub ansehen

Gemini-Modelle können Bilder und Videos verarbeiten und ermöglichen so viele neue Anwendungsfälle für Entwickler, für die bisher domänenspezifische Modelle erforderlich waren. Zu den Funktionen von Gemini gehören:

  • Bilder mit Bildunterschriften versehen und Fragen zu Bildern beantworten
  • PDFs transkribieren und mit bis zu 2 Millionen Tokens begründen
  • Videos mit einer Länge von bis zu 90 Minuten beschreiben, segmentieren und Informationen daraus extrahieren
  • Objekte in einem Bild erkennen und Begrenzungsrahmenkoordinaten für sie zurückgeben

Gemini wurde von Grund auf als multimodales System entwickelt und wir erweitern kontinuierlich die Grenzen des Möglichen.

Bildeingabe

Wenn die Gesamtnutzlastgröße des Bildes unter 20 MB liegt, empfehlen wir, entweder base64-codierte Bilder oder lokal gespeicherte Bilddateien direkt hochzuladen.

Mit lokalen Images arbeiten

Wenn Sie die Python Imaging Library (Pillow ) verwenden, können Sie auch PIL-Bildobjekte verwenden.

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)

Base64-codierte Bilder

Sie können öffentliche Bild-URLs hochladen, indem Sie sie als Base64-Nutzlast codieren. Im folgenden Codebeispiel wird gezeigt, wie Sie dazu nur Standardbibliothekstools verwenden:

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)

Mehrere Bilder

Wenn Sie einen Prompt mit mehreren Bildern erstellen möchten, können Sie im Aufruf von generate_content mehrere Bilder angeben. Sie können in jedem unterstützten Format vorliegen, einschließlich base64 oder 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)

Diese Inline-Datenaufrufe umfassen nicht viele der Funktionen, die über die File API verfügbar sind, z. B. das Abrufen von Dateimetadaten, das Auflisten oder das Löschen von Dateien.

Große Bildnutzlasten

Wenn die Kombination aus Dateien und Systemanweisungen, die Sie senden möchten, größer als 20 MB ist, verwenden Sie die File API, um diese Dateien hochzuladen.

Verwenden Sie die Methode media.upload der File API, um ein Bild beliebiger Größe hochzuladen.

Nach dem Hochladen der Datei kannst du GenerateContent-Anfragen senden, die auf den URI der File API verweisen. Wählen Sie das generative Modell aus und geben Sie einen Text-Prompt und das hochgeladene Bild an.

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)

Kompatibilität mit OpenAI

Sie können über die OpenAI-Bibliotheken auf die Bilderkennungsfunktionen von Gemini zugreifen. So können Sie Gemini in bestehende OpenAI-Workflows einbinden, indem Sie drei Codezeilen aktualisieren und Ihren Gemini API-Schlüssel verwenden. Im Beispiel für die Bilderkennung finden Sie Code, der veranschaulicht, wie Bilder als Base64-Nutzlast gesendet werden.

Prompts mit Bildern

In dieser Anleitung laden Sie Bilder über die File API oder als Inline-Daten hoch und generieren Inhalte auf Grundlage dieser Bilder.

Technische Details (Bilder)

Gemini 1.5 Pro und 1.5 Flash unterstützen maximal 3.600 Bilddateien.

Bilder müssen einen der folgenden MIME-Typen für Bilddaten haben:

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

Tokens

So werden Tokens für Bilder berechnet:

  • Gemini 1.0 Pro Vision: Jedes Bild berücksichtigt 258 Tokens.
  • Gemini 1.5 Flash und Gemini 1.5 Pro: Wenn beide Abmessungen eines Bildes maximal 384 Pixel haben, werden 258 Tokens verwendet. Wenn eine Dimension eines Bildes größer als 384 Pixel ist, wird das Bild in Kacheln zugeschnitten. Die Größe der einzelnen Kacheln entspricht standardmäßig dem kleinsten Maß (Breite oder Höhe) geteilt durch 1,5. Bei Bedarf wird jede Kachel so angepasst, dass sie nicht kleiner als 256 Pixel und nicht größer als 768 Pixel ist. Jede Kachel wird dann auf 768 × 768 Pixel skaliert und verwendet 258 Token.
  • Gemini 2.0 Flash: Bildeingaben mit beiden Abmessungen von maximal 384 Pixeln werden als 258 Tokens gezählt. Bilder, die in einer oder beiden Dimensionen größer sind, werden bei Bedarf zu Kacheln mit einer Größe von 768 × 768 Pixeln zugeschnitten und skaliert. Sie werden jeweils mit 258 Tokens gezählt.

Für optimale Ergebnisse

  • Drehen Sie die Bilder vor dem Hochladen in die richtige Ausrichtung.
  • Vermeiden Sie unscharfe Bilder.
  • Wenn Sie ein einzelnes Bild verwenden, platzieren Sie den Text-Prompt nach dem Bild.

Leistungsspektrum

In diesem Abschnitt werden bestimmte Funktionen der Bilderkennung des Gemini-Modells beschrieben, einschließlich der Objekterkennung und der Begrenzungsrahmenkoordinaten.

Begrenzungsrahmen für ein Objekt abrufen

Gemini-Modelle sind so trainiert, dass sie Begrenzungsrahmenkoordinaten als relative Breiten oder Höhen im Bereich [0, 1] zurückgeben. Diese Werte werden dann mit 1.000 skaliert und in Ganzzahlen umgewandelt. Die Koordinaten stellen den Begrenzungsrahmen in einer Version des Bilds mit 1.000 x 1.000 Pixeln dar. Daher müssen Sie diese Koordinaten in die Abmessungen des ursprünglichen Bildes umrechnen, um die Begrenzungsrahmen korrekt abzubilden.

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)

Sie können Begrenzungsrahmen für die Objekterkennung und -lokalisierung in Bildern und Videos verwenden. Wenn Sie Objekte mit Begrenzungsrahmen genau identifizieren und abgrenzen, können Sie eine Vielzahl von Anwendungen nutzen und die Intelligenz Ihrer Projekte verbessern.

Hauptvorteile

  • Einfach:Sie können Funktionen zur Objekterkennung ganz einfach in Ihre Anwendungen einbinden, unabhängig von Ihren Kenntnissen im Bereich maschinelles Sehen.
  • Anpassbar:Sie können Begrenzungsrahmen anhand benutzerdefinierter Anweisungen erstellen (z.B. „Ich möchte Begrenzungsrahmen für alle grünen Objekte in diesem Bild sehen“), ohne ein benutzerdefiniertes Modell trainieren zu müssen.

Technische Details

  • Eingabe:Ihr Prompt und die zugehörigen Bilder oder Videoframes.
  • Ausgabe:Begrenzungsrahmen im [y_min, x_min, y_max, x_max]-Format. Die linke obere Ecke ist der Ursprung. Die x- und y-Achse verlaufen horizontal bzw. vertikal. Die Koordinatenwerte werden für jedes Bild auf 0–1.000 normalisiert.
  • Visualisierung:AI Studio-Nutzer sehen Begrenzungsboxen, die in der Benutzeroberfläche dargestellt werden.

Python-Entwickler können das Notebook für die 2D-räumliche Wahrnehmung oder das experimentelle Notebook für die 3D-Gesteingabe ausprobieren.

Koordinaten normalisieren

Das Modell gibt Begrenzungsrahmenkoordinaten im Format [y_min, x_min, y_max, x_max] zurück. So wandeln Sie diese normalisierten Koordinaten in die Pixelkoordinaten des Originalbilds um:

  1. Dividieren Sie jede Ausgabekoordinate durch 1.000.
  2. Multiplizieren Sie die X-Koordinaten mit der Breite des Originalbilds.
  3. Multiplizieren Sie die y-Koordinaten mit der Höhe des Originalbilds.

Ausführlichere Beispiele zum Generieren von Begrenzungsrahmenkoordinaten und zum Visualisieren in Bildern finden Sie in unserem Rezeptbuchbeispiel für die Objekterkennung.

Prompts mit Video

In dieser Anleitung laden Sie ein Video mit der File API hoch und generieren Inhalte anhand der Bilder.

Technische Details (Video)

Gemini 1.5 Pro und Flash unterstützen bis zu etwa eine Stunde Videodaten.

Das Video muss einen der folgenden MIME-Typen für Videoformate haben:

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

Der File API-Dienst extrahiert Bildframes aus Videos mit 1 Frame pro Sekunde (FPS) und Audio mit 1 Kbit/s, einzelner Kanal, und fügt jede Sekunde Zeitstempel hinzu. Diese Preise können sich in Zukunft ändern, wenn die Inferenz verbessert wird.

Einzelne Frames umfassen 258 Token und Audio 32 Token pro Sekunde. Mithilfe von Metadaten entspricht jede Videosekunde etwa 300 Tokens. Das bedeutet, dass in einem Kontextfenster mit einer Million Tokens etwas weniger als eine Stunde Video passen.

Wenn Sie Fragen zu Standorten mit Zeitstempel stellen möchten, verwenden Sie das Format MM:SS. Die ersten beiden Ziffern stehen dabei für Minuten und die letzten beiden für Sekunden.

Für optimale Ergebnisse:

  • Verwenden Sie ein Video pro Prompt.
  • Wenn Sie nur ein Video verwenden, platzieren Sie den Textprompt nach dem Video.

Videodatei mit der File API hochladen

Die File API akzeptiert Videodateiformate direkt. In diesem Beispiel wird der kurze NASA-Film „Jupiter's Great Red Spot Shrinks and Grows“ (Der Große Rote Fleck des Jupiters schrumpft und wächst) verwendet. Quelle: Goddard Space Flight Center (GSFC)/David Ladd (2018).

„Jupiter's Great Red Spot Shrinks and Grows“ ist gemeinfrei und zeigt keine erkennbaren Personen. (Richtlinien für die Nutzung von NASA-Bildern und -Medien)

Rufen Sie zuerst das Kurzvideo ab:

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

Lade das Video mit der File API hoch und drucke den URI aus.

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

Dateiupload und Status prüfen

Prüfen Sie, ob die API die Dateien erfolgreich empfangen hat, indem Sie die Methode files.get aufrufen.

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 mit Video und Text

Sobald sich das hochgeladene Video im Status ACTIVE befindet, kannst du GenerateContent-Anfragen stellen, in denen der File API-URI für das Video angegeben ist. Wählen Sie das generative Modell aus und stellen Sie ihm das hochgeladene Video und einen Text-Prompt zur Verfügung.

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)

Zeitstempel in den Inhalten

Mit Zeitstempeln vom Typ HH:MM:SS kannst du auf bestimmte Momente im Video verweisen.

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)

Video transkribieren und visuelle Beschreibungen hinzufügen

Die Gemini-Modelle können Videoinhalte transkribieren und visuelle Beschreibungen liefern, indem sie sowohl den Audiotrack als auch die visuellen Frames verarbeiten. Bei visuellen Beschreibungen wird das Video vom Modell mit einer Rate von 1 Frame pro Sekunde abgetastet. Diese Abtastrate kann sich auf den Detaillierungsgrad der Beschreibungen auswirken, insbesondere bei Videos mit sich schnell ändernden Bildern.

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)

Dateien auflisten

Mit files.list können Sie alle mit der File API hochgeladenen Dateien und ihre URIs auflisten.

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}')

Dateien löschen

Dateien, die mit der File API hochgeladen wurden, werden nach zwei Tagen automatisch gelöscht. Sie können sie auch manuell mit files.delete löschen.

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.

Nächste Schritte

In diesem Leitfaden wird gezeigt, wie Sie Bild- und Videodateien mit der File API hochladen und dann Textausgaben aus Bild- und Videoinputs generieren. Weitere Informationen finden Sie in den folgenden Ressourcen:

  • Strategien für Prompts aus Dateien: Die Gemini API unterstützt Prompts mit Text-, Bild-, Audio- und Videodaten, auch als multimodale Prompts bezeichnet.
  • Systemanweisungen: Mit Systemanweisungen können Sie das Verhalten des Modells entsprechend Ihren spezifischen Anforderungen und Anwendungsfällen steuern.
  • Sicherheitshinweise: Manchmal liefern generative KI-Modelle unerwartete Ergebnisse, z. B. fehlerhafte, voreingenommene oder anstößige Ergebnisse. Eine Nachbearbeitung und eine menschliche Bewertung sind unerlässlich, um das Risiko von Schäden durch solche Ausgaben zu begrenzen.