Kontext-Caching

In einem typischen KI-Workflow werden dieselben Eingabetokens möglicherweise immer wieder an ein Modell übergeben. Die Gemini API bietet zwei verschiedene Caching-Mechanismen:

  • Implizites Caching (automatisch für Gemini 2.5-Modelle aktiviert, keine Garantie für Kosteneinsparungen)
  • Explizites Caching (kann bei den meisten Modellen manuell aktiviert werden, Kosteneinsparungsgarantie)

Explizites Caching ist nützlich, wenn Sie Kosten sparen möchten, aber dafür etwas mehr Entwicklerarbeit in Kauf nehmen.

Implizites Caching

Implizites Caching ist standardmäßig für alle Gemini 2.5-Modelle aktiviert. Wir geben Kosteneinsparungen automatisch weiter, wenn Ihre Anfrage auf Caches trifft. Sie müssen nichts weiter tun, um diese Funktion zu aktivieren. Sie tritt am 8. Mai 2025 in Kraft. Die Mindestanzahl von Eingabetokens für das Kontext-Caching beträgt 1.024 für 2.5 Flash und 4.096 für 2.5 Pro.

So erhöhen Sie die Wahrscheinlichkeit eines impliziten Cache-Treffers:

  • Große und gängige Inhalte am Anfang des Prompts platzieren
  • Versuchen Sie, Anfragen mit ähnlichem Präfix innerhalb kurzer Zeit zu senden.

Die Anzahl der Tokens, die Cache-Treffer waren, finden Sie im Feld usage_metadata des Antwortobjekts.

Explizites Caching

Mit der Funktion zum expliziten Caching der Gemini API können Sie einige Inhalte einmal an das Modell übergeben, die Eingabetokens im Cache speichern und dann bei nachfolgenden Anfragen auf die im Cache gespeicherten Tokens verweisen. Bei bestimmten Mengen ist die Verwendung von zwischengespeicherten Tokens kostengünstiger als die wiederholte Übergabe derselben Menge an Tokens.

Wenn Sie eine Reihe von Tokens im Cache speichern, können Sie festlegen, wie lange der Cache bestehen soll, bevor die Tokens automatisch gelöscht werden. Diese Caching-Dauer wird als Gültigkeitsdauer (time to live, TTL) bezeichnet. Wenn nichts anderes festgelegt ist, beträgt der TTL-Wert standardmäßig 1 Stunde. Die Kosten für das Caching hängen von der Größe der Eingabetokens und der Dauer ab, für die die Tokens beibehalten werden sollen.

In diesem Abschnitt wird davon ausgegangen, dass Sie ein Gemini SDK installiert haben (oder curl installiert ist) und dass Sie einen API-Schlüssel konfiguriert haben, wie in der Kurzanleitung beschrieben.

Inhalte mit einem Cache generieren

Im folgenden Beispiel wird gezeigt, wie Sie Inhalte mit einer im Cache gespeicherten Systemanweisung und Videodatei generieren.

Videos

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

client = genai.Client()

# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
  with path_to_video_file.open('wb') as wf:
    response = requests.get(url, stream=True)
    for chunk in response.iter_content(chunk_size=32768):
      wf.write(chunk)

# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)

# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
  print('Waiting for video to be processed.')
  time.sleep(2)
  video_file = client.files.get(name=video_file.name)

print(f'Video processing complete: {video_file.uri}')

# You must use an explicit version suffix: "-flash-001", not just "-flash".
model='models/gemini-2.0-flash-001'

# Create a cache with a 5 minute TTL
cache = client.caches.create(
    model=model,
    config=types.CreateCachedContentConfig(
      display_name='sherlock jr movie', # used to identify the cache
      system_instruction=(
          'You are an expert video analyzer, and your job is to answer '
          'the user\'s query based on the video file you have access to.'
      ),
      contents=[video_file],
      ttl="300s",
  )
)

# Construct a GenerativeModel which uses the created cache.
response = client.models.generate_content(
  model = model,
  contents= (
    'Introduce different characters in the movie by describing '
    'their personality, looks, and names. Also list the timestamps '
    'they were introduced for the first time.'),
  config=types.GenerateContentConfig(cached_content=cache.name)
)

print(response.usage_metadata)

# The output should look something like this:
#
# prompt_token_count: 696219
# cached_content_token_count: 696190
# candidates_token_count: 214
# total_token_count: 696433

print(response.text)

PDF-Dateien

from google import genai
from google.genai import types
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"

# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

document = client.files.upload(
  file=doc_io,
  config=dict(mime_type='application/pdf')
)

model_name = "gemini-2.0-flash-001"
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
      system_instruction=system_instruction,
      contents=[document],
    )
)

# Display the cache details
print(f'{cache=}')

# Generate content using the cached prompt and document
response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

# (Optional) Print usage metadata for insights into the API call
print(f'{response.usage_metadata=}')

# Print the generated text
print('\n\n', response.text)

Caches auflisten

Es ist nicht möglich, im Cache gespeicherte Inhalte abzurufen oder anzusehen, aber Sie können Cache-Metadaten (name, model, display_name, usage_metadata, create_time, update_time und expire_time) abrufen.

Verwenden Sie CachedContent.list(), um Metadaten für alle hochgeladenen Caches aufzulisten:

for cache in client.caches.list():
  print(cache)

Wenn Sie die Metadaten für ein Cache-Objekt abrufen möchten und den Namen des Objekts kennen, verwenden Sie get:

client.caches.get(name=name)

Cache aktualisieren

Sie können für einen Cache ein neues ttl oder expire_time festlegen. Das Ändern anderer Cache-Einstellungen wird nicht unterstützt.

Das folgende Beispiel zeigt, wie Sie die ttl eines Caches mit client.caches.update() aktualisieren.

from google import genai
from google.genai import types

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      ttl='300s'
  )
)

Zum Festlegen der Ablaufzeit kann entweder ein datetime-Objekt oder ein ISO-formatierter Datetime-String (dt.isoformat(), z. B. 2025-01-27T16:02:36.473528+00:00) verwendet werden. Ihre Zeit muss eine Zeitzone enthalten (datetime.utcnow() fügt keine Zeitzone an, datetime.now(datetime.timezone.utc) fügt eine Zeitzone an).

from google import genai
from google.genai import types
import datetime

# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      expire_time=in10min
  )
)

Cache löschen

Der Caching-Dienst bietet einen Löschvorgang zum manuellen Entfernen von Inhalten aus dem Cache. Das folgende Beispiel zeigt, wie ein Cache gelöscht wird:

client.caches.delete(cache.name)

Explizites Caching mit der OpenAI-Bibliothek

Wenn Sie eine OpenAI-Bibliothek verwenden, können Sie das explizite Caching mit der Eigenschaft cached_content für extra_body aktivieren.

Wann sollte explizites Caching verwendet werden?

Kontext-Caching eignet sich besonders für Szenarien, bei denen in kürzeren Anfragen wiederholt auf eine hohe anfängliche Kontextmenge verwiesen wird. Ziehen Sie die Verwendung von Kontext-Caching für Anwendungsfälle wie diese in Betracht:

  • Chatbots mit ausführlichen Systemanweisungen
  • Wiederholte Analyse langer Videodateien
  • Wiederkehrende Abfragen großer Dokumentgruppen
  • Häufige Analyse des Code-Repositorys oder Fehlerbehebung

So werden Kosten durch explizites Caching gesenkt

Das Kontext-Caching ist eine kostenpflichtige Funktion, die die Gesamtbetriebskosten senken soll. Die Abrechnung basiert auf den folgenden Faktoren:

  1. Anzahl der Cache-Tokens: Die Anzahl der im Cache gespeicherten Eingabetokens, für die ein ermäßigter Tarif für die Nutzung in nachfolgenden Prompts gilt.
  2. Speicherdauer: Die Zeit, über die hinweg im Cache gespeicherte Tokens erhalten werden (TTL). Die Abrechnung erfolgt auf Grundlage der TTL-Dauer der Anzahl der im Cache gespeicherten Tokens. Es gibt keine Mindest- oder Höchstwerte für die TTL.
  3. Andere Faktoren: Es fallen weitere Gebühren an, z. B. für nicht im Cache gespeicherte Eingabe- und Ausgabetokens.

Aktuelle Preisinformationen finden Sie auf der Preisseite für die Gemini API. Informationen zum Zählen von Tokens finden Sie im Token-Leitfaden.

Weitere Überlegungen

Beachten Sie bei der Verwendung von Kontext-Caching Folgendes:

  • Die Mindestanzahl von Eingabetokens für das Kontext-Caching beträgt 1.024 für 2.5 Flash und 2.048 für 2.5 Pro. Das Maximum ist dasselbe wie das Maximum für das angegebene Modell. Weitere Informationen zum Zählen von Tokens finden Sie im Token-Leitfaden.
  • Das Modell unterscheidet nicht zwischen zwischengespeicherten und regulären Eingabetokens. Im Cache gespeicherte Inhalte sind ein Präfix für den Prompt.
  • Für das Kontext-Caching gelten keine besonderen Raten- oder Nutzungslimits. Es gelten die Standardratenlimits für GenerateContent und die Tokenlimits umfassen zwischengespeicherte Tokens.
  • Die Anzahl der im Cache gespeicherten Tokens wird in usage_metadata aus den Vorgängen „create“, „get“ und „list“ des Cache-Dienstes zurückgegeben sowie in GenerateContent, wenn der Cache verwendet wird.