Prompt Caching

Cómo Funciona

Cuando envía el mismo prefijo de prompt en múltiples llamadas API, el proveedor upstream reconoce el duplicado, omite el reprocesamiento y le cobra una tarifa con descuento por la parte en caché. Ahorros típicos:

El caching está habilitado por defecto en todos los modelos compatibles — no se requiere configuración. El proveedor gestiona el ciclo de vida de la caché automáticamente (las cachés suelen persistir de 5 a 30 minutos, variando según el proveedor y la carga).

Diseño de Prompts Optimizado para Caché

La caché coincide por prefijo — tokens desde el inicio de su array de mensajes. Diseñe sus prompts para colocar todo lo estático al frente:

# ✅ GOOD: Static content first = high cache hit rate
messages = [
    {"role": "system", "content": "You are a legal assistant. Reference case law when answering..."},
    {"role": "user", "content": "What are the elements of negligence?"},
]

# ❌ BAD: Dynamic prefix kills cache
messages = [
    {"role": "user", "content": "What are the elements of negligence?"},  # Cache miss
    {"role": "system", "content": "You are a legal assistant..."},  # Too late
]

Lista de Verificación de Diseño

• Mensaje del sistema primero — Colóquelo siempre como el primer elemento en messages
• Contexto estático antes de consultas dinámicas — Los ejemplos few-shot, el contexto RAG recuperado y las definiciones de herramientas van antes de la pregunta actual del usuario
• Sin marcas de tiempo / IDs en prefijos — No anteponga datos únicos por solicitud antes del contenido almacenable en caché
• Mantenga los prompts del sistema idénticos — El prefijo completo debe coincidir byte por byte para acertar en la caché
• Prefijos más largos = mayores ahorros — Almacenar en caché un prompt de sistema de 10K tokens ahorra mucho más que uno de 200 tokens

Monitorear Aciertos de Caché

El objeto usage de la respuesta revela si su prompt acertó en la caché:

• Claude (Anthropic): Busque cache_read_input_tokens y cache_creation_input_tokens
• GPT-4o (OpenAI): Los tokens en caché se reflejan en una facturación más baja de prompt_tokens
• Gemini (Google): El caching de contexto se muestra en los metadatos de uso

import requests

response = requests.post(
    "https://api.tokspan.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-your-key"},
    json={"model": "claude-opus-4-8", "messages": [...]},
)

# Check for cache hits in the usage object
usage = response.json()["usage"]
if "cache_read_input_tokens" in usage:
    print(f"Cache hit! {usage['cache_read_input_tokens']} tokens served from cache")
    print(f"Cache creation: {usage.get('cache_creation_input_tokens', 0)} tokens written")
else:
    print("Cache miss — all prompt tokens billed at full price")

Modelos Compatibles