MessagesGestione del contesto

Diagnostica della cache

Diagnostica i cache miss imprevisti dei prompt confrontando richieste consecutive e identificando esattamente dove il prefisso del prompt è divergente.

Per sapere come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta API e conservazione dei dati.

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) in modo che tu possa correggere la causa principale invece di tirare a indovinare.

La diagnostica della cache è in beta. Includi il beta header cache-diagnosis-2026-04-07 nelle tue richieste API per usare questa funzionalità.

La diagnostica della cache è attualmente disponibile solo sulla Claude API. Non è supportata su Amazon Bedrock o Google Cloud.

Come funziona la diagnostica della cache

Quando il beta header è presente, l'API memorizza un fingerprint (impronta) leggero di ogni richiesta, indicizzato dall'id della risposta. Nella tua richiesta successiva, includi quell'id come diagnostics.previous_message_id. L'API ricostruisce il fingerprint per la nuova richiesta, lo confronta con quello memorizzato 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 a usage per sapere come combinare il risultato di diagnostics con usage.cache_read_input_tokens.

I fingerprint contengono solo hash e stime del conteggio dei token (mai il contenuto grezzo del prompt), vengono conservati per un tempo limitato, sono limitati alla tua organizzazione e al tuo workspace e non vengono utilizzati per nessun altro scopo.

Utilizzo di base

Invia il beta header a ogni turno. Al primo turno, passa "previous_message_id": null per aderire 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 la funzionalità 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 contiene il campo diagnostics completo; consulta Formato della risposta per i valori possibili.

Propagare la diagnostica attraverso un ciclo di conversazione

In una conversazione multi-turno, riporta l'id della risposta più recente come previous_message_id a ogni turno. La prima iterazione passa null per aderire; ogni iterazione successiva passa l'id della risposta precedente.

Questo flusso di lavoro non si traduce bene in un comando shell una tantum. Consulta le schede degli SDK per il pattern del ciclo; la richiesta HTTP per turno è identica a Utilizzo di base.

Formato della risposta

Il campo diagnostics sul Message della risposta ha quattro stati possibili:

Valore	Significato
campo assente	La richiesta non includeva `diagnostics`, oppure il beta header era mancante.
`null`	O `previous_message_id` era `null` (primo turno, niente da confrontare), oppure è stato eseguito un confronto e non è stata trovata alcuna divergenza.
`{"cache_miss_reason": null}`	Il confronto era ancora in esecuzione quando la risposta è stata serializzata. Questo può accadere quando la risposta inizia molto rapidamente. Trattalo come non conclusivo e controlla il turno successivo.
`{"cache_miss_reason": {...}}`	È allegato un `cache_miss_reason`. Per i tipi `*_changed` questo identifica il primo punto di divergenza; `previous_message_not_found` e `unavailable` sono casi in cui non è stato prodotto alcun confronto.

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 motivi di cache miss

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

Tipo	Cosa significa	Cosa cambiare
`model_changed`	Il `model` differisce dalla richiesta precedente (ad esempio, un router, un test A/B o un fallback ha selezionato un modello diverso). La cache è per modello.	Mantieni il modello costante all'interno di una conversazione in cache.
`system_changed`	Il parametro `system` differisce. Tipicamente un timestamp, un ID di richiesta o un altro valore per richiesta è stato interpolato nel prompt di sistema.	Rendi il prompt di sistema una costante stabile a livello di byte e sposta i dati dinamici nel primo messaggio `user` dopo il tuo breakpoint di cache.
`tools_changed`	L'array `tools` differisce: gli strumenti sono stati aggiunti, rimossi o riordinati tra i turni, oppure il JSON di `input_schema` dello strumento è stato serializzato in modo non deterministico.	Invia la stessa lista di strumenti a ogni turno in un ordine fisso con schemi serializzati in modo deterministico (ad esempio, ordina le chiavi).
`messages_changed`	Il modello, il sistema e gli strumenti corrispondono tutti, ma una voce precedente in `messages` è stata alterata, riordinata o rimossa anziché essere oggetto di un'aggiunta in coda. Tipicamente la cronologia della conversazione è stata troncata o modificata, oppure i turni dell'assistente e i blocchi `tool_result` sono stati ri-serializzati in modo diverso al reinvio.	Tratta la cronologia come append-only; restituisci il `content` dell'assistente e i risultati degli strumenti alla lettera.
`previous_message_not_found`	Non esiste alcun fingerprint memorizzato per il `previous_message_id` fornito. Questa non è una prova che la tua richiesta sia cambiata. Tipicamente la richiesta precedente non conteneva il beta header, proveniva da un workspace diverso, oppure è passato troppo tempo da quando è stata inviata.	Invia il beta header a ogni turno e mantieni i turni consecutivi ravvicinati nel tempo.
`unavailable`	Le informazioni diagnostiche non erano disponibili per questa richiesta. Questo include il caso in cui `model`, `system` e `tools` corrispondono ma un altro parametro della richiesta che influisce sul prompt (`tool_choice`, `thinking`, `context_management`, `output_config`, `output_format`, o l'insieme degli header `anthropic-beta` attivi) differisce, e le conversazioni molto lunghe in cui la divergenza è oltre l'orizzonte di confronto. La tua richiesta è stata elaborata normalmente.	Mantieni costanti i parametri della richiesta che influiscono sul prompt per tutta la durata di una conversazione in cache. Se persiste, applica i controlli manuali descritti in Risoluzione dei problemi comuni nella pagina della cache dei prompt.

I quattro tipi *_changed contengono anche un intero cache_missed_input_tokens: una stima di quanti token di input sono caduti dopo il punto di divergenza, che ti dà un'idea di quanto prefisso memorizzabile in cache è andato perso. È derivato dalle lunghezze in byte prima della tokenizzazione, quindi trattalo come un indicatore di grandezza piuttosto che come un numero di fatturazione. Può differire da (e occasionalmente superare) usage.input_tokens.

Leggere la diagnostica insieme a usage

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).

Risultato della diagnostica	Token letti dalla cache	Interpretazione
`null`	alto	Funziona come previsto. Il tuo prefisso è stabile e la cache ha avuto un hit.
`null`	basso o zero	Le tue richieste corrispondono ma la voce della cache non era più disponibile. Considera di ridurre gli intervalli tra i turni o di usare il TTL della cache di 1 ora.
`cache_miss_reason` è un tipo `*_changed`	basso o zero	Bug tuo. La richiesta è cambiata; correggi la causa indicata da `type`.
`cache_miss_reason` è un tipo `*_changed`	alto	Raro. Una modifica è avvenuta tardi nel prompt ma un breakpoint `cache_control` precedente ha comunque avuto un hit. Vale la pena correggerlo, ma ha un impatto basso.

Limitazioni

Beta: I nomi dei campi e la semantica potrebbero cambiare prima della disponibilità generale.
Solo Claude API: Non disponibile su Amazon Bedrock o Google Cloud.
Conservazione limitata: I fingerprint 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 effettuata con una chiave API della stessa organizzazione e dello stesso workspace.
Orizzonte di confronto: Per conversazioni molto lunghe in cui l'unica modifica è in profondità nella lista dei messaggi, la risposta potrebbe essere unavailable anziché una posizione precisa.
Best-effort: La diagnostica non blocca né fa mai fallire 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 funzionalità.

Il fingerprint memorizzato per ogni richiesta consiste solo di hash crittografici e stime del conteggio dei token, indicizzato dall'id della risposta e limitato alla tua organizzazione e al tuo workspace. I fingerprint scadono dopo un breve periodo e non vengono utilizzati per nessun altro scopo.

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

Vedi anche

Was this page helpful?

MessagesGestione del contesto

Diagnostica della cache

Diagnostica i cache miss imprevisti dei prompt confrontando richieste consecutive e identificando esattamente dove il prefisso del prompt è divergente.

Per sapere come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta API e conservazione dei dati.

La diagnostica della cache è in beta. Includi il beta header cache-diagnosis-2026-04-07 nelle tue richieste API per usare questa funzionalità.

La diagnostica della cache è attualmente disponibile solo sulla Claude API. Non è supportata su Amazon Bedrock o Google Cloud.

Come funziona la diagnostica della cache

Utilizzo di base

client = anthropic.Anthropic()

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

# Turno 1: attiva la funzionalità 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 contiene il campo diagnostics completo; consulta Formato della risposta per i valori possibili.

Propagare la diagnostica attraverso un ciclo di conversazione

Questo flusso di lavoro non si traduce bene in un comando shell una tantum. Consulta le schede degli SDK per il pattern del ciclo; la richiesta HTTP per turno è identica a Utilizzo di base.

Formato della risposta

Il campo diagnostics sul Message della risposta ha quattro stati possibili:

Valore	Significato
campo assente	La richiesta non includeva `diagnostics`, oppure il beta header era mancante.
`null`	O `previous_message_id` era `null` (primo turno, niente da confrontare), oppure è stato eseguito un confronto e non è stata trovata alcuna divergenza.
`{"cache_miss_reason": null}`	Il confronto era ancora in esecuzione quando la risposta è stata serializzata. Questo può accadere quando la risposta inizia molto rapidamente. Trattalo come non conclusivo e controlla il turno successivo.
`{"cache_miss_reason": {...}}`	È allegato un `cache_miss_reason`. Per i tipi `*_changed` questo identifica il primo punto di divergenza; `previous_message_not_found` e `unavailable` sono casi in cui non è stato prodotto alcun confronto.

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 motivi di cache miss

Tipo	Cosa significa	Cosa cambiare
`model_changed`	Il `model` differisce dalla richiesta precedente (ad esempio, un router, un test A/B o un fallback ha selezionato un modello diverso). La cache è per modello.	Mantieni il modello costante all'interno di una conversazione in cache.
`system_changed`	Il parametro `system` differisce. Tipicamente un timestamp, un ID di richiesta o un altro valore per richiesta è stato interpolato nel prompt di sistema.	Rendi il prompt di sistema una costante stabile a livello di byte e sposta i dati dinamici nel primo messaggio `user` dopo il tuo breakpoint di cache.
`tools_changed`	L'array `tools` differisce: gli strumenti sono stati aggiunti, rimossi o riordinati tra i turni, oppure il JSON di `input_schema` dello strumento è stato serializzato in modo non deterministico.	Invia la stessa lista di strumenti a ogni turno in un ordine fisso con schemi serializzati in modo deterministico (ad esempio, ordina le chiavi).
`messages_changed`	Il modello, il sistema e gli strumenti corrispondono tutti, ma una voce precedente in `messages` è stata alterata, riordinata o rimossa anziché essere oggetto di un'aggiunta in coda. Tipicamente la cronologia della conversazione è stata troncata o modificata, oppure i turni dell'assistente e i blocchi `tool_result` sono stati ri-serializzati in modo diverso al reinvio.	Tratta la cronologia come append-only; restituisci il `content` dell'assistente e i risultati degli strumenti alla lettera.
`previous_message_not_found`	Non esiste alcun fingerprint memorizzato per il `previous_message_id` fornito. Questa non è una prova che la tua richiesta sia cambiata. Tipicamente la richiesta precedente non conteneva il beta header, proveniva da un workspace diverso, oppure è passato troppo tempo da quando è stata inviata.	Invia il beta header a ogni turno e mantieni i turni consecutivi ravvicinati nel tempo.
`unavailable`	Le informazioni diagnostiche non erano disponibili per questa richiesta. Questo include il caso in cui `model`, `system` e `tools` corrispondono ma un altro parametro della richiesta che influisce sul prompt (`tool_choice`, `thinking`, `context_management`, `output_config`, `output_format`, o l'insieme degli header `anthropic-beta` attivi) differisce, e le conversazioni molto lunghe in cui la divergenza è oltre l'orizzonte di confronto. La tua richiesta è stata elaborata normalmente.	Mantieni costanti i parametri della richiesta che influiscono sul prompt per tutta la durata di una conversazione in cache. Se persiste, applica i controlli manuali descritti in Risoluzione dei problemi comuni nella pagina della cache dei prompt.

Leggere la diagnostica insieme a usage

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.

Risultato della diagnostica	Token letti dalla cache	Interpretazione
`null`	alto	Funziona come previsto. Il tuo prefisso è stabile e la cache ha avuto un hit.
`null`	basso o zero	Le tue richieste corrispondono ma la voce della cache non era più disponibile. Considera di ridurre gli intervalli tra i turni o di usare il TTL della cache di 1 ora.
`cache_miss_reason` è un tipo `*_changed`	basso o zero	Bug tuo. La richiesta è cambiata; correggi la causa indicata da `type`.
`cache_miss_reason` è un tipo `*_changed`	alto	Raro. Una modifica è avvenuta tardi nel prompt ma un breakpoint `cache_control` precedente ha comunque avuto un hit. Vale la pena correggerlo, ma ha un impatto basso.

Limitazioni

Beta: I nomi dei campi e la semantica potrebbero cambiare prima della disponibilità generale.
Solo Claude API: Non disponibile su Amazon Bedrock o Google Cloud.
Conservazione limitata: I fingerprint 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 effettuata con una chiave API della stessa organizzazione e dello stesso workspace.
Orizzonte di confronto: Per conversazioni molto lunghe in cui l'unica modifica è in profondità nella lista dei messaggi, la risposta potrebbe essere unavailable anziché una posizione precisa.
Best-effort: La diagnostica non blocca né fa mai fallire 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 funzionalità.

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

Vedi anche

Was this page helpful?

Come funziona la diagnostica della cache

Utilizzo di base

Streaming

Propagare la diagnostica attraverso un ciclo di conversazione

Formato della risposta

Tipi di motivi di cache miss

Leggere la diagnostica insieme a usage

Limitazioni

Conservazione dei dati

Vedi anche

Come funziona la diagnostica della cache

Utilizzo di base

Streaming

Propagare la diagnostica attraverso un ciclo di conversazione

Formato della risposta

Tipi di motivi di cache miss

Leggere la diagnostica insieme a usage

Limitazioni

Conservazione dei dati

Vedi anche

Come funziona la diagnostica della cache

Utilizzo di base

Streaming

Propagare la diagnostica attraverso un ciclo di conversazione

Formato della risposta

Tipi di motivi di cache miss

Leggere la diagnostica insieme a usage

Limitazioni

Conservazione dei dati

Vedi anche

Come funziona la diagnostica della cache

Utilizzo di base

Streaming

Propagare la diagnostica attraverso un ciclo di conversazione

Formato della risposta

Tipi di motivi di cache miss

Leggere la diagnostica insieme a usage

Limitazioni

Conservazione dei dati

Vedi anche