Diagnóstico de cache

O cache de prompt reduz significativamente a latência e o custo, mas apenas quando o início do seu prompt é idêntico byte a byte a uma requisição recente. Uma ferramenta reordenada, um timestamp interpolado no seu prompt do sistema ou uma edição em uma mensagem anterior podem invalidar o cache silenciosamente. Sem o diagnóstico de cache, o único sinal é usage.cache_read_input_tokens caindo para zero, sem nenhuma indicação do que mudou.

O diagnóstico de cache preenche essa lacuna. Passe o id da sua resposta anterior, e a API compara as duas requisições e informa onde elas divergiram (o modelo, o prompt do sistema, as ferramentas ou o histórico de mensagens) para que você possa corrigir a causa raiz em vez de adivinhar.

Como o diagnóstico de cache funciona

Quando o cabeçalho beta está presente, a API armazena uma impressão digital (fingerprint) leve de cada requisição, indexada pelo id da resposta. Na sua próxima requisição, inclua esse id como diagnostics.previous_message_id. A API reconstrói a impressão digital para a nova requisição, compara-a com a armazenada e anexa um objeto diagnostics à resposta descrevendo o primeiro ponto de divergência.

A comparação diz respeito à estrutura da requisição, independentemente de o cache ter sido efetivamente aproveitado. Consulte Lendo o diagnóstico junto com o uso para saber como combinar o resultado de diagnostics com usage.cache_read_input_tokens.

As impressões digitais contêm apenas hashes e estimativas de contagem de tokens (nunca o conteúdo bruto do prompt), são retidas por tempo limitado, têm escopo restrito à sua organização e workspace, e não são usadas para nenhum outro propósito.

Uso básico

Envie o cabeçalho beta em cada turno. No primeiro turno, passe "previous_message_id": null para aderir ao recurso sem uma mensagem anterior para comparar. Nos turnos subsequentes, passe o id da resposta anterior.

Streaming

Em respostas com streaming, diagnostics aparece no evento message_start.

O evento message_start carrega o campo diagnostics completo; consulte Formato da resposta para os valores possíveis.

Encadeando o diagnóstico em um loop de conversa

Em uma conversa de múltiplos turnos, propague o id da resposta mais recente como previous_message_id em cada turno. A primeira iteração passa null para aderir ao recurso; cada iteração subsequente passa o id da resposta anterior.

Formato da resposta

O campo diagnostics na Message de resposta tem quatro estados possíveis:

Quando cache_miss_reason não é nulo, ele tem esta aparência:

{
  "id": "msg_01Xyz...",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "..." }],
  "usage": {
    "input_tokens": 42,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 41850,
    "output_tokens": 210
  },
  "diagnostics": {
    "cache_miss_reason": {
      "type": "system_changed",
      "cache_missed_input_tokens": 41850
    }
  }
}

Tipos de motivo de falha de cache

cache_miss_reason é uma união discriminada em type. A resposta reporta apenas a divergência mais antiga, então corrija-a primeiro; divergências posteriores podem estar ocultas atrás dela.

Lendo o diagnóstico junto com o uso

diagnostics responde "minha requisição mudou?", enquanto usage.cache_read_input_tokens responde "o cache foi aproveitado?". Combiná-los indica onde procurar.

Esta matriz se aplica a turnos em que você passou um previous_message_id real. No primeiro turno (previous_message_id: null), diagnostics é sempre null e cache_read_input_tokens é normalmente zero porque o cache está sendo escrito, não lido; nenhuma solução de problemas é necessária. A matriz também não se aplica quando cache_miss_reason é null (a comparação ainda está pendente; verifique o próximo turno) ou quando seu type é previous_message_not_found ou unavailable (nenhuma comparação foi produzida).

Limitações

• Beta: Nomes de campos e semântica podem mudar antes da disponibilidade geral.
• Apenas API do Claude: Não disponível no Amazon Bedrock ou Vertex AI.
• Retenção limitada: Impressões digitais para consulta de previous_message_id expiram após um curto período. Execute comparações de diagnóstico entre requisições próximas no tempo.
• Mesmo workspace: A requisição anterior deve ter sido feita com uma chave de API da mesma organização e workspace.
• Horizonte de comparação: Para conversas muito longas em que a única mudança está no fundo da lista de mensagens, a resposta pode ser unavailable em vez de uma localização precisa.
• Melhor esforço: O diagnóstico nunca bloqueia ou faz sua requisição falhar. Se informações de diagnóstico não estiverem disponíveis, a resposta retorna unavailable, ou cache_miss_reason: null quando a comparação ainda estava em execução.

Retenção de dados

O diagnóstico de cache é elegível para ZDR (qualificado). A Anthropic não armazena o texto bruto dos seus prompts ou das saídas do Claude para este recurso.

A impressão digital armazenada para cada requisição consiste apenas em hashes criptográficos e estimativas de contagem de tokens, indexada pelo id da resposta e com escopo restrito à sua organização e workspace. As impressões digitais expiram após um curto período e não são usadas para nenhum outro propósito.

Para elegibilidade ZDR em todos os recursos, consulte API e retenção de dados.

Veja também

• Cache de prompt
• Contagem de tokens
• Cabeçalhos beta