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.
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.
Mensagem de sistema oculta
Instruções fornecidas pela OpenAI
Ferramentas
Definições e esquemas
Mensagem do desenvolvedor
Instruções do aplicativo
Histórico de contexto
Mensagens da conversa, chamadas e resultados de ferramentas, texto e conteúdo multimodal
Alterar uma requisição não descarta necessariamente uma entrada existente no cache. O que importa é se uma requisição posterior tem o mesmo prefixo e consegue encontrar um ponto de interrupção elegível correspondente. As principais configurações a verificar são:
Pode alterar as instruções de raciocínio do modelo. Nos modelos compatíveis, use uma atualização de configuração para alterar o esforço preservando o prefixo anterior.
Substitui o conteúdo anterior da conversa por um contexto compactado que pode impedir a reutilização a partir do primeiro token alterado.
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.
No GPT-5.6 e posteriores, as gravações em cache custam 1,25× a tarifa padrão de tokens de entrada sem cache. Vale a pena pagar esse valor quando você sabe que um prefixo será reutilizado, pois as leituras seguintes custam apenas 0,1× essa tarifa. Gravar um prefixo uma vez e reutilizá-lo integralmente uma vez custa 1,35× seu custo normal de entrada, em comparação com 2× para processá-lo duas vezes sem cache. A economia aumenta a cada leitura adicional do cache: em dez requisições, uma gravação e nove leituras completas custam 2,15×, em comparação com 10× sem cache.
Há suporte tanto para cache implícito quanto explícito. O cache explícito oferece mais controle sobre qual contexto é gravado no cache.
Modo explícito: Você escolhe onde colocar os pontos de interrupção de cache com base no seu gerenciamento de contexto.
Defina prompt_cache_options.mode como explicit para usar apenas pontos de interrupção selecionados pelo desenvolvedor e marque cada ponto desejado adicionando prompt_cache_breakpoint: { "mode": "explicit" } a um bloco de conteúdo compatível dentro de uma mensagem de entrada.
Quando nenhum ponto de interrupção explícito é definido, a requisição não usa o cache de prompts nem realiza gravações em cache.
O modo exclusivamente explícito permite escolher onde as gravações em cache terminam. O conteúdo após o último ponto de interrupção selecionado é processado pela tarifa de tokens de entrada sem cache, sem cobrança de gravação em cache. Assim, você pode evitar gravar conteúdo variável com pouca probabilidade de reutilização.
Vários pontos de interrupção explícitos podem preservar prefixos que mudam com frequências diferentes. Cada requisição pode realizar até quatro gravações em cache.
Os itens de entrada additional_tools atualmente não aceitam prompt_cache_breakpoint.
O campo instructions de nível superior não pode conter um ponto de interrupção explícito. Para marcar instruções reutilizáveis do desenvolvedor, coloque-as em um bloco input_text dentro de uma mensagem do desenvolvedor.
Modo implícito: A OpenAI escolhe automaticamente posições de pontos de interrupção que funcionam bem para a maioria dos casos de uso.
Quando prompt_cache_options.mode é implicit, a OpenAI coloca um ponto de interrupção no fim da mensagem elegível mais recente. As mensagens elegíveis são:
mensagens do usuário
a última resposta de ferramenta em um grupo de respostas consecutivas de ferramentas
a última mensagem do desenvolvedor no grupo inicial de mensagens consecutivas do desenvolvedor.
Você pode adicionar pontos de interrupção explícitos sem desativar o ponto de interrupção implícito; ele ocupa uma das quatro posições de gravação no cache, deixando três disponíveis para gravações explícitas.
Somente o cache implícito é compatível. A OpenAI posiciona pontos de interrupção implícitos em intervalos que variam conforme o modelo, contados a partir do início da mensagem de sistema oculta da OpenAI. Somente os pontos de interrupção que atingem ou ultrapassam o comprimento mínimo para armazenamento em cache (contado a partir do fim do contexto oculto) são elegíveis.
O valor informado de cached_tokens é calculado subtraindo os tokens de sistema ocultos da posição do último ponto de interrupção correspondente e, em seguida, arredondando o resultado para baixo até o múltiplo de 128 mais próximo.
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)
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.
Use prompt_cache_options.ttl para controlar o tempo de vida mínimo do cache. O único valor aceito, 30m, também é o padrão. Um prefixo em cache permanece elegível para reutilização por 30 minutos após a gravação ou reutilização mais recente, embora a OpenAI possa retê-lo por mais tempo.
Use prompt_cache_retention, cujos valores aceitos dependem do modelo:
in_memory: as entradas normalmente permanecem ativas por cerca de 5 a 10 minutos de inatividade, podendo chegar a uma hora.
24h: a retenção estendida normalmente mantém as entradas disponíveis por cerca de 30 minutos e pode retê-las por até 24 horas.
Padrões de retenção e zero retenção de dados
O cache de prompts pode armazenar tensores de chave/valor criptografados no armazenamento local da GPU como estado da aplicação. Para modelos que oferecem suporte tanto a in_memory quanto a 24h, o padrão depende da política de retenção de dados da sua organização:
Organizações sem zero retenção de dados ativada usam 24h por padrão.
Organizações com zero retenção de dados ativada usam in_memory por padrão.
Verifique as políticas de retenção disponíveis para seu modelo e sua organização antes de selecionar um valor.
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.
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.
Em modelos anteriores ao GPT-5.6, use uma prompt_cache_key estável para requisições que compartilham um prefixo reutilizável, ajudando a encaminhar requisições relacionadas ao mesmo cache. Para grupos com muito tráfego, procure manter cerca de 15 requisições por minuto no total, somando todos os prefixos que usam cada chave. Distribua o tráfego de maior volume entre várias chaves usando um mapeamento estável e determinístico. Mantenha as requisições relacionadas na mesma prompt_cache_key para que possam reutilizar o cache associado a ela. As chaves influenciam o roteamento; elas não vinculam as requisições a uma máquina nem garantem um acerto de cache.
No GPT-5.6 e em modelos posteriores, a OpenAI gerencia o roteamento do cache automaticamente; a chave não é necessária para otimizar o cache. Você pode usar chaves distintas para manter a contabilização do cache separada por cliente ou usuário dentro do seu aplicativo.
Usar chaves separadas pode facilitar a explicação do uso e da cobrança de tokens em cache para cada cliente ou usuário. Por exemplo, chaves separadas ajudam a evitar a sondagem por acertos de cache entre usuários: o envio de prompts candidatos e a observação de acertos de cache para descobrir se o conteúdo correspondente já estava armazenado em cache. Consulte Separe a contabilização do cache com chaves.
Resumo das diferenças entre modelos
Comportamento
GPT-5.6 e posteriores
GPT-5.5 e GPT-5.5 Pro
Outros modelos anteriores
Pontos de interrupção implícitos
No 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ícitos
Com suporte
Sem suporte
Sem suporte
prompt_cache_key
Opcional para contabilização separada do cache
Use uma chave estável para otimizar o roteamento do cache
Use uma chave estável para otimizar o roteamento do cache
Comprimento mínimo do prefixo para uso do cache
1.024 tokens de entrada visíveis
Varia conforme as configurações da solicitação
Varia conforme as configurações da solicitação
Contagem informada de tokens em cache
Limite elegível exato, excluindo os tokens ocultos
Exclui os tokens ocultos e arredonda para baixo até um múltiplo de 128
Exclui os tokens ocultos e arredonda para baixo até um múltiplo de 128
Pelo menos 30 minutos após a gravação ou reutilização mais recente
Normalmente cerca de 30 minutos, podendo chegar a 24 horas
Normalmente 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.
Em aplicativos com vários turnos, reutilizar o histórico da conversa à medida que ele cresce pode economizar mais tokens de entrada do que armazenar em cache apenas as instruções iniciais. Preserve as mensagens anteriores e os resultados de ferramentas para que os turnos seguintes possam reutilizar todo o prefixo compartilhado.
Mantenha o prefixo estável. Coloque primeiro as instruções estáveis do desenvolvedor e o material de referência compartilhado. Se essas instruções ou esse material contiverem registros de data e hora, conteúdo específico do usuário ou outro conteúdo dinâmico, coloque esses elementos no final, em vez de no início, ou mova-os para mensagens posteriores da conversa.
Preserve o histórico da conversa. Acrescente novas mensagens em vez de reescrever turnos anteriores. Resumos, compactação ou truncamento de contexto podem alterar o prefixo e fazer a reutilização do cache recomeçar do zero.
Altere o esforço de raciocínio sem reescrever o prefixo. No GPT-6 Astra, acrescente um item de entrada configuration_update para alterar o esforço de raciocínio entre respostas, mantendo reasoning.effort inalterado no nível da requisição. Isso preserva o prefixo original para reutilização do cache. Consulte Alterar o raciocínio durante a conversa para ver exemplos e limites de compatibilidade.
Mantenha o conteúdo variável após o ponto de interrupção
Nos modelos GPT-6 e posteriores compatíveis, acrescente um item de entrada configuration_update para alterar o esforço de raciocínio durante uma conversa, preservando o prefixo já armazenado em cache. Mantenha reasoning.effort no nível superior com seu valor original, pois alterar essa configuração pode reescrever instruções contidas nas instruções ocultas do sistema.
A atualização de configuração mais recente controla o esforço de raciocínio das respostas seguintes. Por exemplo, acrescente este item ao array input existente para mudar o esforço de raciocínio para high nas requisições seguintes:
Quando as ferramentas necessárias ao seu aplicativo variarem entre requisições, altere quais ferramentas podem ser chamadas, mantendo suas definições estáveis para preservar os prefixos reutilizáveis.
Mantenha as ferramentas consistentes. Preserve as definições, a ordem e os esquemas das ferramentas.
Desative o uso de ferramentas em uma requisição. Defina tool_choice como "none" em vez de remover as definições das ferramentas.
Habilite apenas as ferramentas selecionadas. Use allowed_tools para restringir quais ferramentas podem ser chamadas, mantendo estável a lista tools fornecida.
Carregue ferramentas quando necessário. Use a pesquisa de ferramentas com defer_loading: true para reduzir os tokens de entrada gastos com definições de ferramentas nas primeiras requisições de conversas com vários turnos. As ferramentas encontradas são acrescentadas ao final do contexto, preservando o conteúdo reutilizável anterior.
Preserve o histórico de carregamento de ferramentas. Use um item de entrada additional_tools com o papel de desenvolvedor para adicionar ferramentas durante uma conversa de acordo com a lógica do seu aplicativo.
No GPT-5.6 e posteriores, dois controles determinam onde os pontos de interrupção do cache são posicionados: prompt_cache_options.mode seleciona o cache implícito ou exclusivamente explícito, e prompt_cache_breakpoint marca um limite escolhido por você.
Posicione pontos de interrupção automaticamente. Use o cache implícito para posicionar um ponto de interrupção no final da mensagem elegível mais recente. Isso é conveniente para conversas com vários turnos que acrescentam conteúdo ao contexto existente.
Escolha os pontos de interrupção de forma criteriosa. Posicione marcadores explícitos no final do conteúdo estável. Use o modo exclusivamente explícito para evitar gravações desnecessárias no cache de sufixos que mudam.
Prefixo compartilhado em cache para o ponto de interrupção 2
Mensagem oculta do sistema
Ferramentas
Mensagem do desenvolvedor · prefixo estável
Mensagem do desenvolvedor · sufixo variável A
Mensagem do usuário
Chamada de ferramenta
Resultado da ferramenta
Mensagem do assistente
Mensagem do desenvolvedor · sufixo variável B
Nova entrada do usuário A
Nova entrada do usuário B
Ponto de interrupção 1
Ponto de interrupção 2
Prefixo compartilhado em cache para o ponto de interrupção 1
Sufixo não reutilizado: sem cobrança de gravação no cache
Novas entradas do usuário: sem cobrança de gravação no cache
No GPT-5.6 e em modelos posteriores, use prompt_cache_key quando quiser manter a contabilização do cache separada por cliente, usuário ou workspace dentro do seu aplicativo. Isso pode facilitar a explicação do uso e da cobrança de tokens em cache em cada grupo. A chave é opcional e não é necessária para otimizar o cache nesses modelos.
Escolha como separar a contabilização do cache. Atribua uma chave distinta a cada cliente ou usuário cuja contabilização do cache deva permanecer separada. Por exemplo, support:customer_123 e support:customer_456 mantêm a contabilização do cache separada para dois clientes, mesmo quando suas requisições contêm o mesmo prefixo.
Mantenha as chaves estáveis dentro de cada grupo. Reutilize a mesma chave nas requisições relacionadas de um cliente. Gere uma chave separada para uma sessão ou thread somente quando ela precisar de sua própria contabilização do cache.
Aplique as chaves de forma consistente. Use a chave do cliente em todas as requisições dele para manter a contabilização do cache separada. Isso também ajuda a evitar a sondagem por acertos de cache entre clientes.
Em modelos anteriores ao GPT-5.6, prompt_cache_key é importante para otimizar as taxas de acerto de cache. Use uma chave estável para requisições que compartilham um prefixo reutilizável, ajudando a encaminhá-las ao mesmo cache. Para grupos com muito tráfego, siga as orientações para distribuir o tráfego entre mais chaves.
Para modelos anteriores, prefira definir prompt_cache_retention como "24h" para obter retenção estendida quando o modelo e seus requisitos de retenção de dados permitirem. Consulte Tempo de vida do cache para ver as configurações compatíveis e os valores padrão.
Se muitas requisições reutilizarem as mesmas instruções do desenvolvedor e definições de ferramentas, mas esse prefixo compartilhado ficar abaixo do comprimento mínimo para cache do modelo, considere encurtá-lo ou ampliá-lo com instruções, exemplos ou material de referência úteis e estáveis. Meça se a reutilização do cache compensa os tokens de entrada adicionais e eventuais cobranças de gravação no cache, e garanta que as avaliações e o comportamento permaneçam estáveis.
O gráfico destaca a armadilha de custo do comprimento mínimo para cache: prefixos curtos sem cache podem custar mais do que ampliá-los até o número mínimo de tokens necessário para usar o cache.
Comprimento do prompt e custo de entrada
0
500
1,000
1,500
2,000
Comprimento do prefixo reutilizável (tokens)
Para comparar apenas os custos, considere M como o comprimento mínimo armazenável em cache, L<M como o comprimento original do prefixo, r como o multiplicador de leitura do cache, w como o multiplicador de gravação no cache e N como o número total de requisições. Suponha que o prefixo expandido tenha exatamente M tokens, seja gravado uma vez e seja reutilizado integralmente em todas as requisições seguintes. Em equivalentes de tokens de entrada sem cache, manter o prefixo original custa N×L, enquanto expandi-lo custa M[w+(N−1)r]. O comprimento original no ponto de equilíbrio é:
Lbreak-even=M(r+Nw−r)
Expanda quando L>Lbreak-even; manter o prefixo mais curto custa menos quando L<Lbreak-even. Na igualdade, os custos são os mesmos. O menor comprimento em tokens inteiros para o qual a expansão é mais barata é ⌊Lbreak-even⌋+1. Por outro lado, reduzir um prefixo armazenável em cache para menos de M impede o uso do cache: sob as mesmas premissas, o prefixo mais curto sem cache precisa ficar abaixo de Lbreak-even para custar menos do que armazenar em cache M tokens. Não existe um comprimento de prompt de custo máximo universal; o ponto de equilíbrio depende da reutilização e dos preços.
Por exemplo, com M=1,024, r=0.1 e w=1.25, o ponto de equilíbrio é 102.4+N1,177.6 tokens. Considerando 10 requisições, expandir um prefixo original de pelo menos 221 tokens para 1.024 tokens é mais barato. À medida que a reutilização aumenta, o ponto de equilíbrio se aproxima de 102,4 tokens. Um prefixo de 103 tokens precisa de pelo menos 1.963 requisições no total para se beneficiar; um prefixo de 102 tokens ou menos nunca se beneficia sob essas premissas. Essa comparação exclui desempenho, tokens de saída e custos de requisição que permanecem inalterados. Falhas adicionais de cache, gravações adicionais ou tarifas diferentes do modelo alteram o resultado.
Meça o desempenho real do cache. Acompanhe usage.input_tokens_details.cached_tokens, usage.input_tokens_details.cache_write_tokens, as contagens de tokens de entrada, a latência e o custo efetivo. Acompanhe a taxa de acertos de cache por token dividindo o total de tokens em cache pelo total de tokens de entrada e agregando ambas as contagens por usuário, workspace, dia ou outro agrupamento útil.
Calcule o custo de entrada. Use as contagens de tokens em response.usage e os preços por milhão de tokens do modelo.
Os exemplos a seguir se aplicam ao GPT-5.6 e a modelos posteriores.
Considere um LLM avaliador de turno único que verifica se uma interação concluída com um chatbot apresenta indícios de satisfação do usuário. Cada requisição usa a mesma rubrica de avaliação e os mesmos exemplos few-shot rotulados para avaliar uma interação diferente.
Preservação do prefixo: A rubrica fixa e os exemplos vêm primeiro. O comprimento combinado desses elementos é mantido deliberadamente um pouco acima do comprimento mínimo armazenável em cache do modelo, usando material que ajuda a calibrar o avaliador. A interação avaliada vem por último.
Modo de cache e ponto de interrupção: O modo de cache somente explícito está ativado, com um ponto de interrupção após a rubrica fixa e os exemplos. A conversa entre usuário e chatbot que está sendo avaliada vem depois desse ponto e não é gravada no cache, evitando uma cobrança de gravação no cache para conteúdo que provavelmente não será reutilizado.
Uma implantação de exemplo que usou esses princípios registrou uma taxa de acertos de cache por token de ~70%. Esse número ilustra um resultado possível. As taxas máximas de acertos de cache que podem ser alcançadas na prática dependem do seu contexto e do uso da aplicação.
Requisição à API Responses para um avaliador de turno único
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{"model": "gpt-5.6-sol","reasoning": { "effort": "medium", "context": "all_turns" },"text": { "verbosity": "low" },"prompt_cache_options": { "mode": "explicit" },"input": [ {"role": "developer","content": [ {"type": "input_text","text": "Judge whether the completed interaction provides evidence that the user is satisfied. Return true or false. Full grading rubric and labeled few-shot examples...","prompt_cache_breakpoint": { "mode": "explicit" } } ] }, {"role": "user","content": "Completed interaction to evaluate..." } ]}
Considere um agente com múltiplos turnos, instruções de desenvolvedor longas e compartilhadas e chamadas frequentes de ferramentas. No uso típico, os usuários executam várias sessões com o agente ao mesmo tempo e frequentemente criam forks das conversas.
Preservação do prefixo: Cada turno acrescenta novas mensagens, chamadas de ferramentas e resultados sem reescrever o contexto anterior, de modo que o prefixo reutilizável cresce ao longo do tempo.
Chave de cache de prompts opcional: Este exemplo usa agent_123_v1:user_456 para manter a contabilização do cache separada para o usuário 456, facilitando a explicação do uso e da cobrança de tokens em cache desse usuário. Isso também ajuda a evitar a sondagem por acertos de cache entre usuários. A chave permanece a mesma em todas as sessões e forks desse usuário com o agente. Omita-a se sua aplicação não precisar dessa separação.
Modo de cache implícito: O cache implícito está ativado para que a mensagem elegível mais recente do usuário ou de uma ferramenta forneça um ponto de interrupção.
Pontos de interrupção explícitos: Um ponto de interrupção é adicionado após cada resultado de ferramenta para preservar prefixos reutilizáveis anteriores e melhorar a eficiência do cache ao criar forks.
Uma implantação de exemplo que usa esses princípios registrou uma taxa de acertos de tokens no cache >90%. Esse número ilustra um resultado possível. Os limites máximos reais da taxa de acertos no cache dependerão do seu contexto e do uso da aplicação.
Requisição à API Responses para um agente com múltiplos turnos
Isso é particularmente comum ao migrar de modelos anteriores para o GPT-5.6 ou posterior, devido à mudança no comportamento do cache implícito. Se as requisições compartilham um prefixo longo, mas têm sufixos diferentes, armazenar a primeira requisição completa em cache usando apenas o modo implícito não torna reutilizável o prefixo compartilhado mais curto.
Considere uma mensagem estática do desenvolvedor seguida de uma mensagem dinâmica do usuário em cada requisição. Essa requisição grava o prefixo em cache até o fim do conteúdo dinâmico. Se esse conteúdo mudar na próxima requisição, não haverá correspondência com o prefixo mais longo armazenado em cache, e não há um ponto de interrupção separado após o conteúdo estático.
Sem um ponto de interrupção após o conteúdo estático
Para corrigir isso, insira um ponto de interrupção explícito após o conteúdo estático em ambas as requisições. A primeira requisição grava o prefixo reutilizável; a próxima pode reutilizá-lo mesmo quando o conteúdo dinâmico muda. Este exemplo usa o modo somente explícito para evitar a gravação do conteúdo dinâmico em cache.
Com um ponto de interrupção após o conteúdo estático
Suponha que a requisição 1 use o modo implícito e armazene em cache um prefixo até o fim de uma mensagem do usuário. Em seguida, a requisição 2 preserva esse prefixo, mas muda para prompt_cache_options.mode: "explicit". Como explicado em Como funciona a correspondência de prefixos, a requisição 2 verifica apenas os pontos de interrupção explícitos em sua própria entrada, portanto não reutilizará o prefixo implícito salvo pela requisição 1 (a menos que um dos pontos de interrupção explícitos da requisição 2 corresponda ao ponto final armazenado em cache pela requisição 1).
▼ = breakpoint- Request 1: implicit mode [Developer message][User message] ▼- Request 2: explicit-only mode. Does not hit cache. [Developer message][User message][Follow-up] ▼
Para reutilizar o prefixo implícito da requisição 1, insira um ponto de interrupção explícito no limite correspondente do bloco de conteúdo na requisição 2, ou mantenha o modo implícito ativado para que o fim da mensagem elegível anterior continue sendo um candidato à consulta.
Mesmo quando ambas as requisições usam o modo implícito, preservar os mesmos tokens iniciais nem sempre é suficiente. Suponha que a requisição 1 termine com uma mensagem do usuário contendo Content A e que, em seguida, a requisição 2 estenda essa mesma mensagem para Content A + Content B. O antigo ponto final após Content A agora está dentro de uma mensagem, e não no fim dela. Como explicado em Como funciona a correspondência de prefixos, sem um ponto de interrupção explícito nesse limite, a requisição 2 não reutiliza o prefixo salvo ali.
▼ = breakpoint- Request 1: implicit mode [Developer message][User message: Content A] ▼- Request 2: implicit mode. Cannot reuse the prefix through Content A. [Developer message][User message: Content A + Content B] ▼
Quando a estrutura da conversa permitir, preserve a mensagem original e acrescente uma nova mensagem. Caso contrário, mantenha o texto reutilizável em um bloco de conteúdo separado e insira um ponto de interrupção explícito após ele em ambas as requisições.
No modo implícito, as mensagens do desenvolvedor após o bloco inicial de mensagens consecutivas do desenvolvedor não são limites automáticos de consulta ao cache. Adicione um ponto de interrupção explícito ao fim da mensagem reutilizável do desenvolvedor para preservar esse ponto nas requisições subsequentes, permitindo que a OpenAI verifique se há um prefixo correspondente em cache.
Um prefixo que atende aos requisitos para armazenamento em cache em um modelo pode ser curto demais em outro. Consulte a comparação entre modelos e meça o prefixo reutilizável com o modelo e as configurações que você realmente usa. Ao trocar de modelo, repita essa verificação em vez de presumir que o limite do modelo anterior ainda se aplica.
A compactação substitui o contexto anterior da conversa por uma representação mais curta. Isso pode alterar o prefixo, de modo que a primeira requisição após a compactação pode reutilizar uma parte menor do cache anterior, mesmo que a conversa seja logicamente a mesma.
Mantenha as instruções reutilizáveis e o material de referência estáveis sempre que possível e, então, deixe que os turnos subsequentes avancem a partir do contexto compactado. Compare o custo total de entrada antes e depois da compactação: usar menos tokens de entrada ainda pode gerar economia, mesmo quando a taxa de acertos no cache diminui.
Perguntas frequentes
Não. O cache de prompts não altera a forma como o modelo gera tokens de saída. O modelo gera uma nova resposta usando o prefixo em cache, portanto não há garantia de que requisições idênticas produzam saídas idênticas.
Não. A limpeza manual do cache não está disponível no momento. As entradas do cache expiram de acordo com o tempo de vida do cache e as configurações de retenção do modelo.
Sim. Os tokens de entrada em cache continuam contando para os limites de tokens por minuto. O cache de prompts não altera a forma como os limites de taxa são calculados.