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

Um cliente nos avisou que o cache de prompts do nosso gateway não estava sendo ativado na quantidade de tokens prometida pela documentação do próprio modelo. Reproduzimos o problema e repetimos os testes de todos os modelos por uma segunda rota de serving independente, um dos maiores gateways de IA. As mesmas diferenças apareceram, token por token. O otimismo estava na documentação, não em um gateway específico: o mínimo publicado é o limite a partir do qual o prompt se torna elegível para o cache, não o tamanho necessário para obter um cache hit. Nas famílias com cache automático, esses valores diferem entre 1,4 e 2,4x. No OpenAI, o primeiro hit efetivo ocorreu perto de 1.456 tokens, contra os 1.024 documentados. No Gemini 2.5 Flash, a primeira leitura do cache apareceu perto de 5.000 tokens, contra os 2.048 documentados. Já o Claude, que só armazena em cache onde há um marcador explícito, atingiu o mínimo documentado de cada modelo com uma diferença de poucos por cento.

TL;DR

• O mínimo documentado pelo OpenAI é de 1.024 tokens, mas o limite efetivo ficou em cerca de 1.456 tokens nas duas rotas testadas.
• O Gemini 2.5 Flash documenta 2.048 tokens, mas a primeira leitura ocorreu perto de 5.000, cerca de 2,4x mais.
• O cache_control explícito do Claude atingiu o mínimo documentado com uma diferença de poucos por cento (Opus: 1.073 contra 1.024).
• GLM 5.2 e DeepSeek V4 não publicam um mínimo e começaram a ler do cache em cerca de 800 tokens; o MiniMax M3 informa aproximadamente 114 tokens em cache para qualquer tamanho.
• Caches automáticos também precisam de um aquecimento de 2 a 8 chamadas antes da primeira leitura.

Executamos todas as medições por duas rotas de serving: nosso próprio gateway e um dos maiores gateways independentes de IA. Só tratamos um resultado como comportamento do modelo quando as duas rotas concordaram. A segunda rota serve para atribuir a causa: se a diferença também aparece na stack de outro fornecedor, ela vem do modelo, não da nossa implementação. Essa verificação funcionou sem divergências para OpenAI, Gemini e GLM. Os três usaram cache nas duas rotas e apresentaram os mesmos limites efetivos. Nem todo modelo permite essa confirmação. No segundo gateway, os modelos open-weight são atendidos principalmente por hosts com GPU que não implementam o cache de prompts do fornecedor, conforme confirmado pelos metadados de endpoint do próprio gateway para cada provider. Além disso, o roteamento sem pinning alterna entre esses hosts e perde a afinidade do cache. Quando a segunda rota não permitiu confirmar o resultado, usamos abaixo os números da rota que acessa diretamente a API de cache do fornecedor. Os tamanhos estão nos tokens de cada modelo, calibrados pelo usage retornado, não em caracteres. Cada variação usou um prefixo novo e registrou o índice da primeira chamada que gerou uma leitura do cache, em vez de considerar apenas um único hit ou miss.

A diferença entre o mínimo documentado e o efetivo

O mínimo documentado indica quando um prompt pode entrar no cache. O limite efetivo é o tamanho a partir do qual a repetição desse prompt realmente retorna uma leitura. Nas famílias com cache automático, esses valores não são iguais.

O resultado do OpenAI foi idêntico, token por token, nas duas rotas: um prompt com 1.356 tokens nunca foi lido do cache; com 1.456 tokens, foi. O Gemini apresentou a maior diferença. Uma varredura limitada a 3.300 tokens não registrou nenhuma leitura e dava a impressão de que o cache estava desativado. Ao estender o teste até 5.000 tokens, obtivemos uma leitura clara nas duas rotas e no mesmo tamanho. Os 2.048 tokens documentados são o limite de elegibilidade do cache, não o ponto em que ele começa a servir leituras.

O padrão observado no estudo foi simples: caches marcados explicitamente têm uma especificação precisa; caches automáticos, não.

O mínimo não é a única variável sem documentação

Ultrapassar o limite efetivo é necessário, mas não basta. As famílias com cache automático precisam de aquecimento: a primeira leitura acontece em uma chamada posterior, não necessariamente na segunda.

• OpenAI: primeira leitura na chamada 2 ou 3.
• Gemini: primeira leitura entre as chamadas 4 e 8.

Isso afeta a modelagem de custos. Um prompt com 6.000 tokens está acima de todos os limites documentados e efetivos do Gemini. Mesmo assim, um workload que o envia duas vezes e passa para outro prefixo pode pagar o preço integral nas duas chamadas, pois o cache ainda não aqueceu. Tráfego curto ou em rajadas paga a tarifa sem cache mesmo quando o tamanho se qualifica. Só concluímos que um modelo “não usa cache” depois de pelo menos doze chamadas repetidas, com um intervalo de estabilização entre elas. Um teste mais curto gerou um falso negativo no Gemini, corrigido quando aumentamos a quantidade de chamadas.

As contagens em cache também são ajustadas para blocos fixos, o que precisa ser considerado ao reconciliar uma fatura: blocos de 128 tokens no OpenAI e de 64 tokens no DeepSeek. Uma leitura de 4.073 tokens em cache para um prompt de 5.014 tokens representa um hit parcial do prefixo arredondado para o limite de um bloco, não um bug.

Os caches que você controla são exatos

O Claude armazena em cache apenas os segmentos marcados com cache_control, e esse controle vem acompanhado de uma especificação precisa. Todas as afirmações da Anthropic que testamos se confirmaram:

• Mínimo por modelo, token por token. Opus 4.8 e Sonnet 5 fizeram 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 vem do arredondamento dos blocos, não de uma variação do limite.
• Taxa de leitura de 0,1x o input. Calculamos o preço de input de cada modelo a partir das próprias linhas sem cache e depois derivamos a taxa do cache usando uma linha com hit. Opus 4.8 e Haiku 4.5 chegaram a 0,10, exatamente o multiplicador documentado.
• Renovação gratuita de cinco minutos a cada leitura. Criamos uma entrada para um prefixo e repetimos a leitura após dois, quatro e seis minutos. Todas resultaram em hit. Uma leitura dentro de cada janela de cinco minutos mantém a entrada ativa sem nova cobrança de escrita.
• Invalidação em cascata. Com um prefixo de system estável e uma ferramenta definida, alterar apenas a descrição da ferramenta forçou a reescrita completa do cache de system abaixo dela. Alterar a definição de uma ferramenta invalida os caches de system e de mensagens, conforme a hierarquia documentada.

O teste também revelou um conflito entre documentações. Uma tabela de terceiros informava um mínimo de 4.096 tokens para o Claude Opus. A medição retornou uma leitura em 1.073, confirmando que os 1.024 tokens informados pela própria Anthropic são o valor correto.

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

As famílias anteriores pelo menos publicam um número, ainda que incorreto. Modelos open-weight e de laboratórios chineses, em sua maioria, não publicam mínimo algum. Nesse caso, medir é a única opção. Nossa comparação de caches entre fornecedores mostra como as tarifas publicadas se comportam depois de um hit. Aqui, a questão é apenas o tamanho em que aparece a primeira leitura.

O GLM 5.2 não publica um tamanho mínimo e começou a usar o cache em cerca de 800 tokens, com granularidade de blocos de 64 tokens nas duas rotas. É um limite menor que o de qualquer família que publica esse valor. O DeepSeek V4 também não informa um mínimo e começou a ler do cache em cerca de 800 tokens, com a mesma granularidade de 64 tokens, mas apenas em sua própria API de cache. A documentação do DeepSeek classifica o cache como best-effort e não garante taxa de hit. É exatamente isso que aparece por meio de um intermediário: o outro gateway atende o DeepSeek por um conjunto de hosts com GPU, dos quais apenas o endpoint do próprio DeepSeek implementa o cache. Sem fixar o roteamento nesse endpoint, não há leitura alguma.

No MiniMax M3, o próprio número informado induz ao erro. A documentação define um mínimo de 512 tokens, mas o modelo informa uma contagem constante, próxima de 114 tokens em cache, desde a primeira chamada e para todos os tamanhos entre 200 e 5.000 tokens. Esse valor não acompanha o tamanho do prompt e aparece até em rotas que não executam cache. Portanto, é um dado contábil interno do modelo, não um sinal do conteúdo reutilizado. Os modelos mais recentes do OpenAI mostram o mesmo problema pelo caminho inverso: os campos de tokens em usage podem divergir do cache real. Quando a economia for relevante, faça a reconciliação usando usage.cost, não a contagem de tokens.

Os modelos mais novos estão mudando as regras

Antes de presumir que o comportamento antigo continua valendo, considere duas mudanças de documentação. Na família GPT-5.6, o guia do OpenAI informa que escritas no cache custam 1,25x a tarifa de input sem cache; nas famílias anteriores, a escrita era gratuita. O mesmo guia descreve o cache implícito como a inserção de um breakpoint na mensagem mais recente. Esse formato é diferente de armazenar em cache um bloco de system estável para reutilização entre turnos. Se você quiser reutilizar um prefixo estável em diferentes turnos de usuário nesses modelos, marque-o com um breakpoint explícito em vez de depender do fluxo implícito. Confirme o multiplicador de escrita e o mínimo de cada modelo, pois ambos agora variam por família de uma forma que uma única página de documentação não deixa clara.

O que fazer com esses resultados

• Meça seu próprio limite efetivo. Varie o tamanho do prompt nos tokens do seu ambiente e registre o primeiro tamanho que retorna uma leitura do cache. Não presuma que os hits começam no mínimo documentado.
• Inclua o aquecimento no orçamento. No modelo de custos dos fornecedores com cache automático, considere que as primeiras duas a oito chamadas de um novo prefixo não usarão cache.
• Prefira marcadores explícitos quando o fornecedor oferecer esse recurso. O cache_control do Claude forneceu uma especificação precisa e testável: mínimo, tarifa de leitura, TTL e regra de invalidação conhecidos. Essa previsibilidade vale mais do que um limite documentado menor no qual você não pode confiar.
• Refaça a linha de base para novas famílias de modelos. Durante este estudo, mínimos, preços de escrita e comportamento dos breakpoints mudaram dentro do portfólio de um único fornecedor.

Para consultar as tarifas de leitura, os TTLs e as regras de composição de chaves por trás desses limites, veja nosso guia de cache de prompts.

Em resumo: o mínimo documentado é o limite de elegibilidade, não o limite de hit. Nos caches automáticos, os dois diferem entre 1,4 e 2,4x. Verifique o número que determina sua fatura usando seus próprios tokens e seu próprio tráfego.

← Voltar ao blog