Melhores Práticas de Cache de Prompt

Um conjunto de práticas numeradas e acionáveis para obter valor confiável e contínuo do cache de prompt do Claude - cobrindo onde colocar breakpoints, como escolher um TTL e como evitar misses silenciosos que apagam silenciosamente as economias.

Como Usar Esta Lista

Trate estas como padrões, não como regras absolutas - desvie deliberadamente quando sua carga de trabalho tiver um motivo genuíno.
O Grupo A cobre o posicionamento de breakpoints, o Grupo B cobre decisões de TTL e custo, o Grupo C cobre a prevenção de misses silenciosos e o Grupo D cobre monitoramento e verificação.
Revise esta lista sempre que adicionar um novo campo a um prompt do sistema ou esquema de ferramenta, pois esse é o ponto mais comum onde uma configuração anteriormente saudável regride.
Emparelhe essas práticas com as páginas explicativas e de como fazer mais detalhadas vinculadas em "Relacionados" para o raciocínio por trás de cada uma.

A - Posicionamento de Breakpoints

Ordene o conteúdo por estabilidade, não por conveniência. Coloque o conteúdo mais estável (esquemas de ferramentas, documentos de referência longos, instruções do sistema) primeiro e o conteúdo mais volátil (a pergunta do usuário ao vivo, um timestamp, um ID de sessão) por último, após qualquer breakpoint.
Lembre-se da ordem fixa da solicitação: ferramentas, depois sistema, depois mensagens. A cobertura de um breakpoint é determinada por esta ordem, independentemente de como você organiza os argumentos de palavra-chave em sua chamada Python.
Use dois breakpoints quando as ferramentas e o prompt do sistema mudam em taxas diferentes. Um breakpoint na última definição de ferramenta e um segundo no prompt do sistema permite que uma edição do prompt do sistema evite invalidar um catálogo de ferramentas estável, e vice-versa.
Nunca coloque cache_control em um prompt de sistema de string pura. cache_control requer a forma de lista de blocos de conteúdo de system; uma string simples não tem onde anexá-lo.
Em loops de agente com várias voltas, mova o breakpoint para frente a cada volta. Coloque-o na última mensagem do histórico de conversas crescente e remova-o das mensagens anteriores, para que o cache continue cobrindo "tudo o que foi resolvido até agora".

B - Decisões de TTL e Custo

Use o TTL de 5 minutos como padrão, a menos que você tenha um motivo específico para 1 hora. Ele tem um multiplicador de custo de escrita menor e se adapta à maioria das cargas de trabalho interativas e com picos.
Use o TTL de 1 hora para sessões com lacunas reais entre as chamadas. Sessões de agente de longa duração, revisão humana no loop ou trabalhos em lote infrequentes distribuídos ao longo de uma hora se beneficiam de não consumir repetidamente o custo de escrita.
Lembre-se que ambos os TTLs são efêmeros e atualizam a cada hit. Um fluxo constante de solicitações dentro da janela mantém uma entrada ativa bem além de seu TTL nominal - você não precisa "mantê-la aquecida" manualmente.
Pondere o custo de escrita contra o número esperado de leituras antes de se comprometer com um TTL. Um prefixo reutilizado apenas uma ou duas vezes raramente recupera o custo de escrita de qualquer TTL; um prefixo reutilizado dezenas de vezes quase sempre o faz.
Verifique as suposições de preços contra a documentação atual, não a memória. Os multiplicadores de escrita e leitura de cache mudam independentemente dos lançamentos de modelos - confirme os números exatos em platform.claude.com/docs antes de orçar uma carga de trabalho.

C - Evitando Misses Silenciosos

Nunca incorpore um timestamp, UUID ou ID de solicitação antes de um breakpoint. Estes são os invalidadores silenciosos mais comuns - mova qualquer coisa por solicitação para messages, após o breakpoint, em vez disso.
Serializar conteúdo JSON e dict de forma determinística. Sempre passe sort_keys=True (ou uma ordem de chave fixa equivalente) para qualquer dict que caia dentro de um segmento de prompt em cache.
Construa conteúdo em cache a partir de uma função compartilhada, não de literais inline dispersos. Centralizar a construção do prompt do sistema e do esquema da ferramenta evita que pequenas diferenças acidentais surjam entre os locais de chamada.
Audite também o conteúdo de prompt de terceiros e gerado por framework. Um construtor de esquema de ferramenta ou biblioteca de modelo de prompt pode incorporar conteúdo volátil tão facilmente quanto seu próprio código - verifique a carga útil serializada final, não apenas o que você escreveu manualmente.
Trate um miss de cache deliberado (por exemplo, após aparar o histórico da conversa) como esperado, não como um bug. Orce o custo de reescrita único em vez de tentar evitá-lo completamente quando o histórico realmente precisar mudar.

D - Monitoramento e Verificação

Verifique usage.cache_read_input_tokens e cache_creation_input_tokens em cada resposta, não apenas durante a configuração. O cache falha silenciosamente - um miss nunca gera um erro - portanto, o monitoramento contínuo é a única maneira de capturar uma regressão em produção.
Teste com pelo menos duas chamadas consecutivas antes de concluir que o cache está quebrado. A primeira chamada para qualquer prefixo é sempre uma escrita, nunca um hit - isso é esperado, não uma falha.
Use o beta de diagnósticos de cache para investigação direcionada de um miss confirmado. Passar diagnostics.previous_message_id obtém um cache_miss_reason diretamente da API em vez de exigir uma diferença manual.
Marque as métricas de cache por endpoint ou prompt, não apenas no agregado. Uma queda na taxa geral de hits pode ocultar o fato de que apenas um prefixo específico começou a ter misses; a marcação por prompt isola a regressão real.
Compare programaticamente dois prefixos supostamente idênticos ao investigar, nunca visualmente. Um único caractere diferente em um prompt de vários milhares de tokens é efetivamente invisível à inspeção manual.

FAQs

Qual é a causa mais comum de o cache de prompt não funcionar?

Um invalidator silencioso antes do breakpoint - mais frequentemente um timestamp, UUID ou objeto JSON não determinístico serializado incorporado no prompt do sistema ou esquema da ferramenta.

Devo sempre usar o TTL de 1 hora para ter certeza?

Não - use o TTL de 5 minutos como padrão e só use a opção de 1 hora quando sua carga de trabalho realmente tiver lacunas entre as chamadas maiores que alguns minutos.

É um bug se minha primeira solicitação para um novo prompt mostrar zero `cache_read_input_tokens`?

Não, isso é esperado - a primeira chamada para qualquer prefixo é sempre uma escrita de cache, nunca um hit. Você precisa de pelo menos duas chamadas compartilhando o mesmo prefixo para ver uma leitura.

Preciso continuar movendo o breakpoint em uma conversa de agente com várias voltas?

Sim - um breakpoint fixo da primeira volta deixa o histórico crescente das voltas posteriores descoberto. Mova o breakpoint para a mensagem mais recente a cada volta e remova-o das mensagens anteriores.

Quantos breakpoints `cache_control` uma solicitação típica deve ter?

Geralmente um ou dois: um no prompt do sistema (e opcionalmente ferramentas separadamente), mais um segundo breakpoint móvel na mensagem mais recente em uma conversa com várias voltas.

Qual é a maneira mais rápida de confirmar que o cache está realmente funcionando antes de enviar?

Envie a mesma solicitação duas vezes seguidas e verifique se usage.cache_read_input_tokens da segunda resposta é diferente de zero. Se não for, algo no prefixo não é estável entre as chamadas.

A poda do histórico da conversa para gerenciamento de contexto quebra o cache?

Sim, causa um miss de cache naquela volta, pois os bytes do prefixo mudaram - isso é esperado e vale a pena orçar, não um sinal de uma configuração quebrada.

Modelos de prompt de terceiros também devem ser auditados quanto à segurança de cache?

Sim - um gerador de esquema de ferramenta ou modelo de prompt de um framework pode incorporar conteúdo volátil (um timestamp gerado, um ID de exemplo aleatório) tão facilmente quanto código escrito à mão.

Como capturar uma regressão de cache antes que ela apareça como um pico de custo?

Registre usage.cache_read_input_tokens e cache_creation_input_tokens em cada solicitação em produção, marcada por endpoint, para que uma queda na taxa de hits seja visível imediatamente em vez de descoberta posteriormente em uma fatura.

O que devo fazer depois de confirmar um miss de cache, mas não saber por quê?

Use o beta de diagnósticos de cache (diagnostics.previous_message_id) para obter um cache_miss_reason diretamente, ou recorra a uma comparação de bytes programática entre os dois prefixos supostamente idênticos.

Relacionados

Como o Match de Prefixo do Cache de Prompt Realmente Funciona - o mecanismo por trás de cada prática nesta lista.
Colocando Breakpoints cache_control em Prompts de Sistema e Ferramentas - os detalhes completos por trás do Grupo A.
Depurando Invalidadores Silenciosos de Cache em Prompts Longos - os detalhes completos por trás do Grupo C.
Verificando Cache Hits com cache_read_input_tokens - os detalhes completos por trás do Grupo D.

Versões de Stack: 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.