O armazenamento em cache de contexto

Em um fluxo de trabalho de IA típico, é possível transmitir os mesmos tokens de entrada várias vezes para um modelo. A API Gemini oferece dois mecanismos de cache diferentes:

  • Armazenamento em cache implícito (ativado automaticamente nos modelos do Gemini 2.5, sem garantia de economia de custos)
  • Armazenamento em cache explícito (pode ser ativado manualmente na maioria dos modelos, garantia de economia de custos)

O armazenamento em cache explícito é útil quando você quer garantir economia de custos, mas com algum trabalho extra do desenvolvedor.

Armazenamento em cache implícito

O armazenamento em cache implícito é ativado por padrão para todos os modelos do Gemini 2.5. Transferimos automaticamente a economia de custos se sua solicitação atingir os caches. Não é necessário fazer nada para ativar esse recurso. Ela entra em vigor em 8 de maio de 2025. A contagem mínima de tokens de entrada para o cache de contexto é de 1.024 para o 2.5 Flash e de 4.096 para o 2.5 Pro.

Para aumentar a chance de uma ocorrência implícita em cache:

  • Tente colocar conteúdos grandes e comuns no início do comando
  • Tente enviar solicitações com prefixos semelhantes em um curto período

Você pode conferir o número de tokens que foram hits de cache no campo usage_metadata do objeto de resposta.

Armazenamento em cache explícito

Com o recurso de armazenamento em cache explícito da API Gemini, é possível transmitir algum conteúdo para o modelo uma vez, armazenar em cache os tokens de entrada e consultar os tokens armazenados para solicitações subsequentes. Em determinados volumes, usar tokens em cache é mais barato do que transmitir o mesmo conjunto de tokens repetidamente.

Ao armazenar em cache um conjunto de tokens, você pode escolher por quanto tempo quer que o cache exista antes que os tokens sejam excluídos automaticamente. Essa duração do armazenamento em cache é chamada de time to live (TTL). Se não for definido, o TTL será de 1 hora. O custo do armazenamento em cache depende do tamanho do token de entrada e de quanto tempo você quer que os tokens persistam.

Nesta seção, presumimos que você instalou um SDK do Gemini (ou tem o curl instalado) e que configurou uma chave de API, conforme mostrado no início rápido.

Gerar conteúdo usando um cache

O exemplo a seguir mostra como gerar conteúdo usando uma instrução do sistema em cache e um arquivo de vídeo.

Vídeos

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

client = genai.Client()

# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
  with path_to_video_file.open('wb') as wf:
    response = requests.get(url, stream=True)
    for chunk in response.iter_content(chunk_size=32768):
      wf.write(chunk)

# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)

# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
  print('Waiting for video to be processed.')
  time.sleep(2)
  video_file = client.files.get(name=video_file.name)

print(f'Video processing complete: {video_file.uri}')

# You must use an explicit version suffix: "-flash-001", not just "-flash".
model='models/gemini-2.0-flash-001'

# Create a cache with a 5 minute TTL
cache = client.caches.create(
    model=model,
    config=types.CreateCachedContentConfig(
      display_name='sherlock jr movie', # used to identify the cache
      system_instruction=(
          'You are an expert video analyzer, and your job is to answer '
          'the user\'s query based on the video file you have access to.'
      ),
      contents=[video_file],
      ttl="300s",
  )
)

# Construct a GenerativeModel which uses the created cache.
response = client.models.generate_content(
  model = model,
  contents= (
    'Introduce different characters in the movie by describing '
    'their personality, looks, and names. Also list the timestamps '
    'they were introduced for the first time.'),
  config=types.GenerateContentConfig(cached_content=cache.name)
)

print(response.usage_metadata)

# The output should look something like this:
#
# prompt_token_count: 696219
# cached_content_token_count: 696190
# candidates_token_count: 214
# total_token_count: 696433

print(response.text)

PDFs

from google import genai
from google.genai import types
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"

# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

document = client.files.upload(
  file=doc_io,
  config=dict(mime_type='application/pdf')
)

model_name = "gemini-2.0-flash-001"
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
      system_instruction=system_instruction,
      contents=[document],
    )
)

# Display the cache details
print(f'{cache=}')

# Generate content using the cached prompt and document
response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

# (Optional) Print usage metadata for insights into the API call
print(f'{response.usage_metadata=}')

# Print the generated text
print('\n\n', response.text)

Listar caches

Não é possível recuperar ou visualizar o conteúdo armazenado em cache, mas você pode recuperar metadados de cache (name, model, display_name, usage_metadata, create_time, update_time e expire_time).

Para listar metadados de todos os caches enviados, use CachedContent.list():

for cache in client.caches.list():
  print(cache)

Para buscar os metadados de um objeto de cache, se você souber o nome dele, use get:

client.caches.get(name=name)

Atualizar um cache

É possível definir um novo ttl ou expire_time para um cache. Não é possível mudar mais nada sobre o cache.

O exemplo a seguir mostra como atualizar o ttl de um cache usando client.caches.update().

from google import genai
from google.genai import types

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      ttl='300s'
  )
)

Para definir o horário de expiração, ele aceita um objeto datetime ou uma string de data e hora formatada em ISO (dt.isoformat(), como 2025-01-27T16:02:36.473528+00:00). Seu horário precisa incluir um fuso horário (datetime.utcnow() não anexa um fuso horário, datetime.now(datetime.timezone.utc) anexa).

from google import genai
from google.genai import types
import datetime

# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      expire_time=in10min
  )
)

Excluir um cache

O serviço de cache oferece uma operação de exclusão para remover manualmente o conteúdo do cache. O exemplo a seguir mostra como excluir um cache:

client.caches.delete(cache.name)

Cache explícito usando a biblioteca OpenAI

Se você estiver usando uma biblioteca da OpenAI, poderá ativar o armazenamento em cache explícito usando a propriedade cached_content em extra_body.

Quando usar o armazenamento em cache explícito

O armazenamento em cache de contexto é particularmente adequado para cenários em que um contexto inicial substancial é referenciado repetidamente por solicitações mais curtas. Use armazenamento em cache de contexto para casos de uso como estes:

  • Chatbots com instruções do sistema abrangentes
  • Análise repetitiva de arquivos de vídeo longos
  • Consultas recorrentes em grandes conjuntos de documentos
  • Análise frequente do repositório de código ou correção de bugs

Como o armazenamento em cache explícito reduz os custos

O armazenamento em cache de contexto é um recurso pago projetado para reduzir os custos operacionais gerais. O faturamento é baseado nos seguintes fatores:

  1. Contagem de tokens de cache: o número de tokens de entrada armazenados em cache, faturados com uma taxa reduzida quando incluído nos comandos subsequentes.
  2. Duração do armazenamento:o tempo de armazenamento dos tokens em cache (TTL), faturado com base na duração do TTL da contagem de tokens em cache. Não há limites mínimos ou máximos para o TTL.
  3. Outros fatores: outras cobranças se aplicam, como tokens de entrada não armazenados em cache e tokens de saída.

Para detalhes atualizados sobre preços, consulte a página de preços da API Gemini. Para saber como contar tokens, consulte o guia de tokens.

Outras considerações

Considere o seguinte ao usar o cache de contexto:

  • A contagem mínima de tokens de entrada para o cache de contexto é de 1.024 para o Flash 2.5 e de 2.048 para o Pro 2.5. O máximo é igual ao máximo do modelo especificado. Para mais informações sobre como contar tokens, consulte o guia de tokens.
  • O modelo não faz distinção entre tokens armazenados em cache e tokens de entrada regulares. O conteúdo armazenado em cache é um prefixo do comando.
  • Não há limites de uso ou taxas especiais no cache de contexto. Os limites de taxa padrão para GenerateContent se aplicam, e os limites de token incluem tokens armazenados em cache.
  • O número de tokens armazenados em cache é retornado no usage_metadata das operações "create", "get" e "list" do serviço de cache, e também em GenerateContent ao usar o cache.