Mínimos de prompt cache: la documentación se queda corta 1.4-2.4x

Un cliente nos avisó de que el prompt cache de nuestro gateway no se activaba con la cantidad de tokens que prometía la documentación del modelo. Reproducimos el problema y volvimos a probar todos los modelos por una segunda ruta independiente, uno de los mayores gateways de IA. Las mismas diferencias se repitieron token por token. La documentación, y no un gateway concreto, era demasiado optimista: el mínimo publicado solo indica a partir de cuándo un prompt puede entrar en cache, no la longitud necesaria para obtener un cache hit. En las familias con cache automático, ambas cifras difieren entre 1.4 y 2.4x. En OpenAI medimos un umbral efectivo para el primer hit de unos 1,456 tokens, frente a los 1,024 documentados. Gemini 2.5 Flash no leyó del cache hasta cerca de 5,000, aunque la documentación indica 2,048. Claude, que solo guarda en cache donde se añade un marcador explícito, alcanzó el mínimo documentado de cada modelo con un margen de pocos puntos porcentuales.

TL;DR

• El mínimo documentado por OpenAI, 1,024 tokens, se queda por debajo del umbral efectivo de unos 1,456 tokens, medido por dos rutas.
• Gemini 2.5 Flash documenta 2,048, pero la primera lectura apareció cerca de 5,000 tokens, unas 2.4x más.
• El cache_control explícito de Claude alcanzó el 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 desde unos 800 tokens; MiniMax M3 declara aproximadamente 114 tokens en cache con cualquier longitud.
• Los caches automáticos también necesitan entre 2 y 8 llamadas de calentamiento antes de la primera lectura.

Ejecutamos todas las mediciones por dos rutas: nuestro gateway y uno de los mayores gateways independientes de IA. Solo consideramos que un resultado correspondía al comportamiento del modelo cuando ambas rutas coincidían. La segunda ruta permite atribuir la causa: si una discrepancia se reproduce en la infraestructura de otro proveedor sin relación con nosotros, pertenece al modelo, no a nuestro gateway. La comprobación fue concluyente para OpenAI, Gemini y GLM, que usaron cache por ambas rutas y con los mismos umbrales efectivos. No funciona con todos los modelos. En el segundo gateway, los modelos open-weight se sirven principalmente desde hosts con GPU que no implementan el prompt cache del proveedor, tal como confirma la metadata de endpoints del propio gateway para cada proveedor. Además, el routing sin fijar cambia entre esos hosts y se pierde la afinidad del cache. Cuando no fue posible corroborar el resultado por la segunda ruta, las cifras siguientes proceden de la ruta que accede a la API de cache del proveedor correspondiente. Las longitudes están expresadas en los tokens propios de cada modelo, calibrados a partir del usage devuelto, no en caracteres. En cada variante usamos un prefijo nuevo y registramos el índice de la primera llamada que produjo una lectura del cache, en lugar de basarnos en un único hit o miss.

Diferencia entre el mínimo documentado y el efectivo

El mínimo documentado indica cuándo un prompt puede guardarse en cache. El umbral efectivo es la longitud a partir de la cual la repetición de ese prompt produce realmente una lectura. En las familias con cache automático, no son la misma cifra.

La cifra de OpenAI coincidió token por token en ambas rutas: un prompt de 1,356 tokens nunca produjo una lectura, mientras que uno de 1,456 sí. Gemini presentó la mayor diferencia. Un barrido que llegaba hasta 3,300 tokens no produjo ninguna lectura y parecía indicar que el cache estaba desactivado. Al ampliarlo hasta 5,000, obtuvimos una lectura clara por ambas rutas y con la misma longitud. Los 2,048 documentados son el mínimo a partir del cual el prompt puede entrar en cache, no aquel a partir del cual se obtienen lecturas.

El patrón observado en todo el estudio fue claro: el cache que se marca explícitamente tiene una especificación precisa; el que se activa automáticamente, no.

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

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

• OpenAI: primera lectura entre las llamadas 2 y 3.
• Gemini: primera lectura entre las llamadas 4 y 8.

Esto afecta al cálculo de costes. Un prompt de 6,000 tokens supera todos los umbrales documentados y efectivos de Gemini. Sin embargo, una carga que lo envía dos veces y luego cambia de prompt puede pagar el precio completo en ambas llamadas porque el cache todavía no se ha calentado. El tráfico breve o en ráfagas paga la tarifa sin cache aunque la longitud cumpla el requisito. Solo concluimos que un modelo «no usa cache» tras al menos doce llamadas repetidas, con una pausa para que el cache se asentara. Un barrido más corto dio un falso negativo en Gemini que desapareció al ampliar la prueba.

Los recuentos en cache también se ajustan a bloques fijos, algo que conviene tener en cuenta al conciliar una factura: bloques de 128 tokens en OpenAI y de 64 en DeepSeek. Una lectura de 4,073 tokens en cache para un prompt de 5,014 corresponde a un hit parcial del prefijo redondeado al límite de un bloque, no a un bug.

Los caches que controlas sí son precisos

Claude solo guarda en cache los segmentos etiquetados con cache_control, y ese control viene acompañado de una especificación precisa. Todas las afirmaciones de Anthropic que probamos se cumplieron:

• Mínimo por modelo, token por token. Opus 4.8 y Sonnet 5 produjeron su primera lectura con 1,073 tokens frente a los 1,024 documentados; Haiku 4.5, con 4,206 frente a 4,096. La pequeña diferencia se debe al redondeo por bloques, no a una desviación.
• Tarifa de lectura de 0.1x del input. Calculamos el precio de input de cada modelo a partir de sus propias filas sin cache y después despejamos la tarifa de cache usando una fila con hit. Tanto Opus 4.8 como Haiku 4.5 dieron 0.10, igual que el multiplicador documentado.
• Renovación gratuita de cinco minutos con cada lectura. Cargamos un prefijo y volvimos a leerlo a los dos, cuatro y seis minutos. Todas las lecturas produjeron un hit. Una lectura dentro de cada ventana de cinco minutos mantiene viva la entrada sin ninguna escritura adicional.
• Invalidación en cascada. Con un prefijo de sistema estable y una sola tool definida, cambiar únicamente la descripción de la tool obligó a reescribir por completo el cache de sistema situado a continuación. Modificar la definición de una tool invalida los caches de sistema y de mensajes, tal como indica la jerarquía documentada.

También encontramos una contradicción entre documentos. Una tabla de terceros indicaba un mínimo de 4,096 tokens para Claude Opus. La medición produjo una lectura con 1,073, por lo que la cifra correcta es la de Anthropic: 1,024.

Las familias open-weight no suelen documentar ningún mínimo

Al menos, las familias anteriores publican una cifra que se puede contrastar. Los modelos open-weight y de laboratorios chinos, en su mayoría, no publican ningún mínimo, por lo que medir es la única opción. Nuestra comparativa del cache por proveedor analiza cómo se corresponden sus tarifas publicadas una vez que se produce un hit. Aquí solo nos interesa la longitud a la que aparece la primera lectura.

GLM 5.2 no publica una longitud mínima y usó cache desde unos 800 tokens, con una granularidad de bloques de 64 tokens por ambas rutas. Es un mínimo inferior al de cualquiera de las familias que sí lo documentan. DeepSeek V4 tampoco publica un mínimo y produjo lecturas desde unos 800 tokens, con la misma granularidad de 64 tokens, pero solo contra su propia API de cache. La documentación de DeepSeek define el cache como best-effort y no garantiza ningún hit rate. Eso es exactamente lo que expone un intermediario: el otro gateway sirve DeepSeek mediante un conjunto de hosts con GPU en el que solo el endpoint del propio DeepSeek implementa el cache. Si el routing no se fija a ese endpoint, no se obtiene ninguna lectura.

MiniMax M3 es un caso en el que la propia cifra declarada induce a error. Documenta un mínimo de 512 tokens, pero informa de un recuento constante cercano a 114 tokens en cache desde la primera llamada, para todas las longitudes probadas entre 200 y 5,000 tokens. Esa cifra no varía con la longitud del prompt y aparece incluso en rutas que no usan cache, así que corresponde a la contabilidad interna del modelo y no indica qué contenido se ha reutilizado. Los modelos más recientes de OpenAI muestran la misma lección desde el extremo opuesto: los campos de tokens de usage pueden no coincidir con el comportamiento real del cache. Si el ahorro es relevante, concilia el coste con usage.cost, no con el recuento de tokens.

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

Antes de asumir que los modelos nuevos mantienen el comportamiento anterior, hay que tener en cuenta dos cambios de la documentación. Para la familia GPT-5.6, la guía de OpenAI indica que las escrituras de cache cuestan 1.25x la tarifa de input sin cache, mientras que en familias anteriores eran gratuitas. La misma guía describe el cache implícito como la colocación de un breakpoint en el mensaje más reciente. Es un comportamiento distinto de guardar en cache un bloque de sistema estable como prefijo entre turnos. Si quieres reutilizar un prefijo estable con distintos turnos de usuario en esos modelos, márcalo con un breakpoint explícito en lugar de depender de la ruta implícita. Confirma por modelo tanto el multiplicador de escritura como el mínimo, porque ambos varían ahora entre familias de una forma que una única página de documentación no refleja.

Qué hacer con estos datos

• Mide tu propio umbral efectivo. Haz un barrido de la longitud del prompt en los tokens de tu modelo y registra la primera longitud que devuelva una lectura del cache. No des por hecho que los hits empiezan en el mínimo documentado.
• Incluye el calentamiento en el presupuesto. En proveedores con cache automático, contabiliza las primeras dos a ocho llamadas de cada prefijo nuevo como llamadas sin cache.
• Usa marcadores explícitos cuando el proveedor los ofrezca. El cache_control de Claude proporcionó una especificación precisa y verificable: mínimo, tarifa de lectura, TTL y regla de invalidación conocidos. Esa previsibilidad vale más que un mínimo documentado más bajo en el que no se puede confiar.
• Vuelve a establecer la referencia con cada nueva familia de modelos. Durante este estudio cambiaron los mínimos, el precio de escritura y el comportamiento de los breakpoints dentro del catálogo de un mismo proveedor.

Para consultar las tarifas de lectura, los TTL y las reglas de generación de claves asociadas a estos umbrales, nuestra guía de prompt cache explica el funcionamiento de cada proveedor.

En resumen: el mínimo documentado solo indica cuándo un prompt puede entrar en cache, no el umbral para obtener un hit. En los caches automáticos, ambas cifras difieren entre 1.4 y 2.4x. Verifica la cifra que determina tu factura usando los tokens de tu modelo y tu propio tráfico.

← Volver al blog