Caché de prompts de Anthropic — reduce un 90 % tu factura de entrada en 30 minutos

Si envías una instrucción de sistema larga —contexto RAG, un catálogo de herramientas, reglas del agente, ejemplos— probablemente pagas el precio completo de entrada en cada llamada. La caché de indicaciones de Anthropic reduce el coste a un 10 % de la tarifa en la parte almacenada en caché. OpenAI hace lo mismo de forma implícita. A la mayoría de los equipos les compensa dedicar 30 minutos porque reduce de forma fiable entre un 60 y un 90 % la línea de coste de entrada.

Kunavo admite ambas opciones. Tus cache_control propios pasan intactos a la API Messages; en las API Chat Completions y Responses —donde el formato no tiene ningún campo equivalente que enviar— Kunavo los establece por ti y completa los puntos alrededor de lo que hayas enviado, sin superar nunca el límite de 4. Esta publicación explica ambas opciones, los errores sutiles que invalidan las cachés y cómo verificar tu tasa de aciertos.

El antes y el después

Un bucle ingenuo que envía diez veces la misma instrucción de sistema de 18K tokens:

# What most people start with: every call re-pays for the whole prompt.
import anthropic

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

SYSTEM = open("system-prompt.md").read()        # 18,000 tokens of rules + examples

# 10 user questions in a session. Every call sends the 18K-token system block.
for question in questions:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=600,
        system=SYSTEM,
        messages=[{"role": "user", "content": question}],
    )

# Cost per call (input only): 18,000 × $3 / 1M = $0.054
# 10 calls: $0.54 in input alone.

Ahora marca el bloque de sistema como almacenable en caché: un campo adicional:

# The fix: mark the static prefix as cacheable. After the first call,
# subsequent calls within ~5 minutes pay 10% the input rate on the cached
# portion. Same answer, 89% cheaper.
resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=600,
    system=[
        {
            "type": "text",
            "text": SYSTEM,
            "cache_control": {"type": "ephemeral"},  # mark cacheable
        }
    ],
    messages=[{"role": "user", "content": question}],
)

# First call (cache write):  18,000 × $3.75 / 1M = $0.0675  (1.25× input)
# Calls 2–10 (cache hit):    18,000 × $0.30 / 1M = $0.0054 each
# Total: $0.0675 + 9 × $0.0054 = $0.116  (was $0.54 — 78.5% saved)

Acabas de ahorrar un 78.5 % del coste de entrada en esta sesión. La primera llamada es en realidad ligeramente más cara que la versión ingenua (~1.25× la tarifa de entrada para escribir la caché). Las llamadas de la 2 a la 10 pagan el 10 % de la tarifa. El punto de equilibrio llega en la llamada 2; en la 3 ya sales ganando. En la 10, la diferencia es enorme.

Estilo OpenAI: no hay que hacer nada

El formato Chat Completions de OpenAI no tiene el campo cache_control, porque OpenAI almacena en caché implícitamente en sus propios servidores. Claude no lo hace: solo almacena en caché lo que marca un punto de ruptura. Por eso, cuando accedes a un modelo Claude mediante /v1/chat/completions o /v1/responses, Kunavo establece los puntos por ti: uno móvil en el último mensaje cuando la conversación ya tiene al menos un turno del asistente, después de system y después de tools. Todo lo que establezcas tú permanece exactamente donde lo pusiste; Kunavo solo rellena las posiciones que dejaste vacías y únicamente hasta el límite de 4. No hay nada que configurar, y el mismo modelo cuesta lo mismo tanto si entras por la ruta de Anthropic como por la de OpenAI:

# OpenAI Chat Completions style — Kunavo sets the breakpoints for you.
# No flag to set. The "usage" object tells you what was cached.
from openai import OpenAI

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

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

# In the response:
#   resp.usage.prompt_tokens_details.cached_tokens  →  17,800
#   resp.usage.prompt_tokens                        →  18,200
# 17.8K/18.2K = 98% of input came from cache. Bill reflects that automatically.

Lee usage.prompt_tokens_details.cached_tokens para saber cuánto se sirvió desde la caché. Cuanto mayor sea el prefijo fijo, mayor será el ahorro. Regla práctica: si la instrucción de sistema es más corta que el contenido variable del usuario, la caché no aporta mucho. Reestructura la instrucción para que las partes estáticas sean grandes y estén al principio.

Caché multicapa: hasta 4 puntos de ruptura

Para bucles de agentes en los que unas capas cambian más rápido que otras, establece varios puntos de ruptura cache_control. Cada uno es una instantánea de todo lo que lo precede:

# Anthropic supports up to 4 cache breakpoints per request — use them
# to keep the cache hot even as later layers change.
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"}},     # breakpoint 1
        {"type": "text",
         "text": LARGE_KNOWLEDGE_BASE,                # ~15,000 tokens, rarely changes
         "cache_control": {"type": "ephemeral"}},     # breakpoint 2
    ],
    messages=[
        {"role": "user",
         "content": [
             {"type": "text",
              "text": CONVERSATION_HISTORY,           # grows each turn
              "cache_control": {"type": "ephemeral"}}, # breakpoint 3
             {"type": "text", "text": new_question},
         ]},
    ],
)

# When CONVERSATION_HISTORY changes, breakpoints 1+2 still hit cache.
# Only breakpoint 3 + the new question pay full input rate.

La clave de caché es el prefijo completo. Añadir un token en la posición N invalida todos los puntos de ruptura situados en N o después. El orden importa: el contenido más estable debe ir primero. La capa de reglas debería cambiar pocas veces; la base de conocimientos se actualiza semanalmente; la conversación crece en cada turno.

Formas habituales de romper la caché silenciosamente

• Incluir la fecha actual o un request_id en la instrucción. Cada llamada crea un prefijo nuevo y la tasa de aciertos es del 0 %. Calcula un hash de las entradas de la instrucción y compáralo entre llamadas.
• Construir de forma no determinista la instrucción de sistema. Si construyes el sistema desde un diccionario, el orden de iteración puede importar en algunas versiones de Python. Ordena las claves explícitamente.
• La vida útil de la caché es de ~5 minutos. Los patrones de tráfico dispersos, con una llamada cada 10 minutos, obtienen cero aciertos. Agrupa las llamadas o acepta la pérdida.
• El mínimo de 1,024 tokens. Por debajo de 1K tokens, el almacenamiento en caché al estilo OpenAI no se activa. Combina los fragmentos estáticos pequeños en un único prefijo más largo.
• Las herramientas y definiciones de funciones forman parte del prefijo. Añadir una herramienta nueva al catálogo invalida la caché para todos. Mantén estable el catálogo de herramientas y versionalo.

Verificar la tasa de aciertos

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

# Always read usage. If cached_tokens is 0 when you expected a hit,
# something's wrong — usually a non-deterministic prefix.
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,
})

# A common gotcha: putting today's date or a request_id in the system prompt
# silently invalidates the cache. Hash your inputs; verify cache_read_input_tokens
# is non-zero on the 2nd identical call.

En el panel de Kunavo, la página de uso muestra la división de caché por modelo y por día. Si ves que cache_read_input_tokens crece como porcentaje del total de entrada, la caché funciona. Si permanece en 0 o fluctúa mucho, repasa la lista de errores anteriores.

El coste real en Kunavo

La tarifa de caché de cada modelo se publica en la página de precios:

• Modelos de Anthropic: las lecturas de caché cuestan 10% de la tarifa de entrada — 2.5% on Claude Fable 5.1, 5% on Claude Opus 5.5. Las escrituras de caché cuestan 1.25× la tarifa de entrada —el multiplicador de cinco minutos de Anthropic— y Kunavo factura las escrituras de una hora con el mismo 1.25×, por debajo del 2× de Anthropic.
• Modelos de OpenAI / Gemini: las lecturas de caché cuestan 10% de la tarifa de entrada (la proporción publicada por los proveedores). Las escrituras de caché cuestan 1.25× en GPT-5.6 y GPT-6 Astra, y la tarifa de entrada normal en todos los demás modelos.
• Todos los precios de caché ya incluyen el descuento de modelo de Kunavo (por debajo del precio de referencia del upstream según el modelo). Por tanto, una lectura de caché de Sonnet 4.6 en Kunavo cuesta $3 × 0.40 × 0.10 = $0.12 per 1M tokens. Es aproximadamente 25 veces más barata que la tarifa upstream sin caché.

Cuándo la caché no es la respuesta

Algunos casos en los que el trabajo no compensa:

• Instrucciones cortas (menos de 1K tokens en total). La sobrecarga domina; simplemente no te molestes.
• Tareas de una sola ejecución sin tráfico repetido. La primera llamada es ligeramente más cara; la caché solo se amortiza a partir de la llamada 2.
• Tareas con mucha salida y poca entrada (redacción creativa, generación de código). La entrada ya representa una parte pequeña de la factura. Concéntrate en los límites del presupuesto de salida.

Para todo lo demás — chatbots RAG, agentes con un catálogo fijo de herramientas, clasificadores que funcionan sobre una rúbrica estática y canalizaciones de extracción estructurada con pocos ejemplos coherentes — el almacenamiento en caché es la optimización con mayor retorno que puedes implementar en una sola tarde. Combínalo con las otras cuatro técnicas de nuestra guía de optimización de costes y una reducción del 70 % de los costes es realista sin ningún sacrificio en la calidad de los resultados.

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