Diagnostica della cache

La cache dei prompt riduce significativamente la latenza e i costi, ma solo quando l'inizio del tuo prompt è identico byte per byte a una richiesta recente. Uno strumento riordinato, un timestamp interpolato nel tuo prompt di sistema o una modifica a un messaggio precedente possono invalidare silenziosamente la cache. Senza la diagnostica della cache, l'unico segnale è usage.cache_read_input_tokens che scende a zero, senza alcuna indicazione di cosa sia cambiato.

La diagnostica della cache colma questa lacuna. Passa l'id della tua risposta precedente e l'API confronta le due richieste e ti dice dove sono divergenti (il modello, il prompt di sistema, gli strumenti o la cronologia dei messaggi) così puoi correggere la causa principale invece di tirare a indovinare.

Come funziona la diagnostica della cache

Per ogni richiesta che include l'oggetto diagnostics, l'API memorizza un "fingerprint" (impronta digitale) leggero indicizzato tramite l'id della risposta. Non memorizza nulla per le richieste che omettono l'oggetto. Nella richiesta successiva, includi l'id della risposta precedente come diagnostics.previous_message_id. L'API ricostruisce l'impronta per la nuova richiesta, la confronta con quella memorizzata e allega alla risposta un oggetto diagnostics che descrive il primo punto di divergenza.

Il confronto riguarda la struttura della richiesta, indipendentemente dal fatto che la cache abbia effettivamente avuto un hit. Consulta Leggere la diagnostica insieme all'utilizzo per sapere come combinare il risultato di diagnostics con usage.cache_read_input_tokens.

Le impronte contengono solo hash e stime del conteggio dei token (mai il contenuto grezzo del prompt), sono conservate per un tempo limitato, sono circoscritte alla tua organizzazione e al tuo workspace e non sono utilizzate per nessun altro scopo.

Utilizzo di base

Includi l'oggetto diagnostics in ogni turno. L'oggetto costituisce l'adesione esplicita: l'API memorizza un'impronta solo per le richieste che lo includono. Nel primo turno, passa "previous_message_id": null per aderire senza un messaggio precedente con cui effettuare il confronto. Nei turni successivi, passa l'id della risposta precedente. L'header beta cache-diagnosis-2026-04-07 non è più necessario e le richieste che lo inviano ancora funzionano come prima.

client = anthropic.Anthropic()

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"

# Turno 1: attiva l'opzione con previous_message_id=None
r1 = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[{"role": "user", "content": "Summarize section 1."}],
    diagnostics={"previous_message_id": None},
)

# Turno 2: fai riferimento all'id della risposta precedente
r2 = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
)

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

Streaming

Nelle risposte in streaming, diagnostics appare nell'evento message_start.

# Turno 2: streaming, facendo riferimento all'id della risposta precedente
with client.beta.messages.stream(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print()
    r2 = stream.get_final_message()

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

L'evento message_start trasporta il campo diagnostics completo; consulta Formato della risposta per i valori possibili.

Propagare la diagnostica attraverso un ciclo di conversazione

In una conversazione a più turni, porta avanti l'id dell'ultima risposta come previous_message_id a ogni turno. La prima iterazione passa null per attivare la funzione; ogni iterazione successiva passa l'id della risposta precedente.

client = anthropic.Anthropic()

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"

messages = []
prev_id = None

for i, user_message in enumerate(
    ["Summarize section 1.", "Now section 2.", "Now section 3."]
):
    messages.append({"role": "user", "content": user_message})

    r = client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        cache_control={"type": "ephemeral"},
        system=SYSTEM,
        messages=messages,
        diagnostics={"previous_message_id": prev_id},
    )

    if r.diagnostics is not None and r.diagnostics.cache_miss_reason is not None:
        print(f"Turn {i + 1} cache_miss_reason: {r.diagnostics.cache_miss_reason.type}")

    messages.append({"role": "assistant", "content": r.content})
    prev_id = r.id

Formato della risposta

Il campo diagnostics nel Message di risposta ha tre valori possibili:

Quando cache_miss_reason è non-null, appare così:

{
  "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
    }
  }
}

Tipi di motivo del cache miss

cache_miss_reason è un'unione discriminata su type. La risposta riporta solo la divergenza più precoce, quindi correggila per prima; quelle successive potrebbero essere nascoste dietro di essa.

Leggere la diagnostica insieme all'utilizzo

diagnostics risponde a "la mia richiesta è cambiata?" mentre usage.cache_read_input_tokens risponde a "la cache ha avuto un hit?". Combinarli ti dice dove guardare.

Questa matrice si applica ai turni in cui hai passato un previous_message_id reale. Al primo turno (previous_message_id: null), diagnostics è sempre null e cache_read_input_tokens è normalmente zero perché la cache viene scritta, non letta; non è necessaria alcuna risoluzione dei problemi. La matrice inoltre non si applica quando cache_miss_reason è null (il confronto è ancora in sospeso; controlla il turno successivo) o quando il suo type è previous_message_not_found o unavailable (non è stato prodotto alcun confronto).

Limitazioni

• Solo Claude API: Non disponibile su Amazon Bedrock o Google Cloud.
• Conservazione limitata: Le impronte per la ricerca di previous_message_id scadono dopo un breve periodo. Esegui i confronti diagnostici tra richieste ravvicinate nel tempo.
• Stesso workspace: La richiesta precedente deve essere stata eseguita nella stessa organizzazione e nello stesso workspace. Per verificare, confronta l'header di risposta anthropic-workspace-id sulle due risposte.
• Orizzonte di confronto: Per conversazioni molto lunghe in cui l'unico cambiamento è in profondità nella lista dei messaggi, la risposta può essere unavailable invece di una posizione precisa.
• Best-effort: La diagnostica non blocca né fa fallire mai la tua richiesta. Se le informazioni diagnostiche non sono disponibili, la risposta restituisce unavailable, oppure cache_miss_reason: null quando il confronto era ancora in esecuzione.

Conservazione dei dati

La diagnostica della cache è idonea per ZDR (qualificata). Anthropic non memorizza il testo grezzo dei tuoi prompt o degli output di Claude per questa funzione.

L'API memorizza un'impronta solo per le richieste che includono l'oggetto diagnostics. L'impronta è costituita esclusivamente da hash crittografici e stime del conteggio dei token, è indicizzata tramite l'id della risposta ed è circoscritta alla tua organizzazione e al tuo workspace. Le impronte scadono dopo un breve periodo e non vengono utilizzate per nessun altro scopo.

Per l'idoneità ZDR su tutte le funzioni, consulta API e conservazione dei dati.

Vedi anche

• Cache dei prompt
• Conteggio dei token

Compatibility