Caché de prompts a fondo: recorta un 60–90% de tu coste de input

Si envías un system prompt largo — contexto RAG, un catálogo de herramientas, reglas de agente, ejemplos — probablemente estás pagando el precio de input completo en cada llamada. La caché de prompts de Anthropic reduce eso al 10% de la tarifa sobre la parte cacheada. OpenAI hace lo mismo de forma implícita. A la mayoría de los equipos les compensan los 30 minutos de trabajo, porque recorta de forma fiable un 60–90% de su línea de coste de input.

Brievio deja pasar ambas variantes sin alterarlas, contra el modelo genuino. El cache_control al estilo de Anthropic funciona en la Messages API; la caché automática al estilo de OpenAI funciona en la Chat Completions API. Este artículo recorre ambas, los fallos que invalidan cachés en silencio y cómo verificar tu tasa de aciertos.

El antes y el después

Un bucle ingenuo que envía el mismo system prompt de 18K tokens diez veces:

# Por donde empieza casi todo el mundo: cada llamada vuelve a pagar el prompt entero.
import anthropic

client = anthropic.Anthropic(
    api_key="sk-brievio-...",
    base_url="https://api.brievio.com",
)

SYSTEM = open("system-prompt.md").read()        # 18.000 tokens de reglas + ejemplos

# 10 preguntas de usuario en una sesión. Cada llamada envía el bloque system de 18K tokens.
for question in questions:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=600,
        system=SYSTEM,
        messages=[{"role": "user", "content": question}],
    )

# Coste por llamada (solo input): 18.000 × $3 / 1M = $0.054
# 10 llamadas: $0.54 solo de input.

Ahora marca el bloque system como cacheable — un campo de más:

# La solución: marca el prefijo estático como cacheable. Tras la primera llamada,
# las siguientes dentro de ~5 minutos pagan el 10% de la tarifa de input sobre la
# parte cacheada. Misma respuesta, 89% más barato.
resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=600,
    system=[
        {
            "type": "text",
            "text": SYSTEM,
            "cache_control": {"type": "ephemeral"},  # marcar como cacheable
        }
    ],
    messages=[{"role": "user", "content": question}],
)

# Primera llamada (escritura de caché):  18.000 × $3   / 1M = $0.054
# Llamadas 2–10 (acierto de caché):       18.000 × $0.30 / 1M = $0.0054 cada una
# Total: $0.054 + 9 × $0.0054 = $0.103  (eran $0.54 — 81% de ahorro)

Acabas de ahorrar un 81% del coste de input en esta sesión. La primera llamada es en realidad algo más cara que la versión ingenua (~1,25× la tarifa de input para escribir la caché). Las llamadas 2 a 10 pagan el 10% de la tarifa. El punto de cruce está en la llamada 2 — en la llamada 3 ya vas por delante. En la llamada 10 es una goleada.

Estilo OpenAI: nada que hacer

Si usas el SDK de OpenAI, Chat Completions cachea el prefijo de cualquier prompt de más de 1.024 tokens automáticamente. Sin flag, sin configuración. El mismo modelo detrás de Brievio obtiene el descuento tanto si usaste la ruta de Anthropic como la de OpenAI en:

# Estilo OpenAI Chat Completions — la caché es automática para prompts ≥1024 tokens.
# No hay flag que activar. El objeto "usage" te dice qué se cacheó.
from openai import OpenAI

client = OpenAI(
    api_key="sk-brievio-...",
    base_url="https://api.brievio.com/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": LONG_SYSTEM_PROMPT},  # >1024 tokens
        {"role": "user", "content": "Última pregunta…"},
    ],
)

# En la respuesta:
#   resp.usage.prompt_tokens_details.cached_tokens  →  17.800
#   resp.usage.prompt_tokens                        →  18.200
# 17,8K/18,2K = 98% del input vino de la caché. La factura lo refleja automáticamente.

Lee usage.prompt_tokens_details.cached_tokens para ver cuánto se sirvió desde la caché. Cuanto mayor sea el prefijo fijo, mayor el ahorro. La regla práctica: si tu system prompt es más corto que tu contenido variable de usuario, la caché no aporta mucho. Reorganiza el prompt para que las partes estáticas sean grandes y vayan al principio.

Caché multicapa — hasta 4 puntos de corte

Para bucles de agente donde unas capas cambian más rápido que otras, configura varios puntos de corte de cache_control. Cada uno es una instantánea de todo lo que va hasta ese punto:

# Anthropic admite hasta 4 puntos de corte de caché por petición — úsalos
# para mantener la caché caliente aunque cambien las capas posteriores.
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=600,
    system=[
        {"type": "text",
         "text": ROLE_AND_RULES,                      # ~3.000 tokens
         "cache_control": {"type": "ephemeral"}},     # punto de corte 1
        {"type": "text",
         "text": LARGE_KNOWLEDGE_BASE,                # ~15.000 tokens, cambia poco
         "cache_control": {"type": "ephemeral"}},     # punto de corte 2
    ],
    messages=[
        {"role": "user",
         "content": [
             {"type": "text",
              "text": CONVERSATION_HISTORY,           # crece en cada turno
              "cache_control": {"type": "ephemeral"}}, # punto de corte 3
             {"type": "text", "text": new_question},
         ]},
    ],
)

# Cuando CONVERSATION_HISTORY cambia, los puntos de corte 1+2 siguen acertando en caché.
# Solo el punto de corte 3 + la nueva pregunta pagan la tarifa de input completa.

La clave de caché es el prefijo entero. Añade un token en la posición N y cada punto de corte en N o posterior queda invalidado. El orden importa: el contenido más estable primero. La capa de reglas debería cambiar poco; la base de conocimiento se actualiza cada semana; la conversación crece en cada turno.

Formas habituales de romper la caché en silencio

• Poner la fecha actual o un request_id en el prompt. Cada llamada es un prefijo nuevo, la tasa de aciertos de caché es del 0%. Haz un hash de los inputs del prompt y compáralos entre llamadas.
• Ensamblar el system prompt de forma no determinista. Si construyes el system a partir de un dict, el orden de iteración del dict importa en algunas versiones de Python. Ordena las claves de forma explícita.
• La vida de la caché es de ~5 minutos. Los patrones de tráfico disperso (una llamada cada 10 minutos) no obtienen ningún acierto. O agrupas las llamadas, o asumes la pérdida.
• El mínimo de 1.024 tokens. Por debajo de 1K tokens, la caché al estilo de OpenAI no se activa. Combina fragmentos estáticos pequeños en un único prefijo más largo.
• Las herramientas / definiciones de función forman parte del prefijo. Una herramienta nueva añadida al catálogo invalida la caché para todos. Mantén el catálogo de herramientas estable; versiónalo.

Verificar la tasa de aciertos

Una caché que no puedes ver no es ingeniería — es esperanza. Registra usage en cada llamada:

# Lee siempre usage. Si cached_tokens es 0 cuando esperabas un acierto,
# algo va mal — normalmente un prefijo no determinista.
resp = client.messages.create(...)
u = resp.usage
print({
    "input_uncached":  u.input_tokens,
    "input_cache_read": u.cache_read_input_tokens,
    "input_cache_write": u.cache_creation_input_tokens,
    "output": u.output_tokens,
})

# Un fallo habitual: poner la fecha de hoy o un request_id en el system prompt
# invalida la caché en silencio. Haz un hash de tus inputs; verifica que
# cache_read_input_tokens no sea cero en la 2.ª llamada idéntica.

En el panel de Brievio, la página de uso muestra el desglose de caché por modelo y por día. Si ves que cache_read_input_tokens crece como porcentaje del input total, la caché está funcionando. Si se queda en 0 o fluctúa mucho, repasa la lista de fallos de arriba.

Lo que cuesta de verdad en Brievio

La tarifa de caché de cada modelo está publicada en la página de precios:

• Modelos de Anthropic: las lecturas de caché son el 10% de la tarifa de input. Las escrituras de caché se facturan a la tarifa de input — sin recargo aguas arriba.
• Modelos de OpenAI / Gemini: las lecturas de caché son el 20% de la tarifa de input (la proporción publicada por los proveedores).
• Todos los precios con caché reflejan la lista de Brievio — aproximadamente un 15% por debajo de la tarifa oficial del proveedor. Así que una lectura de caché de Sonnet 4.6 en Brievio es $3 × 0.95 × 0.10 = $0.285 por 1M tokens. Unas 10× más barata que la tarifa de input sin cachear.

Cuando la caché no es la respuesta

Algunos casos en los que el trabajo no compensa:

• Prompts cortos (<1K tokens en total). La sobrecarga domina; no te molestes.
• Tareas de una sola vez sin tráfico repetido. La primera llamada es algo más cara — la caché solo se amortiza a partir de la llamada 2.
• Tareas de mucho output y poco input (escritura creativa, generación de código). El input ya es una parte pequeña de la factura. Mejor enfócate en límites al presupuesto de output.

Para todo lo demás — chatbots RAG, agentes con un catálogo de herramientas fijo, clasificadores que corren sobre una rúbrica estática, pipelines de extracción estructurada con few-shots consistentes — la caché es la optimización con mayor retorno que puedes lanzar en una sola tarde. Combínala con las otras cuatro técnicas de nuestro manual de optimización de costes y una reducción de coste del 70% es realista sin ni un solo compromiso en la calidad del output.

¿Ya estás en Brievio? Abre /app/usage y revisa la columna de caché de tu modelo más grande. Si está a cero, estás dejando dinero sobre la mesa. Guía completa: /docs/caching.