Prompt Caching: como reduzir custo de API em LLMs

Prompt caching é o recurso que faz a API de um LLM reaproveitar o processamento de um trecho de prompt que já apareceu antes, em vez de recalculá-lo do zero a cada chamada. Na prática, isso significa pagar bem menos e esperar bem menos quando seu system prompt, o contexto de um documento ou o histórico de uma conversa se repete entre requisições — o cenário mais comum em agentes, chatbots e pipelines de RAG.

O mecanismo existe hoje, com nomes e detalhes diferentes, nas três principais APIs de LLM: Anthropic (Claude), OpenAI e Google (Gemini). Este guia explica o princípio comum a todas elas, os detalhes específicos de cada uma e onde o cache falha — porque tratá-lo como memória permanente é o erro mais caro que dá para cometer aqui.

Como funciona por baixo dos panos

Toda chamada a um LLM processa o prompt inteiro — instruções de sistema, contexto e mensagens — token por token, e isso é a maior parte do custo e do tempo de resposta em prompts longos. Prompt caching guarda o estado computado de um prefixo do prompt (a parte que vem antes de um determinado ponto) para reaproveitar em chamadas seguintes que comecem com o mesmo texto, exatamente igual, caractere por caractere.

• Cache write (escrita): a primeira vez que um trecho é enviado, ele é processado normalmente e o resultado fica guardado — isso custa igual ou um pouco mais que o processamento normal.
• Cache read (leitura): nas chamadas seguintes, se o mesmo prefixo aparecer de novo, o provedor pula o reprocessamento e cobra uma fração do preço normal por esses tokens.
• Expiração: o cache não é permanente — ele vive por um tempo limitado (minutos a poucas horas, dependendo do provedor) e some se não for reutilizado a tempo.

Anthropic (Claude): cache explícito por breakpoints

Na API da Anthropic, você marca manualmente onde o cache deve "cortar" o prompt usando o campo cache_control em um bloco de conteúdo (cache_control: {"type": "ephemeral"}). Tudo que vem antes desse marcador — chamado de breakpoint — vira candidato a cache; é possível definir até 4 breakpoints por requisição, e o provedor processa a requisição nesta ordem de prioridade: tools, depois system, depois messages. Mudar qualquer coisa em um nível invalida o cache daquele nível e de tudo que vem depois.

Segundo a documentação oficial, o cache tem dois tempos de vida: 5 minutos (padrão, sem custo extra para criar, e renovado a cada acerto de cache) ou 1 hora (indicado para fluxos agênticos mais longos, com custo de escrita maior). O preço de escrita é 1,25x o valor normal do token de entrada no modo de 5 minutos, ou 2x no modo de 1 hora; a leitura em cache custa 0,1x o preço normal — um desconto de 90% — exceto em Claude Fable 5.1 e Mythos 5.1, onde a leitura cai para 0,025x. Cada modelo também tem um tamanho mínimo de bloco cacheável, que vai de 512 tokens (Fable/Mythos 5.1, Opus 5, Fable 5, Mythos 5) a 4.096 tokens (Haiku 4.5); prompts menores que o mínimo simplesmente não são cacheados, sem erro.

import anthropic

client = anthropic.Anthropic()

# O bloco grande e estável (ex: manual de 50 páginas) recebe o breakpoint.
# O restante do prompt continua normal.
system_prompt = [
    {"type": "text", "text": "Você é um assistente que responde com base no manual abaixo."},
    {
        "type": "text",
        "text": texto_do_manual,
        "cache_control": {"type": "ephemeral"},
    },
]

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=system_prompt,
    messages=[{"role": "user", "content": "Qual é a política de reembolso?"}],
)

# Confira o que realmente foi cacheado na resposta:
print("Tokens escritos no cache:", response.usage.cache_creation_input_tokens)
print("Tokens lidos do cache:", response.usage.cache_read_input_tokens)
print("Tokens processados normalmente:", response.usage.input_tokens)

Vale usar esse mesmo padrão de cliente da API descrito em [Como consumir a API da Anthropic em Python](/artigo/como-consumir-api-anthropic-python) — o cache_control é só mais um campo dentro da mesma chamada de messages.create.

OpenAI: cache automático, sem código extra

A OpenAI tomou o caminho oposto: caching automático, ativado por padrão, sem nenhum campo extra na chamada. Segundo a documentação oficial e o anúncio do recurso, qualquer prompt com 1.024 tokens ou mais já é candidato a cache, e o provedor compara o maior prefixo idêntico já visto, em incrementos de 128 tokens — por isso um prompt precisa repetir exatamente o mesmo início, palavra por palavra, para gerar um acerto de cache. O campo cached_tokens, dentro de usage na resposta da API, mostra quantos tokens da chamada vieram do cache.

Google Gemini: implícito por padrão, explícito sob demanda

O Gemini API tem dois modos. O implicit caching vem ligado por padrão em todos os modelos Gemini 2.5 ou mais recentes — você não precisa fazer nada, e o desconto (90% sobre os tokens que derem acerto de cache, segundo a documentação do Gemini API) é aplicado automaticamente quando o provedor detecta repetição. O explicit caching exige criar um objeto de cache manualmente, com um tempo de vida (TTL) configurável — 60 minutos por padrão — e é a opção certa quando você quer garantir o desconto em vez de torcer para o cache implícito pegar, por exemplo em uma aplicação que reusa o mesmo contexto longo em horários previsíveis. Em modelos Gemini 2.0, o desconto do cache explícito cai para 75%.

Quando vale a pena usar

• System prompts longos e estáveis — instruções, personas ou exemplos few-shot que não mudam entre chamadas.
• RAG com contexto grande — quando o mesmo trecho recuperado (ou o mesmo documento de referência) é reaproveitado em várias perguntas seguidas.
• Agentes e function calling — loops onde o histórico da conversa e as definições de ferramentas se repetem a cada novo turno, como em Function Calling.
• Chat multi-turno — cada nova mensagem reenvia o histórico inteiro; sem cache, você paga de novo por toda a conversa a cada turno.

Onde o cache falha

• Match exato: qualquer mudança no prefixo cacheado — uma palavra, um espaço, a ordem das ferramentas — invalida o cache inteiro daquele ponto em diante.
• TTL curto: o padrão de 5 minutos (Anthropic) conta a partir do início da requisição, não do fim da resposta; em tráfego esparso, o cache expira antes da próxima chamada chegar.
• Não é memória: o cache não guarda fatos nem aprende nada — é apenas processamento reaproveitado. Para conhecimento que muda, a ferramenta certa é RAG; para mudar o comportamento do modelo de forma permanente, é fine-tuning.
• Custo de escrita: a primeira chamada de uma sequência sempre paga mais caro (a escrita do cache), então caching só compensa quando o mesmo prefixo é reutilizado múltiplas vezes.
• Suporte desigual: nem toda plataforma de deploy tem o mesmo comportamento — a documentação da Anthropic, por exemplo, cita que o caching automático não está disponível no Amazon Bedrock legado.