Kontext-Caching

In einem typischen KI-Workflow übergeben Sie möglicherweise immer wieder dieselben Eingabetokens an ein Modell. Mit der Funktion zum Kontext-Caching der Gemini API können Sie Inhalte einmal an das Modell übergeben, die Eingabe-Tokens im Cache speichern und dann bei nachfolgenden Anfragen auf die im Cache gespeicherten Tokens verweisen. Bei bestimmten Volumina ist die Verwendung von gecachten Tokens kostengünstiger als die wiederholte Weitergabe desselben Token-Korpus.

Wenn Sie eine Reihe von Tokens im Cache speichern, können Sie festlegen, wie lange der Cache vorhanden sein soll, bevor die Tokens automatisch gelöscht werden. Diese Caching-Dauer wird als Gültigkeitsdauer (Time to Live, TTL) bezeichnet. Wenn sie nicht festgelegt ist, wird standardmäßig eine TTL von 1 Stunde verwendet. Die Kosten für das Caching hängen von der Größe des Eingabetokens und davon ab, wie lange die Tokens gespeichert bleiben sollen.

Das Kontext-Caching variiert je nach Modell.

Wann Kontext-Caching verwendet werden sollte

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 Fehlerkorrektur

Kontext-Caching verwenden

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

Inhalte mithilfe eines Caches generieren

Im folgenden Beispiel wird gezeigt, wie Inhalte mit einer im Cache gespeicherten Systemanleitung und Videodatei generiert werden.

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)

PDFs

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. Sie können jedoch 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 Cacheobjekt abrufen möchten und den Namen kennen, verwenden Sie get:

client.caches.get(name=name)

Cache aktualisieren

Sie können für einen Cache eine neue ttl oder expire_time festlegen. Andere Änderungen am Cache werden nicht unterstützt.

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

from google import genai
from google.genai import types

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

Zum Festlegen des Ablaufdatums wird entweder ein datetime-Objekt oder ein im ISO-Format formatierter Datetime-String (dt.isoformat(), z. B. 2025-01-27T16:02:36.473528+00:00) akzeptiert. Die Zeit muss eine Zeitzone enthalten. datetime.utcnow() enthält keine Zeitzone, datetime.now(datetime.timezone.utc) hingegen schon.

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. Im folgenden Beispiel wird gezeigt, wie ein Cache gelöscht wird:

client.caches.delete(cache.name)

So senken Sie mit Caching die Kosten

Kontext-Caching ist eine kostenpflichtige Funktion, mit der sich die Gesamtbetriebskosten senken lassen. Die Abrechnung erfolgt anhand der 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 basierend auf 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 Preisdetails finden Sie auf der Preisseite der Gemini API. Weitere Informationen zum Zählen von Tokens finden Sie im Token-Leitfaden.

Weitere Überlegungen

Beachten Sie bei der Verwendung des Kontext-Cachings Folgendes:

  • Die Mindestanzahl der Eingabetokens für den Kontext-Cache beträgt 4.096 und die Höchstzahl entspricht der Höchstzahl für das jeweilige Modell. Weitere Informationen zum Zählen von Tokens finden Sie im Token-Leitfaden.
  • Das Modell unterscheidet nicht zwischen im Cache gespeicherten und regulären Eingabetokens. Im Cache gespeicherte Inhalte sind ein Präfix für den Prompt.
  • Für das Kontext-Caching gelten keine speziellen Raten- oder Nutzungslimits. Es gelten die Standardratenlimits für GenerateContent. Tokenlimits umfassen auch gecachte Tokens.
  • Die Anzahl der im Cache gespeicherten Tokens wird im usage_metadata von den Vorgängen „create“, „get“ und „list“ des Cache-Dienstes zurückgegeben. Sie wird auch in GenerateContent zurückgegeben, wenn der Cache verwendet wird.