Diagnóstico do cache de prompts

Os diagnósticos do cache de prompts ajudam a explicar por que uma requisição reutilizou menos tokens do que o esperado. Compare uma requisição com uma resposta anterior para identificar mudanças no modelo, nas ferramentas, nas configurações ou na entrada que impediram a reutilização.

Os diagnósticos estão disponíveis na API Responses para GPT-5.6 e modelos posteriores compatíveis. Use-os para investigar requisições individuais e use o Painel de cache de prompts para monitorar o desempenho do cache em todo o seu aplicativo.

Como funciona

Os diagnósticos do cache de prompts comparam sua requisição atual com uma resposta anterior para ajudar a explicar por que um prefixo de prompt não foi reutilizado como esperado. Um prefixo é o conteúdo no início de um prompt. A reutilização exige uma correspondência exata do prefixo e configurações de requisição 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 cujo prefixo você espera que a requisição atual reutilize, como o 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. Leia o resultado. Verifique prompt_cache_diagnostics na resposta atual. Se os diagnósticos identificarem uma falha de cache, o resultado incluirá um 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 diagnósticos. Isso não carrega a conversa anterior nem altera o comportamento do cache. A requisição atual ainda pode reutilizar entradas de cache correspondentes de outras requisições.

Exemplo de uso

O exemplo a seguir envia duas requisições com o mesmo modelo, as mesmas instruções e a mesma entrada, mas altera o nome de uma ferramenta de função de get_time para get_date. A segunda requisição compara a reutilização do cache com a primeira.

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

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 da ferramenta causar uma falha de cache, o resultado poderá ser semelhante a este. 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 inalteradas entre as requisições. Consulte Gerencie ferramentas com atualizações que apenas acrescentam itens ao final.

Conversas com vários turnos

Para comparar turnos consecutivos, salve o id de cada resposta concluída e passe-o como comparison_response_id em prompt_cache_options na próxima requisição. Omita o ID de comparação no primeiro turno.

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

Streaming

Quando stream=True, leia prompt_cache_diagnostics em event.response no evento response.completed.

Entenda a resposta

Leia prompt_cache_diagnostics.type para determinar o resultado da comparação.

Interprete as contagens de tokens

Um resultado cache_hit significa que nenhuma falha de cache foi detectada na comparação. Novos dados de entrada ainda podem exigir processamento. Por exemplo, uma requisição com 2.500 tokens de entrada pode retornar cache_hit quando reutiliza o prefixo de 2.000 tokens da resposta usada na comparação e processa 500 novos tokens.

Para um resultado cache_miss:

• comparison_reusable_tokens, quando presente, é a contagem bruta de tokens do prefixo reutilizável da resposta usada na comparação.
• cache_missed_tokens estima quantos desses tokens não foram reutilizados.

Essas 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 e a cobrança informadas.

Corrija uma falha de cache

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

Algumas mudanças, 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 requisição representativa e compare-a com a referência desejada.
2. Verifique se o resultado do diagnóstico indica alguma diferença restante.
3. Compare cached_tokens, cache_write_tokens e o custo total entre várias requisições.

Consulte Monitore o desempenho do cache para ver métricas de uso e cálculos de custo.

Preços e limites de taxa

Os diagnósticos do cache de prompts não têm custo adicional e não são contabilizados separadamente nos limites de taxa. Quaisquer requisições extras à API Responses para estabelecer uma referência ou tentar novamente são cobradas normalmente e contam para os limites de taxa.

Zero retenção de dados

Os diagnósticos do cache de prompts são compatíveis com 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údo que afeta o cache. Esses registros são restritos à organização, expiram após um curto período e são usados apenas para explicar acertos ou falhas no cache de prompts.

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

Limitações

• Os diagnósticos estão disponíveis na API Responses para o GPT-5.6 e modelos posteriores compatíveis.
• Os registros de diagnóstico expiram após um curto período. Um registro expirado retorna comparison_response_not_found, mesmo que a resposta ainda esteja disponível pela API.
• Os diagnósticos informam o primeiro motivo classificado. Resolva-o e repita a comparação para verificar se há outras causas.
• Os diagnósticos fazem o possível para classificar as falhas de cache, mas podem não classificar todas. Um resultado unavailable não indica acerto nem falha de cache e é retornado quando a comparação ainda não está pronta.
• Os diagnósticos nunca bloqueiam sua requisição, causam sua falha ou alteram a forma como o modelo gera a saída.