Cache de prompts

O cache de prompts é um recurso poderoso que otimiza o uso da API permitindo retomar a partir de prefixos específicos em seus prompts. Essa abordagem reduz significativamente o tempo de processamento e os custos para tarefas repetitivas ou prompts com elementos consistentes.

Aqui está um exemplo de como implementar o cache de prompts com a API Messages usando um bloco cache_control:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Você é um assistente de IA encarregado de analisar obras literárias. Seu objetivo é fornecer comentários perspicazes sobre temas, personagens e estilo de escrita.\n"
      },
      {
        "type": "text",
        "text": "<o conteúdo completo de Orgulho e Preconceito>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analise os principais temas em Orgulho e Preconceito."
      }
    ]
  }'

# Chame o modelo novamente com as mesmas entradas até o ponto de verificação do cache
curl https://api.anthropic.com/v1/messages # resto da entrada

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

Neste exemplo, o texto completo de “Orgulho e Preconceito” é armazenado em cache usando o parâmetro cache_control. Isso permite a reutilização deste texto extenso em várias chamadas de API sem reprocessá-lo a cada vez. Alterar apenas a mensagem do usuário permite que você faça várias perguntas sobre o livro enquanto utiliza o conteúdo em cache, levando a respostas mais rápidas e melhor eficiência.

​

Como funciona o cache de prompts

Quando você envia uma solicitação com o cache de prompts ativado:

1. O sistema verifica se um prefixo de prompt, até um ponto de interrupção de cache especificado, já está em cache de uma consulta recente.
2. Se encontrado, ele usa a versão em cache, reduzindo o tempo de processamento e os custos.
3. Caso contrário, processa o prompt completo e armazena o prefixo em cache assim que a resposta começa.

Isso é especialmente útil para:

• Prompts com muitos exemplos
• Grandes quantidades de contexto ou informações de fundo
• Tarefas repetitivas com instruções consistentes
• Conversas longas com múltiplos turnos

Por padrão, o cache tem uma vida útil de 5 minutos. O cache é atualizado sem custo adicional cada vez que o conteúdo em cache é usado.

​

Preços

O cache de prompts introduz uma nova estrutura de preços. A tabela abaixo mostra o preço por milhão de tokens para cada modelo suportado:

Nota:

• Tokens de escrita em cache de 5 minutos custam 1,25 vezes o preço base de tokens de entrada
• Tokens de escrita em cache de 1 hora custam 2 vezes o preço base de tokens de entrada
• Tokens de leitura de cache custam 0,1 vezes o preço base de tokens de entrada
• Tokens regulares de entrada e saída são cobrados com as taxas padrão

​

Como implementar o cache de prompts

​

Modelos suportados

O cache de prompts é atualmente suportado em:

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

Estruturando seu prompt

Coloque conteúdo estático (definições de ferramentas, instruções do sistema, contexto, exemplos) no início do seu prompt. Marque o final do conteúdo reutilizável para cache usando o parâmetro cache_control.

Os prefixos de cache são criados na seguinte ordem: tools, system e depois messages.

Usando o parâmetro cache_control, você pode definir até 4 pontos de interrupção de cache, permitindo armazenar diferentes seções reutilizáveis separadamente. Para cada ponto de interrupção, o sistema verificará automaticamente se há correspondências de cache em posições anteriores e usará o prefixo correspondente mais longo, se encontrado.

​

Limitações de cache

O comprimento mínimo de prompt armazenável em cache é:

• 1024 tokens para Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 e Claude Opus 3
• 2048 tokens para Claude Haiku 3.5 e Claude Haiku 3

Prompts mais curtos não podem ser armazenados em cache, mesmo se marcados com cache_control. Quaisquer solicitações para armazenar em cache menos do que esse número de tokens serão processadas sem cache. Para ver se um prompt foi armazenado em cache, consulte os campos de uso da resposta.

Para solicitações concorrentes, observe que uma entrada de cache só fica disponível após o início da primeira resposta. Se você precisar de correspondências de cache para solicitações paralelas, aguarde a primeira resposta antes de enviar solicitações subsequentes.

Atualmente, “ephemeral” é o único tipo de cache suportado, que por padrão tem uma vida útil de 5 minutos.

​

O que pode ser armazenado em cache

A maioria dos blocos na solicitação pode ser designada para cache com cache_control. Isso inclui:

• Ferramentas: Definições de ferramentas no array tools
• Mensagens do sistema: Blocos de conteúdo no array system
• Mensagens de texto: Blocos de conteúdo no array messages.content, tanto para turnos do usuário quanto do assistente
• Imagens e Documentos: Blocos de conteúdo no array messages.content, em turnos do usuário
• Uso de ferramentas e resultados de ferramentas: Blocos de conteúdo no array messages.content, tanto em turnos do usuário quanto do assistente

Cada um desses elementos pode ser marcado com cache_control para habilitar o cache para essa parte da solicitação.

​

O que não pode ser armazenado em cache

Embora a maioria dos blocos de solicitação possa ser armazenada em cache, existem algumas exceções:

• Blocos de pensamento não podem ser armazenados em cache diretamente com cache_control. No entanto, blocos de pensamento PODEM ser armazenados em cache junto com outro conteúdo quando aparecem em turnos anteriores do assistente. Quando armazenados em cache dessa forma, eles CONTAM como tokens de entrada quando lidos do cache.

• Blocos de subconteúdo (como citações) não podem ser armazenados em cache diretamente. Em vez disso, armazene em cache o bloco de nível superior.

  No caso de citações, os blocos de conteúdo de documento de nível superior que servem como material de origem para citações podem ser armazenados em cache. Isso permite que você use o cache de prompts com citações de forma eficaz, armazenando em cache os documentos que as citações referenciarão.

• Blocos de texto vazios não podem ser armazenados em cache.

​

Monitorando o desempenho do cache

Monitore o desempenho do cache usando estes campos de resposta da API, dentro de usage na resposta (ou evento message_start se estiver transmitindo):

• cache_creation_input_tokens: Número de tokens escritos no cache ao criar uma nova entrada.
• cache_read_input_tokens: Número de tokens recuperados do cache para esta solicitação.
• input_tokens: Número de tokens de entrada que não foram lidos ou usados para criar um cache.

​

Melhores práticas para cache eficaz

Para otimizar o desempenho do cache de prompts:

• Armazene em cache conteúdo estável e reutilizável como instruções do sistema, informações de fundo, contextos grandes ou definições de ferramentas frequentes.
• Coloque o conteúdo em cache no início do prompt para melhor desempenho.
• Use pontos de interrupção de cache estrategicamente para separar diferentes seções de prefixo armazenáveis em cache.
• Analise regularmente as taxas de acerto do cache e ajuste sua estratégia conforme necessário.

​

Otimizando para diferentes casos de uso

Adapte sua estratégia de cache de prompts ao seu cenário:

• Agentes conversacionais: Reduza o custo e a latência para conversas estendidas, especialmente aquelas com instruções longas ou documentos carregados.
• Assistentes de codificação: Melhore o preenchimento automático e perguntas sobre base de código mantendo seções relevantes ou uma versão resumida da base de código no prompt.
• Processamento de documentos grandes: Incorpore material completo de formato longo, incluindo imagens, em seu prompt sem aumentar a latência de resposta.
• Conjuntos de instruções detalhadas: Compartilhe extensas listas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Desenvolvedores frequentemente incluem um ou dois exemplos no prompt, mas com o cache de prompts você pode obter um desempenho ainda melhor incluindo 20+ exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agênticas: Melhore o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e alterações iterativas de código, onde cada etapa normalmente requer uma nova chamada de API.
• Converse com livros, artigos, documentação, transcrições de podcasts e outros conteúdos de formato longo: Dê vida a qualquer base de conhecimento incorporando o documento inteiro no prompt e permitindo que os usuários façam perguntas sobre ele.

​

Solucionando problemas comuns

Se estiver experimentando comportamento inesperado:

• Certifique-se de que as seções em cache sejam idênticas e marcadas com cache_control nos mesmos locais entre as chamadas
• Verifique se as chamadas são feitas dentro do tempo de vida do cache (5 minutos por padrão)
• Verifique se tool_choice e o uso de imagens permanecem consistentes entre as chamadas
• Valide se você está armazenando em cache pelo menos o número mínimo de tokens
• Embora o sistema tente usar conteúdo previamente armazenado em cache em posições anteriores a um ponto de interrupção de cache, você pode usar um parâmetro cache_control adicional para garantir a busca de cache em partes anteriores do prompt, o que pode ser útil para consultas com listas muito longas de blocos de conteúdo

Observe que alterações em tool_choice ou a presença/ausência de imagens em qualquer lugar no prompt invalidarão o cache, exigindo a criação de uma nova entrada de cache.

​

Cache com blocos de pensamento

Ao usar pensamento estendido com cache de prompts, os blocos de pensamento têm um comportamento especial:

Cache automático junto com outro conteúdo: Embora os blocos de pensamento não possam ser marcados explicitamente com cache_control, eles são armazenados em cache como parte do conteúdo da solicitação quando você faz chamadas de API subsequentes com resultados de ferramentas. Isso comumente acontece durante o uso de ferramentas quando você passa blocos de pensamento de volta para continuar a conversa.

Contagem de tokens de entrada: Quando os blocos de pensamento são lidos do cache, eles contam como tokens de entrada em suas métricas de uso. Isso é importante para cálculo de custo e orçamento de tokens.

Padrões de invalidação de cache:

• O cache permanece válido quando apenas resultados de ferramentas são fornecidos como mensagens do usuário
• O cache é invalidado quando conteúdo do usuário que não é resultado de ferramenta é adicionado, fazendo com que todos os blocos de pensamento anteriores sejam removidos
• Esse comportamento de cache ocorre mesmo sem marcadores explícitos de cache_control

Exemplo com uso de ferramenta:

Solicitação 1: Usuário: "Como está o tempo em Paris?"
Resposta: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1]

Solicitação 2: 
Usuário: ["Como está o tempo em Paris?"], 
Assistente: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1], 
Usuário: [resultado_de_ferramenta_1, cache=True]
Resposta: [bloco_de_pensamento_2] + [bloco de texto 2]
# A Solicitação 2 armazena em cache seu conteúdo de solicitação (não a resposta)
# O cache inclui: mensagem do usuário, bloco_de_pensamento_1, bloco de uso de ferramenta 1 e resultado_de_ferramenta_1

Solicitação 3:
Usuário: ["Como está o tempo em Paris?"], 
Assistente: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1], 
Usuário: [resultado_de_ferramenta_1, cache=True], 
Assistente: [bloco_de_pensamento_2] + [bloco de texto 2], 
Usuário: [Resposta de texto, cache=True]
# Bloco do usuário que não é resultado de ferramenta faz com que todos os blocos de pensamento sejam ignorados
# Esta solicitação é processada como se os blocos de pensamento nunca estivessem presentes

Quando um bloco do usuário que não é resultado de ferramenta é incluído, ele designa um novo loop do assistente e todos os blocos de pensamento anteriores são removidos do contexto.

Para informações mais detalhadas, consulte a documentação de pensamento estendido.

​

Armazenamento e compartilhamento de cache

• Isolamento de Organização: Os caches são isolados entre organizações. Organizações diferentes nunca compartilham caches, mesmo que usem prompts idênticos.

• Correspondência Exata: Os acertos de cache requerem segmentos de prompt 100% idênticos, incluindo todo o texto e imagens até e incluindo o bloco marcado com controle de cache.

• Geração de Tokens de Saída: O cache de prompts não tem efeito na geração de tokens de saída. A resposta que você recebe será idêntica à que você obteria se o cache de prompts não fosse usado.

​

Duração de cache de 1 hora (beta)

Se você achar que 5 minutos é muito curto, a Anthropic também oferece uma duração de cache de 1 hora.

Para usar o cache estendido, adicione extended-cache-ttl-2025-04-11 como um cabeçalho beta à sua solicitação e, em seguida, inclua ttl na definição de cache_control assim:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

A resposta incluirá informações detalhadas de cache como as seguintes:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

Observe que o campo atual cache_creation_input_tokens é igual à soma dos valores no objeto cache_creation.

​

Quando usar o cache de 1 hora

Se você tem prompts que são usados em uma cadência regular (ou seja, prompts do sistema que são usados com mais frequência do que a cada 5 minutos), continue usando o cache de 5 minutos, pois este continuará a ser atualizado sem custo adicional.

O cache de 1 hora é melhor usado nos seguintes cenários:

• Quando você tem prompts que provavelmente são usados com menos frequência do que 5 minutos, mas com mais frequência do que a cada hora. Por exemplo, quando um agente secundário agêntico levará mais de 5 minutos, ou ao armazenar uma longa conversa de chat com um usuário e você geralmente espera que esse usuário possa não responder nos próximos 5 minutos.
• Quando a latência é importante e seus prompts de acompanhamento podem ser enviados além de 5 minutos.
• Quando você deseja melhorar sua utilização de limite de taxa, já que os acertos de cache não são deduzidos do seu limite de taxa.

​

Misturando diferentes TTLs

Você pode usar controles de cache de 1 hora e 5 minutos na mesma solicitação, mas com uma restrição importante: Entradas de cache com TTL mais longo devem aparecer antes de TTLs mais curtos (ou seja, uma entrada de cache de 1 hora deve aparecer antes de qualquer entrada de cache de 5 minutos).

Ao misturar TTLs, determinamos três locais de cobrança em seu prompt:

1. Posição A: A contagem de tokens no acerto de cache mais alto (ou 0 se não houver acertos).
2. Posição B: A contagem de tokens no bloco cache_control de 1 hora mais alto após A (ou igual a A se nenhum existir).
3. Posição C: A contagem de tokens no último bloco cache_control.

Você será cobrado por:

1. Tokens de leitura de cache para A.
2. Tokens de escrita de cache de 1 hora para (B - A).
3. Tokens de escrita de cache de 5 minutos para (C - B).

Aqui estão 3 exemplos. Isso representa os tokens de entrada de 3 solicitações, cada uma com diferentes acertos e falhas de cache. Cada uma tem um preço calculado diferente, mostrado nas caixas coloridas, como resultado.

​

Exemplos de cache de prompts

Para ajudá-lo a começar com o cache de prompts, preparamos um livro de receitas de cache de prompts com exemplos detalhados e melhores práticas.

Abaixo, incluímos vários trechos de código que mostram vários padrões de cache de prompts. Esses exemplos demonstram como implementar o cache em diferentes cenários, ajudando você a entender as aplicações práticas desse recurso:

​

FAQ