[Contexto de IA #7] Reduza o custo da API com cache de prompts

O último artigo da série é sobre dinheiro. Se você já executou um agente por API, provavelmente notou algo estranho na cobrança: os tokens de entrada custam muito mais que os de saída. Lembrando a estrutura do primeiro artigo, isso é esperado. A cada turno, todo o conteúdo, do prompt do sistema ao histórico completo, é enviado novamente; em uma sessão de 50 turnos, o mesmo prompt do sistema é cobrado 50 vezes.

O cache de prompts (prompt caching) reduz esse custo repetitivo. Bem utilizado, ele pode derrubar o custo de entrada para um décimo e acelerar as respostas, mas há uma condição: o contexto precisa ser acumulado de um jeito favorável ao cache. Neste artigo, veremos o princípio e os erros que destroem o cache sem percebermos.

O mesmo prefixo não é recalculado

Já vimos metade do princípio no primeiro artigo. Ao processar a entrada, o modelo produz resultados intermediários de atenção para cada token e os acumula na memória da GPU como cache KV. O cache de prompts mantém esse cache KV após o fim de uma requisição e reutiliza todo o cálculo quando a próxima começa com o mesmo conteúdo.

Veja como isso se encaixa nas conversas de agentes. A entrada do turno 10 é “prompt do sistema + turnos 19 + nova mensagem”; a do turno 11 é “prompt do sistema + turnos 110 + nova mensagem”. O início é idêntico. Com cache, o servidor recupera o resultado já calculado até o turno 10 e calcula apenas a cauda recém-adicionada.

A cobrança segue essa estrutura. Na Anthropic API, tokens de entrada lidos do cache custam apenas 10% do preço normal. Tokens gravados no cache pela primeira vez têm acréscimo de 25%, mas isso é rapidamente compensado no padrão de agentes que escreve uma vez e lê várias. Em sessões de centenas de turnos, ter ou não cache pode multiplicar o custo; como o trecho em cache é ignorado, a latência até o primeiro token também cai bastante.

Uma condição: o prefixo não pode mudar nem um caractere

Não existe almoço grátis. A reutilização do cache exige correspondência do prefixo. Ela se aplica apenas ao trecho idêntico e contínuo desde o início da entrada; a partir do primeiro ponto diferente, tudo é recalculado.

O primeiro artigo também explica o motivo. Na atenção, o valor KV de cada token depende de todos os tokens anteriores. Se um único token inicial mudar, os resultados de todos os tokens seguintes mudam, e o cache deixa de ser utilizável. É por isso que alterar o início do contexto custa tanto.

O princípio de um contexto favorável ao cache cabe em uma frase: o que é estável fica na frente, o que é variável fica atrás, e o histórico só recebe acréscimos (append-only).

Erros descuidados que destroem o cache

O princípio é simples, mas há muitas formas sutis de violá-lo.

A primeira são valores variáveis no prompt do sistema. Se você inserir a hora atual com precisão de segundos, o início do contexto mudará a cada requisição e a taxa de acerto será 0%. Se precisar incluí-la, arredonde para o nível de data ou coloque-a no fim do contexto. IDs de sessão e valores aleatórios são armadilhas iguais.

A segunda é alterar definições de ferramentas. O esquema costuma ficar no topo do contexto; portanto, adicionar ou remover uma ferramenta no meio da sessão invalida todo o cache posterior. No quarto artigo, recomendei organizar os servidores MCP; pela ótica do cache, acrescente: faça isso antes de iniciar a sessão e não mexa depois.

A terceira é editar o histórico no meio. Alterar um turno anterior ou apagar turnos antigos para economizar contexto quebra o prefixo e elimina o cache daquele ponto em diante. Ao tentar poupar alguns milhares de tokens, você pode acabar pagando o recálculo da sessão inteira. Se precisar apagar algo do histórico, é melhor fechar um bloco e limpá-lo por completo.

Por fim, /compact do terceiro artigo também merece uma nova leitura sob a ótica do cache. Como a compactação substitui todo o histórico por um novo resumo, ela reinicia completamente o cache. No longo prazo, pode compensar porque os turnos seguintes constroem um novo cache sobre um histórico menor; ainda assim, entenda que “compact não é uma limpeza gratuita, mas um evento com custo de reconstrução do cache”. Por isso, em muitos casos, /clear a cada bloco é mais barato que compactar com frequência.

Resumo da série: sete sensibilidades para lidar com contexto

Vamos dobrar, uma linha por vez, os princípios que atravessaram os 7 artigos.

1. A janela de contexto é finita, e seu limite vem da física dos cálculos de atenção e do cache KV.
2. Caber não significa ser bem aproveitado. O comprimento, por si só, reduz a qualidade.
3. /clear é o padrão em cada limite de trabalho; use /compact com instruções apenas quando precisar manter o contexto.
4. Prompt do sistema, CLAUDE.md e definições de ferramentas são custos fixos. Mantenha curto apenas o que é sempre verdadeiro.
5. Isole no contexto de um subagente as tarefas cujo processo é pesado, mas cuja conclusão é simples.
6. Externalize em arquivos o conhecimento que precisa atravessar sessões: arquivos de plano, memória e RAG quando crescer.
7. O contexto precisa ser acumulado com append-only para o cache funcionar: estável na frente, variável atrás.

Em uma frase: contexto não é capacidade do modelo, mas um orçamento projetado pelo usuário. Mesmo na era de 1 milhão de tokens, essa percepção continuará válida. Quanto maior a janela, mais a capacidade de escolher o que colocar nela criará diferenças de desempenho.