Cache de prompts: Reutilizar computações
O que é o cache de prompts?
Quando envia repetidamente o mesmo prefixo de prompt — um prompt de sistema longo, instruções detalhadas ou um documento de referência —, a OpenAI pode colocar automaticamente esse prefixo em cache. As chamadas subsequentes que partilham este prefixo beneficiam de um tempo reduzido até ao primeiro token (TTFT) e de custos mais baixos nos tokens de entrada. Por outras palavras, o trabalho de ingestão do contexto estável não é repetido em cada pedido.
O cache de prompts tem sido automático desde 2025: não precisa de ativar nada. A OpenAI deteta prefixos idênticos e coloca-os em cache. A sua alavanca, portanto, não está em ligar ou desligar esta funcionalidade, mas sim em escrever os seus prompts de forma a que o mecanismo possa ser aplicado. Trata-se de uma questão de estrutura, não de configuração, e é aqui que a maioria das equipas deixa dinheiro sobre a mesa.
Como funciona
O cache aplica-se a prefixos de prompt: os primeiros tokens devem ser estritamente idênticos de uma chamada para a seguinte, e a correspondência interrompe-se no primeiro carácter divergente. É necessário um tamanho mínimo de 1.024 tokens para ativar o cache, o que exclui imediatamente prompts de sistema curtos. O cache é partilhado dentro de uma única organização, o que significa que vários serviços na sua empresa que chamam o mesmo prefixo ajudam-se mutuamente. A sua duração varia de alguns minutos a algumas horas, sem garantia firme, e a redução alcançada é de aproximadamente 50% no custo dos tokens de entrada em cache.
A consequência prática da regra do prefixo é que deve colocar os elementos estáveis no início do prompt e os elementos variáveis no final. Um serviço que insira a data de hoje ou um ID de sessão no cabeçalho do seu prompt de sistema invalida o seu cache em cada chamada, sem sequer se dar conta disso.
import openai
client = openai.OpenAI()
# ✅ Boa estrutura: elementos estáveis primeiro
SYSTEM_PROMPT = """You are a legal assistant specializing in French
contract law. You analyze contractual clauses according to the
Civil Code and recent case law. You always respond by
structuring your analysis: 1) Clause identification,
2) Legal analysis, 3) Potential risks, 4) Recommendations.
Here is the reference contract to analyze:
[Insert a 2,000+ token document here that does not change between calls]
"""
def analyze_clause(clause: str) -> str:
"""Cada chamada reutiliza o cache do prompt de sistema."""
response = client.responses.create(
model="gpt-5.6-terra",
instructions=SYSTEM_PROMPT, # Prefixo estável = em cache
input=f"Analyze this clause: {clause}", # Parte variável
)
return response.output_text
Neste exemplo, o contrato de referência e a estrutura de análise constituem o bloco invariante, enquanto a cláusula em exame muda a cada chamada. Analise quarenta cláusulas do mesmo contrato e pagará o contexto uma única vez ao preço total.
Verificar o cache
Uma otimização que não mede é uma otimização que apenas pensa ter. A API devolve informações sobre a utilização do cache na resposta:
response = client.responses.create(
model="gpt-5.6-terra",
instructions=SYSTEM_PROMPT,
input="Analyze the non-compete clause.",
)
# Verificar utilização do cache
usage = response.usage
print(f"Input tokens: {usage.input_tokens}")
print(f"Input tokens (cached): {usage.input_tokens_details.cached_tokens}")
print(f"Output tokens: {usage.output_tokens}")
# Se cached_tokens > 0: o cache foi utilizado
cache_ratio = usage.input_tokens_details.cached_tokens / usage.input_tokens
print(f"Cache ratio: {cache_ratio:.1%}")
Registe esta taxa em produção em vez de a verificar apenas uma vez em desenvolvimento. Uma queda súbita na taxa de cache é o sintoma mais fiável de uma alteração involuntária na construção do prompt, e verá isso antes que a fatura mensal lho indique.
Estruturar para maximizar o cache
A primeira abordagem é enriquecer deliberadamente o prompt de sistema. Isto pode parecer contraproducente quando se tenta reduzir tokens, mas alinha-se com a regra do limiar: um prompt de sistema de 900 tokens nunca será colocado em cache, enquanto o mesmo prompt enriquecido com exemplos few-shot e um documento de referência ultrapassa a linha e muda para a taxa reduzida para a parte em cache.
# Enriquecer o prompt de sistema para maximizar o cache
ENRICHED_PROMPT = """
[Detailed instructions - 500+ tokens]
[Few-shot examples - 500+ tokens]
[Reference document - 1,000+ tokens]
---
Total > 1,024 tokens = eligible for cache
"""
Numa conversa multi-turno, o mecanismo trabalha a seu favor sem esforço adicional: o histórico acumulado forma um prefixo naturalmente estável que cresce a cada troca. Desde que reinjete sempre as mensagens pela mesma ordem, o décimo turno beneficia do cache construído pelos nove anteriores.
def conversation_with_cache(history: list[dict], new_message: str):
"""O histórico crescente maximiza o cache automaticamente."""
history.append({"role": "user", "content": new_message})
response = client.responses.create(
model="gpt-5.6-terra",
instructions=SYSTEM_PROMPT,
input=history,
)
history.append({
"role": "assistant",
"content": response.output_text,
})
return response.output_text
Finalmente, uma vez que a duração do cache se mede em minutos, agrupar pedidos que partilham um prefixo torna-se uma decisão de agendamento. Processar quarenta cláusulas de um contrato seguidas mantém o cache ativo; espalhá-las ao longo do dia, intercalando outros ficheiros, permite que expirem entre chamadas.
import asyncio
async def batch_with_cache(clauses: list[str]) -> list[str]:
"""Envia pedidos rapidamente para aproveitar o cache."""
results = []
for clause in clauses:
result = analyze_clause(clause)
results.append(result)
return results
Três erros anulam todo este trabalho e assemelham-se entre si: modificar o início do prompt, mesmo que seja um único carácter, invalida o cache para todo o pedido; aleatorizar a ordem das instruções, por exemplo, construindo o prompt a partir de um dicionário não ordenado, produz o mesmo efeito intermitentemente e é, portanto, difícil de diagnosticar; e esperar ganhos abaixo do limiar de 1.024 tokens significa tentar otimizar algo que nunca é acionado.
Pontos-chave
- O cache de prompts é automático com a OpenAI — coloque elementos estáveis no início do prompt
- Limiar mínimo: 1.024 tokens idênticos no prefixo
- Ganho: ~50% nos tokens de entrada em cache + TTFT reduzido
- Verifique
usage.input_tokens_details.cached_tokenspara confirmar o cache