Diagnóstico do cache de prompts

O diagnóstico do cache de prompts ajuda a explicar por que uma solicitação reutilizou menos tokens do que o esperado. Compare a solicitação com uma resposta anterior para identificar alterações no modelo, nas ferramentas, nas configurações ou na entrada que impediram a reutilização.

O diagnóstico está disponível na API Responses para o GPT-5.6 e os modelos posteriores compatíveis. Use o diagnóstico para investigar solicitações individuais e o painel de cache de prompts para monitorar o desempenho do cache em todo o aplicativo.

Como funciona

O diagnóstico do cache de prompts compara a solicitação atual com uma resposta anterior para ajudar a explicar por que um prefixo do prompt não foi reutilizado como esperado. O prefixo é o conteúdo no início do prompt. Para que haja reutilização, os prefixos precisam ser idênticos e as configurações das solicitações devem ser compatíveis, incluindo o modelo, o nível de serviço e as ferramentas.

1. Escolha uma resposta de referência. Use uma resposta recente e concluída da mesma organização. Escolha uma cujo prefixo você espera reutilizar na solicitação atual, como a resposta do turno anterior da conversa.
2. Solicite uma comparação. Defina prompt_cache_options.comparison_response_id como o id da resposta de referência.
3. Confira o resultado. Consulte prompt_cache_diagnostics na resposta atual. Se o diagnóstico identificar uma falha de cache, o resultado incluirá o motivo para ajudar na investigação. Use usage.input_tokens_details.cached_tokens para medir a reutilização efetiva do cache.

Definir comparison_response_id apenas solicita o diagnóstico. Isso não carrega a conversa anterior nem altera o comportamento do cache. A solicitação atual ainda pode reutilizar entradas de cache correspondentes de outras solicitações.

Exemplo de uso

O exemplo a seguir envia duas solicitações com o mesmo modelo, as mesmas instruções e a mesma entrada, mas muda o nome de uma ferramenta do tipo função de get_time para get_date. A segunda solicitação usa a primeira como referência para comparar a reutilização do cache.

Use seu próprio documento de políticas em support-policy.txt. O prefixo reutilizável deve atingir o comprimento mínimo que o modelo exige para uso do cache. Para o GPT-5.6 e os modelos posteriores, o mínimo é de 1.024 tokens.

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
27from pathlib import Path

from openai import OpenAI

client = OpenAI()
policy = Path("support-policy.txt").read_text()  # At least 1,024 tokens.

first = client.responses.create(
    model="gpt-6-astra",
    instructions=policy,
    input="Reply with exactly OK.",
    tools=[{"type": "function", "name": "get_time"}],
)

second = client.responses.create(
    model="gpt-6-astra",
    instructions=policy,
    input="Reply with exactly OK.",
    tools=[{"type": "function", "name": "get_date"}],
    prompt_cache_options={"comparison_response_id": first.id},
)

diagnostics = second.prompt_cache_diagnostics
if diagnostics is not None and diagnostics.type == "cache_miss":
    print(diagnostics.reason)
    print(diagnostics.comparison_reusable_tokens)
    print(diagnostics.cache_missed_tokens)

Se a alteração na ferramenta causar uma falha de cache, o resultado poderá ser semelhante ao exemplo abaixo. As contagens de tokens variam conforme a entrada.

12345678{
  "prompt_cache_diagnostics": {
    "type": "cache_miss",
    "reason": "tools_changed",
    "comparison_reusable_tokens": 5629,
    "cache_missed_tokens": 5629
  }
}

Para preservar a reutilização, mantenha as definições e a ordem das ferramentas entre as solicitações. Consulte Gerencie ferramentas adicionando novas entradas apenas ao final da lista.

Conversas com vários turnos

Para comparar turnos consecutivos, salve o id de cada resposta concluída e passe esse valor como comparison_response_id em prompt_cache_options na solicitação seguinte. Omita o ID de comparação no primeiro turno.

Ao testar uma correção, mantenha o ID da resposta de referência como ID de comparação.

Streaming

Ao usar stream=True, consulte prompt_cache_diagnostics em event.response no evento response.completed.

Entenda a resposta

Consulte prompt_cache_diagnostics.type para saber o resultado da comparação.

Interprete as contagens de tokens

O resultado cache_hit indica que a comparação não detectou nenhuma falha de cache. Ainda pode ser necessário processar conteúdo novo. Por exemplo, uma solicitação com 2.500 tokens de entrada pode retornar cache_hit ao reutilizar o prefixo de 2.000 tokens da resposta de referência e processar 500 tokens novos.

Para um resultado cache_miss, interprete os campos da seguinte forma:

• comparison_reusable_tokens, quando presente, indica a contagem bruta de tokens do prefixo reutilizável da resposta de referência.
• cache_missed_tokens estima quantos desses tokens não foram reutilizados.

As contagens de diagnóstico podem diferir das contagens de uso. Use os campos de uso da resposta atual para medir a reutilização do cache registrada e verificar a cobrança.

Corrija uma falha de cache

Use prompt_cache_diagnostics.reason para localizar na tabela a seguir a causa da falha de cache e a correção sugerida.

Algumas alterações, como trocar de modelo ou compactar uma conversa, são intencionais. Você pode optar por mantê-las mesmo que reduzam a reutilização do cache.

Confirme a melhoria

Depois de fazer uma alteração:

1. Envie outra solicitação representativa e compare-a com a resposta de referência escolhida.
2. Confira o resultado do diagnóstico para ver se ainda há alguma diferença.
3. Compare cached_tokens, cache_write_tokens e o custo total em várias solicitações.

Consulte Monitore o desempenho do cache para saber mais sobre as métricas de uso e os cálculos de custo.

Preços e limites de taxa

O diagnóstico do cache de prompts não tem custo adicional nem é contabilizado separadamente para fins de limites de taxa. Solicitações adicionais à API Responses para obter uma resposta de referência ou fazer uma nova tentativa são cobradas normalmente e contam para os limites de taxa.

Zero retenção de dados

O diagnóstico do cache de prompts é compatível com a configuração de zero retenção de dados. A OpenAI não armazena prompts brutos nem saídas do modelo para esse recurso. Os registros de diagnóstico contêm metadados de configuração, estimativas de contagem de tokens e hashes usados para comparar conteúdos cujas alterações podem afetar o cache. Esses registros se restringem à organização, expiram após um curto período e servem apenas para explicar por que houve um acerto ou uma falha no cache de prompts.

Definir comparison_response_id não recupera nem armazena de forma persistente o conteúdo da resposta anterior. Consulte Seus dados para conhecer os controles de dados da OpenAI.

Limitações

• O diagnóstico está disponível na API Responses para o GPT-5.6 e os modelos posteriores compatíveis.
• Os registros de diagnóstico expiram após um curto período. Se o registro tiver expirado, a comparação retornará comparison_response_not_found, mesmo que a resposta ainda esteja disponível pela API.
• O diagnóstico informa o primeiro motivo que consegue classificar. Corrija a causa indicada e repita a comparação para verificar se há outras causas.
• O diagnóstico tenta classificar cada falha de cache, mas nem sempre consegue. O resultado unavailable não indica acerto nem falha de cache. A API retorna esse valor se a comparação ainda não estiver pronta.
• O diagnóstico nunca bloqueia a solicitação, nunca faz com que ela falhe e nunca altera a maneira como o modelo gera a saída.