The latest Gemini models, like Gemini 3.5 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.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Kontext-Caching in Firebase AI Logic

Für Ihre KI-Funktion können Sie dieselben Eingabetokens (Inhalte) immer wieder an ein Modell übergeben. 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. Beim expliziten Caching sollten Sie die Preis informationen unten auf dieser Seite lesen.

Unterstützte Modelle

Caching wird bei Verwendung der folgenden Modelle unterstützt:

gemini-3.1-pro-preview
gemini-3.5-flash
gemini-3.1-flash-lite
gemini-2.5-pro
gemini-2.5-flash
gemini-2.5-flash-lite

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 die 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 verwenden sie:

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 expliziten Inhalte im Cache 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 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. Die Prompt-Anfrage Ihrer App muss dasselbe Modell verwenden.
Der Cache ist spezifisch für einen Standort, wenn die Vertex AI Gemini API verwendet wird.
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 nichts mehr daran ändern, außer der TTL oder der Ablaufzeit.
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 und nicht noch einmal zum Zeitpunkt der Nutzeranfrage. Achten Sie daher darauf, dass alle Daten, die im expliziten Cache enthalten sind, für jeden Nutzer geeignet sind, der eine Anfrage mit diesem Cache stellt.
Wenn Sie Systemanweisungen oder Tools verwenden möchten (z. B. Codeausführung, URL-Kontext, Grounding mit Google Search oder Grounding mit Google Maps), muss der Cache selbst deren 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 Chats). Details zum Konfigurieren von System anweisungen und Tools in Ihrem Cache finden Sie in der REST API der Vertex AI Gemini API.

Schritt 1: Cache erstellen

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

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

Cloud Shell

Syntax :

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3.5-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.5-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.5-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 einfügen.

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

Beachten Sie beim Schreiben Ihrer Anfrage Folgendes:

Verwenden Sie die Vertex AI Gemini API, 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 Vertex AI Gemini API.

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

Cloud Shell

Alle Caches auflisten

Sie können alle expliziten Caches auflisten, die für Ihr Projekt verfügbar sind. Dieser Befehl gibt nur die Caches am angegebenen Standort zurück.

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