Cache de prompts
Releia um prefixo estável por uma fração do preço de entrada — o que armazenar em cache, o que não armazenar e como verificar se funcionou.
O cache de prompts armazena um prefixo da sua solicitação para que chamadas posteriores que o compartilhem sejam cobradas a uma tarifa reduzida de entrada. Para qualquer solicitação com um preâmbulo extenso e estável — um prompt de sistema, esquemas de ferramentas ou um documento sobre o qual se fazem perguntas — essa é a mudança com maior retorno disponível.
O que é um bom candidato para o cache
| Bom | Por quê |
|---|---|
| Prompts de sistema | Idêntico byte a byte em todas as chamadas de uma sessão |
| Definições de ferramentas / funções | Estáveis durante toda a execução de um agente e frequentemente extensas |
| Um documento sobre o qual se fazem perguntas repetidamente | Um envio, muitas perguntas |
| Exemplos de few-shot | Fixo e frequentemente longo |
| Ruim | Por quê |
|---|---|
| A mensagem mais recente do usuário | Diferente a cada vez — nunca há um acerto de cache |
| Qualquer conteúdo com um timestamp ou ID de solicitação perto do início | Um único byte alterado no início do prefixo invalida tudo o que vem depois |
| Prompts curtos | Abaixo do comprimento mínimo para armazenamento em cache, portanto não há ganho |
Como marcar um prefixo
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [{
"type": "text",
"text": "<long stable instructions...>",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "Question that changes every call"}]
}Tudo até o bloco marcado, inclusive ele, passa a ser o prefixo armazenado em cache. A ordem importa: coloque o conteúdo estável primeiro e o conteúdo variável por último.
Como verificar se funciona
Confira a usage objeto. Um acerto de cache informa os tokens em leitura de cache, em vez de entrada comum. Se a leitura de cache permanecer em zero ao longo de chamadas repetidas, seu prefixo não é de fato idêntico — uma causa comum é um timestamp, um ID de sessão ou uma ordenação não determinística das chaves de JSON no preâmbulo.
json.dumps(obj) sem sort_keys=True pode reordenar as chaves entre execuções, o que altera os bytes e faz você perder silenciosamente todos os acertos de cache.Onde faz mais diferença
Ferramentas agênticas reenviam o mesmo prompt de sistema e os mesmos esquemas de ferramentas a cada turno. Em uma sessão de 50 turnos, esse preâmbulo é cobrado 50 vezes sem cache e aproximadamente uma vez com cache.