Cache de prompts

Cache de prompts é um recurso poderoso que otimiza o uso da sua 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 cache de prompts com a API de Mensagens usando um bloco cache_control:

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 cache de prompts ativado:

1. O sistema verifica se um prefixo de prompt, até um ponto 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 custos.
3. Caso contrário, processa o prompt completo e armazena o prefixo em cache para uso futuro.

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

O cache tem uma vida útil de 5 minutos, renovada 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 token para cada modelo suportado:

Nota:

• Tokens de gravação em cache são 25% mais caros que tokens de entrada base
• Tokens de leitura em cache são 90% mais baratos que tokens de entrada base
• Tokens regulares de entrada e saída são cobrados nas taxas padrão

​

Como implementar o cache de prompts

​

Modelos suportados

O cache de prompts é atualmente suportado em:

• Claude 3.5 Sonnet
• Claude 3.5 Haiku
• Claude 3 Haiku
• Claude 3 Opus

​

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 fim 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, 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.

​

Limitações do Cache

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

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

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

O cache tem um tempo de vida (TTL) de 5 minutos. Atualmente, “ephemeral” é o único tipo de cache suportado, que corresponde a esta vida útil de 5 minutos.

​

O que pode ser armazenado em cache

Cada bloco na solicitação pode ser designado 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: Blocos de conteúdo no array messages.content, para turnos de usuário e assistente
• Imagens: Blocos de conteúdo no array messages.content, em turnos de usuário
• Uso de ferramentas e resultados de ferramentas: Blocos de conteúdo no array messages.content, em turnos de usuário e assistente

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

​

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 efetivo

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 frequentes de ferramentas.
• 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 cacheáveis.
• 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 custo e latência para conversas extensas, especialmente aquelas com instruções longas ou documentos carregados.
• Assistentes de codificação: Melhore o autocompletar 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 forma longa incluindo imagens em seu prompt sem aumentar a latência de resposta.
• Conjuntos detalhados de instruções: Compartilhe listas extensivas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Desenvolvedores frequentemente incluem um exemplo ou dois no prompt, mas com 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 mudanças iterativas de código, onde cada etapa tipicamente requer uma nova chamada de API.
• Converse com livros, artigos, documentação, transcrições de podcast e outro conteúdo de forma longa: Traga qualquer base de conhecimento à vida incorporando o(s) documento(s) inteiro(s) no prompt, e permitindo que os usuários façam perguntas sobre ele.

​

Solucionando problemas comuns

Se estiver experimentando comportamento inesperado:

• Garanta 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 de 5 minutos
• 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

Note que mudanças em tool_choice ou a presença/ausência de imagens em qualquer lugar no prompt invalidarão o cache, exigindo que uma nova entrada de cache seja criada.

​

Armazenamento e Compartilhamento de Cache

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

• Correspondência Exata: Acertos de cache requerem segmentos de prompt 100% idênticos, incluindo todo texto e imagens até e incluindo o bloco marcado com cache control. O mesmo bloco deve ser marcado com cache_control durante leituras e criação de cache.

• Geração de Token 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.

​

Exemplos de cache de prompts

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

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

​

Perguntas Frequentes

client.beta.promptCaching.messages.create(...)

client.messages.create(...)