Kontext-Caching in Firebase AI Logic

Für Ihre KI-Funktion übergeben Sie möglicherweise dieselben Eingabetokens (Inhalte) immer wieder an ein Modell. Für diese Anwendungsfälle können Sie diese Inhalte stattdessen zwischenspeichern. Das bedeutet, dass Sie die Inhalte einmal an das Modell übergeben, speichern und in nachfolgenden Anfragen darauf verweisen.

Durch Kontext-Caching können Latenz und Kosten für sich wiederholende Aufgaben mit einer großen Menge an Inhalten wie großen Mengen an Text, einer Audiodatei oder einer Videodatei erheblich reduziert werden. Typische Anwendungsfälle für zwischengespeicherte Inhalte sind detaillierte Persona-Dokumente, Codebases oder Handbücher.

Gemini-Modelle bieten zwei verschiedene Caching-Mechanismen:

• Implizites Caching: Bei den meisten Modellen automatisch aktiviert, keine garantierten Kosteneinsparungen

• Explizites Caching: Kann bei den meisten Modellen optional und manuell aktiviert werden und führt in der Regel zu Kosteneinsparungen.

Explizites Caching ist nützlich, wenn Sie mit etwas mehr Entwickleraufwand mit höherer Wahrscheinlichkeit Kosten sparen möchten.

Sowohl beim impliziten als auch beim expliziten Caching gibt das Feld cachedContentTokenCount in den Metadaten Ihrer Antwort die Anzahl der Tokens im gecachten Teil Ihrer Eingabe an. Informationen zu den Preisen für das explizite Caching finden Sie unten auf dieser Seite.

Hinweis: Kontext-Caching wird häufig als Inhalts-Caching bezeichnet (wie auf den meisten Seiten).

Unterstützte Modelle

Caching wird bei Verwendung der folgenden Modelle unterstützt:

• gemini-3.1-pro-preview
• gemini-3-flash-preview
• gemini-3.1-flash-lite-preview
• gemini-2.5-pro
• gemini-2.5-flash
• gemini-2.5-flash-lite

Modelle, die Medien generieren (z. B. die Nana Banana-Modelle wie gemini-3.1-flash-image-preview), unterstützen kein Kontext-Caching.

Größenbeschränkungen für im Cache gespeicherte Inhalte

Für jedes Modell gilt eine Mindestanforderung für die Anzahl der Tokens für zwischengespeicherte Inhalte. Das Maximum wird durch das Kontextfenster des Modells bestimmt.

• Gemini Pro-Modelle: mindestens 4.096 Tokens
• Gemini Flash-Modelle: mindestens 1.024 Tokens

Außerdem beträgt die maximale Größe von Inhalten, die Sie mit einem Blob oder Text im Cache speichern können, 10 MB.

---

Implizites Caching

Implizites Caching ist standardmäßig aktiviert und für die meisten Gemini-Modelle verfügbar.

Google gibt Kosteneinsparungen automatisch weiter, wenn Ihre Anfrage auf die zwischengespeicherten Inhalte zugreift. Hier sind einige Möglichkeiten, die Wahrscheinlichkeit zu erhöhen, dass bei Ihrer Anfrage implizites Caching verwendet wird:

• Stellen Sie große und allgemeine Inhalte an den Anfang Ihres Prompts.
• Versuchen Sie, Anfragen mit einem ähnlichen Präfix innerhalb kurzer Zeit zu senden.

Die Anzahl der Tokens im zwischengespeicherten Teil Ihrer Eingabe wird im Feld cachedContentTokenCount in den Metadaten einer Antwort angegeben.

---

Explizites Caching

Explizites Caching ist nicht standardmäßig aktiviert und eine optionale Funktion der Gemini-Modelle.

Wichtig :Firebase AI Logic ermöglicht den Zugriff auf explizite-Inhaltscaches nur bei Verwendung von Server-Promptvorlagen.

Für Firebase AI Logic empfehlen wir außerdem dringend, explizite Inhalts-Caches nur mit der Vertex AI Gemini API zu verwendenGemini API, damit Sie sich beim Erstellen und Verwalten Ihrer expliziten Inhalts-Caches keine Gedanken über die Verwendung oder versehentliche Offenlegung eines Gemini API-Schlüssels machen müssen.

Firebase AI Logic arbeitet an der Verbesserung des Workflows für das explizite Caching. Wenn Sie an dieser Funktion interessiert sind, können Sie für den vorhandenen User Voice-Eintrag abstimmen, damit wir wissen, dass wir Ressourcen auf diesen Bereich konzentrieren sollten.

So richten Sie Caches für explizite Inhalte ein und arbeiten damit:

• Expliziten Cache erstellen und verwenden

• Explizite Caches verwalten, einschließlich:

  • Alle Caches auflisten

  • Metadaten zu einem Cache abrufen

  • TTL oder Ablaufzeit eines Caches aktualisieren

  • Cache löschen

Beachten Sie, dass explizite Inhalts-Caches mit dem impliziten Caching interagieren und möglicherweise zu zusätzlichem Caching über die explizit gecachten Inhalte hinaus führen. Sie können die Aufbewahrung von Cache-Daten verhindern, indem Sie das implizite Caching deaktivieren und keine expliziten Caches erstellen. Weitere Informationen finden Sie unter Caching aktivieren und deaktivieren.

---

Expliziten Cache erstellen und verwenden

Zum Erstellen und Verwenden eines Cache für anstößige Inhalte sind folgende Voraussetzungen erforderlich:

1. Expliziten Cache erstellen

2. Auf den Cache in einer Server-Promptvorlage verweisen

3. In einer Prompts-Anfrage aus Ihrer App auf die Server-Prompt-Vorlage verweisen.

Wichtige Informationen zum Erstellen und Verwenden eines expliziten Cache

Ihr Cache muss mit den Prompt-Anfragen Ihrer App und Ihrer Server-Prompt-Vorlage übereinstimmen:

• Der Cache ist für einen bestimmten Gemini API-Anbieter spezifisch. Für die Aufforderungsanfrage Ihrer App muss derselbe Anbieter verwendet werden.
  Für Firebase AI Logic empfehlen wir dringend, explizite Inhaltscaches nur mit Vertex AI Gemini API zu verwenden. Alle Informationen und Beispiele auf dieser Seite beziehen sich auf diesen Gemini API-Anbieter.

• Der Cache ist spezifisch für ein Gemini-Modell. Für die Aufforderungsanfrage Ihrer App muss dasselbe Modell verwendet werden.

• Der Cache ist standortspezifisch, wenn die Vertex AI Gemini API verwendet wird.
  Der Speicherort für den expliziten Cache muss mit dem Speicherort der Server-Promptvorlage und dem Speicherort, an dem Sie in der Prompts-Anfrage Ihrer App auf das Modell zugreifen, übereinstimmen.

Beachten Sie außerdem die folgenden Einschränkungen und Anforderungen für das explizite Caching:

• Nachdem ein expliziter Cache erstellt wurde, können Sie nichts mehr daran ändern, außer die TTL oder die Ablaufzeit.

• Sie können jeden unterstützten MIME-Typ für Eingabedateien oder auch nur Text, der in der Anfrage zum Erstellen des Cache angegeben wird, im Cache speichern.

• Wenn Sie eine Datei in den Cache aufnehmen möchten, müssen Sie die Datei als Cloud Storage-URI angeben. Es darf sich nicht um eine Browser- oder YouTube-URL handeln.

  Außerdem werden die Zugriffsbeschränkungen für die Datei zum Zeitpunkt der Cache-Erstellung geprüft. Zugriffsbeschränkungen werden nicht noch einmal zum Zeitpunkt der Nutzeranfrage geprüft. Achten Sie daher darauf, dass alle Daten im expliziten Cache für jeden Nutzer geeignet sind, der eine Anfrage mit diesem Cache stellt.

• Wenn Sie Systemanweisungen oder Tools wie die Codeausführung, den URL-Kontext oder die Fundierung mit der Google Suche verwenden möchten, muss der Cache selbst die entsprechenden Konfigurationen enthalten. Sie können nicht in der Server-Promptvorlage oder in der Prompts-Anfrage Ihrer App konfiguriert werden. Hinweis: Server-Promptvorlagen unterstützen noch nicht Funktionsaufrufe oder Chat. Weitere Informationen zum Konfigurieren von Systemanweisungen und Tools in Ihrem Cache finden Sie in der REST API von Vertex AI Gemini API.

Schritt 1: Cache erstellen

Erstellen Sie den Cache direkt mit der REST API von Vertex AI Gemini API.

Im folgenden Beispiel wird ein expliziter Cache einer PDF-Datei als Inhalt erstellt.

Hinweis: Im folgenden Beispiel wird davon ausgegangen, dass Sie in der gcloud-Befehlszeile angemeldet sind, indem Sie gcloud init oder gcloud auth login ausgeführt haben.
Wir empfehlen, über Cloud Shell direkt in der Firebase-Konsole auf die gcloud-Befehlszeile zuzugreifen.

Firebase

Syntax:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3-flash-preview
LOCATION="LOCATION"  # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI"  # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME"  # optional
TTL="CACHE_TIME_TO_LIVE"  # optional (if not specified, defaults to 3600s)

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Beispielanfrage:

PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3-flash-preview"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Beispielantwort:

Die Antwort enthält eine voll qualifizierte Ressource name, die für den Cache global eindeutig ist. Das letzte Segment ist die Cache-ID. Sie verwenden diesen gesamten name-Wert im nächsten Schritt des Workflows.

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3-flash-preview",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

Schritt 2: Im Server-Prompt-Template auf den Cache verweisen

Wichtig :Firebase AI Logic ermöglicht den Zugriff auf explizite Inhalts-Caches nur bei Verwendung von Server-Promptvorlagen.

Nachdem Sie den Cache erstellt haben, verweisen Sie mit name in der cachedContent-Eigenschaft einer Server-Promptvorlage darauf.

Beachten Sie beim Erstellen Ihrer Server-Promptvorlage die folgenden Anforderungen:

• Verwenden Sie die vollständig qualifizierte Ressource name aus der Antwort, als Sie den Cache erstellt haben. Dies ist nicht der optionale Anzeigename, den Sie in der Anfrage angegeben haben.

• Der Speicherort der Server-Promptvorlage muss mit dem Speicherort des Cache übereinstimmen.

• Wenn Sie Systemanweisungen oder Tools verwenden möchten, müssen sie als Teil des Cache und nicht als Teil der Server-Promptvorlage konfiguriert werden.

Syntax:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

{{role "user"}}
{{userPrompt}}

Beispiel:

{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}

{{role "user"}}
{{userPrompt}}

Alternativ kann der Wert des Parameters name in der Server-Promptvorlage eine dynamische Eingabevariable sein. Mit {{cachedContent name=someVariable}} können Sie beispielsweise die name des Cache als Eingabe für die Anfrage aus Ihrer App verwenden.

Schritt 3: Server-Promptvorlage in der Anfrage aus Ihrer App referenzieren

Achten Sie beim Verfassen Ihrer Anfrage auf Folgendes:

• Verwenden Sie Vertex AI Gemini API, da der Cache mit diesem Gemini API-Anbieter erstellt wurde.

• Der Standort, an dem Sie in der Aufforderungsanfrage Ihrer App auf das Modell zugreifen, muss mit dem Standort der Server-Aufforderungsvorlage und des Cache übereinstimmen.

Swift

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
let model = FirebaseAI.firebaseAI(backend: .vertexAI(location: "LOCATION"))
                                  .templateGenerativeModel()

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "TEMPLATE_ID"
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
val model = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "LOCATION"))
                        .templateGenerativeModel()

val response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID",
)

val text = response.text
println(text)

Java

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

Future<GenerateContentResponse> response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID"
);
addCallback(response,
      new FutureCallback<GenerateContentResponse>() {
          public void onSuccess(GenerateContentResponse result) {
            System.out.println(result.getText());
          }
          public void onFailure(Throwable t) {
            reportError(t);
          }
    }
executor);

Web

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
const ai = getAI(app, { backend: new VertexAIBackend('LOCATION') });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const result = await model.generateContent(
  // Specify your template ID
  'TEMPLATE_ID'
);

const response = result.response;
const text = response.text();

Dart

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
var _model = FirebaseAI.vertexAI(location: 'LOCATION').templateGenerativeModel()

var response = await _model.generateContent(
        // Specify your template ID
        'TEMPLATE_ID',
      );

var text = response?.text;
print(text);

Einheit

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "LOCATION"));

// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID
      "TEMPLATE_ID"
  );
  Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

Hinweis :Die Anfrage schlägt mit dem Fehler Explicit content cache doesn't exist fehl, wenn der name des Caches in der Vorlage ungültig ist, wenn die Standorte nicht für alle Komponenten übereinstimmen oder wenn der Cache abgelaufen ist.

---

Explizite Caches verwalten

In diesem Abschnitt wird beschrieben, wie Sie Caches für explizite Inhalte verwalten. Dazu gehört, wie Sie alle Caches auflisten, Metadaten zu einem Cache abrufen, die TTL oder das Ablaufdatum eines Caches aktualisieren und einen Cache löschen.

Sie verwalten explizite Caches mit der REST API von Vertex AI Gemini API.

Nachdem ein expliziter Inhaltscache erstellt wurde, können Sie nichts mehr daran ändern, außer die TTL oder die Ablaufzeit.

Hinweis: Bei den folgenden Beispielen wird davon ausgegangen, dass Sie in der gcloud CLI angemeldet sind, indem Sie gcloud init oder gcloud auth login ausgeführt haben.
Wir empfehlen, über Cloud Shell direkt in der Firebase-Konsole auf die gcloud-Befehlszeile zuzugreifen.

Firebase

Alle Caches auflisten

Sie können alle expliziten Caches auflisten, die für Ihr Projekt verfügbar sind. Mit diesem Befehl werden nur die Caches am angegebenen Ort zurückgegeben.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents

Metadaten zu einem Cache abrufen

Es ist nicht möglich, die tatsächlich im Cache gespeicherten Inhalte abzurufen oder anzusehen. Sie können jedoch Metadaten zu einem expliziten Cache abrufen, einschließlich name, model, display_name, usage_metadata, create_time, update_time und expire_time.

Sie müssen die CACHE_ID angeben, das das letzte Segment in der vollständig qualifizierten Ressource name des Cache ist.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}

TTL oder Ablaufzeit für einen Cache aktualisieren

Wenn Sie einen expliziten Cache erstellen, können Sie optional ttl oder expire_time festlegen.

• ttl: Die TTL (Time-to-Live) für den Cache, insbesondere die Anzahl der Sekunden und Nanosekunden, die der Cache nach der Erstellung oder nach der Aktualisierung der ttl gültig ist, bevor er abläuft. Wenn Sie die ttl festlegen, wird die expireTime des Cache automatisch aktualisiert.

• expire_time: Ein Timestamp (z. B. 2024-06-30T09:00:00.000000Z), der das absolute Datum und die Uhrzeit angibt, zu der der Cache abläuft.

Wenn Sie keinen dieser Werte festlegen, beträgt die Standard-TTL 1 Stunde. Es gibt keine Mindest- oder Höchstwerte für die TTL.

Bei vorhandenen expliziten Caches können Sie ttl oder expire_time hinzufügen oder aktualisieren. Sie müssen die CACHE_ID angeben, das das letzte Segment in der vollständig qualifizierten Ressource name des Cache ist.

ttl aktualisieren

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "ttl": "'$TTL'"
}'

expire_time aktualisieren

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "expire_time": "'$EXPIRE_TIME'"
}'

Cache löschen

Wenn ein expliziter Cache nicht mehr benötigt wird, können Sie ihn löschen.

Achtung :Bevor Sie einen Cache löschen, müssen Sie prüfen, ob er von Server-Prompt-Vorlagen oder Anfragen aus Ihrer App verwendet wird. Nach dem Löschen des Cache kann er nicht wiederhergestellt werden. Hinweis: Wenn Sie einen Cache löschen, werden nicht die tatsächlichen Quellinhalte gelöscht, die im Cache enthalten waren.

Sie müssen die CACHE_ID angeben, das das letzte Segment in der vollständig qualifizierten Ressourcen-name des Cache ist.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}

---

Preise für explizites Caching

Explizites Caching ist eine kostenpflichtige Funktion, die dazu dient, Kosten zu senken. Die Preise basieren auf den folgenden Faktoren:

• Eingabetokens für die Cache-Erstellung: Sowohl beim impliziten als auch beim expliziten Caching werden Ihnen die Eingabetokens, die zum Erstellen des Cache verwendet werden, zum Standardpreis für Eingabetokens in Rechnung gestellt.

• Speicherung von Cache: Beim expliziten Caching fallen auch Speicherkosten an, die davon abhängen, wie lange Caches gespeichert werden. Für das implizite Caching fallen keine Speicherkosten an. Weitere Informationen finden Sie unter Preise für Vertex AI Gemini API.

• Verwendung von im Cache gespeicherten Inhalten: Durch explizites Caching wird ein Rabatt gewährt, wenn auf explizite Caches verwiesen wird. Das bedeutet, dass Sie einen Rabatt auf die Eingabetokens erhalten, wenn sie auf einen vorhandenen Cache verweisen. Bei Modellen ab Gemini 2.5 beträgt dieser Rabatt 90%.

Die Anzahl der Tokens im zwischengespeicherten Teil Ihrer Eingabe wird im Feld cachedContentTokenCount in den Metadaten einer Antwort angegeben.