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:
Specifichi 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
, consulta
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.
Limiti
I contenuti memorizzati nella cache devono rispettare i limiti indicati nella tabella seguente:
Limiti della memorizzazione nella cache del contesto | |
---|---|
Numero minimo di token della cache |
|
Dimensione massima dei contenuti che puoi memorizzare nella cache utilizzando un blob o un testo |
10 MB |
Tempo minimo prima della scadenza di una cache dopo la creazione |
1 minuto |
Tempo massimo prima della scadenza di una cache dopo la sua creazione |
Non esiste una durata massima della cache |
Supporto per la posizione
La memorizzazione nella cache del contesto non è supportata nella regione Sydney, Australia
(australia-southeast1
).
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.
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 contestuale utilizzando l'API Vertex AI per inviare una richiesta POST all'endpoint del modello del publisher. L'esempio seguente mostra come creare una cache contestuale 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 è memorizzato 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
,
quindi esegui il comando seguente:
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 chiavi CMEK, crea una chiave CMEK seguendo
le istruzioni e assicurati che l'account di servizio per prodotto e per progetto Vertex AI (P4SA) disponga delle autorizzazioni Autore crittografia/decrittografia CryptoKey Cloud KMS necessarie per la 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 contestuale utilizzando l'API Vertex AI per inviare una richiesta POST all'endpoint del modello del publisher. L'esempio seguente mostra come creare una cache contestuale 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 è memorizzato 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
,
quindi esegui il comando seguente:
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 contestuale.