Cómo funciona realmente la coincidencia de prefijos del almacenamiento en caché de indicaciones

El almacenamiento en caché de indicaciones permite a Claude reutilizar un prefijo procesado previamente de una indicación en lugar de procesarlo desde cero en cada solicitud.

Eso suena simple, pero el mecanismo detrás de él, una coincidencia de prefijo exacta, tiene bordes afilados que tropiezan a casi todos los equipos la primera vez que lo configuran.

Comprender el modelo de coincidencia de prefijos es la diferencia entre obtener de manera confiable aciertos de caché que valen hasta un 90% de reducción de costos y un 85% de reducción de latencia, y pagar silenciosamente el precio completo creyendo que el almacenamiento en caché está funcionando.

Resumen

Idea Central: Claude almacena en caché una indicación como una secuencia ordenada de bytes, y un acierto de caché solo ocurre cuando el prefijo de una nueva solicitud es idéntico byte por byte a un prefijo previamente almacenado en caché, hasta un punto de interrupción marcado.
Por qué importa: Cualquier cambio anterior en ese prefijo, incluso un carácter, invalida la caché para todo lo que viene después, convirtiendo silenciosamente una solicitud en caché barata en una de precio completo.
Conceptos Clave: prefijo, punto de interrupción de caché, cache_control, coincidencia exacta, escritura en caché frente a lectura de caché.
Cuándo usar: Cualquier carga de trabajo que reenvíe un bloque de contenido grande y mayormente estable (una indicación del sistema larga, definiciones de herramientas o documentos de referencia) a través de muchas solicitudes.
Limitaciones / Compensaciones: La caché no es semántica; no sabe que dos indicaciones "significan" lo mismo, solo si sus bytes coinciden.
Temas relacionados: TTL y precios de la caché, colocación del punto de interrupción de la caché, verificación de aciertos de caché a través de campos de uso.

Fundamentos

Un prefijo es la porción inicial del contenido de una solicitud, leída en el orden en que Claude la recibe: primero las definiciones de herramientas, luego la indicación del sistema, luego la matriz de mensajes.

Un punto de interrupción de caché es un marcador que coloca en un bloque específico de contenido usando un campo cache_control.

Todo, desde el inicio de la solicitud hasta ese punto de interrupción, incluido, es elegible para ser almacenado y reutilizado como un prefijo en caché.

Piénselo como una fotocopiadora que recuerda las primeras N páginas del último documento que copió.

Si le entrega un nuevo documento cuyas primeras N páginas son idénticas, reutiliza las páginas memorizadas y solo procesa las nuevas páginas a partir de ese punto.

Si incluso una palabra en la página 3 difiere, la fotocopiadora tiene que empezar de nuevo desde la página 3, sin memorizar nada de la copia que hizo antes.

Aquí está el ejemplo más pequeño de marcar un punto de interrupción en una indicación del sistema:

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Eres un asistente de soporte para Acme Corp. " * 200,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "¿Cuál es su política de devoluciones?"}],
)

El bloque cache_control en ese texto del sistema le dice a Claude: todo hasta este bloque, incluido, es un candidato para el almacenamiento en caché.

Mecánica e Interacciones

La coincidencia es exacta y posicional, no aproximada ni consciente del contenido.

Claude compara el prefijo de la solicitud entrante, byte por byte, con lo que ha almacenado en caché de una solicitud anterior dentro de la ventana de TTL de la caché.

Si los bytes coinciden hasta el punto de interrupción, es un acierto de caché: esos tokens se leen de la caché en lugar de reprocesarse, lo que es más barato y rápido.

Si los bytes divergen en algún punto antes del punto de interrupción, es un fallo de caché para todo el prefijo, no solo para la parte que cambió: todo el segmento hasta el punto de interrupción se reprocesa y se reescribe en la caché.

Esta es la consecuencia más importante del modelo: el almacenamiento en caché es todo o nada para el prefijo, no un diferencial de crédito parcial.

Prefijo en caché (de una solicitud anterior):
  [def. herramientas] [indicación del sistema] [punto de interrupción]
       |                  |
   idéntico           idéntico    -> ACIERTO DE CACHÉ, todo hasta el punto de interrupción se lee de la caché
 
Nueva solicitud, un campo en las def. de herramientas cambió:
  [def. herramientas*] [indicación del sistema] [punto de interrupción]
       |
   difiere aquí -> FALLO DE CACHÉ para todo el prefijo, reprocesado y reescrito

Dos campos de respuesta le indican cuál de estos ocurrió: usage.cache_read_input_tokens se rellena en un acierto, y usage.cache_creation_input_tokens se rellena cuando la solicitud escribe una entrada nueva (o actualizada) en la caché.

Una sola solicitud puede mostrar ambos valores distintos de cero, si parte del prefijo coincidió con una entrada de caché existente y un punto de interrupción posterior más grande escribió una nueva.

El orden de las solicitudes también importa mecánicamente: la API construye el prefijo efectivo a partir de las herramientas, luego el sistema, luego los mensajes, en ese orden fijo, por lo que un punto de interrupción en las definiciones de herramientas cubre un prefijo más corto y anterior que un punto de interrupción colocado en la indicación del sistema.

Consideraciones y Aplicaciones Avanzadas

El requisito de coincidencia exacta significa que el contenido antes de cualquier punto de interrupción debe ser determinista entre solicitudes para que el almacenamiento en caché ayude en algo.

Los culpables comunes que rompen silenciosamente la coincidencia: una marca de tiempo incrustada en la indicación del sistema, un UUID con ámbito de solicitud adjuntado a las instrucciones o un objeto JSON serializado con un orden de claves que no se garantiza que sea estable.

Ninguno de estos produce un error (la solicitud aún tiene éxito), pero cada uno de ellos reprocesa silenciosamente el prefijo completo como si el almacenamiento en caché nunca se hubiera configurado, porque los bytes ya no coinciden.

Enfoque	Fortaleza	Debilidad	Mejor ajuste
Punto de interrupción único al final de la indicación del sistema	Simple, una línea para agregar	Cualquier cambio en cualquier lugar del sistema o herramientas invalida todo	Indicación del sistema estable sin contenido volátil
Puntos de interrupción en herramientas y sistema por separado	Aísla los cambios del esquema de herramientas de los cambios de la indicación del sistema	Un poco más de contabilidad en el generador de solicitudes	Grandes catálogos de herramientas que cambian independientemente de la copia del sistema
Sin `cache_control`	Cero riesgo de errores de contenido obsoleto	Ningún beneficio de costo o latencia	Indicaciones que ya son cortas o cambian en cada llamada

Dado que la coincidencia es posicional, mover un bloque de contenido estable después de uno volátil (en lugar de antes) suele ser la solución: coloque documentos de referencia, esquemas de herramientas e instrucciones primero, y coloque cualquier cosa que cambie por solicitud (la pregunta real del usuario, un ID de sesión, "hora actual") después del punto de interrupción, en la matriz de mensajes donde pertenece.

Ese reordenamiento por sí solo resuelve la mayoría de los errores de invalidación de caché del mundo real sin eliminar ningún contenido de la indicación.

Conceptos erróneos comunes

"El almacenamiento en caché de indicaciones entiende lo que significa mi indicación." No lo hace: la coincidencia es puramente a nivel de bytes. Dos indicaciones que son semánticamente idénticas pero difieren en espacios en blanco, orden de claves o un solo carácter se tratan como prefijos completamente diferentes.
"Un fallo de caché significa que algo está roto." Un fallo solo significa que los bytes no coincidieron esta vez: podría ser la primera solicitud, una TTL caducada o contenido genuinamente diferente. Es un comportamiento esperado, no un estado de error.
"Solo mi indicación del sistema afecta la caché." Las definiciones de herramientas vienen antes de la indicación del sistema en el prefijo efectivo; un esquema de herramientas que cambia entre solicitudes invalida la caché tanto como editar la indicación del sistema.
"Si parte de mi indicación cambió, todavía obtengo crédito por la parte que no lo hizo." Obtiene crédito hasta el punto de interrupción inmediatamente anterior al cambio, pero nada cambia el hecho de que todo, desde el punto de divergencia hasta ese punto de interrupción, se reprocesa como nuevo.

Preguntas frecuentes

¿Qué cuenta exactamente como "el prefijo" en una solicitud de API de Claude?

El contenido hasta e incluyendo un punto de interrupción cache_control marcado, construido en un orden fijo: primero las definiciones de herramientas, luego la indicación del sistema, luego la matriz de mensajes.

¿El almacenamiento en caché de indicaciones utiliza algún tipo de coincidencia semántica o aproximada?

No. Es una coincidencia exacta byte por byte contra un prefijo previamente almacenado en caché. No hay puntuación de similitud ni paso de normalización.

Si cambia una palabra en mi indicación del sistema, ¿pierdo toda la caché?

Sí, para todo, desde esa palabra hasta el siguiente punto de interrupción. El prefijo hasta el punto de cambio se reprocesa y se reescribe en la caché; nada después del punto de cambio puede acceder a la entrada antigua.

¿Las definiciones de herramientas afectan el almacenamiento en caché de indicaciones?

Sí. Las herramientas forman parte del prefijo efectivo y vienen antes de la indicación del sistema, por lo que un esquema de herramientas cambiante invalida la caché incluso si el texto de su indicación del sistema nunca cambia.

¿Cómo sé si una solicitud fue un acierto de caché o un fallo de caché?

Compruebe el objeto usage de la respuesta. cache_read_input_tokens es distinto de cero en un acierto; cache_creation_input_tokens es distinto de cero cuando la solicitud escribe una nueva entrada de caché.

¿Puede una sola solicitud ser tanto un acierto de caché como una escritura en caché?

Sí. Si parte del prefijo coincidió con una entrada existente y un punto de interrupción posterior cubre contenido que aún no estaba en caché, puede ver tanto cache_read_input_tokens como cache_creation_input_tokens rellenados en la misma respuesta.

¿Cuáles son las cosas comunes que rompen silenciosamente la coincidencia de prefijos?

Una marca de tiempo o una cadena de "fecha actual" incrustada en la indicación del sistema
Un UUID por solicitud o ID de sesión colocado antes del punto de interrupción
Contenido JSON serializado con orden de claves no determinista
Cualquier texto dinámico específico del usuario colocado antes del bloque en caché en lugar de después

¿Un fallo de caché produce un error?

No. La solicitud aún se completa normalmente; simplemente se procesa y se factura como si el almacenamiento en caché no estuviera en juego para ese prefijo. Es por eso que la invalidación silenciosa es peligrosa: nada le dice que sucedió a menos que verifique los campos de uso.

¿Dónde debe ir el contenido volátil por solicitud en relación con el punto de interrupción?

Después del punto de interrupción, normalmente en la matriz de mensajes, nunca antes. Cualquier cosa que cambie en cada llamada (hora actual, un ID de solicitud, la pregunta activa del usuario) pertenece aguas abajo del prefijo estable y en caché.

¿La caché se comparte entre diferentes claves de API u organizaciones?

No, el almacenamiento en caché está limitado a sus propias solicitudes; no es una caché global compartida entre clientes. Trátelo como una optimización por cuenta, no como un recurso público.

¿Reordenar el contenido de mi indicación alguna vez soluciona un problema de almacenamiento en caché?

A menudo, sí. Si un bloque estable se encuentra después de uno volátil, mover el bloque estable antes (antes del punto de interrupción) y el bloque volátil después (después de él) suele ser suficiente para restaurar aciertos de caché consistentes.

Relacionado

Conceptos básicos del almacenamiento en caché de indicaciones - agregue su primer punto de interrupción cache_control y confirme un acierto.
Colocación de puntos de interrupción cache_control en indicaciones del sistema y herramientas - obtenga el orden correcto de herramientas/sistema/mensajes.
Depuración de invalidadores de caché silenciosos en indicaciones largas - encuentre las marcas de tiempo y UUID que rompen su prefijo.
Verificación de aciertos de caché con cache_read_input_tokens - confirme aciertos en cada respuesta.
Cómo funcionan realmente los precios de los tokens de Claude - vea dónde encajan las lecturas y escrituras de caché en la facturación.

Versiones de la pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.