← Voltar ao Hub

Boas práticas

Regras de Ouro

O cache depende de prefixos estáveis. Qualquer variação no início do prompt invalida o aproveitamento.

1. Ordem dos fatores altera o produto

Correto

Bloco estático (system/docs/RAG fixo) → depois o conteúdo dinâmico (pergunta, variáveis).

Quebra o cache

Colocar no início: datetime.now(), nome do usuário, request_id, nonce, contadores ou qualquer string que mude a cada chamada.

2. Histórico de chat

Anexe mensagens novas sempre ao final da lista messages.
Não reordene nem reedite mensagens antigas do prefixo se quiser reutilizar o cache da conversa anterior.
O modelo pode reaproveitar o prefixo já visto e processar só o sufixo novo.

3. Tamanho mínimo do prefixo

OpenAI: cache automático costuma exigir prefixo longo (referência comum: ≥ ~1024 tokens — confirme na doc atual).
Anthropic: use cache_control: {"type": "ephemeral"} nos blocos estáticos elegíveis.

4. O que manter estático

Persona e políticas de resposta
Instruções de formato
Documentação / knowledge base fixa
Exemplos few-shot estáveis
Trechos de código ou contratos sob análise contínua

5. O que manter dinâmico (no fim)

Pergunta do turno
Parâmetros da requisição
Timestamps e identificadores de sessão
Resultados de retrieval que mudam a cada query (quando não forem a base fixa)

6. Privacidade

O cache é isolado por organização/conta do provedor, mas ainda está sob o contrato e a política do fornecedor.
Não coloque segredos desnecessários no prefixo estático.
Defina TTL/expectativa de expiração conforme o provedor (minutos a horas de inatividade).

Checklist rápido

[ ] Estático no início, dinâmico no fim
[ ] Sem datetime/user mutável no prefixo
[ ] Prefixo longo o suficiente (quando o provedor exigir)
[ ] Mesmo texto byte-a-byte entre chamadas que devem compartilhar cache
[ ] Métricas de cache_read / cached_tokens monitoradas em staging