Diagnóstico de caché

El almacenamiento en caché de prompts reduce significativamente la latencia y el costo, pero solo cuando el comienzo de tu prompt es idéntico byte por byte a una solicitud reciente. Una herramienta reordenada, una marca de tiempo interpolada en tu indicación del sistema o una edición a un mensaje anterior pueden invalidar silenciosamente la caché. Sin el diagnóstico de caché, la única señal es que usage.cache_read_input_tokens cae a cero, sin ninguna indicación de qué cambió.

El diagnóstico de caché cierra esa brecha. Pasa el id de tu respuesta anterior, y la API compara las dos solicitudes y te dice dónde divergieron (el modelo, la indicación del sistema, las herramientas o el historial de mensajes) para que puedas corregir la causa raíz en lugar de adivinar.



Cómo funciona el diagnóstico de caché

Cuando el encabezado beta está presente, la API almacena una huella digital ligera de cada solicitud, indexada por el id de la respuesta. En tu siguiente solicitud, incluye ese id como diagnostics.previous_message_id. La API reconstruye la huella digital para la nueva solicitud, la compara con la almacenada y adjunta un objeto diagnostics a la respuesta describiendo el primer punto de divergencia.

La comparación se refiere a la estructura de la solicitud, independientemente de si la caché realmente acertó. Consulta Leer el diagnóstico junto con usage para saber cómo combinar el resultado de diagnostics con usage.cache_read_input_tokens.

Las huellas digitales contienen solo hashes y estimaciones de conteo de tokens (nunca contenido sin procesar del prompt), se retienen por un tiempo limitado, están limitadas a tu organización y espacio de trabajo, y no se usan para ningún otro propósito.



Uso básico

Envía el encabezado beta en cada turno. En el primer turno, pasa "previous_message_id": null para optar por la función sin un mensaje previo con el cual comparar. En los turnos siguientes, pasa el id de la respuesta anterior.

client = anthropic.Anthropic()

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

# Turno 1: activar 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: referenciar el id de la respuesta anterior
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

En las respuestas de streaming, diagnostics aparece en el evento message_start.

# Turno 2: streaming, haciendo referencia al id de la respuesta anterior
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}")

El evento message_start lleva el campo diagnostics completo; consulta Formato de respuesta para ver los valores posibles.



Encadenar el diagnóstico a través de un bucle de conversación

En una conversación de múltiples turnos, lleva el id de la respuesta más reciente hacia adelante como previous_message_id en cada turno. La primera iteración pasa null para optar por la función; cada iteración subsiguiente pasa el id de la respuesta anterior.



Formato de respuesta

El campo diagnostics en el Message de la respuesta tiene cuatro estados posibles:

Cuando cache_miss_reason no es null, se ve así:

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



Tipos de razón de fallo de caché

cache_miss_reason es una unión discriminada por type. La respuesta reporta solo la divergencia más temprana, así que corrígela primero; las posteriores pueden estar ocultas detrás de ella.



Leer el diagnóstico junto con usage

diagnostics responde "¿cambió mi solicitud?" mientras que usage.cache_read_input_tokens responde "¿acertó la caché?". Combinarlos te dice dónde buscar.

Esta matriz se aplica a los turnos donde pasaste un previous_message_id real. En el primer turno (previous_message_id: null), diagnostics siempre es null y cache_read_input_tokens normalmente es cero porque la caché se está escribiendo, no leyendo; no se necesita ninguna solución de problemas. La matriz tampoco se aplica cuando cache_miss_reason es null (la comparación todavía está pendiente; verifica el siguiente turno) o cuando su type es previous_message_not_found o unavailable (no se produjo ninguna comparación).



Limitaciones

• Beta: Los nombres de los campos y la semántica pueden cambiar antes de la disponibilidad general.
• Solo API de Claude: No está disponible en Amazon Bedrock ni Google Cloud.
• Retención limitada: Las huellas digitales para la búsqueda de previous_message_id expiran después de un período corto. Ejecuta comparaciones de diagnóstico entre solicitudes cercanas en el tiempo.
• Mismo espacio de trabajo: La solicitud anterior debe haberse realizado con una clave de API de la misma organización y espacio de trabajo.
• Horizonte de comparación: Para conversaciones muy largas donde el único cambio está profundo en la lista de mensajes, la respuesta puede ser unavailable en lugar de una ubicación precisa.
• Mejor esfuerzo: El diagnóstico nunca bloquea ni hace fallar tu solicitud. Si la información de diagnóstico no está disponible, la respuesta devuelve unavailable, o cache_miss_reason: null cuando la comparación todavía se estaba ejecutando.



Retención de datos

El diagnóstico de caché es elegible para ZDR (calificado). Anthropic no almacena el texto sin procesar de tus prompts ni las salidas de Claude para esta función.

La huella digital almacenada para cada solicitud consiste únicamente en hashes criptográficos y estimaciones de conteo de tokens, indexada por el id de la respuesta y limitada a tu organización y espacio de trabajo. Las huellas digitales expiran después de un período corto y no se usan para ningún otro propósito.

Para la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos.



Ver también

• Almacenamiento en caché de prompts
• Conteo de tokens
• Encabezados beta