Caché de prompts
El caché de prompts es una característica poderosa que optimiza el uso de tu API al permitir reanudar desde prefijos específicos en tus prompts. Este enfoque reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o prompts con elementos consistentes.
Aquí tienes un ejemplo de cómo implementar el caché de prompts con la API de Messages usando un bloque cache_control
:
En este ejemplo, todo el texto de “Orgullo y Prejuicio” se almacena en caché usando el parámetro cache_control
. Esto permite la reutilización de este texto grande a través de múltiples llamadas a la API sin reprocesarlo cada vez. Cambiar solo el mensaje del usuario te permite hacer varias preguntas sobre el libro mientras utilizas el contenido en caché, lo que lleva a respuestas más rápidas y mayor eficiencia.
Cómo funciona el caché de prompts
Cuando envías una solicitud con el caché de prompts habilitado:
- El sistema verifica si un prefijo de prompt, hasta un punto de ruptura de caché especificado, ya está en caché desde una consulta reciente.
- Si se encuentra, usa la versión en caché, reduciendo el tiempo de procesamiento y los costos.
- De lo contrario, procesa el prompt completo y almacena en caché el prefijo una vez que comienza la respuesta.
Esto es especialmente útil para:
- Prompts con muchos ejemplos
- Grandes cantidades de contexto o información de fondo
- Tareas repetitivas con instrucciones consistentes
- Conversaciones largas de múltiples turnos
Por defecto, el caché tiene una duración de 5 minutos. El caché se actualiza sin costo adicional cada vez que se usa el contenido en caché.
Si encuentras que 5 minutos es muy poco tiempo, Anthropic también ofrece una duración de caché de 1 hora.
Para más información, consulta Duración de caché de 1 hora.
El caché de prompts almacena en caché el prefijo completo
El caché de prompts hace referencia a todo el prompt - tools
, system
, y messages
(en ese orden) hasta e incluyendo el bloque designado con cache_control
.
Precios
El caché de prompts introduce una nueva estructura de precios. La tabla a continuación muestra el precio por millón de tokens para cada modelo compatible:
Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
---|---|---|---|---|---|
Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Opus 4 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.5 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Haiku 3.5 | $0.80 / MTok | $1 / MTok | $1.6 / MTok | $0.08 / MTok | $4 / MTok |
Claude Opus 3 (deprecated) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Haiku 3 | $0.25 / MTok | $0.30 / MTok | $0.50 / MTok | $0.03 / MTok | $1.25 / MTok |
La tabla anterior refleja los siguientes multiplicadores de precios para el caché de prompts:
- Los tokens de escritura de caché de 5 minutos son 1.25 veces el precio base de tokens de entrada
- Los tokens de escritura de caché de 1 hora son 2 veces el precio base de tokens de entrada
- Los tokens de lectura de caché son 0.1 veces el precio base de tokens de entrada
Cómo implementar el caché de prompts
Modelos compatibles
El caché de prompts está actualmente disponible en:
- Claude Opus 4.1
- Claude Opus 4
- Claude Sonnet 4
- Claude Sonnet 3.7
- Claude Sonnet 3.5 (obsoleto)
- Claude Haiku 3.5
- Claude Haiku 3
- Claude Opus 3 (obsoleto)
Estructurando tu prompt
Coloca el contenido estático (definiciones de herramientas, instrucciones del sistema, contexto, ejemplos) al principio de tu prompt. Marca el final del contenido reutilizable para el caché usando el parámetro cache_control
.
Los prefijos de caché se crean en el siguiente orden: tools
, system
, luego messages
. Este orden forma una jerarquía donde cada nivel se basa en los anteriores.
Cómo funciona la verificación automática de prefijos
Puedes usar solo un punto de ruptura de caché al final de tu contenido estático, y el sistema encontrará automáticamente el prefijo coincidente más largo. Así es como funciona:
- Cuando agregas un punto de ruptura
cache_control
, el sistema verifica automáticamente coincidencias de caché en todos los límites de bloques de contenido anteriores (hasta aproximadamente 20 bloques antes de tu punto de ruptura explícito) - Si alguna de estas posiciones anteriores coincide con contenido en caché de solicitudes anteriores, el sistema usa el prefijo coincidente más largo
- Esto significa que no necesitas múltiples puntos de ruptura solo para habilitar el caché - uno al final es suficiente
Cuándo usar múltiples puntos de ruptura
Puedes definir hasta 4 puntos de ruptura de caché si quieres:
- Almacenar en caché diferentes secciones que cambian con diferentes frecuencias (por ejemplo, las herramientas rara vez cambian, pero el contexto se actualiza diariamente)
- Tener más control sobre exactamente qué se almacena en caché
- Asegurar el caché para contenido más de 20 bloques antes de tu punto de ruptura final
Limitación importante: La verificación automática de prefijos solo mira hacia atrás aproximadamente 20 bloques de contenido desde cada punto de ruptura explícito. Si tu prompt tiene más de 20 bloques de contenido antes de tu punto de ruptura de caché, el contenido anterior a eso no será verificado para coincidencias de caché a menos que agregues puntos de ruptura adicionales.
Limitaciones del caché
La longitud mínima de prompt que se puede almacenar en caché es:
- 1024 tokens para Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (obsoleto) y Claude Opus 3 (obsoleto)
- 2048 tokens para Claude Haiku 3.5 y Claude Haiku 3
Los prompts más cortos no se pueden almacenar en caché, incluso si están marcados con cache_control
. Cualquier solicitud para almacenar en caché menos de este número de tokens será procesada sin caché. Para ver si un prompt fue almacenado en caché, consulta los campos de uso de la respuesta.
Para solicitudes concurrentes, ten en cuenta que una entrada de caché solo está disponible después de que comience la primera respuesta. Si necesitas coincidencias de caché para solicitudes paralelas, espera a la primera respuesta antes de enviar solicitudes posteriores.
Actualmente, “ephemeral” es el único tipo de caché compatible, que por defecto tiene una duración de 5 minutos.
Entendiendo los costos de los puntos de ruptura de caché
Los puntos de ruptura de caché en sí mismos no agregan ningún costo. Solo se te cobra por:
- Escrituras de caché: Cuando se escribe contenido nuevo al caché (25% más que los tokens de entrada base para TTL de 5 minutos)
- Lecturas de caché: Cuando se usa contenido en caché (10% del precio de token de entrada base)
- Tokens de entrada regulares: Para cualquier contenido no almacenado en caché
Agregar más puntos de ruptura cache_control
no aumenta tus costos - aún pagas la misma cantidad basada en qué contenido se almacena en caché y se lee realmente. Los puntos de ruptura simplemente te dan control sobre qué secciones pueden ser almacenadas en caché independientemente.
Qué se puede almacenar en caché
La mayoría de los bloques en la solicitud pueden ser designados para caché con cache_control
. Esto incluye:
- Herramientas: Definiciones de herramientas en el array
tools
- Mensajes del sistema: Bloques de contenido en el array
system
- Mensajes de texto: Bloques de contenido en el array
messages.content
, para turnos tanto de usuario como de asistente - Imágenes y Documentos: Bloques de contenido en el array
messages.content
, en turnos de usuario - Uso de herramientas y resultados de herramientas: Bloques de contenido en el array
messages.content
, en turnos tanto de usuario como de asistente
Cada uno de estos elementos puede ser marcado con cache_control
para habilitar el caché para esa porción de la solicitud.
Qué no se puede almacenar en caché
Aunque la mayoría de los bloques de solicitud pueden ser almacenados en caché, hay algunas excepciones:
-
Los bloques de pensamiento no pueden ser almacenados en caché directamente con
cache_control
. Sin embargo, los bloques de pensamiento SÍ pueden ser almacenados en caché junto con otro contenido cuando aparecen en turnos de asistente anteriores. Cuando se almacenan en caché de esta manera, SÍ cuentan como tokens de entrada cuando se leen desde el caché. -
Los sub-bloques de contenido (como citas) en sí mismos no pueden ser almacenados en caché directamente. En su lugar, almacena en caché el bloque de nivel superior.
En el caso de las citas, los bloques de contenido de documento de nivel superior que sirven como material fuente para las citas pueden ser almacenados en caché. Esto te permite usar el caché de prompts con citas de manera efectiva almacenando en caché los documentos que las citas referenciarán.
-
Los bloques de texto vacíos no pueden ser almacenados en caché.
Qué invalida el caché
Las modificaciones al contenido en caché pueden invalidar parte o todo el caché.
Como se describe en Estructurando tu prompt, el caché sigue la jerarquía: tools
→ system
→ messages
. Los cambios en cada nivel invalidan ese nivel y todos los niveles posteriores.
La siguiente tabla muestra qué partes del caché son invalidadas por diferentes tipos de cambios. ✘ indica que el caché es invalidado, mientras que ✓ indica que el caché permanece válido.
Qué cambia | Caché de herramientas | Caché del sistema | Caché de mensajes | Impacto |
---|---|---|---|---|
Definiciones de herramientas | ✘ | ✘ | ✘ | Modificar definiciones de herramientas (nombres, descripciones, parámetros) invalida todo el caché |
Alternar búsqueda web | ✓ | ✘ | ✘ | Habilitar/deshabilitar la búsqueda web modifica el prompt del sistema |
Alternar citas | ✓ | ✘ | ✘ | Habilitar/deshabilitar citas modifica el prompt del sistema |
Elección de herramienta | ✓ | ✓ | ✘ | Los cambios al parámetro tool_choice solo afectan los bloques de mensajes |
Imágenes | ✓ | ✓ | ✘ | Agregar/quitar imágenes en cualquier lugar del prompt afecta los bloques de mensajes |
Parámetros de pensamiento | ✓ | ✓ | ✘ | Los cambios en la configuración de pensamiento extendido (habilitar/deshabilitar, presupuesto) afectan los bloques de mensajes |
Resultados no-herramienta pasados a solicitudes de pensamiento extendido | ✓ | ✓ | ✘ | Cuando se pasan resultados no-herramienta en solicitudes mientras el pensamiento extendido está habilitado, todos los bloques de pensamiento previamente almacenados en caché se eliminan del contexto, y cualquier mensaje en contexto que siga a esos bloques de pensamiento se elimina del caché. Para más detalles, consulta Caché con bloques de pensamiento. |
Seguimiento del rendimiento del caché
Monitorea el rendimiento del caché usando estos campos de respuesta de la API, dentro de usage
en la respuesta (o evento message_start
si estás transmitiendo):
cache_creation_input_tokens
: Número de tokens escritos al caché al crear una nueva entrada.cache_read_input_tokens
: Número de tokens recuperados del caché para esta solicitud.input_tokens
: Número de tokens de entrada que no fueron leídos desde o usados para crear un caché.
Mejores prácticas para un caché efectivo
Para optimizar el rendimiento del caché de prompts:
- Almacena en caché contenido estable y reutilizable como instrucciones del sistema, información de fondo, contextos grandes o definiciones de herramientas frecuentes.
- Coloca el contenido en caché al principio del prompt para el mejor rendimiento.
- Usa puntos de ruptura de caché estratégicamente para separar diferentes secciones de prefijo que se pueden almacenar en caché.
- Analiza regularmente las tasas de acierto de caché y ajusta tu estrategia según sea necesario.
Optimizando para diferentes casos de uso
Adapta tu estrategia de caché de prompts a tu escenario:
- Agentes conversacionales: Reduce el costo y la latencia para conversaciones extendidas, especialmente aquellas con instrucciones largas o documentos subidos.
- Asistentes de codificación: Mejora el autocompletado y las preguntas y respuestas de la base de código manteniendo secciones relevantes o una versión resumida de la base de código en el prompt.
- Procesamiento de documentos grandes: Incorpora material completo de formato largo incluyendo imágenes en tu prompt sin aumentar la latencia de respuesta.
- Conjuntos de instrucciones detallados: Comparte listas extensas de instrucciones, procedimientos y ejemplos para afinar las respuestas de Claude. Los desarrolladores a menudo incluyen uno o dos ejemplos en el prompt, pero con el caché de prompts puedes obtener un rendimiento aún mejor incluyendo más de 20 ejemplos diversos de respuestas de alta calidad.
- Uso de herramientas agénticas: Mejora el rendimiento para escenarios que involucran múltiples llamadas de herramientas y cambios de código iterativos, donde cada paso típicamente requiere una nueva llamada a la API.
- Hablar con libros, artículos, documentación, transcripciones de podcasts y otro contenido de formato largo: Da vida a cualquier base de conocimiento incrustando todo el documento(s) en el prompt, y permitiendo a los usuarios hacerle preguntas.
Solución de problemas comunes
Si experimentas comportamiento inesperado:
- Asegúrate de que las secciones en caché sean idénticas y estén marcadas con cache_control en las mismas ubicaciones a través de las llamadas
- Verifica que las llamadas se hagan dentro de la duración del caché (5 minutos por defecto)
- Verifica que el uso de
tool_choice
e imágenes permanezca consistente entre llamadas - Valida que estés almacenando en caché al menos el número mínimo de tokens
- El sistema verifica automáticamente coincidencias de caché en límites de bloques de contenido anteriores (hasta ~20 bloques antes de tu punto de ruptura). Para prompts con más de 20 bloques de contenido, puedes necesitar parámetros
cache_control
adicionales más temprano en el prompt para asegurar que todo el contenido pueda ser almacenado en caché
Los cambios a tool_choice
o la presencia/ausencia de imágenes en cualquier lugar del prompt invalidarán el caché, requiriendo que se cree una nueva entrada de caché. Para más detalles sobre la invalidación del caché, consulta Qué invalida el caché.
Caché con bloques de pensamiento
Cuando uses pensamiento extendido con caché de prompts, los bloques de pensamiento tienen un comportamiento especial:
Caché automático junto con otro contenido: Aunque los bloques de pensamiento no pueden ser marcados explícitamente con cache_control
, se almacenan en caché como parte del contenido de la solicitud cuando haces llamadas posteriores a la API con resultados de herramientas. Esto comúnmente sucede durante el uso de herramientas cuando pasas bloques de pensamiento de vuelta para continuar la conversación.
Conteo de tokens de entrada: Cuando los bloques de pensamiento se leen desde el caché, cuentan como tokens de entrada en tus métricas de uso. Esto es importante para el cálculo de costos y el presupuesto de tokens.
Patrones de invalidación de caché:
- El caché permanece válido cuando solo se proporcionan resultados de herramientas como mensajes de usuario
- El caché se invalida cuando se agrega contenido de usuario que no es resultado de herramienta, causando que todos los bloques de pensamiento anteriores sean eliminados
- Este comport
amiento de caché ocurre incluso sin marcadores cache_control
explícitos
Para más detalles sobre la invalidación del caché, consulta Qué invalida el caché.
Ejemplo con uso de herramientas:
Cuando se incluye un bloque de usuario que no es resultado de herramienta, designa un nuevo bucle de asistente y todos los bloques de pensamiento anteriores se eliminan del contexto.
Para información más detallada, consulta la documentación de pensamiento extendido.
Almacenamiento y compartición de caché
-
Aislamiento de Organización: Los cachés están aislados entre organizaciones. Diferentes organizaciones nunca comparten cachés, incluso si usan prompts idénticos.
-
Coincidencia Exacta: Las coincidencias de caché requieren segmentos de prompt 100% idénticos, incluyendo todo el texto e imágenes hasta e incluyendo el bloque marcado con control de caché.
-
Generación de Tokens de Salida: El caché de prompts no tiene efecto en la generación de tokens de salida. La respuesta que recibes será idéntica a la que obtendrías si no se usara el caché de prompts.
Duración de caché de 1 hora
Si encuentras que 5 minutos es muy poco tiempo, Anthropic también ofrece una duración de caché de 1 hora.
Para usar el caché extendido, incluye ttl
en la definición cache_control
así:
La respuesta incluirá información detallada del caché como la siguiente:
Ten en cuenta que el campo actual cache_creation_input_tokens
es igual a la suma de los valores en el objeto cache_creation
.
Cuándo usar el caché de 1 hora
Si tienes prompts que se usan con una cadencia regular (es decir, prompts del sistema que se usan más frecuentemente que cada 5 minutos), continúa usando el caché de 5 minutos, ya que este continuará siendo actualizado sin cargo adicional.
El caché de 1 hora se usa mejor en los siguientes escenarios:
- Cuando tienes prompts que probablemente se usan menos frecuentemente que 5 minutos, pero más frecuentemente que cada hora. Por ejemplo, cuando un agente secundario agéntico tomará más de 5 minutos, o cuando almacenas una conversación de chat larga con un usuario y generalmente esperas que ese usuario puede no responder en los próximos 5 minutos.
- Cuando la latencia es importante y tus prompts de seguimiento pueden ser enviados más allá de 5 minutos.
- Cuando quieres mejorar tu utilización de límite de tasa, ya que las coincidencias de caché no se deducen de tu límite de tasa.
El caché de 5 minutos y 1 hora se comportan igual con respecto a la latencia. Generalmente verás un tiempo mejorado hasta el primer token para documentos largos.
Mezclando diferentes TTLs
Puedes usar controles de caché tanto de 1 hora como de 5 minutos en la misma solicitud, pero con una restricción importante: Las entradas de caché con TTL más largo deben aparecer antes que TTLs más cortos (es decir, una entrada de caché de 1 hora debe aparecer antes que cualquier entrada de caché de 5 minutos).
Cuando mezclas TTLs, determinamos tres ubicaciones de facturación en tu prompt:
- Posición
A
: El conteo de tokens en la coincidencia de caché más alta (o 0 si no hay coincidencias). - Posición
B
: El conteo de tokens en el bloquecache_control
de 1 hora más alto después deA
(o igual aA
si no existe ninguno). - Posición
C
: El conteo de tokens en el último bloquecache_control
.
Si B
y/o C
son mayores que A
, necesariamente serán fallos de caché, porque A
es la coincidencia de caché más alta.
Se te cobrará por:
- Tokens de lectura de caché para
A
. - Tokens de escritura de caché de 1 hora para
(B - A)
. - Tokens de escritura de caché de 5 minutos para
(C - B)
.
Aquí hay 3 ejemplos. Esto representa los tokens de entrada de 3 solicitudes, cada una de las cuales tiene diferentes coincidencias de caché y fallos de caché. Cada una tiene un precio calculado diferente, mostrado en las cajas de colores, como resultado.
Ejemplos de caché de prompts
Para ayudarte a comenzar con el caché de prompts, hemos preparado un libro de cocina de caché de prompts con ejemplos detallados y mejores prácticas.
A continuación, hemos incluido varios fragmentos de código que muestran varios patrones de caché de prompts. Estos ejemplos demuestran cómo implementar el caché en diferentes escenarios, ayudándote a entender las aplicaciones prácticas de esta característica: