Prompt caching no Amazon Bedrock: corte até 90% do custo de tokens de entrada

O problema que o prompt caching resolve

Imagine enviar um contrato de 10 mil tokens ao modelo junto com 50 perguntas diferentes de usuários. Sem cache, são 500 mil tokens de entrada cobrados a preço cheio — por conteúdo que o modelo já processou. O prompt caching do Amazon Bedrock ataca esse desperdício na raiz: ao armazenar partes fixas do contexto (instruções de sistema, documentos, definições de ferramentas), o Bedrock lê os tokens em cache nas requisições seguintes em vez de reprocessá-los. O resultado prático é uma redução de até 90% no custo dos tokens de entrada em cache, além de um tempo até o primeiro token (TTFT) menor, sem alterar o modelo nem a qualidade do prompt.

Neste guia, você verá seis cenários práticos usando a Converse API do Amazon Bedrock, do básico ao avançado. Os exemplos usam o Anthropic Claude Sonnet 4.5 (global.anthropic.claude-sonnet-4-5-20250929-v1:0), mas a sintaxe do cachePoint é idêntica entre famílias de modelos suportadas, incluindo Amazon Nova.

Prós e contras

✅ O que você ganha

• Economia de até 90% nos tokens de entrada lidos do cache.
• Menor latência (TTFT) nas respostas com contexto repetido.
• Sintaxe única entre modelos suportados (Claude e Nova).
• Controle de expiração via TTL configurável por camada de conteúdo.
• Funciona para documentos, system prompts e tool definitions — não só texto solto.

⚠️ O que você NÃO ganha

• Cache expira: TTL padrão de 5 minutos, até 1 hora em modelos selecionados.
• Há custo extra de escrita: gravar no cache custa 25% a mais que input padrão.
• Exige token mínimo por checkpoint (1.024 tokens no Claude Sonnet 4.5/4.6).
• Não substitui cache de aplicação para consultas idênticas.

Como funciona o custo

Em cargas com contexto repetido, a economia líquida fica em torno de 75% no custo dos tokens de entrada. Usando o exemplo do contrato de 10 mil tokens com 10 perguntas: a primeira requisição paga a gravação, e as nove seguintes leem do cache com 90% de desconto. Vale lembrar que, após a expiração do TTL, uma nova gravação é disparada, reduzindo a economia líquida.

Requisitos

Atenção: o parâmetro ttl no cachePoint exige boto3 1.43.0 ou superior (usado no Cenário 4). Instale as dependências com:

pip install boto3>=1.43.0 langchain-aws>=0.2.12 matplotlib pandas

Cenário 1: cache de conteúdo de mensagens

O uso mais comum é cachear um documento longo consultado repetidamente — típico de aplicações RAG ou assistentes de código que referenciam uma base grande. Você coloca um marcador cachePoint entre o conteúdo estático e a pergunta dinâmica:

content = [
    {"text": "<documento estático grande>"},
    {"cachePoint": {"type": "default"}},  # cacheia tudo acima
    {"text": "<pergunta do usuário>"}  # dinâmico, muda a cada requisição
]

O Bedrock armazena tudo antes do checkpoint na primeira chamada e reutiliza nas seguintes. Para o Claude Sonnet 4.5, o documento precisa ter pelo menos 1.024 tokens para ativar o cache (o Opus exige 4.096).

Cenário 2: cache de system prompt

Se você mantém uma persona ou um conjunto de instruções fixo em todas as conversas, cacheie o system prompt. Isso evita reprocessar definições de tom, regras de negócio e contexto de identidade a cada interação — ideal para chatbots de atendimento e assistentes com personalidade definida.

Cenário 3: cache de definições de ferramentas

Em fluxos agentivos, os esquemas de ferramentas (tool definitions) raramente mudam entre chamadas, mas podem ser grandes. Cacheá-los reduz o custo de cada passo do agente que repassa o mesmo conjunto de ferramentas ao modelo — um ganho direto para agentes com dezenas de funções disponíveis.

Cenário 4: TTL misto

Nem todo conteúdo envelhece na mesma velocidade. Você pode atribuir TTLs diferentes a camadas diferentes: um documento de política da empresa pode ter TTL de 1 hora, enquanto o contexto de sessão do usuário expira em 5 minutos. Isso equilibra economia e frescor do conteúdo.

Cenário 5: isolamento por tenant

Em aplicações multi-tenant (SaaS), separar o cache por cliente é essencial para evitar vazamento de contexto entre organizações. O guia mostra como estruturar checkpoints para garantir que cada tenant leia apenas o seu próprio contexto em cache.

Cenário 6: integração com LangGraph

Para quem usa LangGraph (via langchain-aws), o prompt caching se integra ao ciclo de execução do agente, permitindo cachear estado e contexto entre nós do grafo — útil em agentes de múltiplos passos que reutilizam documentos e ferramentas.

Troubleshooting

• ❌ Cache não ativa → Documento abaixo do token mínimo (1.024 no Sonnet 4.5). Aumente o conteúdo do checkpoint.
• ❌ Economia menor que o esperado → Requisições fora da janela de TTL disparam nova gravação. Revise o TTL ou agrupe consultas no tempo.
• ❌ Parâmetro ttl não reconhecido → Versão do boto3 inferior a 1.43.0. Atualize com pip install --upgrade boto3.
• ❌ Custo de gravação alto → Você está reescrevendo cache com frequência. Em cross-Region inference, o roteamento pode aumentar a frequência de gravação.
• ❌ Vazamento de contexto entre tenants → Estruture o cachePoint para isolar o contexto por tenant (Cenário 5).

FAQ

• Qual a economia real? Cerca de 75% líquido em cargas com contexto repetido, chegando a 90% por leitura de cache.
• Quanto custa gravar no cache? 25% a mais que o input padrão; 2x com TTL de 1 hora.
• Por quanto tempo o cache dura? 5 minutos por padrão, até 1 hora em modelos que suportam TTL estendido.
• Preciso mudar de modelo? Não. A sintaxe cachePoint é a mesma para Claude e Amazon Nova.
• Funciona com LangChain? Sim, via langchain-aws (>= 0.2.12).