Utilizzare una cache di contesto

Puoi utilizzare le API REST o l'SDK Python per fare riferimento ai contenuti archiviati in un contesto la cache in un'applicazione di AI generativa. Prima di poter essere utilizzato, è necessario crea la cache di contesto.

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

  • name: il nome della risorsa della cache di contesto. Il formato è projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID. Quando crei una cache di contesto, puoi scoprire che il nome della risorsa si trova nella la risposta corretta. Il numero di progetto è un identificatore univoco del progetto. La cache ID è un ID per la cache. Quando specifichi una cache di contesto nel devi utilizzare il nome completo della risorsa della cache di 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 suo formato è projects/PROJECT_NUMBER/locations/LOCATION/publishers/PUBLISHER_NAME/models/MODEL_ID.

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

  • updateTime: un Timestamp che specifica l'ora di aggiornamento più recente di un cache di contesto. Dopo aver creato una cache di contesto e prima di aggiornarla, createTime e updateTime sono uguali.

  • expireTime: un Timestamp che specifica quando scade una cache di contesto. Il valore predefinito di expireTime è 60 minuti dopo createTime. Puoi aggiornare con una nuova scadenza. Per ulteriori informazioni, vedi Aggiorna la cache di contesto.
    Quando una cache scade, viene contrassegnata per l'eliminazione e non devi dare per scontato che può essere utilizzato o aggiornato. Se devi 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à. Tu non devi specificarli di nuovo nella tua richiesta:

  • La proprietà GenerativeModel.system_instructions. Questa proprietà viene utilizzata per specificare istruzioni al modello prima che il modello le riceva 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, ad esempio uno strumento utilizzato dalla funzionalità di chiamata di funzione.

  • La proprietà GenerativeModel.tools. La proprietà GenerativeModel.tools è utilizzato per specificare le funzioni per creare un'applicazione di chiamata di funzione. Per maggiori informazioni le informazioni, vedi Chiamata di funzione.

Utilizza un esempio di cache di contesto

Di seguito viene mostrato come utilizzare una cache di contesto. Quando utilizzi una cache di contesto, non è possibile 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, consulta Installare l'SDK Vertex AI per Python. Per ulteriori informazioni, consulta SDK Vertex AI per Python documentazione di riferimento dell'API.

Risposte dinamiche e non dinamiche

Puoi scegliere se il modello deve generare risposte in streaming oppure risposte non in streaming. Per le risposte dinamiche, ricevi ogni risposta non appena viene generato il relativo token di output. Per le risposte non dinamiche, ricevi tutte le risposte dopo la generazione di 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 = "your-project-id"
# cache_id = "your-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)
# Example response:
# The provided text is about a new family of multimodal models called Gemini, developed by Google.
# ...

Go

Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Vertex AI Guida rapida. Per ulteriori informazioni, consulta la sezione Vertex AI documentazione di riferimento dell'SDK Go per Gemini.

Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta la sezione Configurazione per un ambiente di sviluppo locale.

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 token di output. Per le risposte non dinamiche, ricevi tutte le risposte dopo la generazione di tutti i token di output.

Per una risposta dinamica, utilizza il metodo GenerateContentStream.

  iter := model.GenerateContentStream(ctx, genai.Text("Tell me a story about a lumberjack and his giant ox. Keep it very short."))

Per una risposta non di streaming, utilizza il metodo GenerateContent.

  resp, err := model.GenerateContent(ctx, genai.Text("What is the average size of a swallow?"))

Codice di esempio

import (
	"context"
	"errors"
	"fmt"
	"io"

	"cloud.google.com/go/vertexai/genai"
)

// useContextCache shows how to use an existing cached content, when prompting the model
// contentName is the ID of the cached content
func useContextCache(w io.Writer, contentName string, projectID, location, modelName string) error {
	// location := "us-central1"
	// modelName := "gemini-1.5-pro-001"
	ctx := context.Background()

	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return fmt.Errorf("unable to create client: %w", err)
	}
	defer client.Close()

	model := client.GenerativeModel(modelName)
	model.CachedContentName = contentName
	prompt := genai.Text("What are the papers about?")

	res, err := model.GenerateContent(ctx, prompt)
	if err != nil {
		return fmt.Errorf("error generating content: %w", err)
	}

	if len(res.Candidates) == 0 ||
		len(res.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	fmt.Fprintf(w, "generated response: %s\n", res.Candidates[0].Content.Parts[0])
	return nil
}

REST

Puoi utilizzare REST per utilizzare una cache di contesto con un prompt utilizzando il metodo 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:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la regione in cui viene inviata la richiesta crea la cache di contesto è stato elaborato.
  • MIME_TYPE: il prompt di testo da inviare al modello.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-002: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, 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-002: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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-1.5-pro-002: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-002"
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"
    }
  ],
}'