Cache avançado de prompts
Nesta página
Para além do cache automático
Já viu os fundamentos do cache de prompts na Lição 3. Aí, o cache surgia como um mecanismo automático que o beneficia sem esforço especial, e isso é verdade enquanto a sua aplicação enviar pedidos bem ordenados. A realidade da produção é mais caótica: múltiplos utilizadores acedem à mesma API simultaneamente, cada um com a sua pasta, documentos e perguntas. O prefixo comum reduz-se então a quase nada, e a taxa de acertos do cache colapsa sem que ninguém perceba, já que nada falha — a fatura é que aumenta.
Múltiplos utilizadores, múltiplos documentos, pipelines de processamento: vamos abordar estes cenários complexos um a um para maximizar a taxa de acertos do cache. O princípio orientador cabe numa frase: o cache não é algo que lhe acontece; é algo que desenha.
Arquitetura de prompts para maximizar o cache
O cache aplica-se ao maior prefixo comum entre os seus pedidos. Quanto mais longo e estável for este prefixo, mais poupa. A consequência prática é que um prompt deve ser organizado do mais estável para o mais variável, como um livro cujas primeiras páginas nunca mudam e apenas o capítulo final é reescrito em cada edição.
O exemplo abaixo aplica este princípio a um assistente de análise documental para um escritório de advocacia. Três camadas sucedem-se: instruções globais, que estão congeladas; a base de conhecimento, revista uma vez por mês; e o processo do caso e a pergunta, que mudam a cada chamada.
import openai
client = openai.OpenAI()
# Arquitetura em camadas: do mais estável ao mais variável
# Camada 1: Instruções globais (nunca mudam)
GLOBAL_INSTRUCTIONS = """
You are a document analysis assistant for a law firm.
Rules:
- Always respond in French
- Cite relevant legal articles
- Structure as: Analysis / Risks / Recommendations
- Be factual and precise
"""
# Camada 2: Base de conhecimento (muda raramente)
KNOWLEDGE_BASE = """
[Insert 5,000+ tokens of case law, legal articles,
analysis templates here—this content changes at most once a month]
"""
# Camada 3: Contexto do caso (muda por cliente)
def build_prompt(case_context: str, question: str) -> str:
return f"""{GLOBAL_INSTRUCTIONS}
{KNOWLEDGE_BASE}
--- Current Case ---
{case_context}
--- Question ---
{question}"""
O erro clássico é colocar o nome do cliente ou a data de hoje no início do prompt do sistema para o «personalizar». Um único carácter variável na posição inicial é suficiente para tornar o prefixo único, reduzindo a taxa de acertos do cache a zero para todas as camadas subsequentes. Tudo o que varia deve ficar no final.
Claro, precisa de verificar se a teoria se traduz em números. O monitor seguinte lê input_tokens_details.cached_tokens em cada resposta e acumula as medições, dando-lhe uma taxa média utilizável em vez de um palpite.
class CacheMonitor:
"""Monitoriza a eficiência do cache de prompts."""
def __init__(self):
self.calls: list[dict] = []
def record(self, usage) -> dict:
total_input = usage.input_tokens
cached_tokens = getattr(
usage.input_tokens_details, "cached_tokens", 0
)
rate = cached_tokens / total_input if total_input > 0 else 0
entry = {
"total_input": total_input,
"cached_tokens": cached_tokens,
"cache_rate": rate,
}
self.calls.append(entry)
return entry
@property
def average_rate(self) -> float:
if not self.calls:
return 0.0
return sum(a["cache_rate"] for a in self.calls) / len(self.calls)
def report(self) -> str:
if not self.calls:
return "Nenhuma chamada."
return (
f"Chamadas: {len(self.calls)} | "
f"Taxa média de cache: {self.average_rate:.1%} | "
f"Tokens poupados: "
f"{sum(a['cached_tokens'] for a in self.calls):,}"
)
monitor = CacheMonitor()
Três padrões que fazem a diferença
O primeiro padrão diz respeito à ordem de processamento. Quando processa um lote de pedidos heterogéneos, executá-los pela ordem de chegada alterna os prefixos e impede que o cache se mantenha quente. Agrupar por contexto comum resolve o problema: reúna primeiro, execute depois, para que cada grupo beneficie do prefixo preparado pelo seu primeiro pedido.
from collections import defaultdict
def group_by_context(
requests: list[dict],
) -> dict[str, list[dict]]:
"""Agrupa pedidos por prefixo comum."""
groups = defaultdict(list)
for request in requests:
# Chave = hash do contexto partilhado
key = hash(request.get("shared_context", ""))
groups[key].append(request)
return dict(groups)
def process_by_cohort(requests: list[dict]):
"""Processa pedidos agrupados para maximizar o cache."""
groups = group_by_context(requests)
for key, group in groups.items():
# Todos os pedidos no grupo partilham o mesmo prefixo
for request in group:
response = client.responses.create(
model="gpt-5.6-terra",
instructions=request["shared_context"],
input=request["question"],
)
monitor.record(response.usage)
O segundo padrão lida com arranques a frio. O primeiro pedido de uma série paga o preço total, já que nada está ainda em cache; se esse primeiro pedido vier de um utilizador real numa segunda-feira de manhã às 9h, ele suporta a latência. Um pedido de aquecimento enviado antes da abertura do serviço desloca esse custo para onde não incomoda ninguém. Note a guarda no início da função: abaixo de 1.024 tokens, o cache não se aplica, e o pré-aquecimento seria pura despesa.
def warm_up_cache(system_prompt: str):
"""Envia um pedido mínimo para preparar o cache."""
if len(system_prompt) // 4 < 1024:
print("Prompt demasiado curto para cache (< 1.024 tokens)")
return
response = client.responses.create(
model="gpt-5.6-terra",
instructions=system_prompt,
input="Confirm that you are ready.",
max_output_tokens=10,
)
usage = response.usage
print(
f"Cache preparado: {usage.input_tokens} tokens de entrada, "
f"{getattr(usage.input_tokens_details, 'cached_tokens', 0)} em cache"
)
O terceiro padrão torna visível a invalidação do cache. Corrigir uma vírgula num prompt de sistema de 5.000 tokens parece trivial, mas essa vírgula limpa o cache para todos. Ao anexar uma impressão digital ao conteúdo, deteta a mudança na implementação e não no dia seguinte na fatura, podendo proceder imediatamente ao pré-aquecimento.
import hashlib
class VersionedPrompt:
"""Gere versões de prompts para controlar o cache."""
def __init__(self, content: str):
self.content = content
self.version = hashlib.md5(content.encode()).hexdigest()[:8]
def is_same_version(self, other: "VersionedPrompt") -> bool:
return self.version == other.version
# Se a versão mudar, o cache será invalidado
prompt_v1 = VersionedPrompt("Instructions v1...")
prompt_v2 = VersionedPrompt("Instructions v2 modified...")
if not prompt_v1.is_same_version(prompt_v2):
print("Aviso: prompt alterado, o cache será invalidado")
warm_up_cache(prompt_v2.content)
O que isto significa em volume
Tome um caso real de 10.000 chamadas por dia com um prompt de sistema de 3.000 tokens. Sem cache, fatura 10.000 × 3.000, ou seja, 30M de tokens de entrada todos os dias. Com uma taxa de acertos de 80%, 6M de tokens permanecem a preço total e 24M caem para metade do preço, levando a poupança a cerca de 40% nos tokens de entrada. O valor parece modesto relativamente a uma única chamada; ao longo de um ano de produção, altera a estrutura de custos da aplicação.
Pontos-chave
- Estruture os seus prompts em camadas, do mais estável ao mais variável
- Agrupe pedidos por contexto partilhado para manter o cache quente
- Aqueça o cache antes de picos de tráfego
- Monitore a taxa de cache com
input_tokens_details.cached_tokens - Versione os seus prompts para antecipar invalidações de cache