The latest Gemini models, like Gemini 3.6 Flash, are available to use with Firebase AI Logic! Learn more.

All Imagen models will shut down as early as June 30, 2026. Learn about migrating your apps to use Nano Banana.

Gemini 2.5 models will shut down in October 2026. To avoid service disruptions, update to a newer model (like gemini-3.6-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. In diesen Anwendungsfällen können Sie diese Inhalte stattdessen im Cache speichern. Das bedeutet, dass Sie die Inhalte einmal an das Modell übergeben, sie speichern und in nachfolgenden Anfragen darauf verweisen.

Durch das Caching von Kontexten können die Latenz und die Kosten für sich wiederholende Aufgaben mit einer großen Menge an Inhalten erheblich reduziert werden, z. B. bei großen Textmengen, einer Audiodatei oder einer Videodatei. Einige häufige Anwendungsfälle für Inhalte im Cache sind detaillierte Personadokumente, Codebasen oder Handbücher.

Gemini Modelle bieten zwei verschiedene Caching-Mechanismen:

Implizites Caching: automatisch bei den meisten Modellen aktiviert, keine garantierten Kosteneinsparungen
Explizites Caching: Bei den meisten Modellen optional und manuell aktivierbar, führt in der Regel zu Kosteneinsparungen

Explizites Caching ist in Fällen nützlich, in denen Sie mit größerer Wahrscheinlichkeit Kosteneinsparungen erzielen möchten, aber mit etwas mehr Aufwand für Entwickler.

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

Unterstützte Modelle

Caching wird bei Verwendung der folgenden Modelle unterstützt:

gemini-3.1-pro-preview
gemini-3.6-flash und das ältere gemini-3.5-flash
gemini-3.5-flash-lite und das ältere gemini-3.1-flash-lite

Die Gemini-Modelle für den allgemeinen Gebrauch Gemini 2.5 unterstützen diese Funktion, sind aber alle veraltet.

Modelle zur Mediengenerierung (z. B. die „Nana Banana“-Modelle wie gemini-3.1-flash-image) unterstützen kein Kontext-Caching.

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

Für jedes Modell gilt eine Mindestanzahl von Tokens für Inhalte im Cache. Die maximale Anzahl 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 Inhalte im Cache trifft. Hier sind einige Möglichkeiten, die Wahrscheinlichkeit zu erhöhen, dass Ihre Anfrage implizites Caching verwendet:

Platzieren Sie große und häufig verwendete Inhalte am Anfang Ihres Prompts.
Senden Sie Anfragen mit einem ähnlichen Präfix in kurzer Zeit.

Die Anzahl der Tokens im Cache-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 explizite Inhalts-Caches ein und arbeiten damit:

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

Explizite Inhalts-Caches interagieren mit implizitem Caching, was möglicherweise zu zusätzlichem Caching über die explizit im Cache gespeicherten Inhalte hinaus führt. Sie können die Aufbewahrung von Cache-Daten verhindern, indem Sie implizites Caching deaktivieren und keine expliziten Caches erstellen. Weitere Informationen finden Sie unter Caching aktivieren und deaktivieren.

Expliziten Cache erstellen und verwenden

Für das Erstellen und Verwenden eines expliziten Inhalts-Caches ist Folgendes erforderlich:

Expliziten Cache erstellen
In einer Server-Prompt-Vorlage auf den Cache verweisen
In einer Prompt-Anfrage aus Ihrer App auf die Server-Prompt-Vorlage verweisen

Wichtige Informationen zum Erstellen und Verwenden eines expliziten Caches

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

Der Cache ist spezifisch für einen Gemini API Anbieter. Die Prompt-Anfrage Ihrer App muss denselben Anbieter verwenden.
Für Firebase AI Logic, empfehlen wir dringend, explizite Inhalts-Caches nur mit der 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. Die Prompt-Anfrage Ihrer App muss dasselbe Modell verwenden.
Der Cache ist spezifisch für einen Standort, wenn Sie die Agent Platform Gemini API (formerly Vertex AI) verwenden.
Der Standort für den expliziten Cache muss mit dem Standort der Server-Prompt-Vorlage und dem Standort übereinstimmen, an dem Sie in der Prompt-Anfrage Ihrer App auf das Modell zugreifen.

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

Nachdem ein expliziter Cache erstellt wurde, können Sie nur noch die TTL oder die Ablaufzeit ändern.
Sie können jeden unterstützten MIME-Typ für Eingabedateien oder auch nur Text im Cache speichern, der in der Anfrage zum Erstellen des Caches angegeben wurde.
Wenn Sie eine Datei in den Cache aufnehmen möchten, müssen Sie sie als Cloud Storage URI angeben. Es kann sich nicht um eine Browser-URL oder YouTube-URL handeln.

Außerdem werden die Zugriffsbeschränkungen für die Datei zum Zeitpunkt der Cache-Erstellung geprüft. Bei einer Nutzeranfrage werden die Zugriffsbeschränkungen nicht noch einmal geprüft. Achten Sie daher darauf, dass alle Daten im expliziten Cache für jeden Nutzer geeignet sind, der eine Anfrage mit diesem Cache sendet.
Wenn Sie Systemanweisungen oder Tools verwenden möchten (z. B. Code-Ausführung, URL Context, Fundierung mit Google Search, oder Fundierung mit Google Maps), muss der Cache selbst die entsprechenden Konfigurationen enthalten. Sie können nicht in der Server-Prompt-Vorlage oder in der Prompt-Anfrage Ihrer App konfiguriert werden. Server-Prompt-Vorlagen unterstützen noch nicht Funktionsaufrufe (oder Chat). Details zum Konfigurieren von System anweisungen und Tools in Ihrem Cache finden Sie in der REST API der Agent Platform Gemini API (formerly Vertex AI).

Schritt 1: Cache erstellen

Erstellen Sie den Cache direkt mit der REST API der 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.6-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.6-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 einen vollständig qualifizierten Ressourcennamen (name), der für den Cache weltweit 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.6-flash",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

Schritt 2: In einer Server-Prompt-Vorlage auf den Cache verweisen

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

Beachten Sie beim Erstellen Ihrer Server-Prompt-Vorlage die folgenden Anforderungen:

Verwenden Sie den vollständig qualifizierten Ressourcennamen (name) aus der Antwort, als Sie den Cache erstellt haben. Dies ist nicht der optionale Anzeigename, den Sie in der Anfrage angegeben haben.
Der Standort für die Server-Prompt-Vorlage muss mit dem Standort des Caches übereinstimmen.
Wenn Sie Systemanweisungen oder Tools verwenden möchten, müssen sie als Teil des Caches 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 name Parameters in der Server-Prompt-Vorlage eine dynamische Eingabevariable sein. Mit {{cachedContent name=someVariable}} können Sie beispielsweise den name des Caches als Eingabe für die Anfrage aus Ihrer App verwenden.

Schritt 3: In der Anfrage aus Ihrer App auf die Server-Prompt-Vorlage verweisen

Beachten Sie beim Schreiben Ihrer Anfrage Folgendes:

Verwenden Sie die Agent Platform Gemini API (formerly Vertex AI) da der Cache mit diesem Gemini API Anbieter erstellt wurde.
Der Standort, an dem Sie in der Prompt-Anfrage Ihrer App auf das Modell zugreifen, muss mit dem Standort der Server-Prompt Vorlage und des Caches ü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}");
}

Explizite Caches verwalten

In diesem Abschnitt wird beschrieben, wie Sie explizite Inhalts-Caches verwalten, einschließlich des Auflistens aller Caches, Abrufens von Metadaten zu einem Cache, Aktualisierens der TTL oder der Ablaufzeit eines Caches, und des Löschens eines Caches.

Sie verwalten explizite Caches mit der REST API der Agent Platform Gemini API (formerly Vertex AI).

Nachdem ein expliziter Inhalts-Cache erstellt wurde, können Sie nur noch die TTL oder die Ablaufzeit ändern.

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 Standort 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 ist das letzte Segment im vollständig qualifizierten Ressourcennamen (name) des Caches.

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 eines Caches aktualisieren

Wenn Sie einen expliziten Cache erstellen, können Sie optional die ttl oder die 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 Caches 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.

Für vorhandene explizite Caches können Sie die ttl oder expire_time hinzufügen oder aktualisieren. Sie müssen die CACHE_ID angeben. Das ist das letzte Segment im vollständig qualifizierten Ressourcennamen (name) des Caches.

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

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