Ativar o cache de prompt não me poupou nada — na verdade, minha fatura da API da OpenAI aumentou cerca de um quarto. O culpado foi uma única linha que mudava a cada requisição: um timestamp incorporado no prompt de sistema.

Provedores de LLM permitem que desenvolvedores façam o cache de fragmentos de prompt para reduzir os custos de processamento de tokens. Uma leitura de cache (um “hit”) custa apenas um décimo da taxa regular, enquanto uma escrita de cache (um “miss”) custa aproximadamente 1,25 × o preço normal. Se uma escrita ocorrer, mas o fragmento em cache nunca for lido, a cobrança extra de 25% é desperdiçada. Foi exatamente isso que aconteceu quando o timestamp impediu que o prompt correspondesse a qualquer entrada de cache existente.

Por que o cache pode ser contraproducente

O cache de prompt funciona correspondendo à sequência exata de bytes da parte em cache. O provedor gera um hash da entrada; se o hash corresponder a uma entrada armazenada, o sistema reutiliza a computação anterior e aplica a taxa de leitura barata. Qualquer variação — mesmo um único caractere — quebra a correspondência e força uma nova computação, cobrada pela taxa de escrita mais alta.

No meu caso, o prompt de sistema começava com:

Current session started: 2026-07-14T09:41:07Z

Como o timestamp era atualizado a cada chamada de API, os primeiros bytes da requisição nunca eram idênticos. O provedor tratava cada chamada como uma nova entrada de cache, cobrava o prêmio de escrita e nunca registrava uma leitura. O resultado foi um aumento constante em cache_creation_input_tokens, enquanto cache_read_input_tokens permanecia em zero, um sinal claro de que o cache nunca estava sendo atingido.

Como identificar um cache quebrado

Os logs de uso fornecidos pela API apresentam dois contadores principais:

  • cache_creation_input_tokens – tokens que acionaram uma escrita.
  • cache_read_input_tokens – tokens que se beneficiaram de uma leitura.

Quando o primeiro sobe e o segundo permanece estável, o cache não está sendo reutilizado. Um teste rápido de sanidade é repetir exatamente a mesma requisição duas vezes; a segunda chamada deve mostrar um pico em tokens de leitura se o cache estiver funcionando.

Corrigindo o problema

A solução é simples: garanta que a região em cache seja estática entre as chamadas. Siga estas duas regras:

  1. Coloque o conteúdo imutável primeiro. Prompts de sistema, definições de ferramentas ou qualquer instrução que nunca mude devem ocupar os primeiros bytes da requisição.
  2. Anexe o conteúdo mutável por último. Timestamps, texto gerado pelo usuário, IDs de requisição ou qualquer dado que varie por chamada devem vir após o segmento em cache.

Se apenas um caractere mudar, o hash muda e o erro de cache (cache miss) persiste. Reorganizar o prompt para que o timestamp fique no final restaura a taxa de acerto do cache e reduz a conta de volta ao nível de baixo custo esperado.

Quando o cache realmente ajuda

O cache de prompt brilha em cenários onde o mesmo conjunto de instruções é reutilizado muitas vezes:

  • Loops de agentes onde uma IA chama repetidamente um conjunto fixo de ferramentas.
  • Sessões de chat que referenciam um documento longo e estático, enquanto apenas a última consulta do usuário muda.
  • Extração de dados em massa onde o mesmo prompt de parsing é aplicado a muitos registros.

Para chamadas de disparo único (single-shot) que incluem um contexto novo a cada vez — como uma pergunta isolada com um preâmbulo único — o cache não oferece benefícios e pode até adicionar custos se a requisição acidentalmente acionar uma escrita.

Armadilhas ocultas

Mesmo que o prompt em si seja estático, a requisição pode ser alterada posteriormente:

  • Proxies ou agregadores que reordenam ou injetam espaços em branco podem quebrar a correspondência byte a byte.
  • Serviços de gateway que adicionam cabeçalhos de autenticação ou modificam a formatação JSON podem alterar involuntariamente o fragmento em cache.

Testar através do gateway enviando uma requisição idêntica duas vezes e verificando os contadores de leitura ajuda a verificar se o caminho de cache permanece intacto.

O panorama geral de custos

A sobretaxa de 25% nas escritas não é uma penalidade por usar o cache; reflete o processamento extra necessário para armazenar o fragmento para reutilização futura. Quando ocorre um acerto de cache (cache hit), o custo cai drasticamente — muitas vezes para uma fração da taxa regular. A chave é permitir que o sistema realmente atinja o cache. Caso contrário, você paga o prêmio sem obter nenhuma economia.

Contra-argumento: o cache não morreu

Alguns desenvolvedores argumentam que a complexidade de gerenciar partes estáticas versus dinâmicas do prompt supera a economia gerada. Essa visão ignora o fato de que muitos pipelines de produção já separam a configuração (estática) dos dados do usuário (dinâmicos). Ao estruturar os prompts dessa forma, o mesmo mecanismo de cache que salvou os desenvolvedores originais da API pode ser aproveitado sem esforço extra. A compensação é uma disciplina modesta no design de prompts, não uma falha fundamental na tecnologia.

O que observar a seguir

  • Monitore os dois contadores de cache no seu painel de uso semanalmente.
  • Audite a construção do prompt para confirmar que qualquer elemento variável esteja posicionado após o bloco em cache.
  • Realize testes A/B com e sem cache em uma carga de trabalho representativa para quantificar a economia real.
  • Valide o gateway comparando os payloads brutos das requisições antes e depois de qualquer proxy.

Conclusão

O cache de prompts pode reduzir drasticamente os custos de APIs de LLM, mas apenas se o segmento em cache for verdadeiramente idêntico entre as chamadas. Um timestamp perdido ou qualquer outro token dinâmico no início de um prompt força uma gravação dispendiosa toda vez, inflando a conta. Ao colocar as instruções estáticas no início e relegar os dados variáveis para o final, você permite que o cache faça o seu trabalho e mantém seus gastos sob controle.