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

Quando l'header beta è presente, l'API memorizza un'impronta leggera di ogni richiesta, indicizzata dall'id della risposta. Nella tua richiesta successiva, includi quell'id come diagnostics.previous_message_id. L'API ricostruisce l'impronta per la nuova richiesta, la confronta con quella memorizzata e allega un oggetto diagnostics alla risposta 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

Invia l'header beta a ogni turno. Al primo turno, passa "previous_message_id": null per attivare la funzione senza un messaggio precedente con cui confrontare. Nei turni successivi, passa l'id della risposta precedente.

client = anthropic.Anthropic()

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

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

# Turno 2: fai riferimento all'id della risposta precedente
r2 = client.beta.messages.create(
    model="claude-opus-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},
    betas=["cache-diagnosis-2026-04-07"],
)

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",
    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},
    betas=["cache-diagnosis-2026-04-07"],
) 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",
        max_tokens=1024,
        cache_control={"type": "ephemeral"},
        system=SYSTEM,
        messages=messages,
        diagnostics={"previous_message_id": prev_id},
        betas=["cache-diagnosis-2026-04-07"],
    )

    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 della risposta ha quattro stati 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

• Beta: I nomi dei campi e la semantica possono cambiare mentre questa funzione è in beta.
• 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'impronta memorizzata per ogni richiesta consiste solo di hash crittografici e stime del conteggio dei token, indicizzata dall'id della risposta e circoscritta alla tua organizzazione e al tuo workspace. Le impronte scadono dopo un breve periodo e non sono 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
• Header beta

Compatibility