Caché de prompts de GPT

​

Inicio rápido

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [Coloca aquí la instrucción larga fija o el material de referencia, ≥1024 tokens]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # La clave se lee desde la variable de entorno
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [Instrucción larga fija o material de referencia, ≥1024 tokens]"

# Dos solicitudes consecutivas con el mismo prefijo; la segunda acierta en la caché
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

// 1.ª llamada: sin acierto
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 2.ª llamada: el prefijo acierta en la caché
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

​

Facturación de la caché

​

Cómo se activa automáticamente la caché

1. Si el prefijo alcanza 1.024 tokens y se encuentra un prefijo en caché coincidente, la parte acertada se factura al precio de lectura de caché y se reduce la latencia del primer token;
2. Si no se encuentra, se procesa como entrada regular y el prefijo se escribe en caché (en GPT-5.6 y posteriores, la escritura se factura a 1,25x);
3. El acierto exige que el prefijo sea idéntico byte a byte; cualquier cambio en el prefijo invalida toda la caché a partir de esa posición.

• Instrucciones de sistema largas y fijas, o gran cantidad de ejemplos few-shot
• Material de referencia extenso citado repetidamente en escenarios RAG
• Flujos de trabajo de agentes que llevan muchas definiciones de herramientas (tools)
• Conversaciones largas de múltiples turnos que solo añaden mensajes al final

​

Parámetros de caché de GPT-5.6

1. Predeterminado (modo implicit): aunque no se pase ningún parámetro de caché, la caché se escribe automáticamente: el sistema establece un punto de corte automático en la posición del mensaje más reciente. En GPT-5.6 y posteriores, las escrituras en caché automáticas también se facturan a 1,25x.
2. Modo implicit + punto de corte explícito: además del punto de corte automático, puede establecerse prompt_cache_breakpoint en un bloque de contenido para fijar el límite de la caché al final del contenido estable; los cambios posteriores al punto de corte no rompen la caché del prefijo anterior.
3. Modo explicit: con prompt_cache_options.mode en "explicit" solo se usan los puntos de corte manuales; si no se establece ningún punto de corte, la solicitud no usa caché ni genera cargos por escritura en caché. Texto oficial: “If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[Contenido largo puntual que no se reutilizará]"}
  ]
}

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[Instrucción larga fija o material de referencia, ≥1024 tokens]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

• Cada solicitud puede crear como máximo 4 nuevas escrituras en caché; en modo implicit, el punto de corte automático ocupa 1 de ellas;
• El prefijo anterior al punto de corte sigue necesitando alcanzar 1.024 tokens para cachearse;
• En la lectura se toma el prefijo coincidente más largo entre los últimos 50 puntos de corte;
• Establecer un punto de corte en un bloque de contenido no admitido devuelve 400 invalid_request_error. Chat Completions admite bloques text / image_url / input_audio / file / refusal; la Responses API admite bloques input_text / input_image / input_file.

​

Por qué la caché no acierta

• El prefijo no alcanza 1.024 tokens: las solicitudes por debajo de la longitud mínima de caché se procesan como entrada regular;
• Contenido variable mezclado en el prefijo: marcas de tiempo, IDs de sesión, variables del usuario, etc. deben ir después del contenido fijo; cualquier cambio en el prefijo invalida la caché a partir de esa posición;
• Cambios en las definiciones o el orden de tools: la lista de herramientas participa en el cálculo del prefijo; las definiciones y su orden deben ser exactamente iguales;
• Parámetro detail de imagen inconsistente: detail afecta a la tokenización de la imagen y debe mantenerse igual;
• Cambio en el schema de salida estructurada: el JSON Schema de response_format participa en la caché como prefijo del mensaje de sistema; un cambio en el schema es un cambio en el prefijo;
• Cambio de reasoning_effort: citado oficialmente entre las causas comunes de una menor tasa de aciertos de caché (“Changes to reasoning effort”);
• Superado el periodo de retención de la caché: antes de GPT-5.6 se borra tras 5–10 minutos de inactividad; en GPT-5.6 y posteriores se conserva al menos 30 minutos;
• prompt_cache_key sin establecer (GPT-5.6): sin él aún puede haber aciertos automáticos, pero no se usa el mecanismo de coincidencia más fiable.

​

Buenas prácticas

• Coloca el contenido fijo (instrucciones de sistema, ejemplos, material de referencia, definiciones de herramientas) al principio de la solicitud, y el contenido que cambia en cada turno al final;
• Establece el mismo prompt_cache_key estable para el tráfico que comparte un mismo prefijo, con un tráfico total por key de unas 15 solicitudes/minuto; si se supera, divide en más keys por negocio;
• En conversaciones de múltiples turnos, añade mensajes solo al final y evita modificar los mensajes históricos;
• Mantén tráfico continuo en las solicitudes con el mismo prefijo para reducir el borrado de la caché;
• Para solicitudes largas puntuales cuyo prefijo no se reutilizará, usa el modo explicit para evitar el cargo por escritura en caché (GPT-5.6 y posteriores);
• Monitoriza los aciertos de forma continua mediante usage.prompt_tokens_details.cached_tokens.

​

Preguntas frecuentes (FAQ)

​

¿Hay que activar manualmente la caché de prompts de GPT?

​

¿Cómo se calcula el cargo por escritura en caché de GPT-5.6? ¿Cómo evitar cargos por escritura innecesarios?

​

¿Cuánto tiempo se conserva la caché?

​

¿Qué diferencia hay entre el punto de corte explícito de GPT-5.6 y el cache_control de Claude?

​

¿La caché afecta al contenido de la salida?

​

Referencias oficiales

• Anuncio de lanzamiento de GPT-5.6: regla de facturación de escritura en caché a 1,25x y descuento del 90% en lectura
• Guía de caché de prompts: mecanismo, parámetros, campos de usage y límites
• OpenAI Pricing: precios oficiales de cada modelo
• Documentación del modelo GPT-5.6: ventana de contexto y umbral de facturación de contexto largo