Poznaj możliwości w zakresie rozpoznawania treści dzięki interfejsowi Gemini API

Wyświetl na stronie ai.google.dev Wypróbuj notatnik Colab Wyświetl notatnik w GitHubie

Modele Gemini potrafią przetwarzać obrazy i filmy, co umożliwia wielu deweloperom wdrażanie innowacyjnych rozwiązań, które w przeszłości wymagały modeli w konkretnej domenie. Gemini może m.in.:

  • Dodawanie podpisów i odpowiadanie na pytania dotyczące obrazów
  • Transkrypcja i rozumowanie na podstawie plików PDF, w tym do 2 milionów tokenów
  • opisywać, dzielić na segmenty i wyodrębniać informacje z filmów o długości do 90 minut;
  • Wykrywanie obiektów na obrazie i zwracanie ich współrzędnych ramki ograniczającej

Gemini został zaprojektowany od podstaw jako multimodalny, a my wciąż przesuwamy granice tego, co możliwe.

Dane wejściowe dotyczące obrazu

W przypadku całkowitego rozmiaru ładunku obrazu poniżej 20 MB zalecamy przesłanie obrazów zakodowanych w formacie base64 lub bezpośrednie przesłanie lokalnie przechowywanych plików z obrazami.

Praca z obrazami lokalnymi

Jeśli używasz biblioteki obrazów Pythona (Pillow ), możesz też używać obiektów obrazu 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)

obrazy zakodowane w formacie Base64,

Możesz przesyłać publiczne adresy URL obrazów, kodując je jako ładunki danych w formacie Base64. Poniższy przykładowy kod pokazuje, jak to zrobić, używając tylko narzędzi standardowej biblioteki:

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)

Wiele obrazów

Aby wyświetlić prompt z większą liczbą obrazów, możesz przesłać wiele obrazów w wywołaniu do funkcji generate_content. Mogą one być w dowolnym obsługiwanym formacie, np. base64 lub 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)

Pamiętaj, że te wywołania danych w ciele wiadomości nie obejmują wielu funkcji dostępnych w interfejsie File API, takich jak pobieranie metadanych plików, wyświetlanie listy czy usuwanie plików.

Duże ładunki obrazów

Jeśli kombinacja plików i instrukcji systemowych, które chcesz wysłać, ma rozmiar większy niż 20 MB, prześlij te pliki za pomocą interfejsu File API.

Aby przesłać obraz o dowolnym rozmiarze, użyj metody media.upload interfejsu File API.

Po przesłaniu pliku możesz wysyłać żądania GenerateContent, które odwołują się do identyfikatora URI interfejsu File API. Wybierz model generatywny i prześlij prompt tekstowy oraz przesłany obraz.

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)

Zgodność z OpenAI

Możesz korzystać z funkcji Gemini dotyczących rozpoznawania obrazów, korzystając z bibliotek OpenAI. Dzięki temu możesz zintegrować Gemini z dotychczasowymi przepływami pracy w OpenAI, aktualizując 3 linie kodu i korzystając z klucza Gemini API. W przykładowym kodzie rozpoznawania obrazu znajdziesz kod, który pokazuje, jak wysyłać obrazy zakodowane jako ładunki danych Base64.

Prompting with images

W tym samouczku przesyłasz obrazy za pomocą interfejsu File API lub jako dane wstawione i generujesz treści na ich podstawie.

Informacje techniczne (obrazy)

Gemini 1.5 Pro i 1.5 Flash obsługują maksymalnie 3600 plików z obrazami.

Obrazy muszą być w jednym z tych typów MIME danych obrazu:

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

Tokeny

Oto sposób obliczania tokenów w przypadku obrazów:

  • Gemini 1.0 Pro Vision: każde zdjęcie to 258 tokenów.
  • Gemini 1.5 Flash i Gemini 1.5 Pro: jeśli oba wymiary obrazu są mniejsze lub równe 384 pikselom, używane jest 258 tokenów. Jeśli jeden z wymiarów obrazu jest większy niż 384 piksele, obraz jest przycinany do formatu kafelkowego. Każdy rozmiar kafelka jest domyślnie ustawiany na podstawie najmniejszego wymiaru (szerokość lub wysokość) podzielonego przez 1,5. W razie potrzeby każda płytka jest dostosowywana tak, aby nie była mniejsza niż 256 pikseli i nie większa niż 768 pikseli. Każda kafelka jest następnie zmieniana na wymiar 768 x 768 i korzysta z 258 tokenów.
  • Gemini 2.0 Flash: dane wejściowe obrazu, których oba wymiary są mniejsze niż 384 piksele, są zliczane jako 258 tokenów. Obrazy większe w jednym lub obu wymiarach są przycinane i w razie potrzeby skalowane do rozmiaru 768 x 768 pikseli. Każdy z nich jest liczony jako 258 tokenów.

Aby uzyskać najlepsze wyniki

  • Przed przesłaniem obróć obrazy w odpowiednią orientację.
  • Unikaj rozmytych obrazów.
  • Jeśli używasz pojedynczego obrazu, umieść prompt tekstowy po obrazie.

Uprawnienia

W tej sekcji opisano konkretne możliwości modelu Gemini w zakresie widzenia, w tym wykrywanie obiektów i współrzędne ramki ograniczającej.

Pobieranie prostokąta ograniczającego obiekt

Modele Gemini są trenowane tak, aby zwracać współrzędne ramki ograniczającej jako względne szerokości lub wysokości w zakresie [0, 1]. Następnie wartości te są przekształcane w liczby całkowite przez pomnożenie przez 1000. Te współrzędne odpowiadają ramce ograniczającej w wersji obrazu o wymiarach 1000 x 1000 pikseli. Dlatego musisz przekształcić te współrzędne z powrotem w wymiary oryginalnego obrazu, aby dokładnie zmapować ramki ograniczające.

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)

Ramki ograniczające możesz używać do wykrywania i lokalizacji obiektów na obrazach oraz w filmach. Dzięki precyzyjnemu identyfikowaniu i oznaczaniu obiektów za pomocą prostokątów ograniczających możesz wykorzystywać wiele aplikacji i ulepszać działanie swoich projektów.

Najważniejsze korzyści

  • Proste: bez względu na to, czy masz doświadczenie w obsłudze technologii widzenia komputerowego, możesz łatwo zintegrować funkcje wykrywania obiektów w swoich aplikacjach.
  • Możliwość dostosowania: generowanie ramek ograniczających na podstawie niestandardowych instrukcji (np. „Chcę zobaczyć ramki ograniczające wszystkich zielonych obiektów na tym obrazie”) bez konieczności trenowania niestandardowego modelu.

Dane techniczne

  • Wejście: prompt i powiązane obrazy lub klatki wideo.
  • Wyjście: ramki ograniczające w formacie [y_min, x_min, y_max, x_max]. Górny lewy róg to punkt początkowy. Osie x i y są odpowiednio poziome i pionowe. Wartości współrzędnych są normalizowane do zakresu 0–1000 w przypadku każdego obrazu.
  • Wizualizacja: użytkownicy AI Studio zobaczą ramki ograniczające narysowane w interfejsie.

Deweloperzy Pythona mogą skorzystać z notatnika 2D do analizy przestrzennej lub eksperymentalnego notatnika 3D do wskazywania.

Normalizowanie współrzędnych

Model zwraca współrzędne ramki ograniczającej w formacie [y_min, x_min, y_max, x_max]. Aby przekonwertować te znormalizowane współrzędne na współrzędne pikseli oryginalnego obrazu:

  1. Podziel każdą współrzędną wyjściową przez 1000.
  2. Pomnóż współrzędną X przez pierwotną szerokość obrazu.
  3. Pomnóż współrzędne y przez pierwotną wysokość obrazu.

Aby zapoznać się ze szczegółowymi przykładami generowania współrzędnych ramki ograniczającej i wizualizacji tych współrzędnych na obrazach, zapoznaj się z przykładem w podręczniku Wykrywanie obiektów.

Prompting with video

W tym samouczku prześlesz film za pomocą interfejsu File API i wygenerujesz treści na podstawie tych obrazów.

Szczegóły techniczne (film)

Gemini 1.5 Pro i Flash obsługują maksymalnie około godziny danych wideo.

Film musi mieć jeden z tych typów MIME:

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

Usługa File API wyodrębnia klatki obrazu z filmów z częstotliwością 1 klatka na sekundę (FPS) i dźwięku z częstotliwością 1 kbps, w jednym kanale, dodając sygnaturę czasową co sekundę. Te stawki mogą ulec zmianie w przyszłości, aby poprawić jakość wnioskowania.

Poszczególne klatki to 258 tokenów, a dźwięk to 32 tokeny na sekundę. Dzięki metadanym każda sekunda filmu staje się około 300 tokenów, co oznacza, że okno kontekstu z 1 mln tokenów może zawierać nieco mniej niż godzinę filmu.

Aby zadawać pytania o lokalizacje z dodatkiem sygnatury czasowej, użyj formatu MM:SS, w którym pierwsze 2 cyfry oznaczają minuty, a ostatnie 2 cyfry – sekundy.

Aby uzyskać najlepsze wyniki:

  • Użyj 1 filmu na prompt.
  • Jeśli używasz jednego filmu, umieść prompt tekstowy po filmie.

Przesyłanie pliku wideo za pomocą interfejsu File API

Interfejs File API akceptuje formaty plików wideo bezpośrednio. W tym przykładzie użyto krótkiego filmu NASA „Jupiter's Great Red Spot Shrinks and Grows” (Wielka Czerwona Plama na Jowiszu kurczy się i powiększa). Źródło: Goddard Space Flight Center (GSFC)/David Ladd (2018).

Film „Jupiter's Great Red Spot Shrinks and Grows” jest w domenie publicznym i nie przedstawia osób, które można zidentyfikować. (wytyczne NASA dotyczące wykorzystania zdjęć i multimediów).

Zacznij od pobrania krótkiego filmu:

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

Prześlij film za pomocą interfejsu File API i wydrukuj identyfikator 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}")

Sprawdzanie przesyłania plików i sprawdzanie stanu

Aby sprawdzić, czy interfejs API otrzymał pliki, wywołaj metodę 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 z filmem i tekstem

Gdy przesłany film znajdzie się w stanie ACTIVE, możesz wysyłać GenerateContentżądania z identyfikatorem URI interfejsu File API tego filmu. Wybierz model generatywny i prześlij do niego przesłany film oraz prompt tekstowy.

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)

odwoływać się do sygnatur czasowych w treściach;

Aby odwoływać się do konkretnych momentów w filmie, możesz używać sygnatur czasowych w formacie HH:MM:SS.

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)

Transkrypcja filmu i dodanie wizualnych opisów

Modele Gemini mogą transkrybować i zapewniać wizualne opisy treści wideo, przetwarzając zarówno ścieżkę audio, jak i ramki wizualne. W przypadku opisów wizualnych model pobiera próbki z filmu z szybkością 1 klatka na sekundę. Ta częstotliwość próbkowania może wpływać na poziom szczegółowości w opisach, zwłaszcza w przypadku filmów z szybko zmieniającymi się obrazami.

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)

Wyświetlanie listy plików

Za pomocą interfejsu File API możesz wyświetlić listę wszystkich plików przesłanych za jego pomocą oraz ich identyfikatory URI za pomocą interfejsu 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}')

Usuwanie plików

Pliki przesłane za pomocą interfejsu File API są automatycznie usuwane po 2 dniach. Możesz je też usunąć ręcznie, korzystając z funkcji 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.

Co dalej?

Z tego przewodnika dowiesz się, jak przesyłać pliki graficzne i wideo za pomocą interfejsu File API, a potem generować tekst na podstawie obrazów i filmów. Więcej informacji znajdziesz w tych materiałach:

  • Strategie wyświetlania promptów dotyczących plików: interfejs Gemini API obsługuje prompty z tekstem, obrazem, dźwiękiem i danymi wideo, które są też nazywane promptami multimodalnymi.
  • Instrukcje systemowe: instrukcje systemowe pozwalają kierować działaniem modelu na podstawie konkretnych potrzeb i przypadków użycia.
  • Wskazówki dotyczące bezpieczeństwa: modele generatywnej AI czasami generują nieoczekiwane wyniki, np. niedokładne, stronnicze lub obraźliwe. Przetwarzanie końcowe i sprawdzanie przez weryfikatorów są niezbędne do ograniczenia ryzyka szkód wynikających z takich danych wyjściowych.