Cache de prompts

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 corte elegível que corresponda a ele. Confira as principais configurações:

No GPT-5.6 e em modelos posteriores, a gravação no cache com a duração padrão de 30 minutos custa 1,25× a tarifa de tokens de entrada sem cache. Na API de Respostas, você pode escolher uma duração mínima de 12 horas, com tarifa de gravação de 2,5× a tarifa de entrada sem cache. Independentemente da duração escolhida, as leituras posteriores custam 0,1× a tarifa de entrada sem cache na maioria desses modelos e 0,05× no GPT-6.1 Sol e no GPT-6.1 Terra.

Com o multiplicador de 0,1× para leitura e gravações de 30 minutos, gravar um prefixo uma vez e reutilizá-lo por inteiro uma vez custa 1,35× o custo de entrada sem cache, contra 2× para processá-lo duas vezes sem cache. Em dez requisições, uma gravação e nove leituras completas custam 2,15× com essa tarifa, contra 10× sem cache.

Há suporte ao cache implícito e ao explícito. O modo explícito oferece mais controle sobre quais partes do contexto são gravadas no cache.

Modo explícito: Você escolhe onde colocar os pontos de corte do cache de acordo com a forma como gerencia o contexto.

• Defina prompt_cache_options.mode como explicit para usar apenas os pontos de corte escolhidos pelo desenvolvedor. Marque cada ponto desejado adicionando prompt_cache_breakpoint: { "mode": "explicit" } a um bloco de conteúdo compatível dentro de uma mensagem de entrada.
• Se você não marcar nenhum ponto de corte explícito, a requisição não usará o cache de prompts nem fará gravações no cache.
• O modo exclusivamente explícito permite escolher onde terminam as gravações no cache. O conteúdo após o último ponto selecionado é processado pela tarifa de tokens de entrada sem cache, sem cobrança de gravação. Assim, você evita gravar conteúdo variável com pouca chance de reutilização.
• Vários pontos de corte explícitos podem preservar prefixos que mudam com frequências diferentes. Cada requisição pode fazer até quatro gravações no cache.
• Atualmente, os itens de entrada additional_tools não aceitam prompt_cache_breakpoint.

Modo implícito: Por padrão, a OpenAI escolhe pontos de corte que funcionam bem para a maioria dos casos de uso.

• Quando prompt_cache_options.mode é implicit, a OpenAI coloca um ponto de corte no fim da mensagem elegível mais recente. São elegíveis:
  • mensagens do usuário
  • a última resposta de ferramenta em um grupo de respostas de ferramentas consecutivas
  • a última mensagem do desenvolvedor no grupo inicial de mensagens consecutivas do desenvolvedor.
• Você pode adicionar pontos de corte explícitos sem desativar o implícito. O ponto implícito ocupa uma das quatro posições disponíveis para gravação no cache, deixando três para gravações explícitas.

Esses modelos oferecem suporte apenas ao cache implícito. A OpenAI coloca pontos de corte implícitos em intervalos que dependem do modelo, contados a partir do início da mensagem de sistema oculta da OpenAI. Só são elegíveis os pontos que atingem ou ultrapassam o comprimento mínimo para uso do cache, contado a partir do fim do contexto oculto.

Para calcular o valor informado em cached_tokens, subtrai-se o número de tokens de sistema ocultos da posição do último ponto de corte correspondente e arredonda-se o resultado para baixo até o múltiplo de 128 mais próximo.

Na API de Respostas, defina prompt_cache_options.ttl para escolher a duração mínima do cache:

Essas tarifas cobrem o custo total da gravação. A tarifa de entrada sem cache não é somada a elas. As tarifas de leitura são iguais para as duas durações. A OpenAI pode reter as entradas por mais tempo que o mínimo solicitado. O valor "12h" não define um prazo para exclusão nem altera a política de retenção máxima de dados.

O ttl definido na requisição se aplica ao ponto de corte implícito e aos pontos explícitos que não têm ttl próprio. Defina prompt_cache_breakpoint.ttl para especificar outra duração em um ponto de corte explícito. Omitir as duas configurações preserva o comportamento padrão de "30m". Valores sem suporte retornam 400 invalid_request_error. Essas configurações não alteram o parâmetro prompt_cache_retention dos modelos anteriores.

Combine durações na mesma requisição

Coloque no início do prompt o material reutilizado ao longo do dia e atribua ao seu ponto de corte a duração de "12h". Use "30m" para o contexto da sessão que muda com mais frequência. O exemplo define 30 minutos como padrão da requisição e especifica outra duração para o prefixo compartilhado. No modo exclusivamente explícito, a pergunta atual fica após o último ponto de corte, de modo que não há cobrança de gravação desse conteúdo no cache.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30{
  "model": "gpt-6.1-sol",
  "prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Shared instructions and reference material reused throughout the day...",
          "prompt_cache_breakpoint": { "mode": "explicit", "ttl": "12h" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Session context reused over the next few minutes...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        {
          "type": "input_text",
          "text": "The current question, which does not need a cache write..."
        }
      ]
    }
  ]
}

Substitua o texto de exemplo pelo seu conteúdo. Cada prefixo que você quiser armazenar em cache precisa atingir o comprimento mínimo exigido pelo modelo.

Sobreposição de gravações e mudanças de duração

Um ponto de corte abrange todo o prefixo que o precede. Em uma mesma requisição, cada token é cobrado uma única vez pela maior duração entre as gravações selecionadas que o abrangem. Uma gravação de 12 horas em um ponto mais adiante também dá cobertura de 12 horas aos pontos de corte anteriores selecionados dentro desse prefixo.

Nos exemplos a seguir, pressupõe-se que qualquer prefixo já em cache corresponda a um limite de consulta elegível na nova requisição.

Ao estender uma cobertura válida de 30 minutos para 12 horas, cobra-se uma nova gravação de 12 horas pelos tokens afetados, sem crédito pela gravação anterior. Toda parte já coberta por uma entrada válida de 12 horas continua sendo cobrada como leitura do cache.

Uma leitura de 30 minutos renova a cobertura por pelo menos 30 minutos a partir dessa leitura. Se a entrada usada já tiver cobertura válida de 12 horas, vale o prazo que terminar mais tarde: o prazo existente ou 30 minutos após a leitura. A leitura não reinicia a contagem das 12 horas nem gera nova cobrança de gravação.

Use prompt_cache_retention. Os valores aceitos dependem do modelo:

• in_memory: As entradas costumam permanecer ativas por cerca de 5 a 10 minutos de inatividade, podendo chegar a uma hora.
• 24h: A retenção estendida costuma manter 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 e valor criptografados no armazenamento local da GPU como estado do aplicativo. Nos modelos compatíveis tanto com in_memory quanto com 24h, o padrão depende da política de retenção de dados da sua organização:

• Para organizações sem zero retenção de dados ativada, o padrão é 24h.
• Para organizações com zero retenção de dados ativada, o padrão é in_memory.

Verifique as políticas de retenção disponíveis para seu modelo e sua organização antes de selecionar um valor.

Nos modelos anteriores ao GPT-5.6, use uma prompt_cache_key estável nas requisições que compartilham um prefixo reutilizável para ajudar a encaminhá-las ao mesmo cache. Em grupos de alto tráfego, procure manter o total em cerca de 15 requisições por minuto por chave, somando todos os prefixos que a utilizam. Para volumes maiores, distribua o tráfego 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, mas não vinculam as requisições a uma máquina nem garantem um acerto no cache.

No GPT-5.6 e em modelos posteriores, a OpenAI cuida automaticamente do roteamento do cache. A chave é dispensável para otimizar o cache. Você pode usar chaves distintas para contabilizar separadamente o uso do cache por cliente ou usuário do aplicativo.

Com chaves distintas, fica mais fácil explicar a cada cliente ou usuário o uso e a cobrança de tokens em cache. Por exemplo, elas ajudam a impedir que um usuário envie prompts de teste e observe os acertos no cache para descobrir se outro usuário já armazenou conteúdo correspondente. Consulte Contabilize o uso do cache separadamente com chaves.

Em aplicativos com vários turnos, reutilizar o histórico à medida que a conversa avança pode economizar mais tokens de entrada do que armazenar apenas as instruções iniciais em cache. Preserve as mensagens anteriores e os resultados das 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 eles contiverem registros de data e hora, conteúdo específico de usuários ou outros elementos dinâmicos, coloque esses elementos no fim ou mova-os para mensagens posteriores da conversa.
• Preserve o histórico da conversa. Acrescente novas mensagens ao fim do histórico em vez de reescrever turnos anteriores. Resumir o histórico, aplicar compactação ou truncar o contexto pode alterar o prefixo e fazer com que a reutilização do cache recomece do zero.
• Altere o esforço de raciocínio sem reescrever o prefixo. Nos modelos GPT-6, acrescente um item de entrada configuration_update para mudar o esforço de raciocínio entre respostas e mantenha inalterado o reasoning.effort da requisição. Isso preserva o prefixo original para reutilização do cache. Consulte Altere o raciocínio durante a conversa para ver exemplos e limites de compatibilidade.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "low", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Stable instructions and shared reference material...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "developer",
      "content": "Dynamic developer instructions, such as user-specific content and timestamps..."
    },
    {
      "role": "user",
      "content": "The user's current question..."
    }
  ]
}

Nos modelos compatíveis a partir do GPT-6, acrescente um item de entrada configuration_update para alterar o esforço de raciocínio durante a conversa e preservar o prefixo anterior em cache. Mantenha o valor original de reasoning.effort no nível superior, pois mudar essa configuração pode reescrever parte das instruções de sistema ocultas.

A atualização mais recente de reasoning.effort define o esforço de raciocínio das respostas seguintes. Acrescente este item ao fim de input para mudar o esforço para high.

1
2
3
4{
  "type": "configuration_update",
  "reasoning": { "effort": "high" }
}

Quando o aplicativo precisar de ferramentas diferentes a cada requisição, altere quais delas podem ser chamadas, mantendo as definições estáveis para preservar os prefixos reutilizáveis.

• Mantenha as ferramentas consistentes. Preserve as definições, a ordem e os schemas das ferramentas.
• Desative o uso de ferramentas em uma requisição. Defina tool_choice como "none" em vez de remover as definições de ferramentas.
• Habilite apenas as ferramentas selecionadas. Use allowed_tools para restringir quais ferramentas podem ser chamadas, mantendo estável a lista tools fornecida.
• Carregue as ferramentas conforme necessário. Use a busca de ferramentas com defer_loading: true para reduzir o número de 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 fim do contexto, preservando o conteúdo reutilizável anterior.
• Preserve o histórico de carregamento das ferramentas. Use um item de entrada additional_tools com o papel de desenvolvedor para adicionar ferramentas durante a conversa conforme a lógica do aplicativo.

No GPT-5.6 e em modelos posteriores, duas configurações determinam a posição dos pontos de corte. prompt_cache_options.mode seleciona o modo implícito ou exclusivamente explícito, e prompt_cache_breakpoint marca um limite que você escolhe.

• Posicione os pontos de corte automaticamente. Use o cache implícito para colocar um ponto de corte no fim da mensagem elegível mais recente. Isso facilita o uso em conversas com vários turnos que acrescentam mensagens ao contexto existente.
• Escolha onde colocar os pontos de corte. Coloque marcadores explícitos no fim do conteúdo estável. Use o modo exclusivamente explícito para evitar gravações desnecessárias de sufixos variáveis no cache.

No GPT-5.6 e em modelos posteriores, prepare o contexto conhecido com antecedência para reduzir o tempo até o primeiro token em uma requisição posterior. Por exemplo, um aplicativo interativo pode pré-aquecer o cache com instruções compartilhadas, definições de ferramentas ou material de referência durante a inicialização, antes que o usuário faça a primeira pergunta.

Defina prompt_cache_options.prewarm como true em uma requisição à API de Respostas para preparar o cache de prompts sem gerar saída. Quando a requisição terminar, envie a requisição real com o mesmo prefixo de prompt e com prewarm omitido ou definido como false.

1
2
3
4
5
6
7
8
9
10
11
12{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    }
  ],
  "prompt_cache_options": {
    "prewarm": true
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    },
    {
      "role": "user",
      "content": "The user's question..."
    }
  ]
}

Os tokens gravados no cache durante uma requisição de pré-aquecimento são cobrados pela tarifa de gravação correspondente à duração selecionada.

No GPT-5.6 e em modelos posteriores, use prompt_cache_key para contabilizar separadamente o uso do cache por cliente, usuário ou espaço de trabalho do aplicativo. Assim, fica mais fácil explicar o uso e a 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. Atribua uma chave distinta a cada cliente ou usuário cujo uso do cache deva ser contabilizado separadamente. Por exemplo, support:customer_123 e support:customer_456 separam a contabilização de 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 distinta para uma sessão ou conversa apenas quando for preciso contabilizar o uso do cache separadamente.
• Aplique as chaves de forma consistente. Use a chave do cliente em todas as requisições dele para manter a contabilização separada. Isso também ajuda a impedir que um cliente use acertos no cache para sondar o conteúdo de outros clientes.

Nos modelos anteriores ao GPT-5.6, prompt_cache_key é importante para otimizar as taxas de acerto no cache. Use uma chave estável nas requisições que compartilham um prefixo reutilizável para ajudar a encaminhá-las ao mesmo cache. Em grupos de alto tráfego, siga as orientações para distribuir o tráfego entre mais chaves.

Nos modelos da API de Respostas compatíveis com prompt_cache_options, use "30m" para contextos reutilizados com frequência e considere "12h" para prefixos estáveis reutilizados após intervalos mais longos. Compare a tarifa mais alta de gravação de 12 horas com o custo de gravar novamente o prefixo após o vencimento da cobertura de 30 minutos. Defina durações específicas nos pontos de corte para que o material compartilhado tenha cobertura mais longa que o contexto de cada sessão. Consulte Duração do cache para ver exemplos e regras de cobrança.

Nos modelos anteriores, dê preferência a prompt_cache_retention com o valor "24h" para retenção estendida quando o modelo e seus requisitos de retenção de dados permitirem. Consulte Duração do cache para ver as configurações aceitas e os valores padrão.

Se muitas requisições reutilizarem as mesmas instruções do desenvolvedor e definições de ferramentas, mas o prefixo compartilhado ficar abaixo do comprimento mínimo para uso do cache, considere encurtá-lo ou ampliá-lo com instruções, exemplos ou material de referência que sejam ú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. Verifique também se os resultados das avaliações e o comportamento permanecem estáveis.

O gráfico mostra quando manter um prefixo curto sem cache pode custar mais do que ampliá-lo até o mínimo de tokens necessário para usar o cache. O cálculo usa a tarifa de gravação de 30 minutos do GPT-5.6 e dos modelos posteriores.

• Meça o desempenho real do cache. Acompanhe usage.input_tokens_details.cached_tokens, usage.input_tokens_details.cache_write_tokens, as contagens de gravação por duração, o número de tokens de entrada, a latência e o custo efetivo. Para calcular a taxa de acerto do cache por token, divida o total de tokens em cache pelo total de tokens de entrada. Agregue ambas as contagens por usuário, espaço de trabalho, dia ou outro agrupamento relevante.
• Calcule o custo de entrada. Use as contagens de tokens em response.usage e os preços do modelo por milhão de tokens.
• Use o painel de cache de prompts. Monitore as taxas de acerto no painel de cache de prompts.

Nos modelos da API de Respostas compatíveis com prompt_cache_options, o campo input_tokens_details.cache_write_tokens_details separa as gravações em ttl_30m_tokens e ttl_12h_tokens. Essas contagens não se sobrepõem e sua soma é igual a cache_write_tokens. A API retorna os dois campos mesmo quando um deles é zero. O campo cached_tokens contabiliza as leituras cobradas e exclui os tokens cobrados como gravação, inclusive quando a cobertura passa de 30 minutos para 12 horas.

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 3000,
        "ttl_12h_tokens": 4000
      }
    }
  }
}

Neste exemplo de uso, 1.000 tokens são de entrada sem cache: 12000 - 4000 - 7000. Para calcular o custo de entrada, multiplique os tokens de entrada sem cache pelo preço de entrada do modelo, cached_tokens pelo preço de entrada em cache, ttl_30m_tokens por 1,25× o preço de entrada e ttl_12h_tokens por 2,5× o preço de entrada. Some os valores e divida por 1.000.000 se estiver usando preços por milhão de tokens. Não some cache_write_tokens novamente depois de contabilizar seus dois componentes.

Por exemplo, com um preço de entrada de US$ 1 por milhão de tokens e um preço de entrada em cache de US$ 0,10 por milhão, o custo de entrada desse uso é (1000 + 4000 × 0.1 + 3000 × 1.25 + 4000 × 2.5) / 1000000 = $0.01515. Use as tarifas reais do seu modelo, incluindo a de entrada em cache.

A função auxiliar a seguir usa um único multiplicador para todas as gravações no cache. Use 1.25 se todas as gravações tiverem duração de 30 minutos ou 2.5 se todas tiverem duração de 12 horas. Em requisições com as duas durações, calcule separadamente o custo de cada tipo de gravação, como descrito acima.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18function calculateInputCost(
  usage,
  inputPricePerMillion,
  cacheInputMultiplier = 0.1,
  cacheWriteMultiplier = 1.25
) {
  const inputTokens = usage.input_tokens;
  const cachedTokens = usage.input_tokens_details.cached_tokens;
  const cacheWriteTokens = usage.input_tokens_details.cache_write_tokens;
  const ordinaryInputTokens = inputTokens - cachedTokens - cacheWriteTokens;

  const weightedInputTokens =
    ordinaryInputTokens +
    cachedTokens * cacheInputMultiplier +
    cacheWriteTokens * cacheWriteMultiplier;
  const inputCost = (weightedInputTokens * inputPricePerMillion) / 1_000_000;
  return inputCost;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from openai.types.responses import ResponseUsage


def calculate_input_cost(
    usage: ResponseUsage,
    input_price_per_million: float,
    cache_input_multiplier: float = 0.1,
    cache_write_multiplier: float = 1.25,
) -> float:
    input_tokens = usage.input_tokens
    cached_tokens = usage.input_tokens_details.cached_tokens
    cache_write_tokens = usage.input_tokens_details.cache_write_tokens
    ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

    weighted_input_tokens = (
        ordinary_input_tokens
        + cached_tokens * cache_input_multiplier
        + cache_write_tokens * cache_write_multiplier
    )
    input_cost = weighted_input_tokens * input_price_per_million / 1_000_000
    return input_cost

1
2
3
4
5func calculateInputCost(usage responses.ResponseUsage, pricePerMillion, cacheInputMultiplier, cacheWriteMultiplier float64) float64 {
	ordinary := usage.InputTokens - usage.InputTokensDetails.CachedTokens - usage.InputTokensDetails.CacheWriteTokens
	weighted := float64(ordinary) + float64(usage.InputTokensDetails.CachedTokens)*cacheInputMultiplier + float64(usage.InputTokensDetails.CacheWriteTokens)*cacheWriteMultiplier
	return weighted * pricePerMillion / 1_000_000
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.models.responses.ResponseUsage;

static double calculateInputCost(
    ResponseUsage usage,
    double pricePerMillion,
    double cacheInputMultiplier,
    double cacheWriteMultiplier) {
  long cached = usage.inputTokensDetails().cachedTokens();
  long written = usage.inputTokensDetails().cacheWriteTokens();
  long ordinary = usage.inputTokens() - cached - written;
  return (ordinary + cached * cacheInputMultiplier + written * cacheWriteMultiplier)
      * pricePerMillion
      / 1_000_000;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17def calculate_input_cost(
  usage,
  input_price_per_million,
  cache_input_multiplier = 0.1,
  cache_write_multiplier = 1.25
)
  input_tokens = usage.input_tokens
  details = usage.input_tokens_details
  cached_tokens = details.cached_tokens
  cache_write_tokens = details.cache_write_tokens
  ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

  weighted_input_tokens = ordinary_input_tokens +
                          (cached_tokens * cache_input_multiplier) +
                          (cache_write_tokens * cache_write_multiplier)
  (weighted_input_tokens * input_price_per_million) / 1_000_000
end

• Mantenha os prefixos estáveis existentes.
• Se você usa prompt_cache_key, mantenha os valores existentes para preservar a contabilização separada do uso do cache por cliente ou usuário.
• Substitua prompt_cache_retention por prompt_cache_options.ttl.
• Confirme que os prefixos reutilizáveis atingem o comprimento mínimo para uso do cache exigido pelo modelo.
• Se o ponto de corte padrão incluir conteúdo que muda entre requisições, adicione um ponto de corte explícito após o prefixo estável.
• Use prompt_cache_options.mode: "explicit" quando não valer a pena gravar o conteúdo posterior.
• Compare cached_tokens, cache_write_tokens, a latência e o custo total antes e depois da migração.

Considere um LLM que avalia, em um único turno, se uma interação concluída com um chatbot mostra sinais de satisfação do usuário. Cada requisição usa os mesmos critérios de avaliação e exemplos few-shot rotulados para avaliar uma interação diferente.

• Preservação do prefixo: Os critérios fixos e os exemplos vêm primeiro. O material escolhido ajuda a calibrar o avaliador e mantém o comprimento combinado pouco acima do mínimo para uso do cache do modelo. A interação a ser avaliada vem por último.
• Modo de cache e ponto de corte: O modo exclusivamente explícito está ativado, com um ponto de corte após os critérios fixos e os exemplos. A conversa entre o usuário e o chatbot vem depois desse ponto e não é gravada no cache, o que evita uma cobrança de gravação por conteúdo com pouca chance de reutilização.

Uma implantação que seguiu esses princípios registrou uma taxa de acerto do cache por token de aproximadamente 70%. Esse é um resultado possível. A taxa máxima que você pode atingir depende do contexto e de como o aplicativo é usado.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  "model": "gpt-6.1-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 vários turnos, instruções longas e compartilhadas do desenvolvedor e chamadas frequentes de ferramentas. Em geral, os usuários mantêm várias sessões simultâneas com o agente 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. Assim, o prefixo reutilizável cresce com o tempo.
• Chave opcional do cache de prompts: Este exemplo usa agent_123_v1:user_456 para contabilizar separadamente o uso do cache pelo usuário 456, facilitando a explicação do uso e da cobrança dos tokens em cache. Isso também ajuda a impedir que um usuário use acertos no cache para sondar o conteúdo de outros usuários. A chave permanece a mesma em todas as sessões e forks desse usuário com o agente. Omita a chave se o aplicativo não precisar dessa separação.
• Modo de cache implícito: O modo implícito está ativado, de modo que a mensagem elegível mais recente do usuário ou de uma ferramenta fornece um ponto de corte.
• Pontos de corte explícitos: Um ponto de corte é adicionado após cada resultado de ferramenta para preservar prefixos anteriores reutilizáveis e tornar o cache mais eficiente nos forks da conversa.

Uma implantação que seguiu esses princípios registrou uma taxa de acerto do cache por token superior a 90%. Esse é um resultado possível. A taxa máxima que você pode atingir depende do contexto e de como o aplicativo é usado.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_key": "agent_123_v1:user_456",
  "prompt_cache_options": { "mode": "implicit" },
  "tools": [
    {
      "type": "function",
      "name": "function_name",
      "description": "Function description",
      "parameters": { "...": "..." }
    }
  ],
  "input": [
    {
      "role": "developer",
      "content": "Stable developer instructions and reference material..."
    },
    { "role": "user", "content": "Can you do...?" },
    {
      "type": "function_call",
      "call_id": "call_123",
      "name": "function_name",
      "arguments": "..."
    },
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": [
        {
          "type": "input_text",
          "text": "Tool result...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    { "role": "assistant", "content": "Assistant response..." },
    { "role": "user", "content": "Can you also do...?" }
  ]
}

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 compartilharem um prefixo longo, mas tiverem sufixos diferentes, armazenar a primeira requisição completa usando apenas o cache 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. A gravação no cache se estende 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 em cache, e não há um ponto de corte separado após o conteúdo estático.

1
2
3
4
5
6
7
8
9
10{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "implicit" },
  "input": [
    { "role": "developer", "content": "Static content..." },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

Para corrigir isso, coloque um ponto de corte explícito após o conteúdo estático nas duas requisições. A primeira grava o prefixo reutilizável, e a seguinte pode reutilizá-lo mesmo que o conteúdo dinâmico mude. Este exemplo usa o modo exclusivamente explícito para evitar a gravação do conteúdo dinâmico no cache.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "Static content...",
        "prompt_cache_breakpoint": { "mode": "explicit" }
      }]
    },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

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. A requisição 2 preserva esse prefixo, mas passa a usar prompt_cache_options.mode: "explicit". Como descrito em Como funciona a correspondência de prefixos, a requisição 2 verifica apenas os pontos de corte explícitos da própria entrada. Por isso, só reutilizará o prefixo implícito salvo pela requisição 1 se um dos seus pontos explícitos coincidir com o fim do prefixo armazenado pela primeira requisição.

▼ = 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, coloque um ponto de corte explícito no limite correspondente do bloco de conteúdo na requisição 2. Outra opção é manter o modo implícito ativado para que o fim da mensagem elegível anterior continue sendo considerado na consulta ao cache.

Mesmo que as duas requisições usem o modo implícito, preservar os mesmos tokens iniciais nem sempre basta. Suponha que a requisição 1 termine com uma mensagem do usuário contendo Content A e que a requisição 2 amplie essa mesma mensagem para Content A + Content B. O limite anterior, logo após Content A, agora está dentro da mensagem, e não no fim. Como descrito em Como funciona a correspondência de prefixos, sem um ponto de corte 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 coloque um ponto de corte explícito após esse bloco nas duas requisições.

No modo implícito, as mensagens do desenvolvedor que vêm após o bloco inicial de mensagens consecutivas do desenvolvedor não definem automaticamente limites de consulta ao cache. Adicione um ponto de corte explícito no fim da mensagem reutilizável do desenvolvedor para preservar esse ponto nas requisições posteriores. Assim, a OpenAI poderá verificar se há um prefixo correspondente no cache.

Um prefixo elegível para o 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ê usa de fato. Ao mudar de modelo, repita a verificação em vez de presumir que o limite anterior continua válido.

A compactação substitui o contexto anterior da conversa por uma representação mais curta. Isso pode alterar o prefixo. Assim, a primeira requisição após a compactação pode reutilizar uma parte menor do cache anterior, mesmo que, do ponto de vista lógico, a conversa seja a mesma.

Sempre que possível, mantenha estáveis as instruções reutilizáveis e o material de referência. Depois, use o contexto compactado como base para os turnos seguintes. Compare o custo total de entrada antes e depois da compactação. Reduzir o número de tokens de entrada pode gerar economia mesmo que a taxa de acerto no cache diminua.

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. Atualmente, não é possível limpar o cache manualmente. As entradas expiram de acordo com a duração 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 de calcular os limites de taxa.