Prompt Caching: custos da primeira e da solicitação repetida

O que o experimento mede

Prompt Cache reduz o reprocessamento da parte inalterada da entrada. Pode ser system prompt, instruções, documento grande ou história estável. A pergunta que muda fica depois do prefixo geral.

O experimento exige três estados:

A. primeira solicitação: prefixo estável + pergunta 1
B. cache hit:           prefixo estável + pergunta 2
C. cache miss:          prefixo alterado + pergunta 3

A e B usam mesmo modelo, settings e cache policy. C muda um caractere da área cacheada ou é executada depois de TTL confirmado. Se mudar modelo, output e tamanho de prompt ao mesmo tempo, o resultado não pode ser explicado apenas pelo cache.

Quer verificar a fórmula no seu uso? Crie uma conta BetterToken e API Key, obtenha taxas atuais na página de preços e faça primeira e solicitações repetidas com o mesmo prefixo. Relacione input, output, cache Token aplicável e consumo no Dashboard, e confira antes regras de cache e TTL na referência de API e documentação do provider.

OpenAI e Anthropic contam cache de formas diferentes

A mesma palavra cache não significa o mesmo mecanismo.

Prompt caching da OpenAI

Nas APIs e modelos OpenAI suportados, caching é aplicado automaticamente ao prefixo adequado. Usage mostra tokens em cache nos detalhes de input. O código geralmente não cria objeto cache separado, mas deve manter o prefixo comum intacto. Limiares, retenção e descontos exatos são verificados na página oficial Prompt Caching.

Prompt caching da Anthropic

Anthropic Messages permite marcar a fronteira do cache com cache_control. Usage pode mostrar separadamente criação e leitura de cache. Tamanho mínimo, TTL, ordem de blocos e custo variam pelo contrato e modelo atuais; verifique na documentação oficial Anthropic.

Não transfira nomes de campos Usage ou coeficientes entre protocolos. Na tabela do experimento, anote exatamente as categorias devolvidas pelo endpoint atual.

Preparar um prefixo estável

Monte a entrada em duas partes:

STABLE_PREFIX
  instruções do sistema
  definições de tools, se necessárias
  documento de referência inalterado

DYNAMIC_SUFFIX
  pergunta atual do usuário

Na primeira experiência é melhor remover tools e streaming. Eles não interferem automaticamente com cache, mas acrescentam variáveis ao uso e output.

O prefixo precisa ter tamanho suficiente conforme regras do modelo escolhido. Se estiver abaixo do limite mínimo, não ocorrer cache hit será resultado esperado. Não o aumente com texto sem sentido em produção; no experimento use documento real já repetido no problema.

Antes da chamada, salve o hash da parte cacheada:

import hashlib

prefix_hash = hashlib.sha256(STABLE_PREFIX.encode("utf-8")).hexdigest()
print(prefix_hash)

O hash confirma que A e B receberam o mesmo prefixo sem publicar conteúdo.

Quais campos anotar

Para cada solicitação, guarde:

• timestamp e request ID;
• Model ID e protocolo;
• prefix_hash;
• regular input tokens;
• tokens de cache creation/write, se contrato os separar;
• tokens de cache read/cached, se contrato os separar;
• output tokens;
• consumo real;
• status e latência somente para diagnóstico.

Latência não prova preço. Uma resposta rápida pode ser miss e um hit pode esperar em fila. A conclusão de custo vem de usage e tarifa.

Fórmula da primeira consulta

Definimos:

I  — regular input tokens
W  — cache write / creation tokens
R  — cache read / cached tokens
O  — output tokens
Pi — preço input regular por 1.000.000 tokens
Pw — preço cache write por 1.000.000 tokens
Pr — preço cache read por 1.000.000 tokens
Po — preço output por 1.000.000 tokens

Para endpoint que separa essas categorias:

cost = I / 1_000_000 × Pi
     + W / 1_000_000 × Pw
     + R / 1_000_000 × Pr
     + O / 1_000_000 × Po

Na primeira solicitação, W e R podem ser maiores que zero. No caching automático os campos podem ser diferentes: use input sem cache e cacheado do usage real, sem criar categoria inexistente.

A primeira solicitação pode ser mais cara que uma sem cache quando criar cache é cobrado separadamente. Isso não é erro por si só. O retorno surge apenas depois de leituras suficientes.

Fórmula de repetição e ponto de equilíbrio

Seja:

C0 — custo da primeira solicitação que cria cache
Ch — custo de uma solicitação com cache hit
Cu — custo de uma solicitação comparável sem cache
n  — número total de solicitações

Série com uma criação e n - 1 hits:

C_cached(n) = C0 + (n - 1) × Ch
C_uncached(n) = n × Cu

O menor n em que o cache se paga é o primeiro inteiro com a condição:

C_cached(n) < C_uncached(n)

Não coloque preços de outro modelo na fórmula. Se Ch >= Cu, a configuração atual não economiza; confira cache hit, tamanho do prefixo e categorias tarifárias.

Cache miss de controle

Depois de A e B, execute C. Mude somente o prefixo cacheado e mantenha modelo e tamanho de resposta esperado. A categoria cache read deve diminuir ou desaparecer conforme contrato, e processamento normal ou criação de cache deve mudar.

Motivos de miss inesperado:

• símbolo ou espaço dentro do prefixo mudou;
• definições de tools chegaram em ordem diferente;
• bloco system foi movido;
• modelo ou endpoint mudou;
• solicitação ficou fora do TTL;
• prefixo era menor que limite mínimo;
• cliente serializa os mesmos dados em ordem diferente.

Mudar a pergunta após prefixo estável é esperado. Mudar dentro do prefixo cria identidade de cache diferente.

Por que não publicamos «resultado em dólares»

Este artigo não tem acesso à API Key e uso de uma conta específica, por isso não oferece exemplo calculado para o teste executado. Preços, modelos e regras de caching mudam. Publicar número aleatório transformaria rapidamente experimento reproduzível em publicidade obsoleta.

Para obter seu resultado:

1. Escolha um modelo e protocolo.
2. Abra a página de preços BetterToken atual.
3. Faça A, B e C.
4. Copie usage e consumo do Dashboard.
5. Calcule C0, Ch, Cu e ponto de equilíbrio.
6. Salve data de inspeção e prefix_hash.

FAQ

Por que a primeira solicitação com cache pode custar mais?

Alguns protocolos cobram cache creation/write separadamente. O adicional inicial só é compensado por cache reads repetidos. Veja o preço atual do modelo específico.

Por que a solicitação repetida não teve cache hit?

Confira comprimento e imutabilidade do prefixo, ordem de blocos, modelo, endpoint, TTL e limite mínimo. Compare prefix_hash.

É possível comparar OpenAI e Anthropic com um campo Usage?

Não. Mecanismos, configurações e nomes das categorias diferem. Normalize valores nos seus campos I, W, R e O, mantendo os campos originais.

Cache sempre reduz custo?

Não. Prefixo curto, repetições raras, mudanças frequentes e baixa taxa de hit podem não pagar a criação do cache.

Onde verificar o débito real BetterToken?

No Dashboard por horário, modelo e status da solicitação. Use a página de preços para tarifa e documentação do protocolo correspondente para regras de cache.