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 bestimmte 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 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.

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 der Eingabetokens für das Kontext-Caching beträgt 1.024 für 2.5 Flash und 2.048 für 2.5 Pro. Der Maximalwert entspricht dem Maximalwert 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 werden dem Prompt vorangestellt.
  • Für das Zwischenspeichern von Kontexten 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.