Phase 11 - Lesson 15

Caching de Prompt y Caching de Contexto

Su prompt de sistema tiene 4,000 tokens. Su contexto RAG tiene 20,000 tokens. Envía ambos con cada solicitud. Y también paga por ambos — cada vez. El almacenamiento en caché de prompts (prompt caching) permite al proveedor mantener ese prefijo caliente de su lado y facturarle el 10% de la tarifa normal al reutilizarlo. Usado correctamente, reduce el costo de inferencia en un 50–90% y la latencia del primer token en un 40–85%.

Tipo: Build Lenguajes: Python Prerrequisitos: Fase 11 · 01 (Ingeniería de Prompts), Fase 11 · 05 (Ingeniería de Contexto), Fase 11 · 11 (Caching y Costo) Tiempo: ~60 minutos

El Problema

Un agente de codificación envía el mismo prompt de sistema de 15,000 tokens a Claude en cada turno de una conversación. Veinte turnos a $3/M tokens de entrada equivalen a $0.90 solo en costo de entrada — antes de cualquiera de los mensajes reales del usuario. Multiplique por 10,000 conversaciones diarias y la factura alcanzará los $9,000/día por texto que nunca cambia.

No puede reducir el prompt sin perjudicar la calidad. No puede evitar enviarlo — el modelo lo necesita en cada turno. La única opción es dejar de pagar el precio completo por un prefijo que el proveedor ya ha procesado.

Esa opción es el almacenamiento en caché de prompts. Anthropic lo lanzó en agosto de 2024 (con una variante de TTL extendido de 1 hora en 2025), OpenAI lo automatizó más tarde ese año, Google lanzó el almacenamiento en caché de contexto explícito junto con Gemini 1.5, y los tres ahora lo ofrecen como una característica de primera clase en sus modelos de frontera.

El Concepto

El funcionamiento. Cuando el prefijo de una solicitud coincide con el de una solicitud reciente, el proveedor sirve el KV-cache de la ejecución anterior en lugar de volver a codificar los tokens. Usted paga un pequeño recargo de escritura la primera vez y un gran descuento de lectura cada vez posterior.

Tres variantes de proveedores en 2026.

La invariante. Los tres almacenan en caché solo prefijos. Si algún token difiere entre solicitudes, todo lo que sigue al primer token diferente se considera un fallo de caché (miss). Coloque las partes estables arriba y las partes variables abajo.

El diseño favorable al caché

[system prompt]          <-- cache this
[tool definitions]       <-- cache this
[few-shot examples]      <-- cache this
[retrieved documents]    <-- cache if reused, else don't
[conversation history]   <-- cache up to last turn
[current user message]   <-- never cache (different every time)

Si altera el orden — colocando el mensaje del usuario por encima del prompt de sistema, o intercalando búsquedas dinámicas entre los ejemplos few-shot — el caché nunca se activará.

El cálculo de punto de equilibrio

El recargo de escritura del 25% de Anthropic significa que un bloque en caché debe leerse al menos dos veces para generar un ahorro neto de dinero. 1 escritura + 1 lectura promedia un costo de 0.675x por solicitud (ahorra un 32%); 1 escritura + 10 lecturas promedia 0.205x (ahorra un 80%). Regla general: almacene en caché cualquier elemento que prevea reutilizar al menos 3 veces dentro del TTL.

Construya

Paso 1: Almacenamiento en caché de prompts de Anthropic con marcadores explícitos

import anthropic

client = anthropic.Anthropic()

SYSTEM = [
    {
        "type": "text",
        "text": "You are a senior Python reviewer. Follow the rubric exactly.\n\n" + RUBRIC_15K_TOKENS,
        "cache_control": {"type": "ephemeral"},
    }
]

def review(code: str):
    return client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        system=SYSTEM,
        messages=[{"role": "user", "content": code}],
    )

El marcador cache_control le indica a Anthropic que almacene el bloque durante 5 minutos. La reutilización dentro de esa ventana genera un acierto (hit); la reutilización después de ese tiempo expira y escribe nuevamente.

Campos de uso en la respuesta:

response = review(code_a)
response.usage
# InputTokensUsage(
#     input_tokens=120,
#     cache_creation_input_tokens=15023,   # paid at 1.25x
#     cache_read_input_tokens=0,
#     output_tokens=340,
# )

response_b = review(code_b)
response_b.usage
# cache_creation_input_tokens=0
# cache_read_input_tokens=15023           # paid at 0.1x

Verifique ambos campos en CI; si cache_read_input_tokens permanece en cero entre solicitudes, sus claves de caché se están desviando (drifting).

Paso 2: TTL extendido de una hora

Para tareas en lote (batch jobs) de larga duración, el valor por defecto de 5 minutos expira entre ejecuciones. Defina ttl:

{"type": "text", "text": RUBRIC, "cache_control": {"type": "ephemeral", "ttl": "1h"}}

Un TTL de 1 hora cuesta el doble de recargo por escritura (50% sobre la línea de base en lugar del 25%), pero se compensa rápidamente en cualquier lote que reutilice el prefijo más de 5 veces.

Paso 3: Almacenamiento en caché automático de OpenAI

OpenAI no requiere configuración alguna. Cualquier prefijo de más de 1,024 tokens que coincida con una solicitud reciente recibe un descuento del 50% de forma automática.

from openai import OpenAI
client = OpenAI()

resp = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},   # long and stable
        {"role": "user", "content": user_msg},
    ],
)
resp.usage.prompt_tokens_details.cached_tokens  # the discounted portion

Se aplica la misma regla de diseño favorable al caché. Dos cosas invalidan el caché de OpenAI que no afectan al de Anthropic: cambiar el campo user (utilizado como componente de la clave de caché) y reordenar las herramientas.

Paso 4: Almacenamiento en caché de contexto explícito de Gemini

Gemini trata el caché como un objeto de primera clase que usted crea y nombra:

from google import genai
from google.genai import types

client = genai.Client()

cache = client.caches.create(
    model="gemini-3-pro",
    config=types.CreateCachedContentConfig(
        display_name="rubric-v3",
        system_instruction=RUBRIC,
        contents=[FEW_SHOT_EXAMPLES],
        ttl="3600s",
    ),
)

resp = client.models.generate_content(
    model="gemini-3-pro",
    contents=["Review this code:\n" + code],
    config=types.GenerateContentConfig(cached_content=cache.name),
)

Gemini cobra por el almacenamiento por token·hora durante todo el tiempo que el caché permanezca activo, y las lecturas se facturan a ~25% de la tarifa de entrada normal. Esta es la estructura adecuada cuando reutiliza el mismo prompt gigante en muchas sesiones a lo largo de varios días.

Paso 5: Medición de la tasa de aciertos (hit rate) en producción

Consulte code/main.py para ver un contador simulado de tres proveedores que realiza un seguimiento de las escrituras/lecturas/fallos y calcula el costo combinado por cada 1K solicitudes. Condicione los despliegues a una tasa de aciertos objetivo; la mayoría de las configuraciones de producción de Anthropic deberían alcanzar una fracción de lectura >80% después de la fase de calentamiento (warmup)."

Errores comunes que todavía persisten en 2026

• Marcas de tiempo dinámicas en la parte superior. "Current time: 2026-04-22 15:30:02" al principio del prompt de sistema. Cada solicitud genera un fallo de caché. Mueva las marcas de tiempo por debajo del punto de interrupción del caché.
• Reordenamiento de herramientas. Serialice las herramientas en un orden estable — una reorganización del diccionario entre despliegues romperá todos los aciertos.
• Cuasi-duplicados en texto libre. "You are helpful." frente a "You are a helpful assistant." — una diferencia de un solo byte = fallo total de caché.
• Bloques demasiado pequeños. Anthropic impone un límite mínimo de 1,024 tokens (2,048 para Haiku). Los bloques más pequeños simplemente no se almacenan en caché.
• Paneles de control de costos ciegos. Separe los "tokens de entrada" en cacheados vs no cacheados. De lo contrario, una caída en el tráfico parecerá un éxito de almacenamiento en caché.

Cuándo Usarlo

Combine esto con el almacenamiento en caché semántico (Fase 11 · 11) para la capa de mensajes de usuario: el almacenamiento en caché de prompts maneja la reutilización de tokens idénticos, mientras que el almacenamiento en caché semántico maneja la reutilización de significados idénticos.

Entréguelo

Guarde outputs/skill-prompt-caching-planner.md:

---
name: prompt-caching-planner
description: Design a cache-friendly prompt layout and pick the right provider caching mode.
version: 1.0.0
phase: 11
lesson: 15
tags: [llm-engineering, caching, cost]
---

Given a prompt (system + tools + few-shot + retrieval + history + user) and a usage profile (requests per hour, TTL needed, provider), output:

1. Layout. Reordered sections with a single cache breakpoint marked; explain which sections are stable, which are volatile.
2. Provider mode. Anthropic cache_control, OpenAI automatic, or Gemini CachedContent. Justify from TTL and reuse pattern.
3. Break-even. Expected reads per write within TTL; net cost vs no-cache with math.
4. Verification plan. CI assertion that cache_read_input_tokens > 0 on the second identical request; dashboard split by cached vs uncached tokens.
5. Failure modes. List the three most likely reasons the cache will miss in this setup (dynamic timestamp, tool reorder, near-duplicate text) and how you will prevent each.

Refuse to ship a cache plan that places a dynamic field above the breakpoint. Refuse to enable 1h TTL without a reuse count that makes the 2x write premium pay back.

Ejercicios

1. Fácil. Realice una conversación de 10 turnos con un prompt de sistema de 5,000 tokens contra Claude. Ejecútela sin cache_control y luego con él. Indique la factura de tokens de entrada para cada caso.
2. Medio. Escriba un entorno de pruebas (test harness) que, dado una plantilla de prompt y un registro de solicitudes, calcule la tasa de aciertos esperada y el ahorro en dólares por proveedor (Anthropic 5m, Anthropic 1h, OpenAI automático, Gemini explícito).
3. Difícil. Construa un optimizador de diseño: dado un prompt y una lista de campos marcados como stable=True/False, reescriba el prompt para colocar un único punto de interrupción del caché en la posición máxima que resulte favorable para el caché, sin perder información. Verifique en un endpoint real de Anthropic.

Términos Clave

Lecturas Adicionales

• Anthropic — Prompt caching — cache_control, TTL de 1h, tablas de punto de equilibrio.
• OpenAI — Prompt caching — coincidencia automática de prefijo.
• Google — Context caching — API CachedContent y precios de almacenamiento.
• Anthropic engineering — Prompt caching for long-context workloads — artículo original de lanzamiento con cifras de latencia.
• Fase 11 · 05 (Ingeniería de Contexto) — dónde dividir el prompt para que el caché funcione.
• Fase 11 · 11 (Caching y Costo) — combine el almacenamiento en caché de prompts con un caché semántico en los mensajes del usuario.
• Pope et al., "Efficiently Scaling Transformer Inference" (2022) — el modelo de memoria KV-cache que el almacenamiento en caché de prompts expone a los usuarios; explica por que un prefijo almacenado en caché es ~10 veces más barato de volver a leer que de volver a calcular.
• Agrawal et al., "SARATHI: Efficient LLM Inference by Piggybacking Decodes with Chunked Prefills" (2023) — el prefill es la fase que el almacenamiento en caché de prompts evita; este artículo explica por qué el TTFT disminuye drásticamente con un acierto de caché mientras que el TPOT no se ve afectado.
• Leviathan et al., "Fast Inference from Transformers via Speculative Decoding" (2023) — el almacenamiento en caché de prompts se sitúa junto con la decodificación especulativa, Flash Attention y MQA/GQA como herramientas que moderan la curva de costos de inferencia; lea esto para conocer las otras tres.