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 IA generativa. Prima di poter essere utilizzata, devi creare la cache di contesto.

L'oggetto cache di contesto utilizzato nel codice include le seguenti proprietà:

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

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

  • model: il nome della risorsa per il modello utilizzato per creare la cache. Il suo formato è projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID.

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

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

  • expireTime: un Timestamp che specifica quando scade una cache contestuale. Il valore predefinito di expireTime è 60 minuti dopo il createTime. Puoi aggiornare la cache con una nuova scadenza. Per maggiori informazioni, vedi Aggiornare la cache di contesto.
    Quando una cache scade, viene contrassegnata per l'eliminazione e non devi dare per scontato che possa essere utilizzata o aggiornata. Per utilizzare una cache di contesto scaduta, devi ricrearla con una data di scadenza appropriata.

Limitazioni all'utilizzo della cache di contesto

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

  • La proprietà GenerativeModel.system_instructions. Questa proprietà viene utilizzata per specificare le istruzioni del modello prima che quest'ultimo riceva istruzioni da un utente. Per ulteriori informazioni, vedi Istruzioni di sistema.

  • La proprietà GenerativeModel.tool_config. La proprietà tool_config viene utilizzata per specificare gli strumenti utilizzati dal modello Gemini, come uno strumento utilizzato dalla funzionalità chiamate 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, consulta Chiamate di funzione.

Utilizza un esempio di cache di contesto

Di seguito viene illustrato 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

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Vertex AI SDK per Python.

Risposte dinamiche e non dinamiche

Puoi scegliere se il modello genera risposte in streaming o non in streaming. Per le risposte dinamiche, ricevi ogni risposta non appena viene generato il relativo token di output. Per le risposte non in streaming, riceverai tutte le risposte dopo che sono stati generati tutti i token di output.

Per una risposta in modalità flusso, utilizza il parametro stream in generate_content.

  response = model.generate_content(contents=[...], stream = True)

Per una risposta non in streaming, rimuovi il parametro o impostalo su False.

Codice di esempio

import vertexai

from vertexai.preview.generative_models import GenerativeModel
from vertexai.preview import caching

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# cache_id = "CACHE_ID"

vertexai.init(project=project_id, location="us-central1")

cached_content = caching.CachedContent(cached_content_name=cache_id)

model = GenerativeModel.from_cached_content(cached_content=cached_content)

response = model.generate_content("What are the papers about?")

print(response.text)

REST

Puoi utilizzare REST per usare una cache di contesto 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, effettua le seguenti sostituzioni:

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-001:generateContent

Corpo JSON della richiesta: 

{
  "cached_content": "projects/PROJECT_NUMBER/locations/LOCATION/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 delle seguenti 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-001:generateContent"

PowerShell

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-001:generateContent" | 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-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 \
'{
  "cached_content": "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"
    }
  ],
}'