Caché de prompts
Vuelve a leer un prefijo estable por una fracción del precio de entrada: qué almacenar en caché, qué no y cómo verificar que ha funcionado.
El almacenamiento de prompts en caché guarda un prefijo de tu solicitud para que las llamadas posteriores que lo compartan se facturen con una tarifa de entrada reducida. Para cualquier solicitud con un preámbulo extenso y estable —un prompt del sistema, esquemas de herramientas o un documento sobre el que se hacen preguntas—, es el cambio que ofrece el mayor retorno.
Qué contenido conviene almacenar en caché
| Adecuado | Por qué |
|---|---|
| Prompts del sistema | Idéntico byte a byte en cada llamada de una sesión |
| Definiciones de herramientas o funciones | Estables durante toda la ejecución de un agente y, a menudo, extensas |
| Un documento sobre el que se hacen preguntas repetidamente | Una carga, muchas preguntas |
| Ejemplos de aprendizaje con pocos ejemplos | Fijo y, con frecuencia, extenso |
| Inadecuado | Por qué |
|---|---|
| El último mensaje del usuario | Distinto cada vez: nunca produce un acierto de caché |
| Cualquier contenido con una marca de tiempo o un identificador de solicitud cerca del principio | Un solo byte que cambie al principio del prefijo invalida todo lo que viene después |
| Prompts cortos | Por debajo de la longitud mínima que se puede almacenar en caché, por lo que no hay nada que ganar |
Cómo marcar un prefijo
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [{
"type": "text",
"text": "<long stable instructions...>",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "Question that changes every call"}]
}Todo el contenido hasta el bloque marcado, incluido este, se convierte en el prefijo almacenado en caché. El orden importa: coloca primero el contenido estable y al final el contenido variable.
Cómo comprobar que funciona
Comprueba la usage objeto. Un acierto de caché registra los tokens como lectura de caché en lugar de entrada ordinaria. Si la lectura de caché se mantiene en cero en llamadas repetidas, tu prefijo no es realmente idéntico: una causa habitual es una marca de tiempo, un identificador de sesión o un orden no determinista de las claves de JSON en el preámbulo.
json.dumps(obj) sin sort_keys=True puede reordenar las claves entre ejecuciones, lo que cambia los bytes y hace que pierdas silenciosamente todos los aciertos de caché.Dónde importa más
Las herramientas de agentes reenvían el mismo prompt de sistema y los mismos esquemas de herramientas en cada turno. En una sesión de 50 turnos, ese preámbulo se paga 50 veces sin caché y aproximadamente una vez con ella.