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 o 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 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

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 que você armazene diferentes seções reutilizáveis separadamente. Para cada ponto de interrupção, o sistema verificará automaticamente os acertos de cache em posições anteriores e usará o prefixo correspondente mais longo se um for encontrado.

​

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 do 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.

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

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, tanto para turnos do usuário quanto do assistente
• Imagens: Blocos de conteúdo no array messages.content, em turnos do usuário
• Uso de ferramentas e resultados: 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 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 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 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 podcasts 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
• 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 em cache em partes anteriores do prompt, o que pode ser útil para consultas com listas muito longas de blocos de conteúdo

Note que alterações 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 o 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(...)