MessaggiGestione del contesto

Diagnostica della cache

Diagnostica i cache miss inattesi dei prompt confrontando richieste consecutive e identificando esattamente dove il prefisso del prompt ha iniziato a divergere.

Questa funzionalità è idonea per la Zero Data Retention (ZDR) con conservazione tecnica limitata. Consulta la sezione Conservazione dei dati per i dettagli su cosa viene conservato e perché.

La cache dei prompt riduce significativamente la "latency" (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 indica dove hanno iniziato a divergere (il modello, il prompt di sistema, gli strumenti o la cronologia dei messaggi), così puoi 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 utilizzare questa funzionalità.

La diagnostica della cache è attualmente disponibile solo sull'API di Claude. Non è supportata su Amazon Bedrock o Vertex AI.

Come funziona la diagnostica della cache

Quando il beta header è presente, l'API memorizza un fingerprint leggero di ogni richiesta, indicizzato dall'id della risposta. Nella 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 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 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 effettuare il confronto. 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 l'opzione con previous_message_id=None
r1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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-4-8",
    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: esegui lo streaming, facendo riferimento all'id della risposta precedente
with client.beta.messages.stream(
    model="claude-opus-4-8",
    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 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.

Formato della risposta

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

Valore	Significato
campo assente	La richiesta non includeva `diagnostics`, oppure mancava il beta header.
`null`	O `previous_message_id` era `null` (primo turno, niente da confrontare), oppure è stato eseguito un confronto che non ha trovato divergenze.
`{"cache_miss_reason": null}`	Il confronto era ancora in esecuzione quando la risposta è stata serializzata. Questo può accadere quando la risposta inizia molto rapidamente. Consideralo come inconcludente 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, ha questo aspetto:

{
  "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 cache miss reason

cache_miss_reason è una discriminated union basata 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 modificare
`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 costante il modello 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: strumenti sono stati aggiunti, rimossi o riordinati tra i turni, oppure il JSON di `input_schema` degli strumenti è 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 system e i tools corrispondono tutti, ma una voce precedente in `messages` è stata alterata, riordinata o rimossa invece di essere 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; rimanda indietro il `content` dell'assistente e i risultati degli strumenti in modo letterale.
`previous_message_not_found`	Non esiste alcun fingerprint memorizzato per il `previous_message_id` fornito. Questo non è una prova che la tua richiesta sia cambiata. Tipicamente la richiesta precedente non includeva 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 di richiesta che influenza il prompt (`tool_choice`, `thinking`, `context_management`, `output_config`, `output_format` o l'insieme di header `anthropic-beta` attivi) differisce, e conversazioni molto lunghe in cui la divergenza è oltre l'orizzonte di confronto. La tua richiesta è stata elaborata normalmente.	Mantieni costanti i parametri di richiesta che influenzano il prompt per tutta la durata di una conversazione in cache. Se il problema persiste, applica i controlli manuali descritti in Risoluzione dei problemi comuni nella pagina sulla cache dei prompt.

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

Leggere la diagnostica insieme a usage

diagnostics risponde alla domanda "la mia richiesta è cambiata?" mentre usage.cache_read_input_tokens risponde a "la cache ha avuto un hit?". Combinarli ti indica 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 non si applica nemmeno 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 di cache non era più disponibile. Considera di ridurre gli intervalli tra i turni o di usare il TTL di cache di 1 ora.
`cache_miss_reason` è un tipo `*_changed`	basso o zero	Il tuo bug. La richiesta è cambiata; correggi la causa indicata da `type`.
`cache_miss_reason` è un tipo `*_changed`	alto	Raro. Si è verificata una modifica in un punto avanzato del prompt ma un breakpoint `cache_control` precedente ha comunque avuto un hit. Vale la pena correggerlo, ma l'impatto è basso.

Limitazioni

Beta: I nomi dei campi e la semantica potrebbero cambiare prima della disponibilità generale.
Solo API di Claude: Non disponibile su Amazon Bedrock o Vertex AI.
Conservazione limitata: I fingerprint per la ricerca di previous_message_id scadono dopo un breve periodo. Esegui 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 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 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 su tutte le funzionalità, consulta API e conservazione dei dati.

Vedi anche

Was this page helpful?

MessaggiGestione del contesto

Diagnostica della cache

Diagnostica i cache miss inattesi dei prompt confrontando richieste consecutive e identificando esattamente dove il prefisso del prompt ha iniziato a divergere.

Questa funzionalità è idonea per la Zero Data Retention (ZDR) con conservazione tecnica limitata. Consulta la sezione Conservazione dei dati per i dettagli su cosa viene conservato e perché.

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

La diagnostica della cache è attualmente disponibile solo sull'API di Claude. Non è supportata su Amazon Bedrock o Vertex AI.

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 l'opzione con previous_message_id=None
r1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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-4-8",
    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: esegui lo streaming, facendo riferimento all'id della risposta precedente
with client.beta.messages.stream(
    model="claude-opus-4-8",
    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

Formato della risposta

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

Valore	Significato
campo assente	La richiesta non includeva `diagnostics`, oppure mancava il beta header.
`null`	O `previous_message_id` era `null` (primo turno, niente da confrontare), oppure è stato eseguito un confronto che non ha trovato divergenze.
`{"cache_miss_reason": null}`	Il confronto era ancora in esecuzione quando la risposta è stata serializzata. Questo può accadere quando la risposta inizia molto rapidamente. Consideralo come inconcludente 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, ha questo aspetto:

{
  "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 cache miss reason

Tipo	Cosa significa	Cosa modificare
`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 costante il modello 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: strumenti sono stati aggiunti, rimossi o riordinati tra i turni, oppure il JSON di `input_schema` degli strumenti è 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 system e i tools corrispondono tutti, ma una voce precedente in `messages` è stata alterata, riordinata o rimossa invece di essere 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; rimanda indietro il `content` dell'assistente e i risultati degli strumenti in modo letterale.
`previous_message_not_found`	Non esiste alcun fingerprint memorizzato per il `previous_message_id` fornito. Questo non è una prova che la tua richiesta sia cambiata. Tipicamente la richiesta precedente non includeva 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 di richiesta che influenza il prompt (`tool_choice`, `thinking`, `context_management`, `output_config`, `output_format` o l'insieme di header `anthropic-beta` attivi) differisce, e conversazioni molto lunghe in cui la divergenza è oltre l'orizzonte di confronto. La tua richiesta è stata elaborata normalmente.	Mantieni costanti i parametri di richiesta che influenzano il prompt per tutta la durata di una conversazione in cache. Se il problema persiste, applica i controlli manuali descritti in Risoluzione dei problemi comuni nella pagina sulla cache dei prompt.

Leggere la diagnostica insieme a usage

diagnostics risponde alla domanda "la mia richiesta è cambiata?" mentre usage.cache_read_input_tokens risponde a "la cache ha avuto un hit?". Combinarli ti indica 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 di cache non era più disponibile. Considera di ridurre gli intervalli tra i turni o di usare il TTL di cache di 1 ora.
`cache_miss_reason` è un tipo `*_changed`	basso o zero	Il tuo bug. La richiesta è cambiata; correggi la causa indicata da `type`.
`cache_miss_reason` è un tipo `*_changed`	alto	Raro. Si è verificata una modifica in un punto avanzato del prompt ma un breakpoint `cache_control` precedente ha comunque avuto un hit. Vale la pena correggerlo, ma l'impatto è basso.

Limitazioni

Beta: I nomi dei campi e la semantica potrebbero cambiare prima della disponibilità generale.
Solo API di Claude: Non disponibile su Amazon Bedrock o Vertex AI.
Conservazione limitata: I fingerprint per la ricerca di previous_message_id scadono dopo un breve periodo. Esegui 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 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 funzionalità.

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

Vedi anche

Was this page helpful?