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 pode ser encontrado 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 é seguro assumir que ele pode 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 chamada 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

Gen AI SDK for Python

Instalar

pip install --upgrade google-genai
 Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK da IA generativa com a 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="v1beta1"))

# 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.0-flash-001",
    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....

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/v1/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/v1/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/v1/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"
    }
  ],
}'