Starting November 2, 2026, Firebase App Check enforcement will be required to use Firebase AI Logic. Learn more.

Model updates:

Gemini 4 Argon is now available to use with Firebase AI Logic! Learn more.
Gemini 2.5 models are limited to projects that actively used them in the past. For the Agent Platform Gemini API, these models will shut down for all projects in October 2026. To avoid service disruptions, update to a newer model (like gemini-4-argon, gemini-3.8-flash, or gemini-3.1-flash-image). Any stable Gemini Live API 2.5 models are not impacted. Learn more.

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Kontext-Caching in Firebase AI Logic

Für Ihre KI-Funktion übergeben Sie möglicherweise immer wieder dieselben Eingabetokens (Inhalte) 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 großen Mengen an Inhalten wie großen Textmengen, einer Audiodatei oder einer Videodatei erheblich reduziert werden. Häufige Anwendungsfälle für zwischengespeicherte Inhalte sind detaillierte Persona-Dokumente, Codebasen 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 einiger zusätzlicher Entwicklerarbeit 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. Bei explizitem Caching sollten Sie sich die Preisinformationen unten auf dieser Seite ansehen.

Unterstützte Modelle

Caching wird bei Verwendung der folgenden Modelle unterstützt:

gemini-3.1-pro-preview
gemini-3.8-flash (und die älteren gemini-3.7-flash, gemini-3.6-flash und gemini-3.5-flash)
gemini-3.5-flash-lite (und die ältere gemini-3.1-flash-lite)

Gemini 2.5-Modelle für den allgemeinen Gebrauch unterstützen diese Funktion, sie sind jedoch alle eingestellt.

Modelle, die Medien generieren (z. B. die „Nana Banana“-Modelle wie gemini-3.1-flash-image), 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 für Ihre 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 im Cache gespeicherten 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.

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

Expliziten Cache erstellen und verwenden
Explizite Caches verwalten, einschließlich:

Beachten Sie, dass explizite Inhalts-Caches mit dem impliziten Caching interagieren und möglicherweise zu zusätzlichem Caching über die explizit im Cache gespeicherten Inhalte hinaus führen. Sie können die Datenaufbewahrung im Cache 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 Caches für explizite Inhalte sind folgende Voraussetzungen erforderlich:

Expliziten Cache erstellen
Im Cache in einer Server-Prompt-Vorlage darauf verweisen
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, Caches für anstößige Inhalte nur mit Agent Platform Gemini API (formerly Vertex AI) 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 Prompt-Anfrage Ihrer App muss dasselbe Modell verwendet werden.
Der Cache ist standortspezifisch, wenn Agent Platform Gemini API (formerly Vertex AI) 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 Caches angegeben ist, 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 zur Cache-Erstellungszeit geprüft und Zugriffsbeschränkungen werden nicht noch einmal zur Zeit 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, die Fundierung mit Google Search oder die Fundierung mit Google Maps 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. Server-Promptvorlagen unterstützen noch nicht Funktionsaufrufe oder Chat. Details zum Konfigurieren von Systemanweisungen und Tools in Ihrem Cache finden Sie in der REST API von Agent Platform Gemini API (formerly Vertex AI).

Schritt 1: Cache erstellen

Erstellen Sie den Cache direkt mit der REST API von Agent Platform Gemini API (formerly Vertex AI).

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

Syntax:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3.8-flash
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.8-flash"
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 vollständig 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.8-flash",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

Schritt 2: Auf den Cache in einer Server-Prompt-Vorlage verweisen

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

Beachten Sie beim Erstellen der 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-Prompt-Vorlage 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-Prompt-Vorlage 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-Prompt-Vorlage in der Anfrage aus Ihrer App referenzieren

Achten Sie beim Verfassen Ihrer Anfrage auf Folgendes:

Verwenden Sie Agent Platform Gemini API (formerly Vertex AI), da der Cache mit diesem Gemini API-Anbieter erstellt wurde.
Der Speicherort, an dem Sie in der Prompt-Anfrage Ihrer App auf das Modell zugreifen, muss mit dem Speicherort der Server-Prompt-Vorlage und des Cache übereinstimmen.

Swift

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform(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 Agent Platform Gemini API backend service (formerly Vertex AI).
// 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.agentPlatform(location = "LOCATION"))
                        .templateGenerativeModel()

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

val text = response.text
println(text)

Java

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"))
      .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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
const ai = getAI(app, { backend: new AgentPlatformBackend('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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
var _model = FirebaseAI.agentPlatform(location: 'LOCATION').templateGenerativeModel()

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

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

Einheit

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(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}");
}

Explizite Caches verwalten

In diesem Abschnitt wird beschrieben, wie Sie Caches mit expliziten Inhalten 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 Agent Platform Gemini API (formerly Vertex AI).

Nachdem ein Cache für explizite Inhalte erstellt wurde, können Sie nichts mehr daran ändern, außer die TTL oder die Ablaufzeit.

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ächlichen Inhalte im Cache 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 im vollständig qualifizierten Ressourcennamen 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 den ttl festlegen, wird der expireTime des Cache automatisch aktualisiert.
expire_time: Ein Timestamp-Wert (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 im vollständig qualifizierten Ressourcennamen name des Cache ist.

Update für ttl

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'"
}'

Update für expire_time

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.