Mínimos de prompt cache: la documentación se queda corta entre 1,4 y 2,4x

Un cliente nos avisó de que el prompt caching de nuestro gateway no se activaba con el número de tokens que prometía la propia documentación del modelo. Lo reprodujimos y luego volvimos a probar cada modelo contra un segundo camino de servicio independiente, uno de los AI gateways más grandes, donde las mismas discrepancias se reprodujeron token a token. Quien pecaba de optimista era la documentación, no un gateway concreto: el mínimo publicado es un umbral de elegibilidad, no la longitud que hace saltar un cache hit. En las familias con caché automática, ambos difieren entre 1,4 y 2,4x. El umbral efectivo del primer hit de OpenAI se midió cerca de 1.456 tokens frente a los 1.024 documentados; Gemini 2.5 Flash leyó de caché por primera vez cerca de los 5.000 frente a los 2.048 documentados; Claude, que solo cachea donde colocas un marcador explícito, alcanzó su mínimo documentado por modelo con un margen de pocos puntos porcentuales.

TL;DR

• El mínimo de caché documentado de OpenAI, 1.024 tokens, se queda por debajo del umbral efectivo de unos 1.456 tokens, medido en dos caminos.
• Gemini 2.5 Flash documenta 2.048 pero leyó por primera vez cerca de los 5.000 tokens, unas 2,4x más.
• El cache_control explícito de Claude alcanzó su mínimo documentado con un margen de pocos puntos porcentuales (Opus 1.073 frente a 1.024).
• GLM 5.2 y DeepSeek V4 no publican ningún mínimo y leen a partir de unos 800 tokens; MiniMax M3 reporta unos 114 tokens cacheados a cualquier longitud.
• Las cachés automáticas además necesitan un calentamiento de entre 2 y 8 llamadas antes de la primera lectura.

Pasamos todas las mediciones por dos caminos de servicio, nuestro propio gateway y uno de los AI gateways independientes más grandes, y solo tratamos un resultado como comportamiento del modelo cuando ambos caminos coincidían. El sentido del segundo camino es la atribución: una discrepancia que se reproduce en el stack de un proveedor ajeno es del modelo, no nuestra. Ese cross-check funcionó sin problemas para OpenAI, Gemini y GLM, que cachearon en ambos con los mismos umbrales efectivos. No funciona con todos los modelos: en ese segundo gateway los modelos open-weight se sirven en su mayoría desde hosts GPU que no implementan el prompt cache del proveedor, algo que la propia metadata de endpoints del gateway confirma por cada proveedor, y el enrutamiento sin fijar salta entre esos hosts, con lo que se pierde la afinidad de caché. Cuando el segundo camino no pudo corroborar, los números de abajo vienen del camino que llega a la propia API de caché de cada proveedor. Las longitudes son los tokens propios de cada modelo, calibrados a partir del usage devuelto, no caracteres. Cada rama usó un prefijo nuevo y registró el índice de la primera llamada que produjo una lectura de caché, no un único acierto o fallo.

La diferencia entre lo documentado y lo efectivo

El mínimo documentado te dice cuándo un prompt puede cachearse. El umbral efectivo es la longitud a partir de la cual un prompt repetido realmente vuelve como una lectura de caché. En las familias con caché automático no son el mismo número.

En OpenAI la cifra se cumplió al token en ambos caminos: un prompt de 1,356 tokens nunca produjo lectura de caché, y uno de 1,456 tokens sí. Gemini fue la diferencia más grande. Un barrido que llegaba hasta 3,300 tokens no registró ninguna lectura y parecía que el caché estaba desactivado; al extenderlo a 5,000 apareció una lectura limpia en ambos caminos a esa misma longitud. Los 2,048 documentados son el piso a partir del cual el caché es elegible, no a partir del cual sirve lecturas.

El patrón de todo el estudio: el caché que marcas de forma explícita tiene una especificación precisa, y el caché que ocurre de forma automática no.

El mínimo no es la única variable sin documentar

Superar el umbral efectivo es necesario, pero no suficiente. Las familias con caché automático necesitan un calentamiento: la primera lectura no llega en la segunda llamada, sino en una posterior.

• OpenAI: primera lectura en la llamada 2 o 3.
• Gemini: primera lectura en la llamada 4 a 8.

Esto importa para modelar costos. Un prompt de 6,000 tokens está por encima de todos los umbrales documentados y efectivos de Gemini, pero una carga que lo envía dos veces y sigue adelante puede pagar precio completo las dos veces, porque el caché no había calentado. El tráfico corto o a ráfagas paga la tarifa sin caché aunque la longitud califique. Solo concluimos “no cachea” después de al menos doce llamadas repetidas con un intervalo de asentamiento entre ellas; un barrido más corto produjo un falso negativo en Gemini que uno más profundo desmintió.

Los conteos de tokens cacheados también se ajustan a bloques fijos, algo que conviene saber al reconciliar una factura: bloques de 128 tokens en OpenAI, bloques de 64 tokens en DeepSeek. Una lectura de 4,073 tokens cacheados sobre un prompt de 5,014 tokens es un hit de prefijo parcial redondeado al límite de un bloque, no un bug.

Los cachés que controlas son exactos

Claude solo cachea los segmentos que marcas con cache_control, y ese control viene con una especificación precisa. Todas las afirmaciones de Anthropic que probamos se cumplieron:

• Mínimo por modelo, al token. Opus 4.8 y Sonnet 5 tuvieron su primera lectura a 1,073 tokens frente a los 1,024 documentados; Haiku 4.5 a 4,206 frente a 4,096. El pequeño exceso es redondeo de bloque, no desviación.
• Tarifa de lectura de 0.1x del input. Derivamos el precio de input de cada modelo a partir de sus propias filas en frío y luego despejamos la tarifa cacheada desde una fila con hit. Opus 4.8 y Haiku 4.5 dieron 0.10, coincidiendo con el multiplicador documentado.
• Refresco de cinco minutos, gratis en cada lectura. Sembramos un prefijo y lo releímos a los dos, cuatro y seis minutos, con hit en cada lectura. Una lectura dentro de cada ventana de cinco minutos mantiene viva la entrada sin un write adicional.
• Invalidación en cascada. Con un prefijo de sistema estable y una herramienta definida, cambiar solo la descripción de la herramienta forzó una reescritura completa del caché de sistema que estaba por debajo. Cambiar una definición de herramienta invalida los cachés de sistema y de mensajes, tal como indica la jerarquía documentada.

De aquí salió un conflicto entre documentaciones. Una tabla de terceros indicaba que el mínimo de Claude Opus era de 4,096 tokens; la medición dio una lectura a 1,073, y los 1,024 de la propia Anthropic son la cifra correcta.

Las familias de peso abierto normalmente no documentan nada

Las familias anteriores al menos publican un número, aunque sea equivocado. Los modelos de peso abierto y de laboratorios chinos por lo general no publican ningún mínimo, así que solo queda medir. Nuestra comparativa de caché entre proveedores cubre cómo cuadran sus tasas publicadas una vez que se produce un hit; aquí la única pregunta es a partir de qué longitud aparece la primera lectura.

GLM 5.2 no publica ningún mínimo de longitud y cachea a partir de unos 800 tokens, con granularidad de bloques de 64 tokens en ambas rutas: un umbral más bajo que el de cualquiera de las familias documentadas. DeepSeek V4 tampoco publica mínimo y lee a partir de unos 800 tokens con la misma granularidad de 64 tokens, pero solo contra su propia API de caché. La documentación de DeepSeek describe la caché como best-effort, sin garantía de tasa de hits, y eso es justo lo que expone un intermediario: el otro gateway sirve DeepSeek a través de un conjunto de hosts GPU donde solo el endpoint propio de DeepSeek implementa la caché, así que cualquier ruteo que no esté fijado a ese endpoint no devuelve ninguna lectura.

MiniMax M3 es el caso en que el propio número reportado engaña. Documenta un mínimo de 512 tokens, pero reporta un conteo constante cercano a 114 tokens en caché desde la primera llamada, a cualquier longitud entre 200 y 5.000 tokens. Ese número no sigue la longitud del prompt y aparece incluso en rutas que no hacen ninguna caché, así que es la contabilidad interna del modelo, no una señal de lo que se reutilizó. Es la misma lección que enseñan los modelos más nuevos de OpenAI desde el otro lado: los campos de tokens en usage y la caché real pueden discrepar, así que cuando el ahorro importa, concíllalo contra usage.cost, no contra el conteo de tokens.

Los modelos más nuevos están cambiando las reglas

Hay dos cambios a nivel de documentación que conviene señalar antes de dar por hecho que el comportamiento antiguo se mantiene. En la familia GPT-5.6, la guía de OpenAI indica que las escrituras en caché cuestan 1,25x la tarifa de input sin cachear, mientras que familias anteriores escribían gratis. Esa misma guía describe la caché implícita como colocar un breakpoint en el último mensaje, algo distinto de cachear por prefijo un bloque de sistema estable a lo largo de los turnos. Si quieres reutilizar un prefijo estable entre turnos de usuario distintos en esos modelos, márcalo con un breakpoint explícito en lugar de confiar en la ruta implícita. Confirma el multiplicador de escritura y el mínimo por modelo, porque ahora ambos varían según la familia de formas que una sola página de documentación aplana.

Qué hacer con esto

• Mide tu propio umbral efectivo. Barre la longitud del prompt en tus propios tokens y anota la primera longitud que devuelve una lectura de caché. No des por hecho que los aciertos empiezan en el mínimo documentado.
• Presupuesta el calentamiento. En proveedores con caché automática, trata las primeras dos a ocho llamadas sobre un prefijo nuevo como si no estuvieran cacheadas en tu modelo de costes.
• Usa marcadores explícitos cuando el proveedor los ofrezca. El cache_control de Claude daba una especificación precisa y verificable: mínimo conocido, tasa de lectura conocida, TTL conocido y regla de invalidación conocida. Esa previsibilidad vale más que un mínimo documentado más bajo en el que no puedes confiar.
• Vuelve a medir la línea base con cada nueva familia de modelos. Los mínimos, el precio de escritura y el comportamiento de los breakpoints cambiaron dentro de la propia gama de un mismo proveedor durante este estudio.

Para las tasas de lectura, los TTL y las reglas de keying que hay detrás de estos umbrales, nuestra guía de prompt caching explica la mecánica de cada proveedor.

En resumen: el mínimo documentado es un umbral de elegibilidad, no un umbral de acierto, y en las cachés automáticas los dos difieren entre 1,4 y 2,4x. Verifica el número que determina tu factura, en tus propios tokens, contra tu propio tráfico.

← Volver al blog