Prompt caching

El prompt caching permite reutilizar el procesamiento de un prefijo de la petición que se repite entre llamadas: el prompt de sistema, las definiciones de herramientas, un documento largo o el historial de una conversación. La primera llamada escribe ese prefijo en caché; las siguientes que empiezan exactamente igual lo leen. Leer de caché cuesta mucho menos que procesar la entrada normal y reduce la latencia; escribir cuesta algo más que la entrada normal.

Consulta los multiplicadores de precio vigentes en la documentación oficial: cambian y dependen del modelo. La lección Control de costes y prompt caching lo enseña en contexto; la receta Recortar costes con prompt caching va directa al grano.

Cómo funciona

flowchart LR
  T[tools] --> S[system] --> M[messages]
  M --> BP[cache_control]
  BP -. prefijo cacheado .-> C[(Caché)]

El prefijo se forma siempre en este orden: tools → system → messages. Un punto de corte (cache_control) marca hasta dónde se cachea. Si cambia cualquier cosa antes del punto de corte, la caché de ese punto deja de servir; si cambias algo en system, se invalida system y todo lo que va detrás, pero no tools.

Dónde poner los puntos de corte

Pon lo estable delante y lo variable detrás. Si el prompt de sistema lleva la fecha de hoy al principio, ningún prefijo coincidirá mañana; si lleva la hora exacta, no coincidirá nunca.

Ejemplo completo

Varias preguntas sobre el mismo manual. La primera llamada escribe en caché; las siguientes leen.

import anthropic

MODEL = "claude-sonnet-5-5"
client = anthropic.Anthropic()

MANUAL = open("manual.txt", encoding="utf-8").read()  # por encima del mínimo cacheable

def preguntar(pregunta: str):
    resp = client.messages.create(
        model=MODEL,
        max_tokens=512,
        system=[
            {"type": "text", "text": "Respondes dudas sobre el manual adjunto. Cita la sección."},
            {"type": "text", "text": f"<manual>{MANUAL}</manual>", "cache_control": {"type": "ephemeral"}},
        ],
        messages=[{"role": "user", "content": pregunta}],
    )
    u = resp.usage
    print(f"entrada={u.input_tokens} escritura={u.cache_creation_input_tokens} lectura={u.cache_read_input_tokens}")
    return "".join(b.text for b in resp.content if b.type == "text")

preguntar("¿Cómo se restablece la configuración de fábrica?")
preguntar("¿Qué significa el piloto rojo intermitente?")

import { readFileSync } from "node:fs";
import Anthropic from "@anthropic-ai/sdk";

const MODEL = "claude-sonnet-5-5";
const client = new Anthropic();

const MANUAL = readFileSync("manual.txt", "utf-8");

async function preguntar(pregunta: string): Promise<string> {
  const resp = await client.messages.create({
    model: MODEL,
    max_tokens: 512,
    system: [
      { type: "text", text: "Respondes dudas sobre el manual adjunto. Cita la sección." },
      { type: "text", text: `<manual>${MANUAL}</manual>`, cache_control: { type: "ephemeral" } },
    ],
    messages: [{ role: "user", content: pregunta }],
  });
  const u = resp.usage;
  console.log(`entrada=${u.input_tokens} escritura=${u.cache_creation_input_tokens} lectura=${u.cache_read_input_tokens}`);
  return resp.content.map((b) => (b.type === "text" ? b.text : "")).join("");
}

await preguntar("¿Cómo se restablece la configuración de fábrica?");
await preguntar("¿Qué significa el piloto rojo intermitente?");

# salida de ejemplo
entrada=21 escritura=18450 lectura=0
entrada=19 escritura=0 lectura=18450

Caché de una conversación

En un chat o un agente, marca el último bloque del último mensaje en cada llamada. Cada turno lee el prefijo del turno anterior y escribe solo lo nuevo.

def con_cache(historial: list[dict]) -> list[dict]:
    copia = [dict(m) for m in historial]
    ultimo = copia[-1]
    bloques = ultimo["content"]
    if isinstance(bloques, str):
        bloques = [{"type": "text", "text": bloques}]
    bloques = [dict(b) for b in bloques]
    bloques[-1]["cache_control"] = {"type": "ephemeral"}
    ultimo["content"] = bloques
    return copia

Si prefieres no gestionarlo a mano, la caché automática (cache_control en el nivel superior de la petición) coloca el punto de corte por ti.

Leer usage

La entrada total de la petición es la suma de los tres. Para saber si la caché funciona, mira la proporción de cache_read_input_tokens sobre esa suma a lo largo del día. Si es cercana a cero en un flujo repetitivo, algo está rompiendo el prefijo.

Por qué no acierta la caché

Errores frecuentes

• Datos variables arriba. Nombre de la persona, fecha u hora en system antes del documento.
• Herramientas generadas en orden distinto en cada llamada (por ejemplo, a partir de un set). Ordénalas.
• Cachear lo que se usa una vez. Pagas la escritura y nunca lees. Solo compensa si el prefijo se repite dentro del TTL.
• Copiar multiplicadores de precio de un artículo. Consulta la documentación vigente.
• No registrar usage. Sin esos campos no sabes si la caché funciona.

Ver también

• Prompt de sistema: el prompt de sistema, el candidato natural.
• Costes y límites: la caché dentro de la estrategia de costes.
• Recortar costes con prompt caching.
• Prompt caching.