Prompt Caching no Amazon Bedrock: Reduza Custos em até 90% e Melhore a Latência

O problema que o prompt caching resolve

Imagine uma aplicação que envia um contrato de 10.000 tokens para um modelo de linguagem junto com 50 perguntas diferentes de usuários. Sem nenhum mecanismo de cache, isso representa 500.000 tokens de entrada cobrados pelo preço cheio — mesmo que o modelo já tenha processado aquele conteúdo dezenas de vezes antes.

As alternativas tradicionais para contornar esse problema têm custos embutidos: reduzir o tamanho dos prompts pode comprometer a qualidade do contexto; diminuir a janela de contexto limita a capacidade de raciocínio do modelo; e o cache de respostas idênticas só ajuda quando a pergunta é exatamente a mesma, o que raramente acontece em produção.

O prompt caching no Amazon Bedrock atua diretamente na infraestrutura para resolver esse problema. Ao armazenar um snapshot do processamento parcial da entrada, requisições subsequentes com o mesmo prefixo ignoram o reprocessamento daquele trecho. O resultado prático: redução de até 90% no custo dos tokens de entrada em cache e melhora no tempo até o primeiro token (TTFT — Time to First Token), sem alterar o modelo ou a qualidade dos prompts.

Como o mecanismo funciona

O funcionamento é direto: ao incluir um marcador cachePoint na requisição, o Amazon Bedrock verifica se o conteúdo anterior a esse marcador corresponde a uma entrada já existente no cache. Se houver correspondência (cache hit), o modelo pula o reprocessamento daqueles tokens e parte do estado já armazenado. Se não houver (cache miss), o conteúdo é processado normalmente e gravado em cache para uso futuro.

Quatro conceitos definem o comportamento do cache na prática:

• Escopo do cache: as entradas são isoladas por conta AWS e por Região.
• Limite mínimo de tokens: cada checkpoint precisa atingir um mínimo para ser ativado. O Claude Sonnet 4.5 e 4.6, por exemplo, exigem ao menos 1.024 tokens por checkpoint; modelos Opus exigem 4.096.
• TTL (Time-to-Live): entradas expiram conforme o TTL definido na requisição. O padrão é 5 minutos, com alguns modelos suportando até 1 hora.
• Sintaxe agnóstica de modelo: a sintaxe cachePoint da Converse API funciona igualmente para Claude (Anthropic) e Amazon Nova.

Estrutura de preços

O prompt caching introduz duas categorias adicionais de tokens, além dos tokens de entrada e saída padrão:

• cacheWriteInputTokens: tokens gravados no cache na primeira requisição — custo 25% maior que o input padrão.
• cacheReadInputTokens: tokens lidos do cache nas requisições seguintes — custo 90% menor que o input padrão.
• cacheWriteInputTokens com TTL de 1 hora: custo 100% maior (2x) que o input padrão.

Para cargas de trabalho com contexto repetido, a economia líquida fica em torno de 75% nos custos de tokens de entrada. Por exemplo: ao enviar um documento de 10.000 tokens com 10 perguntas diferentes, a primeira requisição gera um cache write. As nove seguintes leem do cache com 90% de desconto, resultando em economia líquida de aproximadamente 75% — desde que todas ocorram dentro da janela de TTL. Consulte a página de preços do Amazon Bedrock para os valores detalhados.

Seis cenários práticos com a Converse API

A documentação da AWS apresenta seis padrões progressivos de implementação, do básico ao avançado. Todos os exemplos utilizam o modelo Anthropic Claude Sonnet 4.5 (global.anthropic.claude-sonnet-4-5-20250929-v1:0) e requerem Python 3.10 ou superior com as dependências boto3>=1.43.0 e langchain-aws>=0.2.12. Para habilitar o acesso ao modelo, consulte a documentação de gerenciamento de acesso a modelos.

Cenário 1: Cache de conteúdo de mensagem

O caso de uso mais comum: cachear documentos longos consultados repetidamente, como em aplicações de Geração Aumentada por Recuperação (RAG — Retrieval Augmented Generation) ou assistentes de código que referenciam bases de código extensas.

O marcador cachePoint é inserido entre o documento estático e a pergunta dinâmica:

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

A resposta da API inclui os campos cacheWriteInputTokens (na primeira chamada) e cacheReadInputTokens (nas chamadas seguintes). Em testes com o Claude Sonnet 4.5 e um documento acima de 1.024 tokens, a primeira resposta mostra:

{
  "inputTokens": 28,
  "outputTokens": 253,
  "cacheWriteInputTokens": 1898,
  "cacheReadInputTokens": 0
}

E a requisição seguinte com o mesmo documento, mas pergunta diferente:

{
  "inputTokens": 28,
  "outputTokens": 294,
  "cacheWriteInputTokens": 0,
  "cacheReadInputTokens": 1898
}

Os modelos Claude no Amazon Bedrock suportam gerenciamento simplificado de cache: um único cachePoint já verifica automaticamente hits nos prefixos de até aproximadamente 20 blocos de conteúdo anteriores ao marcador. Para controle mais granular, é possível inserir múltiplos cachePoint após cada seção, habilitando hits parciais de cache.

Cenário 2: Cache de system prompt

Aplicações baseadas em personas detalhadas — assistentes de domínio, bots de atendimento com políticas complexas, agentes com instruções extensas — pagam o custo de reprocessar o system prompt em cada interação. Com o cache de system prompt, esse custo é pago uma única vez.

O cachePoint é inserido dentro do parâmetro system, separado das mensagens do usuário:

system = [
    {"text": "<system prompt detalhado>"},
    {"cachePoint": {"type": "default"}}
]

Independente do que o usuário perguntar, o prefixo do system prompt é reutilizado do cache enquanto o TTL estiver ativo.

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

Aplicações agênticas frequentemente definem dezenas de ferramentas com schemas JSON detalhados. Esses schemas raramente mudam entre requisições, mas são reprocessados a cada chamada. O cache de tool definitions evita esse reprocessamento repetido.

O cachePoint é adicionado como último elemento do array tools dentro de toolConfig:

toolConfig = {
    "tools": [
        {"toolSpec": {"name": "tool_1", ...}},
        {"toolSpec": {"name": "tool_2", ...}},
        {"cachePoint": {"type": "default"}}  # após as definições de ferramentas
    ]
}

Cenário 4: Cache com TTL misto

Nem todo conteúdo tem o mesmo ciclo de vida. Conhecimento de domínio e catálogos de produtos mudam raramente e se beneficiam de TTLs longos. Contexto de sessão e preferências do usuário mudam com frequência e exigem TTLs curtos.

Com o TTL misto, diferentes seções do conteúdo recebem tempos de expiração distintos dentro de uma única requisição:

content = [
    {"text": "<material de referência central>"},
    {"cachePoint": {"type": "default", "ttl": "1h"}},  # TTL longo primeiro
    {"text": "<contexto de sessão>"},
    {"cachePoint": {"type": "default", "ttl": "5m"}},  # TTL curto depois
    {"text": "<pergunta do usuário>"}
]

Regra importante: checkpoints com TTL mais longo devem aparecer antes dos checkpoints com TTL mais curto. A API retorna erro caso a ordem seja invertida. A resposta inclui um campo cacheDetails com o detalhamento de tokens por TTL, permitindo verificar se ambas as camadas estão funcionando corretamente.

Uma referência prática para escolha de TTL por tipo de conteúdo:

• Conhecimento de domínio, catálogos, documentação de referência: 1 hora
• Contexto de sessão, preferências do usuário: 5 minutos
• Definições de ferramentas e schemas de API: 1 hora
• Dados em tempo real e queries específicas do usuário: sem cache

Cenário 5: Isolamento por tenant

Em aplicações multi-tenant, entradas de cache dentro da mesma conta e Região AWS podem ser compartilhadas entre requisições. Para evitar que o cache de um tenant seja lido por outro, a solução recomendada é o padrão de prefixo SHA-256.

O hash do tenant_id é adicionado como prefixo ao conteúdo cacheado. Como o hash muda o prefixo do conteúdo, o Amazon Bedrock cria entradas de cache separadas para cada tenant:

import hashlib

sha256_hash = hashlib.sha256(tenant_id.encode()).hexdigest()
instructions = f"{sha256_hash}:{instructions}"

O overhead é mínimo: o hash SHA-256 adiciona apenas 64 caracteres (aproximadamente 16 tokens) ao prompt. Não há configuração server-side necessária — o isolamento é obtido puramente via prefixo de conteúdo, com entradas de cache independentes por tenant.

Cenário 6: Integração com LangChain

Para equipes que utilizam o framework LangChain, o prompt caching se integra diretamente à classe ChatBedrockConverse através do método create_cache_point(), que gera o bloco cachePoint correto sem necessidade de manipular o formato bruto da API:

from langchain_aws import ChatBedrockConverse
from langchain_core.messages import HumanMessage, SystemMessage

HumanMessage(content=[
    {"type": "text", "text": "<conteúdo do documento>"},
    ChatBedrockConverse.create_cache_point()
])

O mesmo padrão funciona em chains LCEL (LangChain Expression Language) com ChatPromptTemplate, permitindo reutilização em pipelines completos. As métricas de cache ficam disponíveis em usage_metadata da resposta, nos campos cache_creation e cache_read.

Converse API vs. InvokeModel API

Os cenários acima utilizam a Converse API, que oferece sintaxe de cachePoint agnóstica de modelo. Para quem usa a InvokeModel API com modelos Anthropic, a sintaxe é diferente: o controle de cache é feito via "cache_control": {"type": "ephemeral"} dentro do próprio bloco de conteúdo, e o campo cacheDetails não está disponível na resposta.

A recomendação da AWS para novas aplicações é usar a Converse API, pois o mesmo código de caching funciona tanto para Claude quanto para Amazon Nova sem modificações.

Boas práticas para produção

• Mapeie o que é estático vs. dinâmico: system prompts, schemas de ferramentas e documentos de referência são candidatos naturais ao cache. Perguntas do usuário e dados em tempo real, não.
• Respeite o limite mínimo de tokens: conteúdo abaixo do threshold é processado normalmente sem cache. Verifique os requisitos do modelo que está usando.
• Monitore as métricas de cache: acompanhe cacheWriteInputTokens e cacheReadInputTokens nos logs. Uma taxa de hit baixa pode indicar que o conteúdo muda com frequência demais ou que o TTL está muito curto.
• Aplique controles de IA responsável: para deploys em produção, o Amazon Bedrock Guardrails pode ser combinado com os padrões de cache para adicionar filtragem de conteúdo e validação de grounding.
• Combine locais de cache: é possível cachear system prompt, conteúdo de mensagem e definições de ferramentas simultaneamente em uma única requisição, acumulando as economias.

Próximos passos

O conjunto completo de notebooks e scripts referenciados está disponível no repositório amazon-bedrock-samples no GitHub. Para detalhes sobre configuração e modelos suportados, consulte a documentação do Amazon Bedrock Prompt Caching. Para começar, acesse o Amazon Bedrock ou abra o console do Amazon Bedrock para habilitar o acesso ao modelo.

Fonte

Optimizing cost and latency with Amazon Bedrock prompt caching (https://aws.amazon.com/blogs/machine-learning/optimizing-cost-and-latency-with-amazon-bedrock-prompt-caching/)