Como o Correspôndencia de Prefixo do Cache de Prompt Realmente Funciona

O cache de prompt permite que o Claude reutilize um prefixo de prompt processado anteriormente em vez de processá-lo do zero a cada solicitação.

Isso parece simples, mas o mecanismo por trás disso - uma correspondência de prefixo exata - tem arestas afiadas que pegam quase todas as equipes na primeira vez que as configuram.

Entender o modelo de correspondência de prefixo é a diferença entre obter de forma confiável acertos de cache que valem até 90% de redução de custo e 85% de redução de latência, e pagar silenciosamente o preço total acreditando que o cache está funcionando.

Resumo

Ideia Central: O Claude armazena um prompt em cache como uma sequência ordenada de bytes, e um acerto de cache só ocorre quando o prefixo de uma nova solicitação é idêntico byte a byte a um prefixo previamente armazenado em cache, até um ponto de interrupção marcado.
Por que é Importante: Qualquer alteração anterior nesse prefixo, mesmo que seja um caractere, invalida o cache para tudo o que vem depois dele, transformando silenciosamente uma solicitação em cache barata de volta em uma de preço integral.
Conceitos-Chave: prefixo, ponto de interrupção de cache, cache_control, correspondência exata, escrita de cache vs leitura de cache.
Quando Usar: Qualquer carga de trabalho que reenvia um bloco de conteúdo grande e majoritariamente estável - um prompt de sistema longo, definições de ferramentas ou documentos de referência - em muitas solicitações.
Limitações / Compromissos: O cache não é semântico; ele não sabe que dois prompts "significam" a mesma coisa, apenas se seus bytes correspondem.
Tópicos Relacionados: TTL e preços de cache, posicionamento do ponto de interrupção de cache, verificação de acertos de cache por meio de campos de uso.

Fundamentos

Um prefixo é a porção inicial do conteúdo de uma solicitação, lida na ordem em que o Claude a recebe: definições de ferramentas primeiro, depois o prompt do sistema, depois o array de mensagens.

Um ponto de interrupção de cache é um marcador que você coloca em um bloco específico de conteúdo usando um campo cache_control.

Tudo, desde o início da solicitação até e incluindo esse ponto de interrupção, torna-se elegível para ser armazenado e reutilizado como um prefixo em cache.

Pense nisso como uma fotocopiadora que se lembra das primeiras N páginas do último documento que copiou.

Se você entregar a ela um novo documento cujas primeiras N páginas são idênticas, ela reutiliza as páginas memorizadas e processa apenas as novas páginas a partir desse ponto.

Se até mesmo uma palavra na página 3 for diferente, a fotocopiadora terá que começar novamente da página 3, não memorizando nada da cópia que fez antes.

Aqui está o menor exemplo de marcação de um ponto de interrupção em um prompt de sistema:

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Você é um assistente de suporte da Acme Corp. "

O bloco cache_control nesse texto do sistema diz ao Claude: tudo até e incluindo este bloco é um candidato a cache.

Mecânicas e Interações

A correspondência é exata e posicional, não aproximada e não ciente do conteúdo.

O Claude compara o prefixo da solicitação de entrada, byte a byte, com o que ele armazenou em cache de uma solicitação anterior dentro da janela de TTL do cache.

Se os bytes corresponderem até o ponto de interrupção, é um acerto de cache: esses tokens são lidos do cache em vez de serem reprocessados, o que é mais barato e mais rápido.

Se os bytes divergirem em qualquer ponto antes do ponto de interrupção, é uma falha de cache para todo o prefixo, não apenas para a parte que mudou - todo o segmento até o ponto de interrupção é reprocessado e reescrito no cache.

Esta é a consequência mais importante do modelo: o cache é tudo ou nada para o prefixo, não uma diferença de crédito parcial.

Prefixo em cache (de uma solicitação anterior):
  [defs de ferramenta] [prompt do sistema] [ponto de interrupção]
       |             |
   idêntico      idêntico    -> ACERTO DE CACHE, tudo até o ponto de interrupção lido do cache
 
Nova solicitação, um campo nas defs de ferramenta foi alterado:
  [defs de ferramenta*] [prompt do sistema] [ponto de interrupção]
       |
   diferente aqui -> FALHA DE CACHE para todo o prefixo, reprocessado e reescrito

Dois campos de resposta dizem qual desses aconteceu: usage.cache_read_input_tokens é preenchido em um acerto, e usage.cache_creation_input_tokens é preenchido quando a solicitação grava uma nova entrada (ou atualizada) no cache.

Uma única solicitação pode mostrar ambos os valores não zero, se parte do prefixo correspondeu a uma entrada de cache existente e um ponto de interrupção posterior mais amplo gravou uma nova.

A ordem da solicitação também importa mecanicamente: a API constrói o prefixo efetivo a partir de ferramentas, depois sistema, depois mensagens, nessa ordem fixa, portanto, um ponto de interrupção nas definições de ferramentas cobre um prefixo mais curto e anterior do que um ponto de interrupção colocado no prompt do sistema.

Considerações Avançadas e Aplicações

O requisito de correspondência exata significa que o conteúdo antes de qualquer ponto de interrupção deve ser determinístico entre as solicitações para que o cache ajude de alguma forma.

Culpados comuns que quebram silenciosamente a correspondência: um timestamp incorporado no prompt do sistema, um UUID com escopo de solicitação costurado nas instruções ou um objeto JSON serializado com uma ordem de chave que não é garantida como estável.

Nada disso produz um erro - a solicitação ainda é bem-sucedida - mas cada um deles reprocessa silenciosamente o prefixo completo como se o cache nunca tivesse sido configurado, porque os bytes não correspondem mais.

Abordagem	Força	Fraqueza	Melhor Ajuste
Ponto de interrupção único no final do prompt do sistema	Simples, uma linha para adicionar	Qualquer alteração em qualquer lugar no sistema ou nas ferramentas invalida tudo	Prompt de sistema estável sem conteúdo volátil
Pontos de interrupção para ferramentas e sistema separadamente	Isola a alteração do esquema da ferramenta da alteração do prompt do sistema	Um pouco mais de gerenciamento na construção da solicitação	Grandes catálogos de ferramentas que mudam independentemente da cópia do sistema
Sem `cache_control`	Risco zero de bugs de conteúdo obsoleto	Nenhum benefício de custo ou latência nunca	Prompts que já são curtos ou mudam a cada chamada

Como a correspondência é posicional, mover um bloco de conteúdo estável depois de um volátil (em vez de antes dele) é frequentemente a solução: coloque documentos de referência, esquemas de ferramentas e instruções primeiro, e coloque qualquer coisa que mude por solicitação - a pergunta real do usuário, um ID de sessão, "hora atual" - depois do ponto de interrupção, no array de mensagens onde pertence.

Essa reordenação sozinha resolve a maioria dos bugs de invalidação de cache do mundo real sem remover nenhum conteúdo do prompt.

Conceitos Errôneos Comuns

"O cache de prompt entende o que meu prompt significa." Não entende - a correspondência é puramente em nível de byte. Dois prompts que são semanticamente idênticos, mas diferem em espaços em branco, ordem de chaves ou um único caractere, são tratados como prefixos completamente diferentes.
"Uma falha de cache significa que algo está quebrado." Uma falha apenas significa que os bytes não corresponderam desta vez - pode ser a primeira solicitação, um TTL expirado ou conteúdo genuinamente diferente. É um comportamento esperado, não um estado de erro.
"Apenas meu prompt de sistema afeta o cache." As definições de ferramentas vêm antes do prompt do sistema no prefixo efetivo; um esquema de ferramenta que muda entre as solicitações invalida o cache tanto quanto editar o prompt do sistema.
"Se parte do meu prompt mudou, ainda recebo crédito pela parte que não mudou." Você recebe crédito até o ponto de interrupção imediatamente antes da alteração, mas nada muda o fato de que tudo, da divergência até esse ponto de interrupção, é reprocessado como novo.

FAQs

O que exatamente conta como "o prefixo" em uma solicitação da API Claude?

O conteúdo até e incluindo um ponto de interrupção cache_control marcado, construído em uma ordem fixa: definições de ferramentas primeiro, depois o prompt do sistema, depois o array de mensagens.

O cache de prompt usa algum tipo de correspondência semântica ou aproximada?

Não. É uma correspondência exata byte a byte contra um prefixo previamente armazenado em cache. Não há pontuação de similaridade ou etapa de normalização.

Se uma palavra mudar em meu prompt de sistema, eu perco todo o cache?

Sim, para tudo, desde essa palavra até o próximo ponto de interrupção. O prefixo até o ponto de alteração é reprocessado e reescrito no cache; nada após o ponto de alteração pode atingir a entrada antiga.

As definições de ferramentas afetam o cache de prompt?

Sim. As ferramentas fazem parte do prefixo efetivo e vêm antes do prompt do sistema, portanto, um esquema de ferramenta em mudança invalida o cache, mesmo que o texto do seu prompt de sistema nunca mude.

Como sei se uma solicitação foi um acerto de cache ou uma falha de cache?

Verifique o objeto usage da resposta. cache_read_input_tokens é diferente de zero em um acerto; cache_creation_input_tokens é diferente de zero quando a solicitação grava uma nova entrada de cache.

Uma única solicitação pode ser tanto um acerto de cache quanto uma gravação de cache?

Sim. Se parte do prefixo correspondeu a uma entrada existente e um ponto de interrupção posterior cobre conteúdo que ainda não estava em cache, você pode ver ambos cache_read_input_tokens e cache_creation_input_tokens preenchidos na mesma resposta.

Quais são as coisas comuns que silenciosamente quebram a correspondência de prefixo?

Um timestamp ou string de "data atual" incorporada no prompt do sistema
Um UUID por solicitação ou ID de sessão colocado antes do ponto de interrupção
Conteúdo JSON serializado com ordem de chave não determinística
Qualquer texto dinâmico específico do usuário colocado antes do bloco em cache em vez de depois dele

Uma falha de cache produz um erro?

Não. A solicitação ainda é bem-sucedida normalmente - ela é apenas processada e cobrada como se o cache não estivesse em vigor para esse prefixo. É por isso que a invalidação silenciosa é perigosa: nada informa que aconteceu, a menos que você verifique os campos de uso.

Onde o conteúdo volátil, por solicitação, deve ir em relação ao ponto de interrupção?

Após o ponto de interrupção, geralmente no array de mensagens - nunca antes dele. Qualquer coisa que mude a cada chamada (hora atual, um ID de solicitação, a pergunta ao vivo do usuário) pertence a jusante do prefixo estável e em cache.

O cache é compartilhado entre diferentes chaves de API ou organizações?

Não, o cache está restrito às suas próprias solicitações; não é um cache global compartilhado entre clientes. Trate-o como uma otimização por conta, não como um recurso público.

Reordenar o conteúdo do meu prompt alguma vez corrige um problema de cache?

Frequentemente, sim. Se um bloco estável estiver após um volátil, mover o bloco estável para antes (antes do ponto de interrupção) e o bloco volátil para depois (depois dele) geralmente é suficiente para restaurar acertos de cache consistentes.

Relacionados

Noções Básicas de Cache de Prompt - adicione seu primeiro ponto de interrupção cache_control e confirme um acerto.
Posicionando Pontos de Interrupção cache_control em Prompts de Sistema e Ferramentas - acerte a ordem de ferramentas/sistema/mensagens.
Depurando Invalidadores de Cache Silenciosos em Prompts Longos - encontre os timestamps e UUIDs quebrando seu prefixo.
Verificando Acertos de Cache com cache_read_input_tokens - confirme acertos em cada resposta.
Como Funciona o Preço de Tokens do Claude - veja onde as leituras e gravações de cache se encaixam na cobrança.

Versões da Pilha: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.

Buscar na documentação