Reduzca un 90% el coste de los prompts repetidos con una sola línea de prompt caching

Pagar otra vez por un texto que nunca cambia

En algún lugar de su código hay un bloque de texto por el que ha pagado diez mil veces y que no ha cambiado ni una sola. Abra el panel de uso y ponga los tokens de entrada de ayer junto al número de peticiones. Si la proporción se acerca al tamaño de su prompt de sistema, esto va con usted. Ha estado pagando el precio completo por enviar una y otra vez el mismo muro de instrucciones, y el modelo lo lee desde cero cada vez, como si no le conociera de nada.

Pongamos un bot de soporte con unos 9000 tokens de documentos de políticas en el prompt de sistema y unas 40.000 llamadas al mes. Cada llamada arrastraba todo ese bloque por la red. La solución es una sola línea. También hay una trampa que deja esa línea sin valor, explicada más abajo, y es justo ahí donde la mayoría pierde el ahorro que cree haber activado.

En el servidor nada recuerda su contexto

La Messages API no guarda estado. No hay ninguna sesión aparcada que mantenga su prompt listo entre llamadas. Cada petición reconstruye el prompt desde cero, lo tokeniza, lo pasa por el modelo y tira el trabajo. La siguiente llamada repite lo mismo al mismo precio.

without caching

call 1   [ 9,000 tok system ][ 40 tok question ]   full price
  call 2   [ 9,000 tok system ][ 35 tok question ]   full price
  call 3   [ 9,000 tok system ][ 52 tok question ]   full price
            ^^^^^^^^^^^^^^^^^
            same bytes, billed three times

El cambio de una línea

Así es como escribe la llamada la mayoría:

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=DOCS,
    messages=[{"role": "user", "content": q}],
)

Y esta es toda la solución, un campo extra colocado encima de system:

cache_control={"type": "ephemeral"},

Este campo de nivel superior activa el caché automático. La API coloca el punto de corte en el último bloque que se puede cachear y lo va moviendo hacia delante a medida que crece la conversación.

Revise el bloque usage

No se fíe de la impresión de que todo va más rápido. Lea los datos de uso que devuelve la API con cada respuesta:

creation    read    input
  call 1  cold          9012       0       40
  call 2  warm             0    9012       35

Lo importante es la segunda fila. Se sirvieron nueve mil tokens desde el caché a una décima parte del precio, mientras que input_tokens se reduce solo a la parte posterior al punto de corte.

La trampa

Ponga una marca de tiempo al principio del prompt de sistema, o un nombre de usuario, o la fecha actual porque parecía inofensivo, y el prefijo cambiará en cada petición. El hash nunca coincide, así que pagará el recargo de escritura indefinidamente y no obtendrá ni una lectura. Eso es peor que no hacer nada.

A la API le importa un orden fijo. El contenido estable va primero y todo lo que cambia va al final:

tools  ->  system  ->  messages

[ stable stuff ----------------- | volatile ]
                                    ^
                               breakpoint lives here

Cuando no hay lecturas de caché

Hay una longitud mínima, y si no se alcanza, nadie se lo dice. El mínimo es de 512 tokens en Opus 5, 1024 en Sonnet 5 y 4096 en Haiku 4.5. Por debajo no hay caché ni error, solo la factura que intentaba evitar.

El caché dura 5 minutos y se renueva gratis con cada acierto, así que un tráfico constante lo mantiene activo por sí solo. Si sus llamadas están más espaciadas, pida un TTL de una hora. Recuerde también que la coincidencia es exacta al byte: un espacio de más, una definición de herramienta reordenada o un ajuste cambiado le devuelven al precio completo sin ningún aviso.

Más allá de una línea

Más adelante puede pasar a puntos de corte explícitos y añadir cache_control a bloques concretos, de los que se permiten cuatro. Lo sensato es ponerlos en las definiciones de herramientas y al final de los documentos, ya que las herramientas casi no cambian y los documentos cambian cada semana. Aun así, empiece por la línea única: despliéguela, vigile los campos de usage y solo después complíquese.

En los bucles de agentes el efecto se multiplica. Una tarea con diez llamadas a herramientas lee el mismo prefijo diez veces, así que en la última pasada el caché ya no ahorra un poco, sino que es lo que hace asequible la funcionalidad.