Cache de Prompt e Otimização de Custo

Avançado

Se muitas das suas requisições compartilham um trecho grande e imutável — um system prompt longo, um documento extenso, um catálogo de ferramentas — o cache de prompt permite que a API reaproveite o prefixo já processado em vez de relê-lo a cada chamada. Isso reduz tanto o custo quanto a latência na parte em cache.

What you'll learn

O modelo mental: um breakpoint de cache após um prefixo estável, reaproveitado entre chamadas
Como marcar o breakpoint em Python e TypeScript com cache_control
A única invariante que faz ou quebra tudo — o prefixo precisa ser idêntico byte a byte
Como ler os campos de uso (usage) para confirmar que você está de fato obtendo acertos de cache
Onde o cache compensa mais e como combiná-lo com batching e dimensionamento adequado

Como funciona (o modelo mental)

Você marca um breakpoint de cache após o prefixo estável. Na primeira chamada ele é processado e armazenado em cache; chamadas subsequentes que compartilham o exato mesmo prefixo acertam o cache e pagam muito menos por ele.

Vocabulário de cache

Pressione Enter ou Espaço para virar o cartão. Use as setas esquerda e direita para navegar entre os cartões.Termo exibido.

1 / 4

Marque o breakpoint (copiar e colar)

Adicione cache_control ao último bloco estável — aqui, um system prompt grande. A vez do usuário vem depois dele e varia livremente; tudo até o bloco marcado, inclusive, fica em cache.

Guided walkthrough1 of 4

Encontre o trecho grande e imutável — um system prompt longo, um documento extenso ou um catálogo de ferramentas reaproveitado em muitas requisições.

Python
TypeScript

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LARGE_STABLE_PROMPT,  # long, unchanging — the cached prefix
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Summarize the key points."}],  # varies per call
)

print(message.usage.cache_read_input_tokens)  # > 0 means you got a hit

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: LARGE_STABLE_PROMPT, // long, unchanging — the cached prefix
      cache_control: { type: "ephemeral" },
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points." }], // varies per call
});

console.log(message.usage.cache_read_input_tokens); // > 0 means you got a hit

A primeira chamada paga um pequeno custo extra de gravação para popular o cache; toda chamada posterior com o mesmo prefixo o relê de volta por uma fração do preço de input. O prefixo precisa ser longo o suficiente para ser elegível — alguns milhares de tokens, dependendo do modelo — ou ele silenciosamente não será armazenado em cache.

A invariante que faz ou quebra tudo

:::warning O cache é exato no prefixo Um acerto de cache exige que o prefixo em cache seja idêntico byte a byte. O bug mais comum: um invalidador silencioso perto do topo do prompt — um timestamp, um nome de usuário que muda, uma lista de ferramentas reordenada — que altera o prefixo e silenciosamente derruba sua taxa de acerto para zero. :::

Coloque tudo o que é estável primeiro, tudo o que é variável por último, e mantenha o prefixo verdadeiramente constante.

Verifique se realmente está funcionando

Não presuma — leia de volta a partir do usage da resposta:

cache_creation_input_tokens — tokens gravados no cache nesta chamada (a primeira requisição).
cache_read_input_tokens — tokens servidos a partir do cache (a economia).
input_tokens — o restante não cacheado, cobrado a preço cheio.

Se cache_read_input_tokens permanecer em zero em requisições repetidas que deveriam compartilhar um prefixo, há um invalidador silencioso em ação — compare os bytes do prompt renderizado entre duas chamadas para encontrá-lo.

Onde compensa mais

System prompts longos reaproveitados entre usuários.
RAG / perguntas e respostas sobre documentos em que o mesmo texto-fonte é consultado repetidamente.
Agentes com um catálogo de ferramentas e instruções fixos ao longo de muitos turnos.

Combine o cache com batching para cargas de trabalho offline, e com o dimensionamento adequado do modelo (Escolhendo um Modelo) para a maior economia combinada — veja Custo e Latência.

Teste seu conhecimento

0/3

O que um acerto de cache exige do prefixo em cache?
Qual campo de usage informa que tokens foram servidos a partir do cache (a sua economia)?
Onde deve ficar o conteúdo variável, específico de cada chamada, em relação ao breakpoint de cache?

Key takeaways

Marque um breakpoint de cache após o prefixo estável; a primeira chamada o grava, as chamadas posteriores o releem de forma barata.
Um acerto de cache precisa de um prefixo idêntico byte a byte — mantenha o conteúdo estável primeiro e o variável por último.
Invalidadores silenciosos perto do topo do prompt (timestamps, nomes, ferramentas reordenadas) derrubam, sem alarde, a taxa de acerto para zero.
Verifique com o usage: cache_read_input_tokens > 0 significa um acerto; zero em requisições repetidas significa que há um invalidador em ação.
O cache compensa mais para system prompts reaproveitados, RAG e agentes; combine-o com batching e dimensionamento adequado do modelo.

Como funciona (o modelo mental)​

Marque o breakpoint (copiar e colar)​

A invariante que faz ou quebra tudo​

Verifique se realmente está funcionando​

Onde compensa mais​