For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal

Cache de prompts

Reduza a latência e o custo com o cache de prompts.

Por que o cache de prompts é importante

O cache de prompts reaproveita o processamento quando as requisições compartilham o mesmo prefixo de prompt. Isso oferece três benefícios principais:

  • Eficiência computacional: Evite recalcular um prefixo de prompt que o modelo já processou.
  • Tokens de entrada mais baratos: Pague a tarifa reduzida de entrada em cache do modelo pelos tokens reutilizados, com desconto de até 90%.
  • Mais rapidez: Reduza o tempo de processamento da entrada antes do início da resposta.

O cache de prompts é ativado por padrão nos modelos da OpenAI compatíveis. Use o Painel de cache de prompts para monitorar as taxas de acerto de leitura do cache e a ferramenta de diagnóstico do cache de prompts para diagnosticar falhas de acerto e melhorar a reutilização do cache.

As chamadas a modelos pela API de Agentes usam o mesmo comportamento de cache de prompts da API Responses. Reutilizar o contexto dentro de uma sessão pode preservar um prefixo de prompt compartilhado, mas manter uma sessão não garante um acerto de cache. Consulte Observabilidade e uso para conhecer os campos de uso da sessão e a contabilização do uso de subagentes.

Os preços do cache de prompts variam conforme o modelo. Consulte os preços da API para ver as tarifas atuais de entrada em cache e gravação em cache. A tarifa de gravação em cache não é uma cobrança adicional: os tokens de entrada são cobrados pela tarifa de entrada sem cache, de entrada em cache ou de gravação em cache.

O que é o cache de prompts?

Ao processar tokens de entrada, o modelo precisa calcular estados intermediários, conhecidos como estados de chave-valor (KV). Esses estados permitem que o modelo consulte tokens anteriores enquanto processa novas entradas e gera tokens de saída.

O cache de prompts preserva esse estado para um prefixo reutilizável: os tokens que permanecem inalterados no início de um prompt. Quando uma requisição posterior tem o mesmo prefixo e encontra uma entrada correspondente no cache, o modelo pode reutilizar o estado salvo em vez de processar esses tokens novamente. Ele ainda precisa processar qualquer nova entrada para gerar uma nova resposta.

O cache de prompts armazena tensores de chave-valor (KV), não os tokens em si.

Peça ao ChatGPT uma explicação mais aprofundada

A OpenAI armazena em cache todo o contexto renderizado do modelo, incluindo instruções fornecidas pela OpenAI, mensagens do desenvolvedor, definições de ferramentas e o histórico da conversa contendo texto, imagens, documentos e áudio compatível.

A reutilização do cache exige que todo o prefixo renderizado seja idêntico. Se o conteúdo ou uma configuração relevante mudar antes de um ponto de interrupção, o prefixo após essa alteração não poderá corresponder à entrada existente no cache.

Como o cache funciona

Um ponto de interrupção de cache marca o fim de um prefixo de prompt que a OpenAI pode salvar no cache e reutilizar em requisições posteriores. A primeira requisição grava um prefixo elegível no cache, e as requisições seguintes procuram o maior prefixo correspondente disponível no cache, percorrendo os pontos de interrupção elegíveis de trás para frente até encontrar uma correspondência.

Um prefixo de prompt precisa atingir o comprimento mínimo em tokens para armazenamento em cache do modelo antes de poder ser armazenado. Os tokens do conteúdo de sistema oculto fornecido pela OpenAI não contam para esse mínimo. O comprimento mínimo de prompt para armazenamento em cache é de 1.024 tokens no GPT-5.6 e posteriores e varia conforme as configurações da requisição nos modelos anteriores. Consulte a comparação de modelos para saber mais.

Após atingir o comprimento mínimo em tokens para armazenamento em cache, você pode escolher explicitamente onde colocar os pontos de interrupção de cache ou deixar que a OpenAI escolha suas posições implicitamente. As opções disponíveis dependem do modelo.

Como funciona a correspondência de prefixos

A OpenAI percorre apenas os limites de consulta ao cache (explicados abaixo) na solicitação recebida, do prefixo mais longo ao mais curto, procurando um prefixo correspondente disponível que já esteja no cache da máquina.

No GPT-5.6 e em modelos posteriores, os limites de consulta ao cache na solicitação recebida são:

  • Modo somente explícito: Os 2 primeiros e os 50 últimos pontos de interrupção explícitos.
  • Modo implícito: Os 2 primeiros e os 50 últimos pontos de interrupção explícitos, o ponto de interrupção implícito, os finais de até 20 mensagens elegíveis anteriores e o final do bloco inicial de mensagens consecutivas do desenvolvedor. Isso permite que o modo implícito reutilize um prefixo que termina em uma mensagem anterior sem pontos de interrupção explícitos nesse local.
Geração do modelo
Modo de cache

Os pontos de interrupção implícitos são posicionados na mensagem elegível mais recente do usuário.

Sistema ocultoFerramentasDesenvolvedorHistórico de contextoContinuaçãoEntrada em cacheEntrada sem cache
Comprimento mínimo para armazenamento em cache (varia conforme o modelo)

Solicitação 1

12,000 tokens de entrada
3,000 tokens(ilustrativo)

Solicitação 2

15,000 tokens de entrada
3,000 tokens(ilustrativo)
0
2.5k
5k
7.5k
10k
12.5k
15k
17.5k
20k
Tokens de entrada (incluindo tokens ocultos ilustrativos)
15,000
Último ponto de interrupção correspondente
3,000
Tokens ocultos
=
12,000
Tokens em cache informados

Tempo de vida do cache

As entradas de cache não são armazenadas indefinidamente. Uma solicitação posterior só pode reutilizar um prefixo em cache enquanto a entrada estiver disponível, e a reutilização do prefixo renova seu tempo de vida sem uma nova cobrança de gravação no cache. As configurações de tempo de vida e retenção dependem do modelo.

Localização do cache

Os estados em cache ficam em máquinas individuais, nas quais um tráfego acima de 15 solicitações por minuto pode levar ao roteamento do excedente para outras máquinas. Uma solicitação só pode reutilizar um prefixo em cache se chegar a uma máquina que contenha uma entrada correspondente ainda não expirada. Por isso, rotear as solicitações para a máquina certa é importante para a reutilização do cache.

Os caches não são compartilhados entre organizações e não podem ser reutilizados além dos limites regionais de processamento.

A OpenAI faz o roteamento automaticamente. Dentro de uma organização e de uma região de processamento, o roteamento para um determinado modelo depende de:

  • Carga atual da máquina e capacidade disponível.
  • Um hash dos tokens iniciais após o conteúdo oculto da OpenAI, incluindo definições de ferramentas quando presentes. O número de tokens usados no cálculo do hash varia conforme o modelo.
  • Uma chave prompt_cache_key fornecida, que separa a reutilização do cache entre grupos de requisições e ajuda a otimizar o roteamento do cache em modelos anteriores ao GPT-5.6.

Resumo das diferenças entre modelos

ComportamentoGPT-5.6 e posterioresGPT-5.5 e GPT-5.5 ProOutros modelos anteriores
Pontos de interrupção implícitosNo final da mensagem elegível mais recente.Distribuídos em intervalos regulares de 2.048 tokens.Distribuídos em intervalos regulares que dependem do modelo.
Pontos de interrupção explícitosCom suporteSem suporteSem suporte
prompt_cache_keyOpcional para contabilização separada do cacheUse uma chave estável para otimizar o roteamento do cacheUse uma chave estável para otimizar o roteamento do cache
Comprimento mínimo do prefixo para uso do cache1.024 tokens de entrada visíveisVaria conforme as configurações da solicitaçãoVaria conforme as configurações da solicitação
Contagem informada de tokens em cacheLimite elegível exato, excluindo os tokens ocultosExclui os tokens ocultos e arredonda para baixo até um múltiplo de 128Exclui os tokens ocultos e arredonda para baixo até um múltiplo de 128
Cobrança de leitura do cache0,1× a tarifa de tokens de entrada sem cacheTarifa de entrada em cache que depende do modeloTarifa de entrada em cache que depende do modelo
Cobrança de gravação no cache1,25× a tarifa de tokens de entrada sem cacheSem cobrança adicional de gravação no cacheSem cobrança adicional de gravação no cache
Controle do tempo de vida do cacheprompt_cache_options.ttlprompt_cache_retentionprompt_cache_retention
Valores de retenção aceitos"30m"Somente "24h""in_memory" ou "24h"*
Tempo de vida do cachePelo menos 30 minutos após a gravação ou reutilização mais recenteNormalmente cerca de 30 minutos, podendo chegar a 24 horasNormalmente de 5 a 10 minutos de inatividade para in_memory, ou até 24 horas para 24h

* A retenção estendida é compatível com gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5.2, gpt-5.1-codex-max, gpt-5.1, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5.1-chat-latest, gpt-5, gpt-5-codex e gpt-4.1.

Para modelos anteriores ao GPT-5.6, o comprimento mínimo da entrada para uso do cache varia conforme as configurações da solicitação, incluindo ferramentas, imagens, esquemas de saída, esforço de raciocínio e nível de detalhamento.

Pedir ao ChatGPT para identificar o comprimento mínimo para uso do cache na minha requisição

Como otimizar o cache de prompts

Concentre-se em preservar o histórico da conversa, manter as definições de ferramentas estáveis e escolher onde o cache é aplicado. No GPT-5.6 e em modelos posteriores, use prompt_cache_options.mode e prompt_cache_breakpoint para controlar os pontos de interrupção do cache. Você também pode usar uma prompt_cache_key opcional se o seu aplicativo precisar manter a contabilização do cache separada por cliente. Em modelos anteriores ao GPT-5.6, use uma prompt_cache_key estável para otimizar o roteamento do cache para requisições que compartilham um prefixo reutilizável.

Pedir ao ChatGPT para otimizar meu cache de prompts

Exemplos

Os exemplos a seguir se aplicam ao GPT-5.6 e a modelos posteriores.

Pontos de atenção

Perguntas frequentes