Vous devez créer un cache de contexte avant de pouvoir l'utiliser. Le cache de contexte que vous créez contient une grande quantité de données dont vous pouvez vous servir dans plusieurs requêtes envoyées à un modèle Gemini. Le contenu mis en cache est stocké dans la région où vous effectuez la requête de création du cache.
Le contenu mis en cache peut être de n'importe quel type MIME compatible avec les modèles multimodaux Gemini. Par exemple, vous pouvez mettre en cache une grande quantité de texte, ou de contenu audio et vidéo. Vous pouvez spécifier plusieurs fichiers à mettre en cache. Pour en savoir plus, consultez ces exigences concernant les contenus multimédias :
Vous spécifiez le contenu à mettre en cache à l'aide d'un blob, d'un texte ou d'un chemin d'accès à un fichier stocké dans un bucket Cloud Storage. Si la taille du contenu que vous mettez en cache est supérieure à 10 Mo, vous devez l'indiquer à l'aide de l'URI d'un fichier stocké dans un bucket Cloud Storage.
La durée de vie du contenu mis en cache est limitée. Le délai d'expiration par défaut d'un cache de contexte est de 60 minutes après sa création. Si vous souhaitez spécifier un délai d'expiration différent, utilisez la propriété ttl
ou expire_time
lorsque vous créez un cache de contexte. Vous pouvez également mettre à jour le délai d'expiration d'un cache de contexte non expiré. Pour savoir comment spécifier ttl
et expire_time
, consultez Mettre à jour un cache de contexte.
Une fois qu'un cache de contexte a expiré, il n'est plus disponible. Si vous souhaitez référencer le contenu d'un cache de contexte expiré dans les futures requêtes, vous devez recréer le cache de contexte.
Compatibilité avec les emplacements
La mise en cache du contexte n'est pas disponible dans la région Sydney, Australie (australia-southeast1
).
La mise en cache du contexte est compatible avec le point de terminaison global.
Compatibilité avec les clés de chiffrement
La mise en cache du contexte est compatible avec les clés de chiffrement gérées par le client (CMEK). Vous pouvez ainsi contrôler le chiffrement de vos données mises en cache et protéger vos informations sensibles à l'aide de clés de chiffrement que vous gérez et possédez. Cela ajoute un niveau de sécurité et de conformité supplémentaire.
Pour en savoir plus, consultez l'exemple.
Les clés CMEK ne sont pas compatibles avec le point de terminaison global.
Compatibilité avec Access Transparency
La mise en cache du contexte est compatible avec Access Transparency.
Exemple de création de cache de contexte
Les exemples suivants montrent comment créer un cache de contexte.
Python
Installer
pip install --upgrade google-genai
Pour en savoir plus, lisez la documentation de référence du SDK.
Définissez les variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :
# 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
Découvrez comment installer ou mettre à jour le Go.
Pour en savoir plus, lisez la documentation de référence du SDK.
Définissez les variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :
# 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
Découvrez comment installer ou mettre à jour le Java.
Pour en savoir plus, lisez la documentation de référence du SDK.
Définissez les variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :
# 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
Installer
npm install @google/genai
Pour en savoir plus, lisez la documentation de référence du SDK.
Définissez les variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :
# 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
Vous pouvez utiliser REST pour créer un cache de contexte à l'aide de l'API Vertex AI afin d'envoyer une requête POST au point de terminaison du modèle de l'éditeur. L'exemple suivant montre comment créer un cache de contexte à l'aide d'un fichier stocké dans un bucket Cloud Storage.
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet.
- LOCATION : région dans laquelle traiter la requête et où le contenu mis en cache est stocké. Pour obtenir la liste des régions compatibles, consultez Régions disponibles.
- CACHE_DISPLAY_NAME : nom significatif à afficher pour décrire et identifier chaque cache de contexte.
- MIME_TYPE : type MIME du contenu à mettre en cache.
- CONTENT_TO_CACHE_URI : URI Cloud Storage du contenu à mettre en cache.
- MODEL_ID : modèle à utiliser pour la mise en cache.
Méthode HTTP et URL :
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents
Corps JSON de la requête :
{ "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." }] }] }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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
Vous devriez recevoir une réponse JSON de ce type :
Exemple de commande curl
LOCATION="us-central1"
MODEL_ID="gemini-2.0-flash-001"
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}"
}
}
]
}
]
}'
Créer un cache de contexte avec CMEK
Pour implémenter la mise en cache du contexte avec des clés CMEK, créez une clé CMEK en suivant les instructions et assurez-vous que le compte de service Vertex AI par produit et par projet (P4SA) dispose des autorisations Chiffreur/Déchiffreur de CryptoKeys Cloud KMS nécessaires sur la clé.
Cela vous permet de créer et de gérer du contenu mis en cache de manière sécurisée, ainsi que d'effectuer d'autres appels tels que {List
, Update
, Delete
, Get
} CachedContent
(s) sans avoir à spécifier une clé KMS à plusieurs reprises.
REST
Vous pouvez utiliser REST pour créer un cache de contexte à l'aide de l'API Vertex AI afin d'envoyer une requête POST au point de terminaison du modèle de l'éditeur. L'exemple suivant montre comment créer un cache de contexte à l'aide d'un fichier stocké dans un bucket Cloud Storage.
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : .
- LOCATION : région dans laquelle traiter la requête et où le contenu mis en cache est stocké. Pour obtenir la liste des régions compatibles, consultez Régions disponibles.
- MODEL_ID : gemini-2.0-flash-001.
- CACHE_DISPLAY_NAME : nom significatif à afficher pour décrire et identifier chaque cache de contexte.
- MIME_TYPE : type MIME du contenu à mettre en cache.
- CACHED_CONTENT_URI : URI Cloud Storage du contenu à mettre en cache.
- KMS_KEY_NAME : nom de la clé Cloud KMS.
Méthode HTTP et URL :
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents
Corps JSON de la requête :
{ "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" } }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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
Vous devriez recevoir une réponse JSON de ce type :
Exemple de commande curl
LOCATION="us-central1"
MODEL_ID="gemini-2.0-flash-001"
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}"
}
}'
SDK GenAI pour Python
Installer
pip install --upgrade google-genai
Pour en savoir plus, consultez la documentation de référence du SDK.
Définissez les variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :
# 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.0-flash-001",
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)
SDK Gen AI pour Go
Découvrez comment installer ou mettre à jour le SDK Gen AI pour Go.
Pour en savoir plus, consultez la documentation de référence du SDK.
Définissez les variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :
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.0-flash-001"
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
}
Étapes suivantes
- Découvrez comment utiliser un cache de contexte.
- Découvrez comment mettre à jour le délai d'expiration d'un cache de contexte.