Gemini Explizites Caching (cachedContents)

Gemini bietet zwei Arten von Caching:

• Implizites Caching (automatisch) — Das Modell erkennt und verwendet wiederholte Prompt-Präfixe automatisch wieder, ohne jede Konfiguration. Das ist das Standardverhalten, das unter Prompt-Caching beschrieben wird; Treffer erfolgen nach dem Best-Effort-Prinzip, und jede kleine Änderung am Präfix kann zu einem Fehlschlag führen.
• Explizites Caching (diese Seite) — Sie erstellen aktiv einen großen Kontextabschnitt als Cache-Objekt, erhalten ein cachedContents/{id}-Handle zurück und referenzieren es in nachfolgenden generateContent-Anfragen. Treffer sind deterministisch: Solange der Cache nicht abgelaufen ist, trifft eine Referenz immer.

Verwenden Sie explizites Caching, wenn Sie einen großen, stabilen Kontext haben, der wiederholt verwendet wird (lange Dokumente, Codebasen, Wissensdatenbanken, feste System-Anweisungen) und steuerbare Trefferquoten sowie vorhersehbare Abrechnung wünschen.

Wann explizites Caching verwenden

Endpunkte

OfoxAI stellt die vollständigen cachedContents-Endpunkte unter dem Gemini-nativen Protokoll bereit:

POST   https://api.ofox.ai/gemini/v1beta/cachedContents              # Erstellen
GET    https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Abfragen
DELETE https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Löschen

Um einen Cache für die Inhaltsgenerierung zu referenzieren, verwenden Sie den Standard-generateContent-Endpunkt und fügen cachedContent zum Anfrage-Body hinzu:

POST   https://api.ofox.ai/gemini/v1beta/models/{model}:generateContent

Authentifizierung

Wie bei anderen Gemini-Endpunkten verwenden Sie den x-goog-api-key-Header:

x-goog-api-key: <Ihr OFOXAI_API_KEY>

Vollständiger Ablauf

Im Folgenden wird ein vollständiger Ablauf gezeigt: Cache erstellen → Cache zur Generierung referenzieren → Cache löschen.

1. Cache erstellen

Legen Sie den großen Kontext, den Sie wiederverwenden möchten, in contents und geben Sie model und ttl (Lebensdauer) an:

from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<Ihr OFOXAI_API_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
# Ein großes Dokument, das wiederholt verwendet wird (muss den Mindest-Token-Schwellenwert erreichen)
LONG_DOCUMENT = open("knowledge_base.txt").read()
 
cache = client.caches.create(
    model="google/gemini-3.1-pro-preview",
    config=types.CreateCachedContentConfig(
        contents=[LONG_DOCUMENT],
        ttl="600s",  # Cache lebt 10 Minuten
    ),
)
 
print(cache.name)  # cachedContents/xxxxxxxx — das Handle für spätere Referenzen

import { GoogleGenAI } from '@google/genai'
import fs from 'node:fs'
 
const ai = new GoogleGenAI({
  apiKey: '<Ihr OFOXAI_API_KEY>',
  httpOptions: { apiVersion: 'v1beta', baseUrl: 'https://api.ofox.ai/gemini' },
})
 
const longDocument = fs.readFileSync('knowledge_base.txt', 'utf-8')
 
const cache = await ai.caches.create({
  model: 'google/gemini-3.1-pro-preview',
  config: {
    contents: [longDocument],
    ttl: '600s', // Cache lebt 10 Minuten
  },
})
 
console.log(cache.name) // cachedContents/xxxxxxxx — das Handle für spätere Referenzen

curl "https://api.ofox.ai/gemini/v1beta/cachedContents" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-pro-preview",
    "contents": [
      { "role": "user", "parts": [{ "text": "<ein großer Kontextblock zur Wiederverwendung>" }] }
    ],
    "ttl": "600s"
  }'

Der zurückgegebene name (z. B. cachedContents/xxxxxxxx) ist das Cache-Handle. Speichern Sie es für spätere Referenzen und die Verwaltung.

2. Cache zur Generierung referenzieren

Referenzieren Sie das Cache-Handle über cachedContent in einer generateContent-Anfrage; contents muss nur die neue Frage für diesen Schritt enthalten:

response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="Fassen Sie auf Basis des obigen Dokuments drei Kernpunkte zusammen",
    config=types.GenerateContentConfig(
        cached_content=cache.name,  # Cache referenzieren
    ),
)
 
print(response.text)
# Cache-Treffer: Der gecachte Anteil wird zum niedrigeren „Read"-Tarif berechnet
print(response.usage_metadata.cached_content_token_count)

const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: 'Fassen Sie auf Basis des obigen Dokuments drei Kernpunkte zusammen',
  config: {
    cachedContent: cache.name, // Cache referenzieren
  },
})
 
console.log(response.text)
// Cache-Treffer: Der gecachte Anteil wird zum niedrigeren „Read"-Tarif berechnet
console.log(response.usageMetadata?.cachedContentTokenCount)

curl "https://api.ofox.ai/gemini/v1beta/models/google/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cachedContent": "cachedContents/xxxxxxxx",
    "contents": [
      { "role": "user", "parts": [{ "text": "Fassen Sie auf Basis des obigen Dokuments drei Kernpunkte zusammen" }] }
    ]
  }'

Bei einem Treffer zeigt usageMetadata.cachedContentTokenCount in der Antwort, wie viele Tokens aus dem Cache stammen. Derselbe Cache kann beliebig oft referenziert werden, jedes Mal ein deterministischer Treffer, bis er abläuft.

3. Abfragen und Löschen

Cache-Metadaten abfragen oder bei Bedarf proaktiv löschen (ohne auf den Ablauf der TTL zu warten):

# Abfragen
info = client.caches.get(name=cache.name)
print(info.expire_time)
 
# Löschen
client.caches.delete(name=cache.name)

// Abfragen
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// Löschen
await ai.caches.delete({ name: cache.name })

# Abfragen
curl "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"
 
# Löschen
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

Lebenszyklus und TTL

Geben Sie bei der Erstellung über ttl eine Lebensdauer an, als Sekunden-String mit s-Endung (z. B. "600s").

• Innerhalb der TTL kann der Cache wiederholt mit deterministischen Treffern referenziert werden.
• Nach Ablauf der TTL wird der Cache automatisch ungültig, und eine erneute Referenzierung führt zu einem Fehler (der Cache existiert nicht mehr).
• Sie können den Cache jederzeit per delete vorzeitig freigeben.

Abrechnung

Explizites Caching wird transparent pro Token in drei Teilen abgerechnet:

Verbesserung bei OfoxAI: Deterministisches Routing

OfoxAI verteilt die Last über mehrere GCP-Regionen / Vertex-Projekte. Explizite Caches sind region-scoped (regionsgebunden): Ein in einem GCP-Projekt erstellter Cache muss in genau diesem Projekt referenziert werden, andernfalls gibt es ein 404.

OfoxAI handhabt dies automatisch: Bei der Erstellung wird die Upstream-Instanz erfasst, an die der Cache gebunden ist, anschließend wird diese Instanz anhand des Cache-Handles nachgeschlagen und Referenzen werden hart auf denselben Upstream gesperrt. Unabhängig davon, ob Ihre Referenzanfrage eine Benutzerkennung enthält oder wie die Last verteilt wird, werden Referenzen präzise zu dem Projekt geroutet, das den Cache erstellt hat, mit null Drift. Sie müssen sich nicht um die zugrunde liegende Regionsverteilung kümmern.

Explizites vs. implizites Caching

Verwandte Dokumente

• Prompt-Caching (implizites Caching / protokollübergreifender Überblick)
• Gemini generateContent API
• Modellkatalog und Preise