Sie müssen einen Kontext-Cache erstellen, bevor Sie ihn verwenden können. Der von Ihnen erstellte Kontext-Cache enthält eine große Datenmenge, die Sie in verschiedenen Anfragen an ein Gemini-Modell verwenden können. Die im Cache gespeicherten Inhalte werden in der Region gespeichert, in der Sie die Anfrage zum Erstellen des Cache stellen.
Im Cache gespeicherte Inhalte können beliebige, von multimodalen Gemini-Modellen unterstützte MIME-Typen haben. Sie können beispielsweise eine große Menge an Text, Audio oder Video im Cache speichern. Sie können mehr als eine Datei für den Cache angeben. Weitere Informationen finden Sie in den folgenden Media-Anforderungen:
Sie geben den Inhalt, der im Cache gespeichert werden soll, mit einem Blob, Text oder einem Pfad zu einer Datei an, die in einem Cloud Storage-Bucket gespeichert ist. Wenn die Größe des Inhalts, den Sie im Cache speichern, 10 MB übersteigt, müssen Sie ihn mit dem URI einer Datei angeben, die in einem Cloud Storage-Bucket gespeichert ist. Eine Anleitung zum Erstellen eines Cloud Storage-Bucket zum Hosten Ihrer Datei finden Sie unter Buckets erstellen.
Im Cache gespeicherte Inhalte haben eine begrenzte Lebensdauer. Die Standardablaufzeit eines Kontext-Caches beträgt 60 Minuten nach seiner Erstellung. Wenn Sie eine andere Ablaufzeit wünschen, können Sie sie beim Erstellen eines Kontext-Caches mit der Eigenschaft ttl oder expire_time angeben. Sie können weiter die Ablaufzeit für einen noch nicht abgelaufenen Kontext-Cache aktualisieren. Informationen zum Angeben von
ttl und expire_time finden Sie unter
Ablaufzeit aktualisieren.
Nachdem ein Kontext-Cache abgelaufen ist, ist er nicht mehr verfügbar. Wenn Sie in zukünftigen Prompt-Anfragen auf den Inhalt in einem abgelaufenen Kontext-Cache verweisen möchten, müssen Sie den Kontext-Cache neu erstellen.
Standortunterstützung
Das Speichern von Kontexten im Cache wird in der Region Sydney, Australien (australia-southeast1) nicht unterstützt.
Das Speichern von Kontexten im Cache unterstützt den globalen Endpunkt.
Unterstützung von Verschlüsselungsschlüsseln
Das Speichern von Kontexten im Cache unterstützt vom Kunden verwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK). So können Sie die Verschlüsselung Ihrer im Cache gespeicherten Daten steuern und Ihre vertraulichen Informationen mit Verschlüsselungsschlüsseln schützen, die Sie verwalten und besitzen. Das bietet eine zusätzliche Ebene für Sicherheit und Compliance.
Weitere Informationen finden Sie im Beispiel.
CMEK wird bei Verwendung des globalen Endpunkts nicht unterstützt.
Unterstützung von Access Transparency
Das Speichern von Kontexten im Cache unterstützt Access Transparency.
Beispiel für das Erstellen eines Kontext-Cache
Die folgenden Beispiele zeigen, wie ein Kontext-Cache erstellt wird.
Python
Installieren
pip install --upgrade google-genai
Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.
Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True
Go
Informationen zum Installieren oder Aktualisieren von Go
Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.
Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True
Java
Informationen zum Installieren oder Aktualisieren von Java
Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.
Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True
Node.js
Installieren
npm install @google/genai
Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.
Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True
REST
Sie können mit REST einen Kontext-Cache erstellen. Dazu senden Sie mit der Agent Platform API eine POST-Anfrage an den Endpunkt des Publisher-Modells. Im folgenden Beispiel wird gezeigt, wie ein Kontext-Cache mithilfe einer in einem Cloud Storage Bucket gespeicherten Datei erstellt wird.
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- PROJECT_ID: Ihre [Projekt-ID](/resource-manager/docs/creating-managing-projects#identifiers). .
- LOCATION: Die Region, in der die Anfrage verarbeitet wird und in der der im Cache gespeicherte Inhalt gespeichert wird. Eine Liste der unterstützten Regionen finden Sie unter Verfügbare Regionen.
- CACHE_DISPLAY_NAME: Ein aussagekräftiger Anzeigename, mit dem Sie die einzelnen Kontext-Caches beschreiben und identifizieren können.
- MIME_TYPE: Der MIME-Typ des Inhalts, der im Cache gespeichert werden soll.
- CONTENT_TO_CACHE_URI: Der Cloud Storage-URI des Inhalts, der im Cache gespeichert werden soll.
- MODEL_ID: Das Modell, das für das Speichern im Cache verwendet werden soll.
HTTP-Methode und URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents
JSON-Text der Anfrage:
{
"model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID",
"displayName": "CACHE_DISPLAY_NAME",
"contents": [{
"role": "user",
"parts": [{
"fileData": {
"mimeType": "MIME_TYPE",
"fileUri": "CONTENT_TO_CACHE_URI"
}
}]
},
{
"role": "model",
"parts": [{
"text": "This is sample text to demonstrate explicit caching."
}]
}]
}
Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:
curl
Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents"
PowerShell
Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents" | Select-Object -Expand Content
Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:
Beispiel: cURL-Befehls
LOCATION="us-central1"
MODEL_ID="gemini-2.5-flash"
PROJECT_ID="test-project"
MIME_TYPE="video/mp4"
CACHED_CONTENT_URI="gs://path-to-bucket/video-file-name.mp4"
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents -d \
'{
"model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
"contents": [
{
"role": "user",
"parts": [
{
"fileData": {
"mimeType": "${MIME_TYPE}",
"fileUri": "${CACHED_CONTENT_URI}"
}
}
]
}
]
}'
Kontext-Cache mit CMEK erstellen
Wenn Sie das Speichern von Kontexten im Cache mit CMEK implementieren möchten, erstellen Sie einen CMEK gemäß
der Anleitung und prüfen Sie, ob das
dienstkontobezogene P4SA (Per-Product, Per-Project Service Account) der Gemini Enterprise Agent Platform die
erforderlichen Berechtigungen für Cloud Key Management Service CryptoKey-Verschlüsseler/Entschlüsseler für den Schlüssel hat.
So können Sie im Cache gespeicherte Inhalte sicher erstellen und verwalten sowie andere Aufrufe wie {List, Update, Delete, Get} CachedContent(s) ausführen, ohne wiederholt einen KMS-Schlüssel angeben zu müssen.
REST
Sie können mit REST einen Kontext-Cache erstellen. Dazu senden Sie mit der Agent Platform API eine POST-Anfrage an den Endpunkt des Publisher-Modells. Im folgenden Beispiel wird gezeigt, wie ein Kontext-Cache mithilfe einer in einem Cloud Storage Bucket gespeicherten Datei erstellt wird.
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- PROJECT_ID: .
- LOCATION: Die Region, in der die Anfrage verarbeitet wird und in der der im Cache gespeicherte Inhalt gespeichert wird. Eine Liste der unterstützten Regionen finden Sie unter Verfügbare Regionen.
- MODEL_ID: gemini-2.0-flash-001.
- CACHE_DISPLAY_NAME: Ein aussagekräftiger Anzeigename, mit dem Sie die einzelnen Kontext-Caches beschreiben und identifizieren können.
- MIME_TYPE: Der MIME-Typ des Inhalts, der im Cache gespeichert werden soll.
- CACHED_CONTENT_URI: Der Cloud Storage-URI des Inhalts, der im Cache gespeichert werden soll.
- KMS_KEY_NAME: Der Name des Cloud KMS-Schlüssels.
HTTP-Methode und URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents
JSON-Text der Anfrage:
{
"model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001",
"displayName": "CACHE_DISPLAY_NAME",
"contents": [{
"role": "user",
"parts": [{
"fileData": {
"mimeType": "MIME_TYPE",
"fileUri": "CONTENT_TO_CACHE_URI"
}
}]}],
"encryptionSpec": {
"kmsKeyName": "KMS_KEY_NAME"
}
}
Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:
curl
Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents"
PowerShell
Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents" | Select-Object -Expand Content
Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:
Beispiel: cURL-Befehls
LOCATION="us-central1"
MODEL_ID="gemini-2.5-flash"
PROJECT_ID="test-project"
MIME_TYPE="video/mp4"
CACHED_CONTENT_URI="gs://path-to-bucket/video-file-name.mp4"
KMS_KEY_NAME="projects/${PROJECT_ID}/locations/{LOCATION}/keyRings/your-key-ring/cryptoKeys/your-key"
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents -d \
'{
"model": "projects/{PROJECT_ID}}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}",
"contents" : [
{
"role": "user",
"parts": [
{
"file_data": {
"mime_type":"{MIME_TYPE}",
"file_uri":"{CACHED_CONTENT_URI}"
}
}
]
}
],
"encryption_spec" :
{
"kms_key_name":"{KMS_KEY_NAME}"
}
}'
GenAI SDK für Python
Installieren
pip install --upgrade google-genai
Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.
Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit der Gemini Enterprise Agent Platform zu verwenden:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
import os
from google import genai
from google.genai.types import Content, CreateCachedContentConfig, HttpOptions, Part
os.environ['GOOGLE_CLOUD_PROJECT'] = 'vertexsdk'
os.environ['GOOGLE_CLOUD_LOCATION'] = 'us-central1'
os.environ['GOOGLE_GENAI_USE_VERTEXAI'] = 'True'
client = genai.Client(http_options=HttpOptions(api_version="v1"))
system_instruction = """
You are an expert researcher. You always stick to the facts in the sources provided, and never make up new facts.
Now look at these research papers, and answer the following questions.
"""
contents = [
Content(
role="user",
parts=[
Part.from_uri(
file_uri="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf",
mime_type="application/pdf",
),
Part.from_uri(
file_uri="gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf",
mime_type="application/pdf",
),
],
)
]
content_cache = client.caches.create(
model="gemini-2.5-flash",
config=CreateCachedContentConfig(
contents=contents,
system_instruction=system_instruction,
display_name="example-cache",
kms_key_name="projects/vertexsdk/locations/us-central1/keyRings/your-project/cryptoKeys/your-key",
ttl="86400s",
),
)
print(content_cache.name)
print(content_cache.usage_metadata)
GenAI SDK für Go
Informationen zum Installieren oder Aktualisieren des Gen AI SDK für Go
Weitere Informationen finden Sie in der Referenzdokumentation zum SDK.
Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit der Gemini Enterprise Agent Platform zu verwenden:
import (
"context"
"encoding/json"
"fmt"
"io"
genai "google.golang.org/genai"
)
// createContentCache shows how to create a content cache with an expiration parameter.
func createContentCache(w io.Writer) (string, error) {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta1"},
})
if err != nil {
return "", fmt.Errorf("failed to create genai client: %w", err)
}
modelName := "gemini-2.5-flash"
systemInstruction := "You are an expert researcher. You always stick to the facts " +
"in the sources provided, and never make up new facts. " +
"Now look at these research papers, and answer the following questions."
cacheContents := []*genai.Content{
{
Parts: []*genai.Part{
{FileData: &genai.FileData{
FileURI: "gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf",
MIMEType: "application/pdf",
}},
{FileData: &genai.FileData{
FileURI: "gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf",
MIMEType: "application/pdf",
}},
},
Role: "user",
},
}
config := &genai.CreateCachedContentConfig{
Contents: cacheContents,
SystemInstruction: &genai.Content{
Parts: []*genai.Part{
{Text: systemInstruction},
},
},
DisplayName: "example-cache",
KmsKeyName: "projects/vertexsdk/locations/us-central1/keyRings/your-project/cryptoKeys/your-key",
TTL: "86400s",
}
res, err := client.Caches.Create(ctx, modelName, config)
if err != nil {
return "", fmt.Errorf("failed to create content cache: %w", err)
}
cachedContent, err := json.MarshalIndent(res, "", " ")
if err != nil {
return "", fmt.Errorf("failed to marshal cache info: %w", err)
}
// See the documentation: https://pkg.go.dev/google.golang.org/genai#CachedContent
fmt.Fprintln(w, string(cachedContent))
return res.Name, nil
}