Cache de prompts: como reduzir o custo de prompts repetidos

A maior parte do tráfego de LLMs se repete. Um chatbot reenvia o mesmo system prompt a cada turno, e um agente reenvia suas definições de ferramentas e toda a conversa até o momento. O cache de prompts permite que o modelo leia esse prefixo repetido do cache, e a entrada em cache é cobrada por uma fração da tarifa normal de entrada. Este guia explica como isso funciona no GetVibe API e como aproveitar ao máximo esse recurso.

Quanto você paga pela entrada em cache

Cada modelo de texto do nosso catálogo informa suas condições de cache. Em https://getvibeapi.com/api/catalog, cada variante de modelo inclui:

• cachedInputUsd: o preço por 1M de tokens de entrada em cache.
• cacheReadMult: o preço em cache como uma fração do preço normal de entrada.
• cacheWriteMult: como a gravação no cache é cobrada em relação à entrada normal.

No momento da redação, quase todos os modelos de texto listam cacheReadMult: 0.1, o que significa que um token de entrada em cache custa um décimo do preço normal, e cacheWriteMult: 1. A única exceção é Claude Fable 5.1, com 0.025 para leituras e 1.25 para gravações. Esses valores podem mudar, portanto, leia-os no catálogo ou na página de cada modelo em vez de defini-los diretamente no código.

As páginas dos modelos listam o preço da entrada em cache ao lado desses números.

Modelos OpenAI: automático

Em /v1/chat/completions, os modelos da família OpenAI usam o cache automaticamente. Quando várias solicitações começam com o mesmo prefixo estável, esse prefixo é lido do cache. Você não precisa de nenhum campo especial. O que importa é que o início da solicitação não mude. Encaminhamos o corpo da solicitação byte a byte, sem reordenar os campos, portanto, um prefixo idêntico do seu lado continua idêntico no upstream.

Claude: pontos de interrupção cache_control

O Claude só usa o cache quando a solicitação contém um ponto de interrupção cache_control explícito. Repetir o prefixo, por si só, não ativa o cache. Coloque o ponto de interrupção no final da parte que não muda:

curl https://getvibeapi.com/v1/messages \
  -H "x-api-key: $GETVIBE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5.5",
    "max_tokens": 256,
    "system": [
      {"type": "text", "text": "Uma instrução fixa extensa que vale a pena colocar em cache...",
       "cache_control": {"type": "ephemeral"}}
    ],
    "messages": [{"role": "user", "content": "Pergunta sobre a instrução"}]
  }'

Se você não enviar um ponto de interrupção por conta própria, o gateway inserirá um para você, tanto em /v1/messages quanto em /v1/chat/completions. Se você gerenciar os pontos de interrupção por conta própria, sua marcação permanecerá como está.

Cinco regras para um prompt compatível com cache

1. Conteúdo estável primeiro, conteúdo variável por último. O system prompt, as definições de ferramentas e os documentos de referência devem ficar no início. A nova mensagem do usuário deve ficar no final.
2. Nada de timestamps ou IDs de solicitação no prefixo. Um único caractere alterado perto do início invalida tudo que vem depois.
3. Mantenha as definições de ferramentas em uma ordem fixa. Gerar a lista de ferramentas a partir de um mapa sem ordem definida altera o prefixo a cada chamada.
4. Adicione ao histórico, não o reescreva. Agentes que resumem ou reordenam turnos anteriores quebram o cache. Adicione novos turnos ao final.
5. Permaneça em um único modelo. Um cache pertence a um modelo, portanto, trocar de modelo no meio da conversa começa sem cache.

Verifique se está funcionando

Observe o objeto usage na resposta. No formato OpenAI, os tokens em cache aparecem em prompt_tokens_details.cached_tokens. No formato Anthropic, procure por cache_read_input_tokens e cache_creation_input_tokens. A visualização de uso no seu dashboard também mostra a proporção de acertos de cache por modelo. Se a contagem em cache permanecer em zero em solicitações idênticas, algo no seu prefixo está mudando.

Próximos passos

Leia a documentação sobre cache, configure o Claude Code em um endpoint personalizado (os agentes são os que mais se beneficiam do cache) ou compare os preços em cache na página de modelos.