O que é prompt caching? Como um prompt repetido é reutilizado

O cache de prompt significa que a API lembra o início da sua requisição e o reutiliza na próxima vez que você enviar o mesmo início. Você ainda envia o texto completo a cada chamada, mas o provedor pode pular o trabalho de ler novamente a parte repetida, e alguns provedores cobram essa parte a uma taxa menor. Só funciona no início da requisição, e apenas se esse início for idêntico.

O bot de suporte que fica relendo a mesma página#

Digamos que você opere um bot de suporte com 2.000 tickets por dia. Toda requisição começa com os mesmos 3.000 tokens: tom de voz, regras de reembolso, política de envio. Depois vem a mensagem do cliente em uma linha, algo como "Onde está meu pedido?" (Se tokens ainda são nebulosos, comece por o que é um token.)

Sem cache, o provedor lê todos os 3.000 tokens de regras de novo para o ticket número 1, o ticket número 2 e o ticket número 2.000. A mesma página, lida 2.000 vezes. Com cache, a primeira requisição paga o preço cheio de lê-la, e as requisições seguintes que começam com o mesmo texto podem reutilizar o trabalho.

O guia da API da DeepSeek (verificado em 24 de outubro de 2026) descreve exatamente isso: o cache de contexto vem ativado por padrão, não exige mudanças no código, e uma requisição posterior com um prefixo sobreposto conta como "cache hit". Apenas a entrada é armazenada em cache. A resposta é gerada do zero a cada vez.

O que conta como "o mesmo": a regra do prefixo#

O cache compara a partir do primeiro caractere. No momento em que sua requisição difere da que está em cache, tudo depois desse ponto é novo. É por isso que a ordem da sua requisição importa mais do que o tamanho dela.

Aqui está o erro que mata o cache silenciosamente. Um desenvolvedor quer que o bot saiba a hora e a coloca no topo:

Current time: 14:03:22
You are a support assistant for a shop...
(3,000 tokens of rules)

A hora muda a cada segundo, então a primeira linha difere em toda requisição, e nada depois dela pode corresponder. A correção é mover o que muda para o final:

You are a support assistant for a shop...
(3,000 tokens of rules)
Current time: 14:03:22
Customer: Where is my order?

Agora os 3.000 tokens de regras vêm primeiro e permanecem idênticos. A mesma lógica cobre os outros dois casos comuns: um chat longo reenvia todo o histórico a cada turno, então as mensagens antigas são um início repetido pronto (mais sobre isso em por que um chat longo custa mais), e um agente repete suas definições de ferramentas e instruções a cada passo.

O cache também é best-effort. A DeepSeek diz que o cache leva alguns segundos para ser construído, um hit precisa de uma correspondência completa de uma unidade de prefixo de cache existente, não há taxa de acerto garantida, e caches não utilizados são limpos, geralmente em horas ou dias. Então uma segunda requisição disparada meio segundo depois da primeira pode ainda não acertar, e o hit pode cobrir menos do que todo o seu prefixo.

Como ver isso: os campos de cache no usage#

Você não precisa adivinhar se funcionou. Cada provedor reporta isso na parte usage da resposta, com seus próprios nomes de campo.

A DeepSeek usa dois campos:

• prompt_cache_hit_tokens — tokens de entrada encontrados no cache
• prompt_cache_miss_tokens — tokens de entrada que não estavam

Digamos que seu primeiro ticket de suporte volte com prompt_cache_hit_tokens: 0 e prompt_cache_miss_tokens: 3200, e um ticket um minuto depois mostre prompt_cache_hit_tokens: 3000 e prompt_cache_miss_tokens: 200. Os 3.000 tokens de regras foram reutilizados; apenas a nova mensagem do cliente e alguns tokens foram lidos do zero. Se o número de hits ficar em zero em toda chamada, olhe o início da sua requisição: algo ali está mudando.

A Anthropic funciona de forma diferente, porque você marca o que deve ser armazenado em cache. Você adiciona cache_control com tipo ephemeral à requisição ou a um bloco de conteúdo:

{
  "model": "your-model-id",
  "max_tokens": 300,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant... (long rules)",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "Where is my order?"}]
}

De acordo com a documentação de prompt caching da Anthropic (verificada em 24 de outubro de 2026), a resposta reporta três números: cache_creation_input_tokens (gravado no cache agora), cache_read_input_tokens (lido dele) e input_tokens (o que veio depois do último ponto de quebra de cache). Digamos que a primeira chamada mostre cache_creation_input_tokens: 10000, cache_read_input_tokens: 0; a segunda mostre 0 e 10000. Isso é uma gravação em cache seguida de uma leitura de cache.

Há uma armadilha na tela. Prompts menores que o mínimo do modelo (512, 1.024 ou 4.096 tokens, dependendo do modelo) são processados sem cache e sem erro. Você verá zeros nos dois campos de cache e nenhum aviso. O tempo de vida padrão é de 5 minutos, renovado gratuitamente a cada uso; um ttl opcional de 1h o mantém por mais tempo.

O que isso faz com a sua conta#

O cache muda o preço da parte repetida, então vale a pena calcular uma vez. A Anthropic lista multiplicadores sobre o preço base de entrada: uma gravação em cache com tempo de vida de 5 minutos custa 1,25×, uma leitura custa 0,1× (0,05× para Opus 5.5 e Sonnet 5.5). Pegue um prefixo de 10.000 tokens reutilizado em 20 requisições dentro da janela de 5 minutos, usando a leitura padrão de 0,1×:

10.000 × 20 = 200.000 tokens pelo preço base sem cache

10.000 × 1,25 = 12.500 para a primeira requisição que grava o cache

19 × 10.000 × 0,1 = 19.000 para as 19 requisições que o leem

12.500 + 19.000 = 31.500 equivalentes de token com cache

Então a parte repetida custa bem menos de um quinto do valor sem cache. A pegadinha: se os 5 minutos passarem entre as requisições, a próxima grava o cache de novo a 1,25×, e um prefixo raramente usado pode acabar custando mais do que sem cache nenhum.

Agora o bot do início, como uma linha de base simples a preço cheio. 2.000 requisições por dia, 3.000 tokens de entrada e cerca de 300 tokens de saída cada:

2.000 × 3.000 = 6.000.000 tokens de entrada por dia

2.000 × 300 = 600.000 tokens de saída por dia

A tabela precifica a carga de trabalho desse dia em cada modelo CheapTokens disponível ao lado do OpenRouter:

O DeepSeek-V4-Flash é mais barato que o OpenRouter no total, com entrada e saída somadas, e a carga de trabalho cabe facilmente: contexto de 380K e até 32.768 tokens de saída por resposta. Este é o custo a preço cheio da carga de trabalho: tokens de entrada × preço por token. Um prefixo longo e estável é onde essa parcela de entrada é maior.

Experimente você mesmo em cinco minutos#

O plano: envie o mesmo prompt de sistema longo duas vezes com perguntas diferentes e observe usage. Coloque seu próprio texto de regras em support_rules.txt (uma ou duas páginas de texto bastam). O endpoint é a API CheapTokens compatível com OpenAI, e você pode pegar a chave na sua conta.

from openai import OpenAI

client = OpenAI(base_url='https://api.cheaptokens.dev/v1', api_key='YOUR_API_KEY')

SYSTEM = open('support_rules.txt').read()  # long, never changes

for question in ['Where is my order?', 'Can I change the address?']:
    r = client.chat.completions.create(
        model='deepseek-ai/DeepSeek-V4-Flash-0731',
        messages=[
            {'role': 'system', 'content': SYSTEM},
            {'role': 'user', 'content': question},
        ],
        max_tokens=300,
    )
    print(r.usage)

O que verificar na saída: prompt_tokens informa o tamanho da sua requisição. Ambas as requisições carregam o mesmo texto SYSTEM, então a maior parte desse número se repete de uma requisição para a outra — aproximadamente o tamanho do seu arquivo de regras. Esse início repetido é a parte que um provedor com cache, como a API DeepSeek ou a Anthropic acima, pode reutilizar. Agora um exercício sobre ordem: adicione uma linha com a hora atual (datetime.now()) no topo de SYSTEM e execute de novo. As duas requisições não compartilham mais um início, porque diferem desde a primeira linha. Coloque a mesma linha no final do prompt e o início compartilhado volta.

Uma lista de verificação curta para seus próprios prompts:

1. Texto estável primeiro: instruções, regras, definições de ferramentas, exemplos.
2. Texto que muda por último: data, nome do usuário, a mensagem mais recente.
3. Mantenha o prefixo idêntico byte a byte — até um espaço extra conta.
4. Verifique o tamanho mínimo do provedor antes de se perguntar por que nada está em cache.
5. Olhe os campos de usage depois de uma mudança, não antes.

Para precificar sua própria carga de trabalho, abra a página de preços e insira seus tamanhos de entrada e saída, ou comece pela página da DeepSeek. Depois que a primeira requisição funcionar, a mesma estimativa leva um minuto para qualquer prompt que você escrever. Para saber quanto custam os dois lados de uma requisição, veja tokens de entrada vs saída.