Prompt caching en Claude, OpenAI y Gemini: 8 buenas prácticas

¿Qué guarda el prompt caching?

Un modelo de lenguaje no recuerda nada entre peticiones. Si envías cien veces la misma instrucción de sistema, el mismo documento o el mismo contexto de código, se procesa cien veces y se cobra cien veces. El prompt caching (caché de prompts) cambia eso: el proveedor procesa una vez la parte fija del inicio de la petición y la guarda; las peticiones siguientes que empiezan igual la leen de la caché.

Lo que se guarda no es el texto, sino los estados intermedios que el modelo calcula al procesarlo; la siguiente sección lo explica. Por eso la coincidencia tiene que ser exacta: si el prefijo no es idéntico byte a byte, no se puede leer de la caché.

Hay tres conceptos que se confunden a menudo:

Fuente: documentación de OpenAI, Anthropic, vLLM y GPTCache, 15 de octubre de 2026.

Es algo que vivimos a diario: cuando diffox revisa un pull request, varios agentes especializados leen el mismo contexto en llamadas separadas (contamos cómo funciona en otro artículo).

Cómo funciona la caché

Antes de empezar a generar una respuesta, un modelo de lenguaje lee la entrada completa; a esta fase se la llama prefill (prellenado). Mientras tanto, para cada token calcula unos estados intermedios llamados clave (key) y valor (value). La documentación de OpenAI los llama estados KV: al generar la respuesta, el modelo vuelve a mirar los tokens anteriores a través de esos estados. Eso es lo que guarda el prompt caching: no el texto, sino los tensores que el modelo calcula al procesarlo.

De ahí viene la ventaja. Si el prefijo está en caché, el modelo se salta ese cálculo y solo procesa los tokens nuevos. La documentación de vLLM explica también dónde termina la ganancia: la caché acorta el procesamiento de la entrada, no la generación de los tokens nuevos. Por eso, lo que más se beneficia de la caché es un prefijo largo con una respuesta corta. El artículo de Prompt Cache midió que el tiempo hasta el primer token se reducía hasta 8 veces en GPU y hasta 60 veces en CPU.

Esta estructura explica también por qué el prefijo tiene que ser idéntico byte a byte. El documento de diseño de vLLM identifica cada bloque de la caché por dos cosas: los tokens del propio bloque y los tokens del prefijo que lo precede. Es decir, la misma frase es otro bloque si delante hay otro texto. Basta añadir una fecha al principio para que todos los bloques que vienen detrás sean nuevos; la caché solo sirve hasta el punto donde está el cambio.

Estos estados tampoco son pequeños. El artículo de PagedAttention explica que la memoria de KV cache de cada petición es enorme y que crece y se reduce a lo largo de la petición. Por eso los proveedores limitan la caché a minutos: según la documentación de Google Cloud, la caché en memoria es limitada y las entradas se descartan cuando hace falta espacio. Anthropic también dice que estos estados solo están en memoria y no se guardan de forma permanente.

Cómo se activa el prompt caching en cuatro proveedores y cuánto se ahorra

Los cuatro proveedores admiten la caché, pero cambian la forma de activarla, el prefijo mínimo y el precio. Los datos de la tabla salen de la documentación de cada proveedor, consultada el 15 de octubre de 2026.

Fuente: documentación de los proveedores, 15 de octubre de 2026. Los multiplicadores son respecto al precio de entrada sin caché. La fila de Google Cloud se refiere a Gemini 2.5 y posteriores.

En Anthropic y en los modelos de OpenAI desde GPT-5.6, escribir en la caché cuesta más que enviar ese mismo token sin caché, y leer cuesta mucho menos. Por eso una caché que escribe a 1,25× se amortiza en la primera lectura, y la caché de 1 hora de Anthropic, que escribe a 2×, en la segunda. En la caché explícita de Gemini la escritura va a precio estándar, pero se cobra almacenamiento por cada hora que la caché sigue ahí; que salga a cuenta depende de cuántas lecturas haya y de cuánto tiempo se mantenga.

En la API de Claude, cuando muchas llamadas leen el mismo contexto, pon la marca en el bloque común y la instrucción propia de cada llamada detrás. ephemeral es por ahora el único tipo de caché admitido; el nombre del modelo es el del propio ejemplo de la documentación:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<contexto común: el mismo texto en cada llamada>",
      "cache_control": {"type": "ephemeral"}
    },
    {
      "type": "text",
      "text": "<instrucción propia de esta llamada>"
    }
  ],
  "messages": [
    {"role": "user", "content": "<la pregunta de esta llamada>"}
  ]
}

¿Cuánto tiempo sigue caliente la caché?

Una entrada de la caché no dura para siempre. La documentación de Claude Code lo resume en dos palabras: si la entrada sigue dentro de su tiempo de vida (TTL), la caché está caliente (warm); si ese plazo ha vencido, está fría (cold). Con la caché caliente, la siguiente petición lee el prefijo a bajo precio; con la caché fría, lo procesa desde cero y paga la escritura.

Fuente: documentación de los proveedores, 15 de octubre de 2026. La documentación no indica la duración de la caché implícita de Gemini; en Google Cloud es de 24 horas como máximo y la mayoría de las entradas se descartan antes.

Ese plazo funciona como un contador, con dos detalles importantes. En Anthropic, el contador corre desde que empieza la petición, no desde que termina la respuesta: si el streaming de la respuesta duró 4 minutos, la siguiente petición que vaya a leer el mismo prefijo tiene que empezar en más o menos 1 minuto. Y en Anthropic, OpenAI y Bedrock cada acierto pone el contador a cero, así que un tráfico regular mantiene la caché caliente por sí solo.

La mayoría de los proveedores no tienen un endpoint que diga si la caché sigue caliente. La excepción es la caché explícita de Gemini: cachedContents.get devuelve siempre la hora de caducidad (expireTime), no el contenido. En Anthropic, OpenAI y Bedrock, solo lo sabes por la respuesta siguiente: si el número de tokens leídos de la caché cae a cero, o el prefijo ha cambiado o la entrada se ha enfriado. La herramienta cache diagnostics de Anthropic distingue los dos casos: si las peticiones son iguales y la lectura es cero, la entrada ha caducado.

En Claude Code, la duración depende de cómo pagues. Según la documentación, con una suscripción de Claude la conversación principal usa una caché de 1 hora mientras no salgas del uso incluido en tu plan. Si pasas a créditos de uso, usas una clave de API o un proveedor de nube, la caché es de 5 minutos. Los subagentes tienen 5 minutos también con suscripción. Puedes cambiar la duración con el ajuste promptCacheTtl o con la variable CLAUDE_CODE_PROMPT_CACHE_TTL.

El estado se ve en tres sitios. /usage indica si la caché está caliente o fría, junto con la duración vigente. En el JSON que recibe la línea de estado (status line), el objeto prompt_cache incluye los campos warm, ttl y expires_at; este último indica cuándo se enfriará la caché. El reloj de caché de la extensión de VS Code también cuenta hacia atrás desde una vida de 5 minutos o de 1 hora y muestra los minutos que quedan; con la caché de 1 hora, empieza en 60 minutos.

Tres cosas que vigilar:

• El intervalo entre peticiones tiene que quedar por debajo del plazo. Cada petición que llega más de 5 minutos después de la anterior vuelve a escribir el prefijo. Anthropic recomienda quedarse con la caché de 5 minutos si el prefijo se reutiliza antes de que pasen 5 minutos, porque renovarla es gratis.
• Un plazo largo no sale gratis. En Anthropic, la escritura de 1 hora cuesta 2 veces y no se amortiza hasta que el prefijo se lee dos veces; en la caché explícita de Gemini se paga almacenamiento por cada hora.
• La primera petición tras una pausa larga es cara. Con la caché fría, la primera petición escribe el prefijo entero. Se puede precalentar la caché antes de que llegue la petición real: en Anthropic, con max_tokens: 0; en los modelos de OpenAI desde GPT-5.6, con prompt_cache_options.prewarm.

En un ejemplo con diez llamadas, el prefijo cuesta un 78,5 % menos

Los números son redondos e hipotéticos; solo muestran los multiplicadores de la documentación. Supongamos que 10 llamadas leen un prefijo común de 50.000 tokens. La unidad es un token cobrado al precio base de entrada; la escritura se toma como 1,25× y la lectura como 0,1×. La caché de 5 minutos de Anthropic y la mayoría de los modelos de OpenAI desde GPT-5.6 usan estos multiplicadores.

sin caché      10 × 50.000 × 1      = 500.000

con caché       1 × 50.000 × 1,25   =  62.500   escribe la primera llamada
              + 9 × 50.000 × 0,1    =  45.000   leen las otras nueve
                                    = 107.500

Diez llamadas lanzadas una tras otra pagan por el prefijo el equivalente a 107.500 tokens: un 78,5 % menos que los 500.000 sin caché. En un modelo con lectura a 0,05×, el total baja a 85.000. Con la caché de 1 hora, la escritura sube a 100.000 y el total queda en 145.000.

La tercera barra muestra el peor caso: las mismas diez llamadas salen a la vez. Ninguna puede leer lo que escribe otra y, si todas escriben el prefijo, el total llega a 625.000. Es un 25 % más caro que no activar la caché. El porqué está más abajo, en la sección sobre las llamadas en paralelo.

Las 8 reglas para mantener alta la tasa de aciertos

La documentación de los cuatro proveedores dice lo mismo sobre los aciertos. Cada una de las reglas siguientes aparece en la documentación de al menos dos proveedores.

La que más se pasa por alto es la segunda. Una línea de las notas de versión de Claude Code lo muestra: sacar la fecha del prompt de sistema subió la tasa de aciertos. La fecha cambia cada día y, si está al principio del prefijo, la primera petición de cada día nuevo vuelve a escribir el prefijo entero.

Dos reglas son propias de un solo proveedor. En los modelos de OpenAI anteriores a GPT-5.6, las peticiones que comparten prefijo llevan un prompt_cache_key fijo. Esa clave ayuda a dirigirlas a la misma caché, y la documentación recomienda unas 15 peticiones por minuto por clave. Anthropic, por su parte, pide que el orden de las claves JSON en las llamadas a herramientas sea estable. Según su documentación, algunos lenguajes como Swift y Go ordenan las claves al azar, y el mismo contenido sale con otros bytes.

Qué invalida la caché

En Anthropic y en Bedrock la caché sigue una jerarquía: tools, system, messages. Un cambio en un nivel invalida ese nivel y todos los que vienen detrás. Seis casos de los que enumera la documentación de Anthropic:

Activar o desactivar las citas tiene el mismo efecto que la búsqueda web, y añadir o quitar imágenes del prompt, el mismo que tool_choice. El caso que la documentación describe como «error común» es la cuarta tarjeta: si el breakpoint está en un bloque que contiene una marca de tiempo o el mensaje del usuario, cada petición escribe una entrada nueva y ninguna puede leer. El sistema busca hacia atrás como máximo 20 bloques, pero lo que busca no es contenido sin cambios, sino una entrada que escribió una petición anterior. La escritura solo ocurre en el breakpoint. Por eso la marca se pone en el último bloque que se mantiene igual entre peticiones.

Llamadas en paralelo y caché

Lanzar a la vez las llamadas que leen el mismo prefijo parece lo natural. La documentación de Anthropic lo deja claro: en peticiones simultáneas, la entrada de caché solo está disponible cuando empieza la primera respuesta; si quieres que las peticiones en paralelo lean de la caché, espera a la primera respuesta antes de enviar las demás. OpenAI también explica que la caché está en máquinas concretas y que más de 15 peticiones por minuto pueden acabar en otras máquinas.

No hace falta que la primera respuesta termine; basta con que empiece. La documentación propone tres caminos:

• Envía la primera llamada sola. Claude Code lo hace por sí mismo cuando, en un flujo de trabajo, lanza juntos agentes que comparten prefijo: retiene a todos menos al primero hasta que empieza la respuesta del primer agente; la espera es, por defecto, de 5.000 milisegundos como máximo.
• Precalienta la caché. Una petición enviada con max_tokens: 0 escribe en la caché en el breakpoint y vuelve sin generar salida; no se cobran tokens de salida. La marca tiene que estar en el bloque común, y la configuración de thinking y el valor de output_config.effort tienen que ser los mismos que en las llamadas reales. Se rechaza si va con ajustes que requieren salida (por ejemplo, stream: true).
• En los trabajos por lotes, usa la caché de 1 hora. En la Batch API las peticiones se procesan en cualquier orden y la lectura no está garantizada. La documentación recomienda enviar primero, con la caché de 1 hora, una sola petición que lleve el prefijo común, y el resto cuando esa termine.

Cómo medir la tasa de aciertos

No des por hecho que la caché funciona: compruébalo en la respuesta. Los cuatro proveedores indican los tokens leídos de la caché en un campo aparte de la información de uso de la respuesta:

Fuente: documentación de los proveedores, 15 de octubre de 2026.

La tasa de aciertos es la proporción de tokens leídos de la caché sobre la entrada total; OpenAI la define así y recomienda agregarla por usuario, por espacio de trabajo o por día. Hay que calcular bien la entrada total: en Anthropic y en Bedrock, el campo de entrada no cuenta los tokens que pasan por la caché, y el total es la suma de tres campos; en Gemini, promptTokenCount ya incluye los leídos de la caché.

La entrada total es la suma de los tres campos. input_tokens por sí solo no muestra toda la entrada; solo cuenta lo que va después del último breakpoint. Si todo va bien, en la primera llamada el campo de escritura coincide con el tamaño del prefijo, y en las siguientes ese mismo número aparece en el campo de lectura. Si los dos campos son cero, el prompt no ha entrado en la caché; la causa más probable es que el prefijo no llegue a la longitud mínima. Si el campo de escritura sigue alto en cada llamada, algo cambia en el prefijo.

Nosotros registramos por separado los tres campos de cada llamada. Una llamada que llega sin información de uso cuenta como no medida, no como cero; un hueco escrito como cero se lee como una llamada gratis.

Cuándo no compensa la caché

La caché no compensa en todas las cargas de trabajo. Antes de activarla, mira estos cuatro casos:

• Si el prefijo se lee una sola vez. Si escribir cuesta 1,25 veces y ninguna segunda llamada lee el prefijo, pagas un 25 % más.
• Si entre llamadas pasa más tiempo que el plazo. La caché está fría cada vez y el prefijo se vuelve a escribir.
• Si el prefijo no llega a la longitud mínima. La petición funciona y la caché no, sin devolver ningún error.
• Si el prefijo cambia en cada petición. Una fecha al principio obliga a escribir de nuevo en la caché en cada petición.

La ganancia no es solo de precio: con prefijos largos también se acorta el tiempo hasta el primer token. En el límite de uso (rate limit), los proveedores difieren: según Anthropic y Bedrock, en Claude los tokens leídos de la caché no cuentan para ese límite; en OpenAI, en cambio, sí cuentan para el límite de tokens por minuto.

En diffox, los agentes especializados de una revisión leen el mismo contexto común: el diff del cambio y el contexto de los archivos. Ese contexto va en un solo bloque al principio de la petición, y es ese bloque el que lleva la marca de caché; la primera llamada sale sola y las demás arrancan después en paralelo. Los tokens que escribe y lee cada llamada se registran por separado.