Prompt caching puede reducir el costo de tokens de entrada hasta en un 90% y la latencia de forma proporcional, pero solo si entiendes que es una coincidencia de prefijo exacta — un solo byte fuera de lugar invalida todo lo que sigue.
La regla que hay que interiorizar antes de tocar código: prompt caching es una coincidencia de prefijo. La clave de caché se deriva de los bytes exactos del prompt renderizado hasta cada punto de corte (`cache_control`). Un cambio de un solo byte en la posición N invalida el caché de todos los breakpoints posteriores a esa posición.
El orden de renderizado en cada petición es fijo: `tools` → `system` → `messages`. Un breakpoint en el último bloque de `system` cachea tanto las herramientas como el prompt de sistema juntos. Entender este orden es la mitad del trabajo de diseñar bien el caching — la otra mitad es asegurarte de que el contenido volátil (timestamps, IDs de sesión, la pregunta específica del usuario) siempre quede después del último breakpoint.
El uso más simple es el caching automático a nivel de request, que cachea el último bloque cacheable sin que tengas que anotar bloques individuales:
Si `cache_read_input_tokens` es cero en peticiones repetidas con el mismo prefijo, hay un invalidador silencioso operando — la causa más común es un timestamp o un UUID interpolado en el prompt de sistema, o un `JSON.stringify` sin orden determinista de claves.
Para un prompt de sistema grande y compartido entre muchas peticiones, el breakpoint va en el último bloque de texto de `system`. Para conversaciones multi-turno, va en el último bloque de contenido del turno más reciente — cada petición subsiguiente reutiliza todo el prefijo de la conversación anterior. Para el patrón de "prefijo compartido, sufijo variable" (mismo contexto de pocos ejemplos o documentos recuperados, pregunta distinta cada vez), el breakpoint debe ir al final de la parte **compartida**, nunca al final del prompt completo — de lo contrario cada petición escribe una entrada de caché distinta y ninguna llega a leerse.
El mínimo de tokens cacheables depende del modelo: 4096 tokens en la familia Opus 4.x y Haiku 4.5, 2048 en Sonnet 4.6 y modelos Haiku anteriores. Un prompt de 3000 tokens se cachea en Sonnet pero no en Opus — sin error, simplemente `cache_creation_input_tokens: 0`.
El error más común no es de sintaxis sino de diseño: interpolar "fecha actual: X" o el nombre del usuario directamente en el prompt de sistema. Como ese contenido está al inicio del prefijo, invalida todo lo que sigue en cada petición. La solución es inyectar ese contexto dinámico más adelante en `messages`, no al principio de `system`.
Cambiar el conjunto de herramientas o el modelo a mitad de una conversación también invalida el caché completo — las herramientas se renderizan en la posición cero del prompt. Si necesitas "modos" distintos de comportamiento, no cambies el conjunto de tools; dale a Claude una herramienta que registre la transición de modo, o pásalo como contenido de mensaje.
Una lectura de caché cuesta aproximadamente 0.1x el precio base de entrada; una escritura cuesta 1.25x con TTL de 5 minutos, o 2x con TTL de 1 hora. El punto de equilibrio con TTL de 5 minutos se alcanza en dos peticiones; con TTL de 1 hora, se necesitan al menos tres. El TTL de una hora tiene sentido cuando el tráfico es intermitente pero recurrente (por ejemplo, un flujo de trabajo que se ejecuta cada 20-30 minutos); el de 5 minutos es suficiente para la mayoría de aplicaciones conversacionales con tráfico continuo.
Para eliminar la latencia del primer cache-miss en aplicaciones donde el tiempo de primera respuesta es visible al usuario (chat en vivo, asistentes de voz), se puede enviar una petición con `max_tokens: 0` al arrancar la aplicación o el worker. Esto ejecuta el prefill del prompt, escribe el caché en el breakpoint indicado, y devuelve inmediatamente sin generar output — sin costo de tokens de salida, solo el costo normal de escritura de caché.
Esto vale la pena solo cuando el tráfico real tiene huecos más largos que el TTL; si las peticiones llegan con más frecuencia que cada 5 minutos, ya se mantienen calientes solas y un pre-calentamiento adicional es una escritura extra innecesaria.
Carlos Montiel es arquitecto de soluciones IA empresarial. Implementa LLMs, Agentes, RAG y orquestadores en empresas de Guatemala y Latinoamérica. Contáctalo para una consultoría.
Contactar a Carlos Montiel