Sua conta de IA triplicou da noite para o dia. O modelo, o volume de tráfego e até mesmo o texto dos prompts permaneceram os mesmos; o culpado foi uma única linha de código que quebrou o cache de prompt da OpenAI.

Por que o cache é importante

O cache de prompt do provedor economiza dinheiro ao evitar o reprocessamento de qualquer requisição que comece com um prefixo byte a byte idêntico. Se os primeiros tokens corresponderem a uma chamada anterior, o provedor reutiliza a representação já computada desses tokens e cobra apenas pelo novo sufixo. A regra é rigorosa: a correspondência deve ser exata, não apenas semelhante. Um único token diferente no início destrói todo o acerto do cache.

O erro que destruiu a taxa de acerto

Em nosso agente, colocamos um timestamp atual no topo do prompt do sistema para dar ao modelo uma noção de "agora". Como o timestamp muda a cada segundo, a sequência de primeiros tokens era única para cada requisição. O cache nunca encontrava uma correspondência, então cada chamada incorria no preço total para os 18.000 tokens estáticos que vinham a seguir — esquemas de ferramentas, trechos de documentação, exemplos few-shot e instruções fixas. O resultado foi uma taxa de acerto de cache de 0% e uma conta que triplicou.

Reordenando para facilitar o cache

A solução é simples: mantenha tudo o que nunca muda no início do prompt e mova qualquer dado volátil para o final.

Prefixo estático (cacheável)

  • Definições de ferramentas
  • Documentos de recuperação
  • Exemplos few-shot
  • Instruções de sistema fixas

Sufixo volátil (não cacheável)

  • Hora atual
  • Identificadores de sessão
  • Mensagens do usuário
  • Contexto em tempo real

Se o modelo precisar da hora, anexe-a após o bloco estático em vez de colocá-la no início. O cache pode, então, reutilizar a parte estática pesada enquanto você ainda fornece o contexto atualizado ao final.

Assassinos ocultos na stack

Mesmo quando o template parece correto, middlewares ou SDKs podem adicionar metadados silenciosamente no início — IDs de requisição, timestamps ou outros cabeçalhos — antes que o payload chegue à API. Alguns pipelines de implantação também embaralham as definições de ferramentas a cada rollout. Essas mudanças invisíveis alteram a sequência de bytes e sabotam o cache sem qualquer alteração de código no seu próprio construtor de prompts.

Monitore a taxa de acerto do cache

Trate a taxa de acerto do cache como uma métrica de saúde primária para qualquer agente de IA. Uma queda repentina sinaliza que algo nos bytes iniciais da requisição tornou-se variável. Ferramentas de monitoramento que expõem a porcentagem de acerto permitem identificar anomalias de custo antes que elas explodam.

Resumo

O cache de prompt depende de um prefixo imutável. Qualquer coisa que mude — até mesmo um único timestamp — no início de cada requisição anula o cache e pode triplicar sua conta. Mantenha o conteúdo estático primeiro, o conteúdo volátil por último, audite sua cadeia de ferramentas em busca de prefixos ocultos e monitore as taxas de acerto do cache. Um layout de prompt disciplinado protege tanto o desempenho quanto o seu lucro.