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:
| Modelo | Checkpoint mínimo | Retenção mínima | APIs com cache explícito |
| Kimi K3 | 256 tokens | 30 minutos | Responses, Chat Completions e InvokeModel; não Converse |
| GLM 5.3 | 1.024 tokens | 30 minutos | Responses 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
- 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.
- 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.
- Ative o modo explícito e marque o checkpoint. No exemplo da AWS para Chat Completions, defina
prompt_cache_optionscomo{"mode":"explicit"}e acrescenteprompt_cache_breakpointa uma parte de texto do conteúdo. No exemplo com o SDK da OpenAI, as opções específicas do Bedrock são passadas porextra_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.