Crea una cache di contesto

Devi creare una cache di contesto prima di poterla utilizzare. La cache di contesto 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 dei tipi MIME supportati dai modelli multimodali di 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 ulteriori informazioni, consulta i seguenti requisiti relativi ai contenuti multimediali:

Specifica i contenuti da memorizzare nella cache utilizzando un blob, del testo o il percorso di un file archiviato 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 archiviato in un bucket Cloud Storage.

La durata dei contenuti memorizzati nella cache è limitata. La scadenza predefinita di una cache contestuale è 60 minuti dopo la creazione. Se vuoi un'ora di scadenza diversa, puoi specificarne una utilizzando la proprietà ttl o expire_time quando crei una cache di contesto. Puoi anche aggiornare la data di scadenza per una cache di contesto non scaduta. Per informazioni su come specificare ttl e expire_time, consulta Aggiornare la data e l'ora di scadenza.

Una volta scaduta, una cache di contesto non è più disponibile. Se vuoi fare riferimento ai contenuti di una cache di contesto scaduta nelle richieste di prompt future, devi ricreare la cache di contesto.

Limiti

I contenuti memorizzati nella cache devono rispettare i limiti indicati nella tabella riportata di seguito:

Limiti della memorizzazione nella cache del contesto

Dimensioni minime di una cache

 32.769 token

Dimensioni massime dei contenuti che puoi memorizzare nella cache utilizzando un blob o del testo

 10 MB

Tempo minimo prima della scadenza di una cache dopo la sua creazione

 1 minuto

Tempo massimo prima della scadenza di una cache dopo la sua creazione

 Non esiste una durata massima della cache

Assistenza per la posizione

La memorizzazione nella cache del contesto non è supportata nella regione di Sydney, Australia (australia-southeast1).

Supporto delle chiavi di crittografia

La memorizzazione nella cache del contesto non supporta le chiavi di crittografia gestite dal cliente (CMEK).

Supporto per la trasparenza degli accessi

La memorizzazione nella cache del contesto supporta la trasparenza degli accessi.

Esempio di creazione della cache del contesto

Gli esempi riportati di seguito mostrano come creare una cache di contesto.

Gen AI SDK for Python

Installa

pip install --upgrade google-genai
 Per scoprire 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
 

from google import genai
from google.genai.types import Content, CreateCachedContentConfig, HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))

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",
        ttl="86400s",
    ),
)

print(content_cache.name)
print(content_cache.usage_metadata)
# Example response:
#   projects/111111111111/locations/us-central1/cachedContents/1111111111111111111
#   CachedContentUsageMetadata(audio_duration_seconds=None, image_count=167,
#       text_count=153, total_token_count=43130, video_duration_seconds=None)

REST

Puoi utilizzare REST per creare una cache di 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 di 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 vengono archiviati i contenuti memorizzati nella cache. Per un elenco delle regioni supportate, consulta Regioni disponibili.
  • CACHE_DISPLAY_NAME: un nome visualizzato significativo per descrivere e 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.

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-1.5-pro-002",
  "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 delle seguenti 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-1.5-pro-002"
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}"
          }
        }
      ]
    }
  ]
}'

Passaggi successivi