Prompt caching de Claude: tarifas, objeto de uso y por qué las tasas de aciertos caen detrás de una pasarela

El almacenamiento en caché de prompts es la palanca individual más importante en la factura de un agente y la que más probablemente no funciona sin que nadie lo advierta. Si se marca correctamente, la parte repetida de tu solicitud se factura a una décima parte de la tarifa de entrada. Si se marca incorrectamente —o se dirige a través de algo que reescribe tu prefijo—, se factura por encima de la tarifa normal, porque pagas por escribir entradas de caché que nadie lee.

El mecanismo está bien documentado en otros lugares. Lo que no está documentado en ninguna parte es qué cambia cuando la solicitud pasa por una pasarela, que es la situación de la mayoría de las personas que leen esto. Ambas cosas se explican a continuación.

El mecanismo, brevemente

Marcas un prefijo estable —un prompt del sistema, un esquema de herramientas o un documento— y el proveedor almacena su forma procesada. La siguiente solicitud cuyo prefijo coincida exactamente lo lee en lugar de volver a procesarlo.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

Dos propiedades hacen todo el trabajo y causan todos los problemas. La coincidencia se realiza sobre un prefijo, por lo que cualquier cambio al principio invalida todo lo que viene después. Además, una entrada tiene una vida útil, por lo que una conversación con pausas largas entre turnos se reconstruye en lugar de leerse.

Cuánto cuesta

La tercera columna muestra la proporción estándar: una lectura cuesta una décima parte de la entrada. La cuarta también es estándar: una escritura de caché cuesta 1,25× la entrada, el multiplicador que Anthropic indica para una entrada de cinco minutos; y, como ambas proporciones se aplican al precio de entrada de Kunavo, cada una mantiene el mismo descuento respecto a la tarifa publicada de Anthropic que la entrada del modelo. Donde Kunavo se aparta de Anthropic es en la entrada de una hora: Anthropic indica esa escritura a 2× la entrada, y Kunavo la factura al mismo 1,25×. Esto importa específicamente para las cargas de trabajo que se reconstruyen con frecuencia —agentes de larga duración, conversaciones lentas o cualquier situación en la que cambie el prefijo—, porque son las cargas donde las escrituras, no las lecturas, dominan la línea de caché de la factura.

Ambas cifras se leen del catálogo en tiempo de renderizado, la misma fuente que consultan la tabla de precios y la calculadora de Claude; no hay tarifas introducidas manualmente en esta página.

Lectura del objeto de uso

No deduzcas el comportamiento de la caché a partir de la factura; cada respuesta te lo indica directamente, y los tres recuentos de tokens constituyen todo el diagnóstico.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

Por qué las tasas de aciertos disminuyen detrás de una pasarela

Una caché vive en el upstream que la creó, y la coincidencia del prefijo es exacta. Juntos, esos dos hechos producen tres modos de fallo que nunca ocurren cuando llamas directamente a un único proveedor:

El enrutamiento cambió. Si las solicitudes consecutivas llegan a upstreams distintos, la segunda no encuentra ninguna caché; la entrada que escribió la primera no es visible desde donde se ejecutó la segunda. Esto es invisible en tus propios registros y solo aparece como un recuento de creación de caché que debería haber sido una lectura. Es la causa más común y por eso una pasarela que redirige libremente entre upstreams puede ser más barata por token y más cara por sesión.

Se inyectó algo delante de tu prefijo. Una capa que reescribe el mensaje del sistema, normaliza las definiciones de herramientas o reordena campos produce un prefijo diferente, y un prefijo diferente es un fallo de caché. No se produce ningún error; simplemente aumenta la factura.

La pausa duró más que la entrada. Un agente que tarda varios minutos en pensar entre turnos puede reconstruirlo todo cada vez. Esto es una propiedad de tu carga de trabajo, no de la pasarela, pero interactúa mal con lo primero: una reconstrucción también es una oportunidad de redireccionamiento.

El diagnóstico de los tres casos es el mismo: observa cache_creation_input_tokens a lo largo de una sesión. Un valor grande y plano significa que estás reconstruyendo. Un valor grande una vez y cero después significa que funciona. En Kunavo, el coste a nivel de solicitud y los recuentos de tokens en caché aparecen en la vista de uso, y la referencia sobre caché contiene los detalles a nivel de endpoint.

Qué hacer al respecto

Mantén el prefijo almacenado en caché realmente estable: coloca todo lo que cambie por solicitud después del bloque marcado, nunca antes. Agrupa los turnos de un agente más cerca unos de otros cuando puedas, ya que el tiempo de inactividad es el enemigo de una entrada de corta duración. Y mide una sesión de extremo a extremo en lugar de una solicitud: la caché es una propiedad de una secuencia, y una estimación por solicitud no puede detectarla. La calculadora de costes de tokens de Claude tiene un campo de tokens en caché precisamente por este motivo: configúralo con la fracción de tu prompt que realmente se repite y la cifra mensual dejará de ser ficticia.

Preguntas frecuentes