Diagnostics du cache

La mise en cache des prompts (« prompt caching ») réduit considérablement la latence et les coûts, mais uniquement lorsque le début de votre prompt est identique octet pour octet à une requête récente. Un outil réordonné, un horodatage interpolé dans votre invite système (« system prompt ») ou une modification d'un message antérieur peuvent invalider silencieusement le cache. Sans les diagnostics du cache, le seul signal est la chute de usage.cache_read_input_tokens à zéro, sans aucune indication de ce qui a changé.

Les diagnostics du cache comblent cette lacune. Transmettez l'id de votre réponse précédente, et l'API compare les deux requêtes et vous indique où elles ont divergé (le modèle, l'invite système, les outils ou l'historique des messages) afin que vous puissiez corriger la cause première au lieu de deviner.

Fonctionnement des diagnostics du cache

Lorsque l'en-tête bêta est présent, l'API stocke une empreinte (« fingerprint ») légère de chaque requête, indexée par l'id de la réponse. Lors de votre requête suivante, incluez cet id en tant que diagnostics.previous_message_id. L'API reconstruit l'empreinte de la nouvelle requête, la compare à celle stockée et joint à la réponse un objet diagnostics décrivant le premier point de divergence.

La comparaison porte sur la structure de la requête, indépendamment du fait que le cache ait effectivement été atteint ou non. Consultez Lire les diagnostics conjointement avec l'utilisation pour savoir comment combiner le résultat diagnostics avec usage.cache_read_input_tokens.

Les empreintes ne contiennent que des hachages et des estimations du nombre de jetons (jamais le contenu brut du prompt), sont conservées pendant une durée limitée, sont restreintes à votre organisation et à votre espace de travail, et ne sont utilisées à aucune autre fin.

Utilisation de base

Envoyez l'en-tête bêta à chaque tour. Au premier tour, transmettez "previous_message_id": null pour activer la fonctionnalité sans message antérieur auquel comparer. Aux tours suivants, transmettez l'id de la réponse précédente.

client = anthropic.Anthropic()

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

# Tour 1 : activer avec 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"],
)

# Tour 2 : référencer l'id de la réponse précédente
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

Dans les réponses en streaming, diagnostics apparaît dans l'événement message_start.

# Tour 2 : streaming, en référençant l'id de la réponse précédente
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'événement message_start contient le champ diagnostics complet ; consultez Format de la réponse pour connaître les valeurs possibles.

Propager les diagnostics dans une boucle de conversation

Dans une conversation à plusieurs tours, reportez le dernier id de réponse en tant que previous_message_id à chaque tour. La première itération transmet null pour activer la fonctionnalité ; chaque itération suivante transmet l'id de la réponse précédente.

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

Format de la réponse

Le champ diagnostics de l'objet Message de la réponse peut prendre quatre états :

Lorsque cache_miss_reason est non nul, il se présente ainsi :

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

Types de raisons d'échec du cache

cache_miss_reason est une union discriminée sur type. La réponse ne signale que la divergence la plus précoce ; corrigez-la donc en premier, car des divergences ultérieures peuvent se cacher derrière elle.

Lire les diagnostics conjointement avec l'utilisation

diagnostics répond à la question « ma requête a-t-elle changé ? » tandis que usage.cache_read_input_tokens répond à la question « le cache a-t-il été atteint ? ». Les combiner vous indique où chercher.

Cette matrice s'applique aux tours où vous avez transmis un véritable previous_message_id. Au premier tour (previous_message_id: null), diagnostics vaut toujours null et cache_read_input_tokens est normalement nul, car le cache est en cours d'écriture et non de lecture ; aucun dépannage n'est nécessaire. La matrice ne s'applique pas non plus lorsque cache_miss_reason vaut null (la comparaison est encore en attente ; vérifiez au tour suivant) ni lorsque son type est previous_message_not_found ou unavailable (aucune comparaison n'a été produite).

Limitations

• Bêta : les noms de champs et leur sémantique peuvent changer tant que cette fonctionnalité est en bêta.
• Claude API uniquement : non disponible sur Amazon Bedrock ni sur Google Cloud.
• Conservation limitée : les empreintes utilisées pour la recherche par previous_message_id expirent après une courte période. Effectuez les comparaisons de diagnostic entre des requêtes rapprochées dans le temps.
• Même espace de travail : la requête précédente doit avoir été exécutée dans la même organisation et le même espace de travail. Pour le vérifier, comparez l'en-tête de réponse anthropic-workspace-id des deux réponses.
• Horizon de comparaison : pour les conversations très longues où le seul changement se situe profondément dans la liste des messages, la réponse peut être unavailable plutôt qu'un emplacement précis.
• Au mieux : les diagnostics ne bloquent ni ne font jamais échouer votre requête. Si les informations de diagnostic ne sont pas disponibles, la réponse renvoie unavailable, ou cache_miss_reason: null lorsque la comparaison était encore en cours.

Conservation des données

Les diagnostics du cache sont éligibles au ZDR (sous conditions). Anthropic ne stocke pas le texte brut de vos prompts ni les sorties de Claude pour cette fonctionnalité.

L'empreinte stockée pour chaque requête se compose uniquement de hachages cryptographiques et d'estimations du nombre de jetons, indexés par l'id de la réponse et restreints à votre organisation et à votre espace de travail. Les empreintes expirent après une courte période et ne sont utilisées à aucune autre fin.

Pour connaître l'éligibilité au ZDR de l'ensemble des fonctionnalités, consultez API et conservation des données.

Voir aussi

• Mise en cache des prompts
• Comptage des jetons
• En-têtes bêta

Compatibility