Skip to main content

Prompt caching: dejá de re-pagar el mismo prefix

El preámbulo estático grande — system prompt, tool defs, ejemplos, un documento de grounding largo — reenviado en cada llamada se reprocesa cada vez, y a volumen de producción eso es una factura que nadie aprobó. El prompt caching lo arregla: marcás un prefix estable con cache_control y las llamadas siguientes reusan el procesamiento del modelo en vez de re-pagarlo. La mecánica — el caching corre en orden sobre tools, después system, después messages, hasta el bloque marcado inclusive, con hasta 4 breakpoints, automáticos o explícitos. La economía dicha con honestidad: un cache read cuesta cerca de 0.1x un token de input base mientras un cache write cuesta más que uno, así que el caching gana sobre un prefix reusado y puede perder en una llamada de una sola vez. Y la regla de diseño que lo hace rendir — el contenido estable primero, el input variable último.

Referencia·Actualizado 2026-06-03·Escrito por Lira · Editado por German Medina

Un system prompt largo, un set gordo de tool definitions, un bloque de ejemplos fijos, un documento de grounding estático — enviado una vez en una demo, ese preámbulo es gratis. Enviado en cada llamada a volumen de producción, es la factura: el modelo reprocesa los tokens líderes idénticos en cada pedido, y a un millón de llamadas por mes el prompt que estaba bien en la demo es una línea de costo que nadie aprobó. Ese es el gotcha 10 de los gotchas de prompting, y el prompt caching es el arreglo. Esta página es la mecánica — qué hace de verdad el caching, la economía dicha como aritmética y no como un win gratis, y la regla estructural que decide si el cache rinde siquiera (principio 6 — costo y latencia son features).

Esta es una referencia para la superficie de la Claude API. La misma idea existe en otras plataformas de modelos bajo otros nombres; la disciplina de abajo se transfiere, los knobs y los ratios exactos son de Anthropic.

Qué es el prompt caching

Marcás un prefix estable del prompt con cache_control. El modelo cachea su procesamiento de todo hasta ese breakpoint, y cualquier llamada posterior que comparta el mismo prefix reusa el cache en vez de reprocesar esos tokens desde cero. El contenido líder — la parte que no cambia de llamada a llamada — se procesa una vez y después se vuelve a leer, en vez de pagarse de nuevo en cada pedido.

Lo que se cachea es el procesamiento del prefix por parte del modelo, no solo el texto. Por eso el ahorro es real y no contable: reenviar diez mil tokens idénticos significa que el modelo, si no, rehace el trabajo de leerlos cada vez. El caching significa que hizo ese trabajo una sola vez, y las llamadas siguientes que abren con los mismos diez mil tokens los saltean derecho.

La mecánica

El caching cubre el prompt en orden — primero tools, después system, después messages — hasta el bloque que marcás con cache_control inclusive. Todo lo anterior al breakpoint se cachea como un único prefix contiguo; todo lo posterior se procesa fresco en cada llamada. Podés poner hasta 4 cache breakpoints, lo que te deja cachear más de un segmento estable (por ejemplo, las tool definitions y un documento estático largo como regiones cacheadas separadas).

Hay dos formas de poner el breakpoint:

  • Caching automático — el breakpoint se mueve hacia adelante a medida que crece una conversación, así el historial estable y acumulado queda cacheado sin que lo re-marques en cada turno. Útil para conversaciones multi-turno donde el prefix se sigue extendiendo.
  • Breakpoints explícitos — ponés cache_control sobre bloques específicos para control fino de exactamente qué se cachea y dónde termina la región cacheada. Útil cuando sabés qué segmento es estable y querés fijar el límite vos.

Una entrada cacheada tiene un tiempo de vida: un mínimo de 5 minutes (standard) o 1 hour (extended), y usar el cache refresca esa ventana. Dejala inactiva más allá del tiempo de vida y la entrada expira; la próxima llamada reprocesa el prefix y escribe un cache nuevo. Así que el caching rinde cuando las llamadas que comparten un prefix llegan lo bastante seguido como para mantener la entrada tibia — un endpoint con tráfico, no un pedido por hora.

La economía — leela como aritmética

El caching no es un win gratis, y tratarlo como tal es cómo los equipos terminan pagando más. Los ratios lo deciden:

  • Un cache read cuesta cerca de 0.1x el precio de un token de input base — más o menos un décimo, un ahorro de cerca del 90 por ciento sobre la porción cacheada. Este es el win, y es grande.
  • Un cache write cuesta más que un token de input normal — cerca de 1.25x para el cache de 5 minutes, cerca de 2x para el de 1 hour. Escribir el cache es un premium sobre simplemente enviar los tokens una vez.

Así que el trade es claro: pagás un premium una vez para escribir el prefix en el cache, y después pagás cerca de un décimo cada vez que lo volvés a leer. El caching gana cuando un prefix estable se reusa lo suficiente como para amortizar ese write — los ahorros de read tienen que sumar por encima del premium del write. En una llamada de una sola vez que no volvés a pegar, el caching pierde: pagaste el premium del write y nunca cobraste el descuento del read. La decisión es aritmética — cuántas veces se va a reusar este prefix exacto antes de enfriarse — no un switch que prendés porque el caching suena a ahorro. (Este es el principio 6 hecho concreto: el costo es un número que modelás contra el volumen real, no algo que se atornilla después.)

Estructura cache-friendly: la regla de diseño

La mecánica de arriba solo rinde si el prompt está con la forma para eso, y esa forma es una regla: poné el contenido estable primero y el contenido variable último. El caching cubre un prefix contiguo, así que la corrida más larga que no cambia tiene que estar adelante para que el cache la cubra.

  • Estable, primero: el system prompt, las tool definitions, los ejemplos fijos, un bloque estático de conocimiento o grounding — todo lo que es idéntico entre llamadas. Este es el prefix que marcás y reusás.
  • Variable, último: el input del usuario, el dato por pedido, cualquier cosa que cambie de llamada a llamada. Esto va después del breakpoint y se procesa fresco cada vez, como tiene que ser.

Poné un solo token por pedido temprano — un timestamp, un user id, la pregunta misma — y rompiste el prefix: nada después de ese punto se comparte entre llamadas, así que nada después se puede cachear. El cache solo ve una corrida líder idéntica, así que la ingeniería es hacer esa corrida lo más larga posible ordenando todo lo estable adelante de todo lo variable.

[ tools ]            ← estable: igual en cada llamada
[ system prompt ]    ← estable
[ ejemplos fijos ]   ← estable
[ documento estático ] ← estable     ──► cache_control breakpoint acá
─────────────────────────────────────────  (termina el prefix cacheado; fresco abajo)
[ pregunta del usuario ] ← variable: cambia en cada llamada

Este es el rédito estructural de tratar el prompt como contexto ingenierizado en vez de un string que armás en el orden que sea cómodo. El mismo instinto que ordena un prompt para la salience (mirá system prompts e instrucciones) también lo ordena para el cache: el andamiaje estable arriba, la única cosa que cambia abajo. Conseguís la salience y el caching de la misma decisión.

El hilo

El prompt caching es la respuesta a una falla específica — un preámbulo estático grande re-pagado en cada llamada — y es una decisión aritmética, no un switch gratis. El descuento del read es real (cerca de un décimo del precio base) y el premium del write es real (más que un token), así que el caching rinde cuando un prefix estable se reusa lo suficiente como para superar el write, y te cuesta cuando no. Lo que lo hace rendir siquiera es la estructura: el contenido estable primero para que el prefix cacheable sea largo, el input variable último para que el cache nunca lo rompa un token por pedido cerca de arriba. Acertá el orden y un sistema que era correcto-pero-impagable se vuelve correcto-y-barato; ignoralo y el cache no tiene nada contiguo de donde agarrarse. El costo es un feature que diseñás de entrada, igual que diseñás grounding y evals — modelalo contra tu volumen real antes de construir, no después de que llega la factura.

Related

Reference: