Caché de prompts de Claude

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [Place complete text content here]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    api_key="sk-***", # Replace with the key you generated in AiHubMix
    base_url="https://aihubmix.com"
)

# Streaming response with caching
with client.messages.stream(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    thinking={
        "type": "enabled",
        "budget_tokens": 16000
    },
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# Non-streaming response
message = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works."
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
)
print(message.content)

import requests

url = "https://aihubmix.com/v1/messages"
headers = {
    "content-type": "application/json",
    "x-api-key": "sk-***", # Replace with the key you generated in AiHubMix
    "anthropic-version": "2023-06-01"
}
data = {
    "stream": True,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}]
}

response = requests.post(url, headers=headers, json=data, stream=True)

# Check response status
if response.status_code == 200:
    # Process the streaming response
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))
else:
    print(f"Error: {response.status_code}, {response.text}")

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

Cómo funciona la caché de prompts

1. El sistema comprueba si un prefijo del prompt, hasta un punto de corte de caché especificado, ya está almacenado en caché de una consulta reciente.
2. Si lo encuentra, utiliza la versión en caché, reduciendo el tiempo de procesamiento y los costos.
3. De lo contrario, procesa el prompt completo y almacena en caché el prefijo cuando 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

​

Error común: caché que “solo escribe pero nunca lee”

​

❌ Forma incorrecta: poner la pregunta que cambia en cada turno antes del punto de corte

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这份资料的核心观点。" },                          // ← 每轮会变,却放在断点前
        { "type": "text", "text": "<大文档>", "cache_control": { "type": "ephemeral" } }   // 断点
      ]
    }
  ]
}

​

✅ Forma correcta: el documento extenso primero + punto de corte + la pregunta al final

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<固定不变的大文档/参考资料，≥4096 token>", "cache_control": { "type": "ephemeral" } },  // 断点;前缀恒定
        { "type": "text", "text": "请总结这份资料的核心观点。" }                                                          // ← 每轮变化的问题,放在断点之后
      ]
    }
  ]
}

​

Comparación medida (claude-opus-4-6, intervalo de unos segundos entre las dos llamadas)

1. Coloca el bloque grande e invariable (documento de referencia, contexto extenso) en la parte más al frente del mensaje user de messages, con el cache_control marcado al final de ese bloque; ese contenido no puede cambiar ni un carácter.
2. Pon la pregunta/instrucción que cambia en cada turno después del punto de corte (en el mismo mensaje user, tras el documento extenso, o en mensajes posteriores); en las conversaciones de múltiples turnos solo añade contenido al final y no vuelvas a modificar los mensajes históricos.
3. Cuando thinking está activado, los bloques de razonamiento de los turnos históricos del asistente deben devolverse tal cual; de lo contrario el prefijo también se rompe (ver más abajo “Qué no se puede almacenar en caché”).
4. Si un bloque es menor que el umbral mínimo de caché (varía entre 512 y 4.096 tokens según el modelo, ver más abajo “Limitaciones de la caché”), no se escribirá en caché aunque esté marcado con cache_control; este es el comportamiento esperado.

​

Precios

• Los tokens de escritura en caché de 5 minutos cuestan 1,25 veces el precio de los tokens de entrada base
• Los tokens de escritura en caché de 1 hora cuestan 2 veces el precio de los tokens de entrada base
• Los tokens de lectura de caché cuestan 0,1 veces el precio de los tokens de entrada base
• Los tokens regulares de entrada y salida tienen los precios estándar de la plataforma

​

Cómo implementar la caché de prompts

​

Modelos admitidos

​

Caché automática (cache_control de nivel superior)

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are an AI assistant tasked with analyzing literary works.",
  "messages": [
    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
  ]
}

​

Estructuración de tu prompt

​

Limitaciones de la caché

• “ephemeral”: Vida útil predeterminada de 5 minutos
• Caché de 1 hora: Establece "ttl": "1h" en cache_control, para escenarios que requieran una duración de caché más larga

​

Duración de caché de 1 hora

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

Cuándo usar la caché de 1 hora

• Procesamiento por lotes: Procesar grandes volúmenes de solicitudes con prefijos comunes
• Sesiones de larga duración: Conversaciones que requieren mantener el contexto durante periodos prolongados
• Análisis de documentos grandes: Múltiples tipos diferentes de análisis sobre el mismo documento
• Preguntas y respuestas sobre código: Múltiples consultas sobre la misma base de código a lo largo de periodos prolongados

​

Combinando distintos TTL

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

Qué se puede almacenar en caché

• Herramientas: Definiciones de herramientas en el array tools
• Mensajes del sistema: Bloques de contenido en el array system
• Mensajes: Bloques de contenido en el array messages.content, tanto en los turnos del usuario como en los del asistente
• Imágenes y documentos: Bloques de contenido en el array messages.content, en los turnos del usuario
• Uso de herramientas y resultados de herramientas: Bloques de contenido en el array messages.content, tanto en los turnos del usuario como en los del asistente

​

Qué no se puede almacenar en caché

• Los bloques de razonamiento (thinking) no pueden almacenarse en caché directamente con cache_control. Sin embargo, los bloques de razonamiento SÍ pueden almacenarse en caché junto con otro contenido cuando aparecen en turnos anteriores del asistente. Cuando se almacenan así, SÍ cuentan como tokens de entrada cuando se leen de la caché.
• Los subbloques de contenido (como las citas) no pueden almacenarse en caché directamente por sí mismos. En su lugar, almacena en caché el bloque de nivel superior.
• Los bloques de texto vacíos no se pueden almacenar en caché.

​

Seguimiento del rendimiento de la caché

• cache_creation_input_tokens: Número de tokens escritos en la caché al crear una nueva entrada.
• cache_read_input_tokens: Número de tokens recuperados de la caché para esta solicitud.
• input_tokens: Número de tokens de entrada que no se leyeron desde la caché ni se usaron para crear una caché.

​

Buenas prácticas para una caché eficaz

• Almacena en caché contenido estable y reutilizable como instrucciones del sistema, información de fondo, contextos extensos o definiciones de herramientas frecuentes.
• Coloca el contenido en caché al principio del prompt para obtener el mejor rendimiento.
• Usa los puntos de corte de caché de forma estratégica para separar distintas secciones de prefijo cacheables.
• Analiza regularmente las tasas de acierto de caché y ajusta tu estrategia según sea necesario.
• Para contenido a largo plazo, considera usar la caché de 1 hora para una mejor eficiencia de costos.

​

Optimización para distintos casos de uso

• Agentes conversacionales: Reduce el costo y la latencia en conversaciones extensas, especialmente aquellas con instrucciones largas o documentos cargados.
• Asistentes de programación: Mejora el autocompletado y las preguntas y respuestas sobre la base de código manteniendo en el prompt las secciones relevantes o una versión resumida de la base de código.
• Procesamiento de documentos grandes: Incorpora material extenso completo, incluidas imágenes, en tu prompt sin aumentar la latencia de la respuesta.
• Conjuntos de instrucciones detallados: Comparte listas exhaustivas de instrucciones, procedimientos y ejemplos para afinar las respuestas de Claude. Los desarrolladores suelen incluir uno o dos ejemplos en el prompt, pero con la caché de prompts puedes obtener un rendimiento aún mejor incluyendo más de 20 ejemplos diversos de respuestas de alta calidad.
• Uso agentic de herramientas: Mejora el rendimiento en escenarios que involucran múltiples llamadas a herramientas y cambios iterativos de código, donde cada paso suele requerir una nueva llamada a la API.
• Conversar con libros, papers, documentación, transcripciones de podcasts y otro contenido extenso: Da vida a cualquier base de conocimiento incrustando los documentos completos en el prompt y dejando que los usuarios hagan preguntas.

​

Solución de problemas comunes

• Asegúrate de que las secciones cacheadas sean idénticas y estén marcadas con cache_control en las mismas ubicaciones en todas las llamadas
• Comprueba que las llamadas se realicen dentro de la vida útil de la caché (5 minutos o 1 hora)
• Verifica que tool_choice y el uso de imágenes se mantengan consistentes entre las llamadas
• Valida que estás almacenando en caché al menos el número mínimo de tokens
• Aunque el sistema intentará utilizar el contenido cacheado previamente en las posiciones anteriores a un punto de corte de caché, puedes usar un parámetro cache_control adicional para garantizar la búsqueda en caché en porciones previas del prompt, lo que puede ser útil en consultas con listas muy largas de bloques de contenido

​

Almacenamiento y compartición de la caché

• Aislamiento por organización: Las cachés están aisladas entre organizaciones. Distintas organizaciones nunca comparten cachés, incluso si usan prompts idénticos.
• Coincidencia exacta: Los aciertos de caché requieren segmentos de prompt 100 % idénticos, incluido todo el texto e imágenes hasta el bloque marcado con cache_control. El mismo bloque debe marcarse con cache_control tanto en la lectura como en la creación de la caché.
• Generación de tokens de salida: La caché de prompts no afecta a la generación de tokens de salida. La respuesta que recibirás será idéntica a la que obtendrías sin caché de prompts.

​

Habilitar la caché de Claude en clientes / plataformas

​

Dify (mediante el plugin de Aihubmix)

1. Envuelve el prompt que quieres almacenar en caché (el prompt de sistema fijo e invariable / contexto extenso) con <cache>…</cache>; el plugin lo convertirá automáticamente en un punto de corte de cache_control en ese lugar.
2. En los parámetros del modelo, establece el “umbral de caché automática para mensajes grandes” en un entero positivo: la caché solo se escribe realmente cuando el contenido alcanza ese umbral de tokens (sigue sujeto a la restricción mínima de caché de “Limitaciones de la caché” más abajo, 4096 tokens para Opus 4.5/4.6 y Haiku 4.5); con 0 o vacío se desactiva.

​

Cherry Studio

1. Haz clic en el engranaje a la derecha del nombre del proveedor Aihubmix para abrir “API Settings”:

2. Configura los tres elementos siguientes; el cliente inyectará automáticamente cache_control para Claude en función de ellos:

• Cache Token Threshold: solo inyecta el punto de corte de caché cuando el contenido supere ese número de tokens (un número positivo lo activa; 0 o vacío lo desactiva).
• Cache System Message: al activarlo, marca un punto de corte de caché en el mensaje system (ideal para almacenar en caché un prompt de sistema largo y fijo).
• Cache Last N Messages: marca un punto de corte de caché en los últimos N mensajes (ideal para una caché deslizante en conversaciones de múltiples turnos).

​

Preguntas frecuentes (FAQ)

​

¿Por qué escribo en caché (cache_creation_input_tokens es grande) pero nunca leo (cache_read_input_tokens es 0)?

​

¿Cuántos tokens como mínimo necesita la caché?

​

¿Cuánto dura la caché? ¿Se puede cambiar a 1 hora?

​

¿Cómo activo la caché en Dify / Cherry Studio?

​

Soporte en distintos modelos

• Si Prompt Caching está admitido o no depende del propio modelo.
• Si el modelo admite inherentemente la caché sin necesidad de declaraciones de parámetros explícitas, puede admitirse mediante el reenvío compatible con OpenAI.
• OpenAI admite Prompt Caching por defecto, con activación automática (prefijo ≥1024 tokens). En los modelos anteriores a GPT-5.6, la escritura en caché no tiene cargo adicional y la caché se borra automáticamente tras 5-10 minutos de inactividad; en GPT-5.6 y posteriores, la escritura en caché se factura a 1,25 veces el precio de entrada, la lectura a 0,1 veces, la caché se conserva al menos 30 minutos y se admiten puntos de corte de caché explícitos. Detalles en Caché de prompts de GPT.
• Claude requiere la declaración nativa cache_control: { type: "ephemeral" }. La tasa de almacenamiento es 1,25 veces el costo de entrada estándar (5 minutos) o 2 veces (1 hora), la recuperación de tokens cacheados cuesta 0,1 veces la tarifa normal, con un ciclo de vida de 5 minutos o 1 hora. Detalles
• Deepseek V3 y R1 admiten la caché de forma nativa. La tasa de almacenamiento equivale al costo de entrada estándar y la recuperación de tokens cacheados cuesta 0,1 veces la tarifa normal. Detalles
• Soporte de caché implícita de Gemini:
  • Caché implícita: Habilitada por defecto para todos los modelos Gemini 2.5. Si tu solicitud acierta en la caché, los ahorros de costo se aplican automáticamente. Esta función entró en vigor el 8 de mayo de 2025. El recuento mínimo de tokens de entrada para la caché de contexto es de 1.024 para Gemini 2.5 Flash y de 2.048 para Gemini 2.5 Pro.
  • Consejos para mejorar la tasa de aciertos de la caché implícita:
    • Intenta colocar al principio del prompt el contenido extenso y de uso frecuente.
    • Intenta enviar solicitudes con prefijos similares dentro de una ventana de tiempo corta.
  • Puedes ver el número de tokens con acierto de caché en el campo usage_metadata del objeto de respuesta.
  • Los ahorros de costos se calculan según los aciertos de caché en prefill. Solo la caché de prefill y la caché de preprocesamiento de vídeo de YouTube son elegibles para la caché implícita.