Utilizzare una cache di contesto

Puoi utilizzare le API REST o l'SDK Python per fare riferimento ai contenuti archiviati in una cache di contesto in un'applicazione di AI generativa. Prima di poterlo utilizzare, devi prima creare la cache del contesto.

L'oggetto cache del contesto che utilizzi nel codice include le seguenti proprietà:

  • name: il nome della risorsa della cache contestuale. Il formato è projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID. Quando crei una cache contestuale, puoi trovare il nome della risorsa nella risposta. Il numero di progetto è un identificatore univoco del progetto. L'ID cache è un ID per la tua cache. Quando specifichi una cache del contesto nel tuo codice, devi utilizzare il nome completo della risorsa della cache del contesto. Di seguito è riportato un esempio che mostra come specificare il nome di una risorsa di contenuti memorizzata nella cache nel corpo di una richiesta:

    "cached_content": "projects/123456789012/locations/us-central1/123456789012345678"

  • model: il nome della risorsa per il modello utilizzato per creare la cache. Il formato è projects/PROJECT_NUMBER/locations/LOCATION/publishers/PUBLISHER_NAME/models/MODEL_ID.

  • createTime: un Timestamp che specifica l'ora di creazione della cache del contesto.

  • updateTime: un Timestamp che specifica l'ora dell'aggiornamento più recente di una cache del contesto. Dopo la creazione di una cache contestuale e prima dell'aggiornamento, i relativi createTime e updateTime sono uguali.

  • expireTime: un Timestamp che specifica la scadenza di una cache contestuale. Il expireTime predefinito è 60 minuti dopo il createTime. Puoi aggiornare la cache con un nuovo tempo di scadenza. Per ulteriori informazioni, vedi Aggiornare la cache del contesto. Una volta scaduta, una cache viene contrassegnata per l'eliminazione e non devi presumere che possa essere utilizzata o aggiornata. Se devi utilizzare una cache di contesto scaduta, devi ricrearla con un tempo di scadenza appropriato.

Limitazioni all'utilizzo della cache contestuale

Quando crei una cache contestuale, puoi specificare le seguenti funzionalità. Non devi specificarli di nuovo nella richiesta:

  • La proprietà GenerativeModel.system_instructions. Questa proprietà viene utilizzata per specificare le istruzioni per il modello prima che riceva istruzioni da un utente. Per ulteriori informazioni, consulta le istruzioni di sistema.

  • La proprietà GenerativeModel.tool_config. La proprietà tool_config viene utilizzata per specificare gli strumenti utilizzati dal modello Gemini, ad esempio uno strumento utilizzato dalla funzionalità chiamata di funzione.

  • La proprietà GenerativeModel.tools. La proprietà GenerativeModel.tools viene utilizzata per specificare le funzioni per creare un'applicazione di chiamata di funzione. Per ulteriori informazioni, vedi Chiamata di funzioni.

Utilizzare un esempio di cache contestuale

Di seguito viene mostrato come utilizzare una cache di contesto. Quando utilizzi una cache di contesto, non puoi specificare le seguenti proprietà:

  • GenerativeModel.system_instructions
  • GenerativeModel.tool_config
  • GenerativeModel.tools

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
 

from google import genai
from google.genai.types import GenerateContentConfig, HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))
# Use content cache to generate text response
# E.g cache_name = 'projects/111111111111/locations/us-central1/cachedContents/1111111111111111111'
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Summarize the pdfs",
    config=GenerateContentConfig(
        cached_content=cache_name,
    ),
)
print(response.text)
# Example response
#   The Gemini family of multimodal models from Google DeepMind demonstrates remarkable capabilities across various
#   modalities, including image, audio, video, and text....

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
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// useContentCacheWithTxt shows how to use content cache to generate text content.
func useContentCacheWithTxt(w io.Writer, cacheName string) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	resp, err := client.Models.GenerateContent(ctx,
		"gemini-2.0-flash-001",
		genai.Text("Summarize the pdfs"),
		&genai.GenerateContentConfig{
			CachedContent: cacheName,
		},
	)
	if err != nil {
		return fmt.Errorf("failed to use content cache to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The provided research paper introduces Gemini 1.5 Pro, a multimodal model capable of recalling
	// and reasoning over information from very long contexts (up to 10 million tokens).  Key findings include:
	//
	// * **Long Context Performance:**
	// ...

	return nil
}

REST

Puoi utilizzare REST per utilizzare una cache contestuale con un prompt utilizzando l'API Vertex AI per inviare una richiesta POST all'endpoint del modello del publisher.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent

Corpo JSON della richiesta: 

{
  "cachedContent": "projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID",
  "contents": [
      {"role":"user","parts":[{"text":"PROMPT_TEXT"}]}
  ],
  "generationConfig": {
      "maxOutputTokens": 8192,
      "temperature": 1,
      "topP": 0.95,
  },
  "safetySettings": [
      {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      },
      {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      },
      {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      },
      {
          "category": "HARM_CATEGORY_HARASSMENT",
          "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      }
  ],
}

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/publishers/google/models/gemini-2.0-flash-001:generateContent"

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/publishers/google/models/gemini-2.0-flash-001:generateContent" | 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"

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}/publishers/google/models/${MODEL_ID}:generateContent" -d \
'{
  "cachedContent": "projects/${PROJECT_NUMBER}/locations/${LOCATION}/cachedContents/${CACHE_ID}",
  "contents": [
      {"role":"user","parts":[{"text":"What are the benefits of exercise?"}]}
  ],
  "generationConfig": {
      "maxOutputTokens": 8192,
      "temperature": 1,
      "topP": 0.95,
  },
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HATE_SPEECH",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    }
  ],
}'