Phase 17 - Lesson 14

Prompt Caching and Semantic Caching Economics

Preços de referência em abril de 2026. Os valores numéricos abaixo refletem as tabelas de preços dos provedores capturadas na publicação desta lição; verifique a documentação oficial nos links antes de utilizá-los em projetos reais.

O cache ocorre em duas camadas. O cache de prompt/prefixo L2 (nível do provedor) reutiliza a atenção KV para prefixos repetidos — a documentação de cache de prompts da Anthropic aponta redução de até 90% nos custos e 85% na latência para prompts longos; para o Claude 3.5 Sonnet, leituras de cache custam $0.30/M contra $3.00/M para requisições originais (fresh) com TTL de 5 minutos, havendo uma taxa adicional de escrita (write premium) de 2x para a opção com TTL de 1 hora (docs.anthropic.com, 04/2026). O cache de prompts da OpenAI é aplicado automaticamente para prompts ≥1024 tokens e cobra pelas entradas em cache com cerca de 90% de desconto em relação ao processamento original (platform.openai.com, 04/2026); o valor exato do token armazenado em cache varia de acordo com a tabela do modelo. O cache semântico L1 (nível da aplicação) ignora totalmente a chamada de LLM ao encontrar similaridade de embeddings acima de um limiar. A alegação de "95% de precisão" dos provedores refere-se à acurácia da similaridade, não à taxa de acerto do cache (hit rate) — as taxas reais reportadas em produção variam de 10% (chats abertos) a 70% (FAQs estruturadas); nenhum provedor publica uma taxa de referência oficial, portanto, trate esses dados como telemetria da comunidade e não como garantia. Principais armadilhas em produção: a paralelização anula os benefícios do cache (N requisições paralelas feitas antes do encerramento da primeira escrita em cache podem inflar os custos em várias vezes) e conteúdo dinâmico dentro do prefixo impede totalmente os acertos (cache hits). A ProjectDiscovery reportou aumento de 7% para 74% na taxa de acerto (11/2025) ao remover textos dinâmicos do prefixo cacheável.

Type: Learn Languages: Python (stdlib, toy two-layer cache simulator) Prerequisites: Phase 17 · 04 (vLLM Serving Internals), Phase 17 · 06 (SGLang RadixAttention) Time: ~60 minutos

Learning Objectives

• Distinguir o cache de prompt/prefixo L2 (reutilização de KV no provedor) do cache semântico L1 (desvio da chamada de LLM para prompts semelhantes).
• Explicar a marcação explícita cache_control da Anthropic e as duas opções de TTL (5 minutos vs 1 hora) com seus respectivos multiplicadores de preço.
• Calcular a economia mensal esperada com base na taxa de acerto do cache (hit rate), proporção de prompts/respostas e preço dos tokens.
• Identificar o antipadrão de paralelização que infla as faturas em 5-10x e o antipadrão de conteúdo dinâmico que destrói a taxa de acerto.

O Problema

Você adiciona cache de prompt ao seu serviço de RAG, mas a fatura continua igual. Ao medir a taxa de acerto, descobre que ela é de 7%. Seus prompts parecem estáticos, mas não são — o prompt do sistema inclui a data atual formatada até o minuto, um identificador de requisição e uma reordenação aleatória de exemplos para aumentar a diversidade. Com isso, cada requisição realiza uma nova escrita no cache e obtém zero leituras.

Em paralelo, seu agente executa dez chamadas de ferramenta de forma concorrente por pergunta do usuário. As dez chamadas chegam ao provedor antes que a primeira escrita de cache termine. Resultado: dez escritas, zero leituras. Sua fatura chega a 5-10x o valor estimado usando cache.

O cache é um protocolo, não apenas um parâmetro de configuração. São duas camadas com dois modos de falha totalmente distintos.

O Conceito

L2 — cache de prompt/prefixo no provedor

O provedor armazena a atenção KV de um prefixo cacheável e a reutiliza na requisição seguinte que corresponda exatamente àquele prefixo. Você paga o custo de escrita uma única vez, e as leituras subsequentes saem quase de graça.

Anthropic (família Claude 3.5 / 3.7 / 4): marcador explícito cache_control na requisição. Você sinaliza quais blocos devem ser armazenados em cache. TTL: de 5 minutos (escrita custa 1.25x o preço base) ou de 1 hora (escrita custa 2x o preço base). As leituras do cache custam $0.30/M no Claude 3.5 Sonnet contra $3.00/M fresh — 10x mais barato (docs.anthropic.com, em 04/2026). Os valores variam por modelo (Opus/Haiku possuem preços separados); sempre consulte a página oficial de tarifas.

OpenAI: cache automático para prompts ≥1024 tokens (platform.openai.com, 04/2026). Sem parâmetros explícitos. As entradas em cache custam cerca de 10x menos que as requisições normais nas tabelas atuais do gpt-4o/gpt-5. Nem a documentação nem as notas de versão especificam uma taxa de acerto padrão; relatórios da comunidade giram em torno de 30-60% com design cuidadoso de prompts. Monitore a métrica usage.cached_tokens para validar seus resultados.

Google (Gemini): cache de contexto disponível por meio de uma API explícita; com contextos de 1 milhão de tokens, o uso de cache se torna ainda mais vantajoso.

Auto-hospedado (vLLM, SGLang): a lição 06 da Fase 17 aborda RadixAttention — o mesmo padrão rodando na sua própria infraestrutura de hardware.

L1 — cache semântico no nível da aplicação

Antes mesmo de realizar a chamada ao LLM, calcula-se o hash do prompt, gera-se o embedding e busca-se por uma requisição semelhante no cache (similaridade de cosseno acima de um limiar, geralmente 0.95+). Se houver acerto (hit), a resposta armazenada é devolvida de imediato. Em caso de erro (miss), chama-se o LLM e salva-se o resultado no cache.

Soluções de código aberto: Redis Vector Similarity, GPTCache, Qdrant. Comerciais: Portkey Cache, Helicone Cache.

As alegações de acurácia dos provedores indicam o quão adequado semânticamente era o resultado armazenado em cache fornecido — e não a frequência de acertos. Taxas de acerto observadas em produção:

• Conversas abertas (open-ended chat): 10-15%.
• FAQ estruturado / suporte: 40-70%.
• Perguntas sobre programação: 20-30% (pequenas variações impedem os acertos).
• Agentes de voz que repetem prompts: 50-80% (graças a conjuntos de normalização de voz fixos).

O antipadrão de paralelização

Seu agente dispara 10 chamadas de ferramentas de forma concorrente. Todas as 10 utilizam o mesmo prompt de sistema de 4K tokens. As escritas de cache da Anthropic ocorrem por requisição; a primeira escrita finaliza cerca de 300 ms após o provedor ler o prompt. Como as requisições 2 a 10 chegam dentro desse mesmo intervalo de milissegundos, todas encontram falhas no cache (cache miss). Assim, você paga 10 adicionais de escrita e obtém 0 descontos de leitura.

Solução: agrupar enviando o primeiro de forma sequencial — execute a primeira chamada sozinha e, assim que o cache for preenchido com a primeira resposta, dispare as requisições 2 a 10. Isso acrescenta cerca de 300 ms de latência apenas na primeira chamada de ferramenta, mas reduz a fatura em até 5-10x.

O antipadrão de conteúdo dinâmico

Seu prompt de sistema possui o seguinte formato:

You are a helpful assistant. The current time is 14:32:17.
User ID: abc123. Today is Tuesday...

Cada requisição gerada se torna única. Toda chamada realiza escrita. Zero acertos.

Solução: mova tudo o que for de fato estático para o prefixo cacheável; adicione o conteúdo dinâmico após o limite do cache:

[cacheable]
You are a helpful assistant. [rules, examples, instructions]
[/cacheable]
[dynamic, not cached]
Current time: 14:32:17. User: abc123.

A ProjectDiscovery subiu a sua taxa de acertos no cache de 7% para 74% adotando esse ajuste de prompt e detalhou a estratégia em seu blog.

Agrupamento de desenvolvimento em lote e cache para fluxos de trabalho noturnos

APIs de processamento em lote (Batch APIs, abordadas na Fase 17 · 15) concedem 50% de desconto para prazos de entrega de 24 horas. Ao empilhar o cache de entrada sobre isso, é possível obter mais ~10x de desconto. Classificações noturnas, rotulagem e geração de relatórios volumosos podem cair para ~10% do custo síncrono e sem cache ao se acumularem esses dois recursos.

Números que você deve lembrar

Os valores de tarifas de referência foram coletados em abril de 2026 a partir das documentações dos respectivos provedores, podendo sofrer alterações ao longo do tempo — reconfirme os preços vigentes antes de utilizá-los para modelagem financeira.

• Leitura de cache na Anthropic: $0.30/M de tokens no Claude 3.5 Sonnet, cerca de 10x mais barato que a leitura normal (docs.anthropic.com).
• Taxa adicional de escrita (write premium) na Anthropic: 1.25x (TTL de 5 min) ou 2x (TTL de 1 hora).
• Cache automático na OpenAI: aplicado a prompts com pelo menos 1024 tokens; a entrada em cache é tarifada com cerca de 10% do custo normal de entrada nas tabelas de preços vigentes (platform.openai.com).
• Taxa de acerto de cache semântico (reportado pela comunidade): ~10% para conversação aberta; até ~70% para FAQs estruturadas. Não é uma especificação oficial registrada pelos provedores.
• Caso ProjectDiscovery: elevação de 7% para 74% de acertos após mover conteúdo dinâmico para fora do prefixo cacheável (blog oficial, 11/2025).
• Antipadrão de paralelização: relatos de faturas infladas em 5 a 10x quando N chamadas paralelas encontram falhas sucessivas de escrita de cache.

Use na Prática

code/main.py simula o comportamento dos caches L1 e L2 em fluxos de trabalho variados. Apresenta as taxas de acerto, a fatura consolidada e demonstra o impacto do custo de paralelização concorrente.

Envie para Produção

Esta lição produz outputs/skill-cache-auditor.md. A partir de um modelo de prompt e um volume de tráfego, analisa a cacheabilidade e orienta a reestruturação das variáveis do sistema.

Exercícios

1. Execute code/main.py. Altere a flag de paralelização. Qual é o impacto na fatura consolidada?
2. Seu prompt de sistema contém um campo dinâmico de data. Altere a estrutura do prompt movendo esse campo e calcule a projeção matemática de acerto antes/depois.
3. Calcule o ponto de equilíbrio para escolha entre TTL de 1 hora (2x de escrita) versus TTL de 5 minutos (1.25x de escrita) considerando a taxa de chegada de requisições do seu serviço.
4. Um cache semântico com limiar de 0.95 obtém 20% de acertos. Ao baixar o limiar para 0.85, a taxa sobe para 50%, mas respostas incorretas começam a ser fornecidas. Indique o limiar ideal com base nas premissas técnicas e justifique.
5. Você dispara 10 subconsultas de forma concorrente para responder a cada pergunta do usuário. Reestruture essa rotina visando otimização de cache sem introduzir latência fim a fim indesejada.

Termos-Chave

Leitura Adicional

• Anthropic Prompt Caching — semântica oficial do cache_control e regras de TTL.
• OpenAI Prompt Caching — funcionamento e critérios de elegibilidade automática do cache.
• TianPan — Semantic Caching for LLMs Production
• ProjectDiscovery — Cut LLM Costs 59% With Prompt Caching
• DigitalOcean / Anthropic — Prompt Caching