Devi creare una cache del contesto prima di poterla utilizzare. La cache contestuale che crei contiene una grande quantità di dati che puoi utilizzare in più richieste a un modello Gemini. I contenuti memorizzati nella cache vengono archiviati nella regione in cui effettui la richiesta di creazione della cache.
I contenuti memorizzati nella cache possono essere uno qualsiasi dei tipi MIME supportati dai modelli multimodali Gemini. Ad esempio, puoi memorizzare nella cache una grande quantità di testo, audio o video. Puoi specificare più di un file da memorizzare nella cache. Per maggiori informazioni, consulta i seguenti requisiti relativi ai contenuti multimediali:
Specifica i contenuti da memorizzare nella cache utilizzando un blob, un testo o un percorso di un file memorizzato in un bucket Cloud Storage. Se le dimensioni dei contenuti che memorizzi nella cache sono superiori a 10 MB, devi specificarle utilizzando l'URI di un file memorizzato in un bucket Cloud Storage.
I contenuti memorizzati nella cache hanno una durata limitata. Il tempo di scadenza predefinito di una cache
di contesto è 60 minuti dopo la creazione. Se vuoi un tempo di scadenza diverso,
puoi specificarlo utilizzando la proprietà ttl o expire_time
quando crei una cache del contesto. Puoi anche aggiornare l'ora di scadenza
per una cache del contesto non scaduta. Per informazioni su come specificare
ttl e expire_time, vedi
Aggiornare il tempo di scadenza.
Una volta scaduta, la cache del contesto non è più disponibile. Se vuoi fare riferimento ai contenuti in una cache del contesto scaduta nelle richieste future, devi ricreare la cache del contesto.
Supporto per la posizione
La memorizzazione nella cache del contesto non è supportata nella regione Sydney, Australia
(australia-southeast1).
La memorizzazione nella cache del contesto supporta l'endpoint globale.
Supporto delle chiavi di crittografia
La memorizzazione nella cache del contesto supporta le chiavi di crittografia gestite dal cliente (CMEK), consentendoti di controllare la crittografia dei dati memorizzati nella cache e proteggere le tue informazioni sensibili con chiavi di crittografia che gestisci e di cui sei proprietario. Ciò fornisce un ulteriore livello di sicurezza e conformità.
Per maggiori dettagli, consulta l'esempio.
CMEK non è supportata quando utilizzi l'endpoint globale.
Supporto di Access Transparency
La memorizzazione nella cache del contesto supporta Access Transparency.
Crea esempio di cache del contesto
Gli esempi riportati di seguito mostrano come creare una cache del contesto.
Python
Installa
pip install --upgrade google-genai
Per saperne di più, consulta la documentazione di riferimento dell'SDK.
Imposta le variabili di ambiente per utilizzare l'SDK Gen AI con 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
Scopri come installare o aggiornare Go.
Per saperne di più, consulta la documentazione di riferimento dell'SDK.
Imposta le variabili di ambiente per utilizzare l'SDK Gen AI con 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
Puoi utilizzare REST per creare una cache del contesto utilizzando l'API Vertex AI per inviare una richiesta POST all'endpoint del modello del publisher. L'esempio seguente mostra come creare una cache del contesto utilizzando un file archiviato in un bucket Cloud Storage.
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto
- LOCATION: la regione in cui elaborare la richiesta e in cui è archiviato il contenuto memorizzato nella cache. Per un elenco delle regioni supportate, consulta Regioni disponibili.
- CACHE_DISPLAY_NAME: un nome visualizzato significativo per descrivere e aiutarti a identificare ogni cache del contesto.
- MIME_TYPE: Il tipo MIME dei contenuti da memorizzare nella cache.
- CONTENT_TO_CACHE_URI: l'URI Cloud Storage dei contenuti da memorizzare nella cache.
- MODEL_ID: il modello da utilizzare per la memorizzazione nella cache.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents
Corpo JSON della richiesta:
{
"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."
}]
}]
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
ed esegui questo comando:
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
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$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
Dovresti ricevere una risposta JSON simile alla seguente:
Comando curl di esempio
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}"
}
}
]
}
]
}'
Crea una cache del contesto con CMEK
Per implementare la memorizzazione nella cache del contesto con le CMEK, crea una CMEK seguendo
le istruzioni e assicurati che l'account di servizio per prodotto e per progetto Vertex AI (P4SA) disponga delle
autorizzazioni necessarie per la crittografia/decrittografia CryptoKey Cloud KMS sulla chiave.
In questo modo puoi creare e gestire in modo sicuro i contenuti memorizzati nella cache, nonché effettuare
altre chiamate come {List, Update, Delete, Get} CachedContent senza
specificare ripetutamente una chiave KMS.
REST
Puoi utilizzare REST per creare una cache del contesto utilizzando l'API Vertex AI per inviare una richiesta POST all'endpoint del modello del publisher. L'esempio seguente mostra come creare una cache del contesto utilizzando un file archiviato in un bucket Cloud Storage.
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: .
- LOCATION: la regione in cui elaborare la richiesta e in cui è archiviato il contenuto memorizzato nella cache. Per un elenco delle regioni supportate, consulta Regioni disponibili.
- MODEL_ID: gemini-2.0-flash-001.
- CACHE_DISPLAY_NAME: un nome visualizzato significativo per descrivere e aiutarti a identificare ogni cache del contesto.
- MIME_TYPE: Il tipo MIME dei contenuti da memorizzare nella cache.
- CACHED_CONTENT_URI: l'URI Cloud Storage dei contenuti da memorizzare nella cache.
- KMS_KEY_NAME: il nome della chiave Cloud KMS.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents
Corpo JSON della richiesta:
{
"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"
}
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
ed esegui questo comando:
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
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$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
Dovresti ricevere una risposta JSON simile alla seguente:
Comando curl di esempio
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 per Python
Installa
pip install --upgrade google-genai
Per saperne di più, consulta la documentazione di riferimento dell'SDK.
Imposta le variabili di ambiente per utilizzare l'SDK Gen AI con 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 GenAI per Go
Scopri come installare o aggiornare l'SDK Gen AI per Go.
Per saperne di più, consulta la documentazione di riferimento dell'SDK.
Imposta le variabili di ambiente per utilizzare l'SDK Gen AI con 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
}
Passaggi successivi
- Scopri come utilizzare una cache contestuale.
- Scopri come aggiornare il tempo di scadenza di una cache di contesto.