Para configurar o cache explícito de prompts no Amazon Bedrock, inclua prompt_cache_options no modo explicit e marque o fim do trecho reutilizável com prompt_cache_breakpoint. O procedimento é voltado a quem desenvolve uma integração com Bedrock: depois de escolher um modelo e uma API compatíveis, confira nos dados de uso se houve gravação ou leitura do cache.

O cache de prompts reaproveita o processamento de um prefixo que se repete entre pedidos. Instruções, ferramentas e material de referência podem compor esse trecho; a pergunta variável fica depois do ponto de controle. Assim, o modelo não precisa reprocessar da mesma forma o prefixo em cada chamada.

Antes de configurar, confira o modelo e a API

Os requisitos variam conforme o modelo. A AWS lista os seguintes limites para Kimi K3 e GLM 5.3:

ModeloCheckpoint mínimoRetenção mínimaAPIs com cache explícito
Kimi K3256 tokens30 minutosResponses, Chat Completions e InvokeModel; não Converse
GLM 5.31.024 tokens30 minutosResponses e Chat Completions

O GLM 5.3 também exige um perfil geográfico dos EUA ou um perfil global de inferência entre regiões; a inferência sob demanda dentro de uma única região não está disponível para esse modelo. O acesso é limitado a clientes elegíveis. Já o cartão do Kimi K3 recomenda Chat Completions para novos usos. Confira o cartão do modelo que pretende usar antes de escolher a API e o perfil de inferência.

Configure o prefixo e os dois campos

  1. Escolha um modelo e uma API compatíveis. Compare a API da sua integração com os requisitos do modelo e dimensione o trecho reutilizável para atingir o checkpoint mínimo. Para cache explícito no Kimi K3, o mínimo é 256 tokens; no GLM 5.3, 1.024 tokens.
  2. Coloque o conteúdo estável antes da parte variável. Posicione as instruções de sistema, as definições de ferramentas e o material de referência antes da pergunta que muda a cada chamada. Marque o checkpoint ao final do prefixo que pretende reutilizar: o conteúdo até e incluindo esse ponto fica elegível para o cache; o que vier depois do último checkpoint é processado em cada pedido. A documentação da AWS sobre cache de prompts explica que a correspondência do prefixo é importante para a reutilização.
  3. Ative o modo explícito e marque o checkpoint. No exemplo da AWS para Chat Completions, defina prompt_cache_options como {"mode":"explicit"} e acrescente prompt_cache_breakpoint a uma parte de texto do conteúdo. No exemplo com o SDK da OpenAI, as opções específicas do Bedrock são passadas por extra_body. Os dois campos cumprem funções diferentes: sem o modo explícito, o checkpoint segue o comportamento de cache implícito; sem o checkpoint, o modo explícito não cria um trecho em cache. O exemplo da AWS mostra essa configuração.
Para saber se o cache está sendo usado, acompanhe as leituras e gravações registradas no uso da resposta; a configuração, sozinha, não confirma uma leitura.

Faça uma chamada fria e observe as seguintes

A amostra da AWS sugere começar com um identificador de execução exclusivo no início do prompt de sistema. Esse prefixo serve para a primeira chamada; mantenha-o igual nas chamadas seguintes para verificar se o cache pode ser reutilizado.

A amostra usa Python 3.12, OpenAI Python SDK 3.26.0 ou posterior e aws-bedrock-token-generator 1.1.0 ou posterior. Também é necessário ter uma conta AWS, acesso ao modelo e permissão para invocá-lo. A chave de API do Bedrock gerada pelo exemplo é temporária e pode ser válida por até 12 horas.

Confira os dados de uso e as métricas

Na resposta, examine cached_tokens e cache_write_tokens nos dados de uso. Uma gravação indica que o prefixo foi escrito no cache; uma leitura mostra que a chamada reutilizou tokens em cache. Para acompanhar o comportamento ao longo de várias chamadas, a AWS recomenda as métricas de execução CacheReadInputTokenCount e CacheWriteInputTokenCount.

O suporte ao recurso não garante que toda chamada encontre uma entrada reutilizável. Se o prefixo ficar abaixo do mínimo do modelo, a inferência ainda pode ser concluída sem que ele seja armazenado em cache. Uma chamada atendida por outro servidor pode gerar uma nova gravação; uma leitura bem-sucedida reinicia o tempo de retenção. O cache de prompts funciona em endpoints de inferência sob demanda, não na API de inferência em lote. Em roteamento entre regiões, a AWS também alerta que picos de demanda podem provocar gravações adicionais. Esses comportamentos constam da documentação do Amazon Bedrock.

A AWS afirma que prompts e respostas de modelos de pesos abertos no Bedrock não são compartilhados com os provedores dos modelos nem usados para treinar modelos, conforme o guia de cache explícito da AWS.