Cache de prompts no Claude API: economize 90% em contextos repetidos

import anthropic

client = anthropic.Anthropic()

# Seu contexto custoso - prompt de sistema, docs, etc.
contexto_custoso = """
## Especificação do Produto v2.1
[... 10.000 tokens de especificação detalhada ...]

## Documentação da API
[... mais 5.000 tokens ...]

## Guia de Estilo
[... 2.000 tokens adicionais ...]
"""

# Primeira requisição - armazena o contexto em cache
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": contexto_custoso,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Resuma os limites de taxa da API"
        }
    ]
)

print(response.usage.cache_creation_input_tokens)  # Número alto
print(response.usage.cache_read_input_tokens)      # 0

Na segunda requisição com conteúdo em cache idêntico:

```python
# Segunda requisição - usa o cache
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": contexto_custoso,  # Idêntico - fica em cache
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Quais são os métodos de autenticação?"
        }
    ]
)

print(response.usage.cache_creation_input_tokens)  # 0
print(response.usage.cache_read_input_tokens)      # Número alto
```

É isso. O parâmetro `cache_control` faz o trabalho pesado. O tipo `ephemeral` mantém o cache por 5 minutos. Para retenção mais longa, use `{"type": "ephemeral"}` com valores explícitos de `ttl` ou planeje sua própria estratégia de atualização de cache.

## Cenários do Mundo Real Onde o Cache Compensa

**Processamento de Documentos em Escala**: Você está rodando suporte ao cliente onde cada consulta referencia a mesma base de conhecimento de 20KB. Em 500 consultas diárias, isso é um cache hit por requisição. Você sai de 10M tokens cobrados para 1M.

**Bot de Revisão de Código**: Sua integração com GitHub envia o mesmo contexto de repositório (README, docs de arquitetura, guia de estilo) em cada revisão de pull request. Coloque esse contexto em cache uma vez e a revisão em si usa tokens mínimos. O primeiro PR custa 50K tokens. O segundo custa 5K.

**RAG com Contextos Fixos**: Você está construindo um sistema de geração aumentada por recuperação. Seus embeddings recuperam os mesmos 5 documentos principais em 80% das consultas. Coloque esses documentos em cache. A variação nas perguntas dos usuários não importa—os resultados de recuperação caros mantêm-se baratos.

**Processamento em Lote**: Processando uma fila de 10.000 emails contra o mesmo conjunto de regras de classificação. Coloque o conjunto de regras em cache. Apenas o conteúdo do email varia por requisição.

## Os Limites (e Como Contorná-los)

**Invalidação de Cache**: Sua especificação é atualizada. A versão em cache persiste por 5 minutos. Ou espere, ou mude um único caractere no seu texto em cache para forçar uma atualização. Não é elegante, mas funciona.

**Tamanho Eficiente Mínimo**: O cache adiciona overhead mínimo, mas há um ponto de equilíbrio. Para contexto sob 1.024 tokens que você usa uma vez, o cache adiciona complexidade sem benefício. Para contexto que você reutilizará 3+ vezes em 5 minutos, o cache vence.

**Mudanças de Modelo e Mensagem**: Qualquer mudança no seu prompt em cache invalida o cache. Um modelo diferente, ordem de mensagem diferente ou prompt de sistema ajustado? Miss de cache fresco. Mantenha conteúdo em cache estável e separe input do usuário do contexto em cache.

**Rastreamento de Custo**: Seu painel de uso mostrará tokens em cache separadamente. Certifique-se de que sua equipe de finanças entenda que `cache_read_input_tokens` não são cobranças "faltando"—são economias.

## Padrão Avançado: Cache Estruturado

Não apenas coloque seu prompt de sistema inteiro em cache. Estruture seu contexto cuidadosamente:

```python
mensagens_sistema = [
    {
        "type": "text",
        "text": "Você é um especialista em produtos.",  # Pequeno, raramente muda
    },
    {
        "type": "text",
        "text": docs_produto_estavel,  # Grande, estável - COLOQUE ISSO EM CACHE
        "cache_control": {"type": "ephemeral"}
    },
    {
        "type": "text",
        "text": "A data de hoje é " + hoje,  # Variável - não coloque em cache
    }
]
```

Dessa forma, o grande contexto custoso fica em cache enquanto conteúdo pequeno e variável permanece fresco.

## Medindo Suas Economias

Rastreie essas métricas:

- **Tokens de criação de cache**: A primeira requisição que cria o cache
- **Tokens de leitura de cache**: Requisições subsequentes que acertam o cache (multiplique por 0,1 pelo custo real)
- **Taxa de eficiência de cache**: (total de tokens de leitura de cache) / (criação inicial de cache + todos os tokens de input não armazenados em cache subsequentes)

Uma taxa de eficiência acima de 3 significa que o cache vale o esforço de implementação.

## A Conclusão

O cache de prompts não é revolucionário—é pragmático. Se você está enviando o mesmo contexto repetidamente, está pagando a mais. Adicionar `cache_control` ao seu código existente é uma mudança de 10 minutos que se paga imediatamente.

Para equipes rodando workflows sérios com Claude, é fruta de baixa altura. Implemente, meça as economias e reinvista em melhores prompts ou mais requisições com seu novo orçamento.

```