Usar um cache de contexto

É possível usar APIs REST ou o SDK Python para referenciar conteúdo armazenado em um cache de contexto em um aplicativo de IA generativa. Antes de usar, é necessário criar o cache de contexto.

O objeto de cache de contexto usado no código inclui as seguintes propriedades:

  • name: o nome do recurso do cache de contexto. O formato é projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID. Quando você cria um cache de contexto, o nome do recurso dele está na resposta. O número do projeto é um identificador exclusivo. O ID do cache é um ID para seu cache. Ao especificar um cache de contexto no código, use o nome completo do recurso do cache de contexto. Confira a seguir um exemplo que mostra como especificar um nome de recurso de conteúdo em cache no corpo da solicitação:

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

  • model: o nome do recurso do modelo usado para criar o cache. O formato é projects/PROJECT_NUMBER/locations/LOCATION/publishers/PUBLISHER_NAME/models/MODEL_ID.

  • createTime: uma Timestamp que especifica o horário de criação do cache de contexto.

  • updateTime: uma Timestamp que especifica o horário da atualização mais recente de um cache de contexto. Depois que um cache de contexto é criado e antes de ser atualizado, o createTime e o updateTime são iguais.

  • expireTime: uma Timestamp que especifica quando um cache de contexto expira. O expireTime padrão é 60 minutos após o createTime. É possível atualizar o cache com um novo tempo de expiração. Para mais informações, consulte Atualizar o cache de contexto.
    Depois que um cache expira, ele é marcado para exclusão, e não se pode presumir que ele possa ser usado ou atualizado. Se você precisar usar um cache de contexto expirado, precisará recriar o cache com um tempo de expiração adequado.

Restrições de uso do cache de contexto

Os recursos a seguir podem ser especificados ao criar um cache de contexto. Não especifique-os novamente na solicitação:

  • A propriedade GenerativeModel.system_instructions. Essa propriedade é usada para especificar instruções para o modelo antes que ele receba instruções de um usuário. Para mais informações, consulte Instruções do sistema.

  • A propriedade GenerativeModel.tool_config. A propriedade tool_config é usada para especificar ferramentas usadas pelo modelo Gemini, como uma ferramenta usada pelo recurso chamadas de função.

  • A propriedade GenerativeModel.tools. A propriedade GenerativeModel.tools é usada para especificar funções para criar um aplicativo de chamada de função. Para mais informações, consulte Chamada de função.

Usar um exemplo de cache de contexto

Confira a seguir como usar um cache de contexto. Ao usar um cache de contexto, não é possível especificar as seguintes propriedades:

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

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python.

Respostas com e sem streaming

Escolha se o modelo vai gerar respostas de streaming ou sem streaming. Para respostas de streaming, você recebe cada resposta assim que o token de saída for gerado. Para respostas que não são de streaming, você recebe todas as respostas depois que todos os tokens de saída forem gerados.

Para uma resposta de streaming, use o parâmetro stream em generate_content.

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

Para uma resposta que não seja de streaming, remova o parâmetro ou defina-o como False.

Código de amostra

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

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido da Vertex AI. Para mais informações, consulte a documentação de referência do SDK da Vertex AI para Go para Gemini.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Respostas com e sem streaming

Escolha se o modelo vai gerar respostas de streaming ou sem streaming. Para respostas de streaming, você recebe cada resposta assim que o token de saída for gerado. Para respostas que não são de streaming, você recebe todas as respostas depois que todos os tokens de saída forem gerados.

Para uma resposta de streaming, use o método GenerateContentStream.

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

Para uma resposta que não seja de streaming, use o método GenerateContent.

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

Código de amostra

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

É possível usar o REST para usar um cache de contexto com um comando usando a API Vertex AI para enviar uma solicitação POST ao endpoint do modelo do editor.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

Método 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 da solicitação:

{
  "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"
      }
  ],
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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

Você receberá uma resposta JSON semelhante a seguinte.

Exemplo de comando curl

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 \
'{
  "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"
    }
  ],
}'