Mínimos de prompt cache: a documentação subestima em 1,4 a 2,4x

Um cliente nos disse que o prompt caching no nosso gateway não estava sendo acionado na contagem de tokens que a própria documentação do modelo prometia. Reproduzimos o problema e rodamos cada modelo de novo por um segundo caminho de serving independente, um dos maiores AI gateways que existem, onde as mesmas discrepâncias se reproduziram token por token. O otimista era a documentação, não um gateway específico: o mínimo publicado é um piso de elegibilidade, não o comprimento que garante um cache hit. Nas famílias de cache automático, os dois diferem em 1,4 a 2,4x. O limiar efetivo do primeiro hit da OpenAI medimos perto de 1.456 tokens contra os 1.024 documentados; o Gemini 2.5 Flash fez a primeira leitura do cache perto de 5.000 contra os 2.048 documentados; o Claude, que só faz cache onde você coloca um marcador explícito, bateu o mínimo por modelo documentado com poucos pontos percentuais de diferença.

TL;DR

• O mínimo de cache de 1.024 tokens documentado pela OpenAI subestima o limiar efetivo de cerca de 1.456 tokens, medido em dois caminhos.
• O Gemini 2.5 Flash documenta 2.048, mas fez a primeira leitura perto de 5.000 tokens, cerca de 2,4x acima.
• O cache_control explícito do Claude bateu o mínimo documentado com poucos pontos percentuais de diferença (Opus 1.073 contra 1.024).
• GLM 5.2 e DeepSeek V4 não publicam mínimo e leem a partir de cerca de 800 tokens; o MiniMax M3 reporta aproximadamente 114 tokens em cache em qualquer comprimento.
• Os caches automáticos também precisam de um warm-up de 2 a 8 chamadas antes da primeira leitura.

Rodamos cada medição por dois caminhos de serving, nosso próprio gateway e um dos maiores AI gateways independentes, e só tratamos um resultado como comportamento do modelo quando os dois caminhos concordavam. O objetivo do segundo caminho é a atribuição: uma discrepância que se reproduz na stack de um fornecedor sem relação é do modelo, não nossa. Essa verificação cruzada funcionou direitinho para OpenAI, Gemini e GLM, que fizeram cache nos dois, nos mesmos limiares efetivos. Ela não funciona para todo modelo: nesse segundo gateway, os modelos open-weight são servidos em grande parte por hosts de GPU que não implementam o prompt cache do fornecedor, o que os próprios metadados de endpoint do gateway confirmam por provider, e o roteamento sem pin fica variando entre esses hosts, então se perde a afinidade de cache. Onde o segundo caminho não conseguiu corroborar, os números abaixo vêm do caminho que chega à própria API de caching de cada fornecedor. Os comprimentos são os tokens de cada modelo, calibrados a partir do usage retornado, não caracteres. Cada braço usou um prefixo novo e registrou o índice da primeira chamada que produziu uma leitura de cache, não um único hit-or-miss.

A diferença entre o documentado e o efetivo

O mínimo documentado indica quando um prompt pode ser cacheado. O limiar efetivo é o tamanho a partir do qual um prompt repetido de fato volta como leitura de cache. Para as famílias de cache automático, esses dois números não coincidem.

O número da OpenAI bateu no token nos dois caminhos: um prompt de 1.356 tokens nunca teve leitura de cache, um de 1.456 teve. O Gemini foi a maior diferença. Uma varredura que ia até 3.300 tokens não teve nenhuma leitura e parecia que o cache estava desligado; estender a varredura até 5.000 produziu uma leitura limpa nos dois caminhos, no mesmo tamanho. O valor documentado de 2.048 é o piso em que o cache fica elegível, não o piso em que ele serve leituras.

O padrão em todo o estudo: o cache que você marca explicitamente tem uma especificação precisa, e o cache que acontece automaticamente não tem.

O mínimo não é a única variável não documentada

Passar do limiar efetivo é necessário, mas não suficiente. As famílias de cache automático precisam de um aquecimento: a primeira leitura chega numa chamada posterior, não na segunda.

• OpenAI: primeira leitura na chamada 2 ou 3.
• Gemini: primeira leitura na chamada 4 a 8.

Isso importa na hora de modelar custos. Um prompt de 6.000 tokens está acima de todos os limiares documentados e efetivos do Gemini, mas uma carga que o envia duas vezes e segue adiante ainda pode pagar o preço cheio nas duas, porque o cache não aqueceu. Tráfego curto ou em rajadas paga a taxa sem cache mesmo quando o tamanho qualifica. Só concluímos “não cacheia” depois de pelo menos doze chamadas repetidas com um intervalo de assentamento entre elas; uma varredura mais curta gerou um falso negativo no Gemini que uma mais profunda derrubou.

As contagens de cache também são arredondadas para blocos fixos, algo útil de saber ao reconciliar uma fatura: blocos de 128 tokens na OpenAI, blocos de 64 tokens na DeepSeek. Uma leitura de 4.073 tokens cacheados num prompt de 5.014 tokens é um hit de prefixo parcial arredondado para o limite de bloco, não um bug.

Os caches que você controla são exatos

O Claude cacheia apenas os segmentos que você marca com cache_control, e esse controle vem com uma especificação precisa. Toda afirmação da Anthropic que testamos se confirmou:

• Mínimo por modelo, no token. Opus 4.8 e Sonnet 5 tiveram a primeira leitura em 1.073 tokens contra os 1.024 documentados; o Haiku 4.5 em 4.206 contra 4.096. A pequena diferença a mais é arredondamento de bloco, não desvio.
• Taxa de leitura de 0,1x do input. Derivamos o preço de input de cada modelo a partir das próprias linhas de cache frio e depois calculamos a taxa cacheada a partir de uma linha de hit. Opus 4.8 e Haiku 4.5 deram 0,10, batendo com o multiplicador documentado.
• Renovação de cinco minutos, gratuita a cada leitura. Semeando um prefixo e relendo aos dois, quatro e seis minutos, houve hit em todas as leituras. Uma leitura dentro de cada janela de cinco minutos mantém a entrada viva sem escrita extra.
• Invalidação em cascata. Com um prefixo de sistema estável e uma ferramenta definida, mudar apenas a descrição da ferramenta forçou uma reescrita completa do cache de sistema abaixo dela. Mudar a definição de uma ferramenta invalida os caches de sistema e de mensagens, batendo com a hierarquia documentada.

Daí saiu um conflito entre documentações. Uma tabela de terceiros listava o mínimo do Claude Opus como 4.096 tokens; a medição teve leitura em 1.073, e os próprios 1.024 da Anthropic são o número correto.

As famílias open-weight geralmente não documentam nada

As famílias acima pelo menos publicam um número sobre o qual estar errado. Já os modelos open-weight e dos labs chineses em geral não publicam mínimo nenhum, e aí só resta medir. Nossa comparação de cache entre providers mostra como as taxas publicadas se comportam depois que um hit acontece; aqui a pergunta é só a partir de que tamanho a primeira leitura aparece.

O GLM 5.2 não publica tamanho mínimo e passou a cachear a partir de uns 800 tokens, com granularidade de blocos de 64 tokens nos dois caminhos — um piso mais baixo que o de qualquer família documentada. O DeepSeek V4 também não publica mínimo e leu a partir de uns 800 tokens com a mesma granularidade de 64 tokens, mas só contra a própria API de caching. A documentação do DeepSeek diz que o cache é best-effort, sem garantia de hit-rate, e é exatamente isso que um intermediário revela: o outro gateway serve o DeepSeek através de um conjunto de hosts de GPU onde só o endpoint próprio do DeepSeek implementa o cache, então roteamento que não está fixado nesse endpoint não retorna leitura nenhuma.

O MiniMax M3 é o caso em que o próprio número reportado engana. Ele documenta um mínimo de 512 tokens, mas reporta uma contagem constante perto de 114 tokens em cache já na primeira chamada, em qualquer tamanho de 200 a 5.000 tokens. Esse número não acompanha o tamanho do prompt e aparece até em caminhos que não fazem cache nenhum, ou seja, é a contabilidade interna do modelo, não um sinal do que foi reaproveitado. É a mesma lição que os modelos mais novos da OpenAI ensinam pelo outro lado: os campos de token do usage e o cache real podem discordar, então quando a economia importa, reconcilie contra usage.cost, não contra a contagem de tokens.

Os modelos mais novos estão mudando as regras

Duas mudanças no nível da documentação merecem atenção antes de assumir que o comportamento antigo continua valendo. Na família GPT-5.6, o guia da OpenAI diz que as escritas no cache custam 1,25x a taxa de input sem cache, enquanto famílias anteriores escreviam de graça. O mesmo guia descreve o caching implícito como colocar um breakpoint na mensagem mais recente, o que tem um formato diferente de cachear por prefixo um bloco de system estável ao longo dos turnos. Se você quer um prefixo estável reaproveitado entre turnos de usuário diferentes nesses modelos, marque-o com um breakpoint explícito em vez de contar com o caminho implícito. Confirme o multiplicador de escrita e o mínimo por modelo, porque hoje os dois variam por família de um jeito que uma única página de doc achata.

O que fazer com isso

• Meça seu próprio limite efetivo. Varie o tamanho do prompt medindo em seus próprios tokens e anote o primeiro tamanho que retorna um cache read. Não parta do princípio de que os hits começam no mínimo documentado.
• Reserve orçamento para o aquecimento. Nos providers de cache automático, considere as primeiras duas a oito chamadas de um novo prefixo como não cacheadas no seu modelo de custo.
• Prefira marcadores explícitos quando o provider oferecer. O cache_control da Claude entregou uma spec precisa e testável: mínimo conhecido, read rate conhecido, TTL conhecido e regra de invalidação conhecida. Essa previsibilidade vale mais do que um piso documentado mais baixo no qual você não pode confiar.
• Refaça o baseline em novas famílias de modelos. Mínimos, preço de escrita e comportamento dos breakpoints mudaram dentro da linha de um mesmo fornecedor ao longo deste estudo.

Para os read rates, TTLs e regras de chaveamento por trás desses limites, nosso guia de prompt caching traz a mecânica de cada provider.

Resumindo: o mínimo documentado é um piso de elegibilidade, não um limite de hit, e nos caches automáticos os dois diferem por um fator de 1,4 a 2,4x. Verifique o número que determina sua conta, em seus próprios tokens, contra seu próprio tráfego.

← Voltar ao blog