Economizando Tokens do Gemini através do uso de Context Caching Implícito e Explícito

Sumário (TL/DR): Este artigo explora os desafios de custo e latência em aplicações que demandam o uso de grandes janelas de contexto e como a proposta de Context Caching do Google Cloud viabiliza economicamente o processamento de grandes volumes de dados.

1. Contexto: O Divisor de Águas do Milhão de Tokens

A janela de contexto de 1 milhão de tokens do Gemini abriu as portas para casos de uso que antes seriam completamente inviáveis na inteligência artificial generativa. Situações recorrentes envolvem o processamento de áudios de reuniões de várias horas para gerar atas, análise de vídeos extensos para detecção de eventos ou auditorias de segurança, e até o uso de System Instructions extensas, onde personas complexas e regras de negócio rígidas precisam ser “lembradas” pelo modelo em cada interação.

No entanto, um dos cenários mais emblemáticos para esta tecnologia é o setor jurídico. Imagine um “megaprocesso” de falência corporativa ou uma disputa fundiária que se arrasta por anos. Os autos digitais desse processo hipotético ultrapassam facilmente várias centenas de páginas, acumulando laudos periciais, transcrições de depoimentos, petições de dezenas de advogados e decisões interlocutórias.

Neste cenário, um magistrado ou assessor precisa extrair informações cruzadas: “Onde o perito mencionou a depreciação do imóvel X em relação ao depoimento da testemunha Y realizado há dois anos?”. O sistema de IA tem a capacidade técnica de ler essa “enciclopédia” jurídica, mas ao trabalhar com processos extensos (acima de 32.768 tokens), surgem dois obstáculos críticos para a viabilidade do projeto:

1. Custo de Reprocessamento: Cada nova pergunta sobre o mesmo conjunto de documentos exige que o modelo processe integralmente todos os tokens novamente. Em um chat com 10 iterações, o custo de entrada é multiplicado por dez, tornando a solução proibitiva.
2. Gargalo de Latência: O modelo leva um tempo considerável para realizar o “aquecimento” e a leitura do volume massivo de dados antes de começar a responder. Em um ambiente de tomada de decisão, essa espera prejudica a produtividade e a fluidez do uso da solução.

2. O que é Cache e a Proposta do Gemini

Na computação tradicional, o conceito de Cache é fundamental: trata-se de uma camada de armazenamento de alta velocidade que retém um subconjunto de dados para que solicitações futuras sejam atendidas de forma muito mais rápida.

O Context Caching do Gemini permite preservar o estado de processamento dos tokens de entrada. Em vez de repetir o esforço computacional de atenção e codificação a cada nova consulta em documentos extensos, o Google Cloud permite ‘congelar’ esse estado. Na prática, isso converte o custo variável de reprocessamento em um custo fixo de armazenamento, resultando em uma redução considerável de custos e do tempo de resposta inicial (TTFT). Conforme documentação, no momento da escrita deste artigo, o token de entrada referenciado no cache têm 90% de desconto.

Configuração da Engine de Execução

Para os exemplos abaixo, utilizaremos uma função auxiliar baseada em curl para interagir diretamente com a API REST do Vertex AI, garantindo total controle sobre os cabeçalhos e payloads.

import subprocess
import json
import os
import time

# --- CONFIGURAÇÕES ---
# O ID do projeto foi atualizado para o seu ambiente de testes
PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT", "[SEU-PROJECT-ID]")
LOCATION = "global"

if LOCATION == "global":
   API_ENDPOINT = "aiplatform.googleapis.com"
else:
   API_ENDPOINT = f"{LOCATION}-aiplatform.googleapis.com"

MODEL_ID = "gemini-3-flash-preview"

def run_curl(method, path, data=None):
   """Executa um comando curl e retorna o JSON de resposta."""
   # Obtém o token de autenticação via gcloud
   token_proc = subprocess.run(["gcloud", "auth", "print-access-token"], capture_output=True, text=True)
   token = token_proc.stdout.strip()

   url = f"https://{API_ENDPOINT}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/{path}"

   cmd = [
       "curl", "-s", "-X", method,
       "-H", f"Authorization: Bearer {token}",
       "-H", "Content-Type: application/json",
       url
   ]

   if data:
       cmd += ["-d", json.dumps(data)]

   result = subprocess.run(cmd, capture_output=True, text=True)

   if not result.stdout:
       return {"error": "Sem resposta da API (stdout vazio)", "details": result.stderr}

   try:
       return json.loads(result.stdout)
   except json.JSONDecodeError:
       return {"error": "Falha ao decodificar JSON", "raw": result.stdout}

3. Abordagem 1: Cache Implícito (Otimização Automática)

O **Cache Implícito** detecta automaticamente prefixos comuns de tokens e os armazena sem intervenção manual. É a solução ideal para fluxos de conversação onde o contexto (os autos do processo) permanece fixo enquanto as perguntas mudam.

def test_implicit_caching():
   print("\n--- TESTANDO CACHE IMPLÍCITO ---")

   # 1. Garantir que o cache está habilitado no projeto (ele é habilitado por padrão)
   print("Ativando o cache no projeto...")
   run_curl("PATCH", "cacheConfig", {
       "name": f"projects/{PROJECT_ID}/locations/{LOCATION}/cacheConfig",
       "disableCache": False
   })

   # 2. Enviar requisições repetidas com o mesmo prefixo
   # Incluindo um PDF e texto longo para garantir que passamos do limite mínimo de tokens
   payload = {
       "contents": [{
           "role": "user",
           "parts": [
               {
                   "fileData": {
                       "mimeType": "application/pdf",
                       "fileUri": "gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
                   }
               },
               {"text": "Este é um contexto muito longo que deve ser repetido para testar o cache... " * 100},
               {"text": "Pergunta: Resume o documento PDF e o texto acima."}
           ]
       }]
   }

   for i in range(1, 4):
       print(f"Tentativa {i}...")
       response = run_curl("POST", f"publishers/google/models/{MODEL_ID}:generateContent", payload)

       if "error" in response:
           print(f"Erro na API: {json.dumps(response, indent=2)}")
           break

       usage = response.get("usageMetadata", {})
       cached_tokens = usage.get("cachedContentTokenCount", 0)
       print(f"Tokens de entrada: {usage.get('promptTokenCount')}")
       print(f"Tokens em cache: {cached_tokens}")

       if cached_tokens > 0:
           print("✓ Cache hit detectado no cache implícito!")
           break
       time.sleep(1)

4. Abordagem 2: Cache Explícito (Controle de Infraestrutura)

O **Cache Explícito** é um recurso gerenciado onde o desenvolvedor cria, atualiza e deleta o cache manualmente. É a escolha para sistemas multiusuário onde o custo de armazenamento é compartilhado entre centenas de consultas ao mesmo processo jurídico.

def test_explicit_caching():
   print("\n--- TESTANDO CACHE EXPLÍCITO ---")

   # 1. Criar o Context Cache
   print("Criando cache explícito...")
   cache_config = {
       "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}",
       "contents": [{
           "role": "user",
           "parts": [
               {"fileData": {"mimeType": "application/pdf", "fileUri": "gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"}},
               {"fileData": {"mimeType": "application/pdf", "fileUri": "gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf"}}
           ]
       }],
       "ttl": "600s"
   }

   cache_response = run_curl("POST", "cachedContents", cache_config)

   if "error" in cache_response:
       print(f"Erro ao criar cache: {json.dumps(cache_response, indent=2)}")
       return

   cache_name = cache_response.get("name")
   print(f"Cache criado com sucesso: {cache_name}")

   # 2. Usar o Cache para gerar conteúdo
   print("Enviando pergunta usando o cache criado...")
   query_payload = {
       "contents": [{
           "role": "user",
           "parts": [{"text": "Qual o objetivo comum destes dois artigos?"}]
       }],
       "cachedContent": cache_name
   }

   gen_response = run_curl("POST", f"publishers/google/models/{MODEL_ID}:generateContent", query_payload)

   if "error" in gen_response:
       print(f"Erro ao gerar conteúdo: {json.dumps(gen_response, indent=2)}")
   elif "candidates" not in gen_response:
       print(f"Resposta inesperada da API: {json.dumps(gen_response, indent=2)}")
   else:
       usage = gen_response.get("usageMetadata", {})
       text = gen_response['candidates'][0]['content']['parts'][0].get('text', 'Sem texto na resposta.')
       print(f"Resposta do modelo: {text[:100]}...")
       print(f"Tokens em cache utilizados: {usage.get('cachedContentTokenCount')}")

   # 3. Atualizar TTL do cache
   print("Atualizando o tempo de expiração (TTL)...")
   run_curl("PATCH", cache_name, {"ttl": "3600s"})
   # 4. Eliminar o cache
   print("Limpeza: Eliminando o cache...")
   run_curl("DELETE", cache_name)
   print("Cache eliminado.")
if __name__ == "__main__":
   if PROJECT_ID == "[SEU-PROJECT-ID]":
       print("Por favor, configure o PROJECT_ID no script ou na variável de ambiente.")
   else:
       test_implicit_caching()
       test_explicit_caching()

5. Teoria: Comparativo de Estratégias

Conclusão

A adoção de uma estratégia de caching no Vertex AI vai além do aspecto técnico: trata-se de um movimento estratégico de produto e gestão financeira. Especialmente no setor jurídico, onde a precisão exige o processamento de contextos extensos, o caching equilibra a balança entre a inovação disruptiva e a viabilidade econômica.

É fundamental destacar que, nas famílias de modelos mais recentes do Gemini, o Cache Implícito vem ativado por padrão. Isso significa que a infraestrutura do Google Cloud já trabalha silenciosamente para otimizar suas requisições desde o primeiro token.

O código de referência completo está disponível neste repositório e aqui temos a documentação oficial. Para fins de suporte complementar consta no mesmo repositório uma ferramenta simples para teste de cache implícito direto no navegador: