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
- 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. " * 200,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "Qual é a sua política de devolução?"}],
)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 reescritoDois 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_controle confirme um acerto. - Posicionando Pontos de Interrupção
cache_controlem 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
anthropicpara 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.