Almacenamiento en caché de prompts

Modificar una solicitud no implica necesariamente descartar una entrada de caché existente. Lo importante es que la solicitud posterior tenga el mismo prefijo y pueda encontrar un punto de corte válido que coincida. Revisa estos ajustes principales:

En GPT-5.6 y versiones posteriores, las escrituras en caché con la vigencia predeterminada de 30 minutos cuestan 1,25 veces la tarifa estándar de los tokens de entrada sin caché. En la API de respuestas, puedes elegir una vigencia mínima de 12 horas con una tarifa de escritura de 2,5 veces la tarifa estándar de entrada. Las lecturas posteriores cuestan 0,1 veces la tarifa estándar de entrada en la mayoría de estos modelos y 0,05 veces esa tarifa en GPT-6.1 Sol y GPT-6.1 Terra, independientemente de la vigencia elegida.

Con la tarifa de lectura de 0,1× y escrituras de 30 minutos, escribir un prefijo una vez y reutilizarlo por completo una vez cuesta 1,35 veces su costo de entrada estándar. Procesarlo dos veces sin caché cuesta el doble. Para diez solicitudes, una escritura y nueve lecturas completas a esa tarifa cuestan 2,15 veces el costo de entrada estándar, frente a 10 veces sin caché.

Puedes usar el almacenamiento en caché implícito o explícito. El modo explícito te da más control sobre qué partes del contexto se escriben en caché.

Modo explícito: tú eliges dónde colocar los puntos de corte según cómo administres el contexto.

• Configura prompt_cache_options.mode en explicit para usar solo los puntos de corte que seleccione el desarrollador. Marca cada punto de corte que quieras usar agregando prompt_cache_breakpoint: { "mode": "explicit" } a un bloque de contenido compatible dentro de un mensaje de entrada.
• Si no colocas puntos de corte explícitos, la solicitud no usa el almacenamiento en caché de prompts ni genera escrituras en caché.
• El modo exclusivamente explícito te permite elegir dónde terminan las escrituras en caché. El contenido posterior al último punto de corte seleccionado se procesa a la tarifa de tokens de entrada sin caché y sin cargo por escritura. Así puedes evitar escribir contenido que cambia y que probablemente no se reutilice.
• Con varios puntos de corte explícitos puedes conservar prefijos que cambian con distinta frecuencia. Cada solicitud puede generar hasta cuatro escrituras en caché.
• Los elementos de entrada additional_tools aún no admiten prompt_cache_breakpoint.

Modo implícito: OpenAI elige automáticamente ubicaciones para los puntos de corte que funcionan bien en la mayoría de los casos de uso.

• Cuando prompt_cache_options.mode es implicit, OpenAI coloca un punto de corte al final del mensaje válido más reciente. Los mensajes válidos son:
  • los mensajes de usuario
  • la última respuesta de herramienta de un grupo de respuestas de herramientas consecutivas
  • el último mensaje de desarrollador del grupo inicial de mensajes de desarrollador consecutivos.
• Puedes agregar puntos de corte explícitos sin desactivar el implícito. El punto de corte implícito ocupa uno de los cuatro espacios de escritura en caché y deja tres disponibles para escrituras explícitas.

Solo se admite el almacenamiento en caché implícito. OpenAI coloca puntos de corte implícitos a intervalos que dependen del modelo, contados desde el inicio del mensaje de sistema oculto de OpenAI. Solo son válidos los puntos de corte que alcanzan o superan la longitud mínima para el almacenamiento en caché, que se cuenta desde el final del contexto oculto.

Para calcular el valor de cached_tokens que se informa, se restan los tokens ocultos del sistema de la posición del último punto de corte coincidente y se redondea el resultado hacia abajo al múltiplo de 128 más cercano.

En la API de respuestas, configura prompt_cache_options.ttl para elegir la vigencia mínima de la caché:

Estas tarifas cubren el costo total de la escritura. No se suman a la tarifa de entrada estándar. La tarifa de lectura de caché es la misma para ambas vigencias. OpenAI puede conservar las entradas más tiempo que el mínimo solicitado. El valor "12h" no fija un plazo de eliminación ni cambia la política de retención máxima de datos.

El valor de ttl de la solicitud se aplica al punto de corte implícito y a los puntos de corte explícitos que no tengan su propio ttl. Configura prompt_cache_breakpoint.ttl para especificar otra vigencia para un punto de corte explícito individual. Si omites ambos ajustes, se conserva el comportamiento predeterminado de "30m". Si indicas un valor no admitido, la API devuelve 400 invalid_request_error. Estos ajustes no modifican el parámetro prompt_cache_retention de los modelos anteriores.

Combinar vigencias en una solicitud

Coloca al inicio del prompt el material que reutilices a lo largo del día y asigna a su punto de corte una vigencia de "12h". Usa "30m" para el contexto de la sesión que cambie con más frecuencia. Este ejemplo fija una vigencia predeterminada de 30 minutos para la solicitud y especifica otra para el prefijo compartido. En el modo exclusivamente explícito, la pregunta actual queda después del último punto de corte, por lo que ese contenido no genera un cargo por escritura en caché.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30{
  "model": "gpt-6.1-sol",
  "prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Shared instructions and reference material reused throughout the day...",
          "prompt_cache_breakpoint": { "mode": "explicit", "ttl": "12h" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Session context reused over the next few minutes...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        {
          "type": "input_text",
          "text": "The current question, which does not need a cache write..."
        }
      ]
    }
  ]
}

Reemplaza el texto de ejemplo con tu contenido. Cada prefijo que quieras guardar en caché debe alcanzar la longitud mínima que exige el modelo.

Escrituras superpuestas y cambios de vigencia

Un punto de corte abarca todo el prefijo que lo precede. En una misma solicitud, cada token se factura una sola vez según la vigencia más larga entre las escrituras seleccionadas que lo abarcan. Si una escritura posterior tiene una vigencia de 12 horas, los puntos de corte seleccionados anteriormente dentro de ese prefijo también quedan cubiertos durante 12 horas.

En estos ejemplos, se supone que cualquier prefijo existente en caché coincide con un límite de búsqueda válido de la nueva solicitud.

Si amplías una cobertura vigente de 30 minutos a 12 horas, se cobra una nueva escritura de 12 horas por esos tokens, sin aplicar ningún crédito por la escritura anterior. Cualquier parte que ya esté cubierta por una entrada vigente de 12 horas se sigue facturando como lectura de caché.

Una lectura de 30 minutos renueva la cobertura por al menos 30 minutos a partir de esa lectura. Si usa una entrada con cobertura vigente de 12 horas, se conserva el vencimiento más tardío entre el original y el que corresponde a 30 minutos después de la lectura. La lectura no reinicia el plazo de 12 horas ni genera otro cargo por escritura.

Usa prompt_cache_retention con uno de los valores admitidos por el modelo:

• in_memory: las entradas suelen permanecer activas durante unos 5 a 10 minutos de inactividad, con un máximo de una hora.
• 24h: la retención extendida suele mantener las entradas disponibles durante unos 30 minutos y puede conservarlas hasta 24 horas.

Valores de retención predeterminados y retención cero de datos

El almacenamiento en caché de prompts puede guardar tensores de clave-valor cifrados como estado de la aplicación en el almacenamiento local de la GPU. En los modelos que admiten tanto in_memory como 24h, el valor predeterminado depende de la política de retención de datos de tu organización:

• En las organizaciones sin retención cero de datos habilitada, el valor predeterminado es 24h.
• En las organizaciones con retención cero de datos habilitada, el valor predeterminado es in_memory.

Antes de seleccionar un valor, verifica qué políticas de retención están disponibles para tu modelo y tu organización.

En modelos anteriores a GPT-5.6, usa una prompt_cache_key estable para las solicitudes que comparten un prefijo reutilizable. Así ayudas a dirigir las solicitudes relacionadas a la misma caché. En los grupos con mucho tráfico, procura que cada clave reciba en total unas 15 solicitudes por minuto entre todos los prefijos que la usan. Si el volumen es mayor, distribuye el tráfico entre varias claves con una asignación estable y determinista. Usa la misma prompt_cache_key para las solicitudes relacionadas, de modo que puedan reutilizar su caché. Las claves influyen en el enrutamiento, pero no fijan las solicitudes a una máquina ni garantizan un acierto de caché.

En GPT-5.6 y versiones posteriores, OpenAI gestiona el enrutamiento hacia la caché automáticamente. No necesitas la clave para optimizar el almacenamiento en caché. Puedes usar claves distintas para contabilizar por separado el uso de la caché de cada cliente o usuario de tu aplicación.

Usar claves distintas puede facilitar la explicación del uso y la facturación de tokens en caché para cada cliente o usuario. Por ejemplo, las claves separadas ayudan a impedir que un usuario envíe prompts de prueba y observe los aciertos de caché para averiguar si ya se almacenó contenido coincidente de otros usuarios. Consulta Contabilizar el uso de la caché por separado mediante claves.

En aplicaciones de varios turnos, reutilizar el historial a medida que crece puede ahorrar más tokens de entrada que guardar en caché solo las instrucciones iniciales. Conserva los mensajes anteriores y los resultados de las herramientas para que los turnos posteriores puedan reutilizar todo el prefijo compartido.

• Mantén el prefijo estable. Coloca primero las instrucciones de desarrollador estables y el material de referencia compartido. Si las instrucciones o el material compartido incluyen marcas de tiempo, contenido específico de un usuario u otro contenido dinámico, coloca esos elementos al final en vez de al principio, o muévelos a mensajes posteriores de la conversación.
• Conserva el historial de la conversación. Agrega los mensajes nuevos al final en lugar de reescribir turnos anteriores. Resumir la conversación, aplicar la compactación o truncar el contexto puede cambiar el prefijo y hacer que la reutilización de la caché vuelva a empezar desde cero.
• Cambia el esfuerzo de razonamiento sin reescribir el prefijo. En modelos GPT-6, agrega al final un elemento de entrada configuration_update para cambiar el esfuerzo de razonamiento entre respuestas sin modificar reasoning.effort en la solicitud. Así se conserva el prefijo original para reutilizarlo desde la caché. Consulta Cambiar el razonamiento durante la conversación para ver ejemplos y limitaciones de compatibilidad.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "low", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Stable instructions and shared reference material...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "developer",
      "content": "Dynamic developer instructions, such as user-specific content and timestamps..."
    },
    {
      "role": "user",
      "content": "The user's current question..."
    }
  ]
}

En los modelos compatibles de GPT-6 y versiones posteriores, agrega al final un elemento de entrada configuration_update para cambiar el esfuerzo de razonamiento durante una conversación y conservar el prefijo anterior en caché. Mantén el valor original de reasoning.effort en el nivel superior, ya que modificarlo puede reescribir parte de las instrucciones ocultas del sistema.

La actualización más reciente de reasoning.effort determina el esfuerzo de razonamiento para las respuestas posteriores. Agrega este elemento al final de input para cambiar el esfuerzo a high.

1
2
3
4{
  "type": "configuration_update",
  "reasoning": { "effort": "high" }
}

Si tu aplicación necesita distintas herramientas según la solicitud, cambia cuáles se pueden llamar y mantén estables sus definiciones para conservar los prefijos reutilizables.

• Mantén estables las herramientas. Conserva sus definiciones, su orden y sus esquemas.
• Desactiva el uso de herramientas para una solicitud. Configura tool_choice en "none" en lugar de eliminar las definiciones de herramientas.
• Habilita solo las herramientas seleccionadas. Usa allowed_tools para restringir qué herramientas se pueden llamar sin cambiar la lista tools proporcionada.
• Carga las herramientas cuando se necesiten. Usa la búsqueda de herramientas con defer_loading: true para reducir los tokens de entrada dedicados a las definiciones de herramientas en las primeras solicitudes de un hilo de varios turnos. Las herramientas encontradas se agregan al final del contexto, lo que conserva el contenido reutilizable anterior.
• Conserva el historial de carga de herramientas. Usa un elemento de entrada additional_tools con el rol de desarrollador para agregar herramientas durante un hilo según la lógica de tu aplicación.

En GPT-5.6 y versiones posteriores, dos controles determinan dónde se colocan los puntos de corte de caché. Con prompt_cache_options.mode seleccionas el modo implícito o el exclusivamente explícito, y con prompt_cache_breakpoint marcas el límite que elijas.

• Coloca puntos de corte automáticamente. Usa el almacenamiento en caché implícito para colocar un punto de corte al final del mensaje válido más reciente. Es práctico en hilos de varios turnos donde se agrega contenido al final del contexto existente.
• Elige dónde colocar los puntos de corte. Coloca marcadores explícitos al final del contenido estable. Usa el modo exclusivamente explícito para evitar escrituras en caché innecesarias de sufijos que cambian.

En GPT-5.6 y versiones posteriores, prepara de antemano el contexto conocido para reducir el tiempo hasta el primer token en una solicitud posterior. Por ejemplo, durante el inicio, una aplicación interactiva puede cargar en caché instrucciones compartidas, definiciones de herramientas o material de referencia antes de que el usuario haga su primera pregunta.

Configura prompt_cache_options.prewarm en true en una solicitud a la API de respuestas para preparar la caché de prompts sin generar salida. Una vez completada la solicitud, envía la solicitud real con el mismo prefijo de prompt y omite prewarm o configúralo en false.

1
2
3
4
5
6
7
8
9
10
11
12{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    }
  ],
  "prompt_cache_options": {
    "prewarm": true
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    },
    {
      "role": "user",
      "content": "The user's question..."
    }
  ]
}

Los tokens que se escriben en caché durante una solicitud de preparación se facturan a la tarifa de escritura en caché correspondiente a la vigencia seleccionada.

En GPT-5.6 y versiones posteriores, usa prompt_cache_key cuando quieras contabilizar por separado el uso de la caché de distintos clientes, usuarios o espacios de trabajo de tu aplicación. Esto puede facilitar la explicación del uso y la facturación de tokens en caché para cada grupo. La clave es opcional y no se necesita para optimizar el almacenamiento en caché en estos modelos.

• Elige cómo contabilizar por separado el uso de la caché. Asigna una clave distinta a cada cliente o usuario cuyo uso de la caché deba contabilizarse por separado. Por ejemplo, support:customer_123 y support:customer_456 permiten llevar cuentas separadas para dos clientes aunque sus solicitudes contengan el mismo prefijo.
• Mantén estables las claves dentro de cada grupo. Reutiliza la misma clave para las solicitudes relacionadas de un cliente. Genera una clave distinta para una sesión o un hilo solo cuando necesites contabilizar su uso de la caché por separado.
• Usa las claves de forma consistente. Usa la clave de cada cliente en todas sus solicitudes para contabilizar su uso de la caché por separado. Esto también ayuda a impedir que un cliente sondee los aciertos de caché de otros clientes.

En modelos anteriores a GPT-5.6, prompt_cache_key es importante para optimizar la tasa de aciertos de caché. Usa una clave estable para las solicitudes que compartan un prefijo reutilizable. Así ayudas a dirigirlas a la misma caché. En los grupos con mucho tráfico, sigue las indicaciones para distribuir el tráfico entre más claves.

En los modelos de la API de respuestas que admiten prompt_cache_options, usa "30m" para el contexto que reutilices con frecuencia y considera "12h" para los prefijos estables que reutilices a intervalos más largos. Compara la tarifa de escritura más alta de 12 horas con el costo de volver a escribir el prefijo cuando venza la cobertura de 30 minutos. Configura la vigencia de cada punto de corte para dar al material compartido una vigencia mayor que la del contexto específico de la sesión. Consulta Vigencia de la caché para ver ejemplos y reglas de facturación.

En los modelos anteriores, es preferible configurar prompt_cache_retention en "24h" para usar la retención extendida cuando lo permitan el modelo y tus requisitos de retención de datos. Consulta Vigencia de la caché para conocer los ajustes admitidos y los valores predeterminados.

Si muchas solicitudes reutilizan las mismas instrucciones de desarrollador y definiciones de herramientas, pero el prefijo compartido no alcanza la longitud mínima para el almacenamiento en caché del modelo, considera acortarlo o ampliarlo con instrucciones, ejemplos o material de referencia que sean útiles y estables. Mide si la reutilización de la caché compensa el costo de los tokens de entrada adicionales y los cargos por escritura en caché. Verifica también que los resultados de las evaluaciones y el comportamiento se mantengan estables.

La gráfica muestra cuándo usar un prefijo corto sin caché puede costar más que ampliarlo hasta alcanzar la longitud mínima para almacenarlo en caché. Para el cálculo se usa la tarifa de escritura en caché de 30 minutos de GPT-5.6 y versiones posteriores.

• Mide el rendimiento real de la caché. Monitorea usage.input_tokens_details.cached_tokens, usage.input_tokens_details.cache_write_tokens, los recuentos de escrituras por vigencia, la cantidad de tokens de entrada, la latencia y el costo real. Para medir la tasa de aciertos de caché por token, divide el total de tokens en caché entre el total de tokens de entrada. Agrupa ambos recuentos por usuario, espacio de trabajo, día u otro criterio útil.
• Calcula el costo de entrada. Usa los recuentos de tokens de response.usage y los precios por millón de tokens del modelo.
• Usa el panel de almacenamiento en caché de prompts. Monitorea las tasas de aciertos de caché en el panel de almacenamiento en caché de prompts.

En los modelos de la API de respuestas que admiten prompt_cache_options, el campo input_tokens_details.cache_write_tokens_details desglosa las escrituras en ttl_30m_tokens y ttl_12h_tokens. Estos recuentos no se superponen y su suma es igual a cache_write_tokens. Se devuelven ambos campos, incluso cuando uno vale cero. El campo cached_tokens contabiliza las lecturas facturadas y excluye los tokens que se cobran como escrituras, incluidas las ampliaciones de cobertura de 30 minutos a 12 horas.

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 3000,
        "ttl_12h_tokens": 4000
      }
    }
  }
}

En este ejemplo de uso, 1000 tokens de entrada corresponden a entrada estándar: 12000 - 4000 - 7000. Para calcular el costo de entrada, multiplica los tokens de entrada estándar por el precio de entrada del modelo, cached_tokens por el precio de entrada en caché, ttl_30m_tokens por 1,25 veces el precio de entrada y ttl_12h_tokens por 2,5 veces el precio de entrada. Suma estos importes y divide el total entre 1 000 000 si usas precios por millón de tokens. No vuelvas a sumar cache_write_tokens después de contar sus dos componentes.

Por ejemplo, con un precio de entrada de $1 por millón de tokens y un precio de entrada en caché de $0,10 por millón, el costo de entrada para este uso es (1000 + 4000 × 0.1 + 3000 × 1.25 + 4000 × 2.5) / 1000000 = $0.01515. Usa las tarifas reales de tu modelo, incluida la de entrada en caché.

La siguiente función auxiliar usa un único multiplicador para todas las escrituras en caché. Usa 1.25 cuando todas las escrituras tengan una vigencia de 30 minutos o 2.5 cuando todas tengan una vigencia de 12 horas. Para las solicitudes con ambas vigencias, calcula cada componente de escritura por separado, como se describe aquí.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18function calculateInputCost(
  usage,
  inputPricePerMillion,
  cacheInputMultiplier = 0.1,
  cacheWriteMultiplier = 1.25
) {
  const inputTokens = usage.input_tokens;
  const cachedTokens = usage.input_tokens_details.cached_tokens;
  const cacheWriteTokens = usage.input_tokens_details.cache_write_tokens;
  const ordinaryInputTokens = inputTokens - cachedTokens - cacheWriteTokens;

  const weightedInputTokens =
    ordinaryInputTokens +
    cachedTokens * cacheInputMultiplier +
    cacheWriteTokens * cacheWriteMultiplier;
  const inputCost = (weightedInputTokens * inputPricePerMillion) / 1_000_000;
  return inputCost;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from openai.types.responses import ResponseUsage


def calculate_input_cost(
    usage: ResponseUsage,
    input_price_per_million: float,
    cache_input_multiplier: float = 0.1,
    cache_write_multiplier: float = 1.25,
) -> float:
    input_tokens = usage.input_tokens
    cached_tokens = usage.input_tokens_details.cached_tokens
    cache_write_tokens = usage.input_tokens_details.cache_write_tokens
    ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

    weighted_input_tokens = (
        ordinary_input_tokens
        + cached_tokens * cache_input_multiplier
        + cache_write_tokens * cache_write_multiplier
    )
    input_cost = weighted_input_tokens * input_price_per_million / 1_000_000
    return input_cost

1
2
3
4
5func calculateInputCost(usage responses.ResponseUsage, pricePerMillion, cacheInputMultiplier, cacheWriteMultiplier float64) float64 {
	ordinary := usage.InputTokens - usage.InputTokensDetails.CachedTokens - usage.InputTokensDetails.CacheWriteTokens
	weighted := float64(ordinary) + float64(usage.InputTokensDetails.CachedTokens)*cacheInputMultiplier + float64(usage.InputTokensDetails.CacheWriteTokens)*cacheWriteMultiplier
	return weighted * pricePerMillion / 1_000_000
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.models.responses.ResponseUsage;

static double calculateInputCost(
    ResponseUsage usage,
    double pricePerMillion,
    double cacheInputMultiplier,
    double cacheWriteMultiplier) {
  long cached = usage.inputTokensDetails().cachedTokens();
  long written = usage.inputTokensDetails().cacheWriteTokens();
  long ordinary = usage.inputTokens() - cached - written;
  return (ordinary + cached * cacheInputMultiplier + written * cacheWriteMultiplier)
      * pricePerMillion
      / 1_000_000;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17def calculate_input_cost(
  usage,
  input_price_per_million,
  cache_input_multiplier = 0.1,
  cache_write_multiplier = 1.25
)
  input_tokens = usage.input_tokens
  details = usage.input_tokens_details
  cached_tokens = details.cached_tokens
  cache_write_tokens = details.cache_write_tokens
  ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

  weighted_input_tokens = ordinary_input_tokens +
                          (cached_tokens * cache_input_multiplier) +
                          (cache_write_tokens * cache_write_multiplier)
  (weighted_input_tokens * input_price_per_million) / 1_000_000
end

• Conserva los prefijos estables existentes.
• Si usas prompt_cache_key, conserva los valores existentes para seguir contabilizando el uso de la caché por separado para cada cliente o usuario.
• Reemplaza prompt_cache_retention por prompt_cache_options.ttl.
• Confirma que los prefijos reutilizables alcancen la longitud mínima para el almacenamiento en caché del modelo.
• Si el punto de corte predeterminado abarca contenido que cambia entre solicitudes, agrega un punto de corte explícito después del prefijo estable.
• Usa prompt_cache_options.mode: "explicit" cuando no valga la pena escribir en caché el contenido posterior.
• Compara cached_tokens, cache_write_tokens, la latencia y el costo total antes y después de la migración.

Considera un LLM que, en un solo turno, evalúa si una interacción finalizada con un chatbot muestra indicios de que el usuario quedó satisfecho. Cada solicitud usa la misma rúbrica de evaluación y unos pocos ejemplos etiquetados para evaluar una interacción distinta.

• Conservación del prefijo: la rúbrica fija y los ejemplos van primero. Se usa material que ayuda a calibrar al juez y se procura que la longitud combinada quede apenas por encima de la longitud mínima para el almacenamiento en caché del modelo. La interacción que se evalúa va al final.
• Modo de almacenamiento en caché y punto de corte: se habilita el modo exclusivamente explícito, con un punto de corte después de la rúbrica fija y los ejemplos. La conversación entre el usuario y el chatbot que se evalúa queda después de ese punto de corte y no se escribe en caché. Así se evita el cargo por escribir contenido que probablemente no se reutilice.

En una implementación que siguió estos principios, se registró una tasa de aciertos de caché por token de aproximadamente el 70 %. Esta cifra ilustra un resultado posible. La tasa máxima de aciertos que puedas alcanzar dependerá de tu contexto y del uso de la aplicación.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Judge whether the completed interaction provides evidence that the user is satisfied. Return true or false. Full grading rubric and labeled few-shot examples...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "user",
      "content": "Completed interaction to evaluate..."
    }
  ]
}

Considera un agente de varios turnos que usa instrucciones de desarrollador largas y compartidas, y llama a herramientas con frecuencia. Por lo general, los usuarios mantienen varias sesiones simultáneas con el agente y suelen crear forks de los hilos.

• Conservación del prefijo: en cada turno se agregan al final nuevos mensajes, llamadas a herramientas y resultados sin reescribir el contexto anterior, de modo que el prefijo reutilizable crece con el tiempo.
• Clave opcional de almacenamiento en caché de prompts: este ejemplo usa agent_123_v1:user_456 para contabilizar por separado el uso de la caché del usuario 456, lo que facilita explicar cuántos tokens en caché usó y cómo se le facturaron. También ayuda a impedir que un usuario sondee los aciertos de caché de otros usuarios. La clave se mantiene igual en todas las sesiones y forks de ese usuario con el agente. Omítela si tu aplicación no necesita esta separación.
• Modo de almacenamiento en caché implícito: se habilita el modo implícito para que el mensaje válido más reciente, ya sea de usuario o de herramienta, proporcione un punto de corte.
• Puntos de corte explícitos: se agrega un punto de corte después de cada resultado de herramienta para conservar los prefijos reutilizables anteriores y aprovechar mejor la caché al crear forks.

En una implementación que siguió estos principios, se registró una tasa de aciertos de caché por token superior al 90 %. Esta cifra ilustra un resultado posible. La tasa máxima de aciertos que puedas alcanzar dependerá de tu contexto y del uso de la aplicación.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_key": "agent_123_v1:user_456",
  "prompt_cache_options": { "mode": "implicit" },
  "tools": [
    {
      "type": "function",
      "name": "function_name",
      "description": "Function description",
      "parameters": { "...": "..." }
    }
  ],
  "input": [
    {
      "role": "developer",
      "content": "Stable developer instructions and reference material..."
    },
    { "role": "user", "content": "Can you do...?" },
    {
      "type": "function_call",
      "call_id": "call_123",
      "name": "function_name",
      "arguments": "..."
    },
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": [
        {
          "type": "input_text",
          "text": "Tool result...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    { "role": "assistant", "content": "Assistant response..." },
    { "role": "user", "content": "Can you also do...?" }
  ]
}

Esto ocurre con especial frecuencia al migrar de modelos anteriores a GPT-5.6 o versiones posteriores, debido al cambio en el funcionamiento del almacenamiento en caché implícito. Si las solicitudes comparten un prefijo largo pero tienen sufijos distintos, guardar la primera solicitud completa solo mediante el modo implícito no permite reutilizar el prefijo compartido más corto.

Supongamos que cada solicitud contiene un mensaje de desarrollador estático seguido de un mensaje de usuario dinámico. La escritura en caché abarca hasta el final del contenido dinámico. Si cambias ese contenido en la siguiente solicitud, ya no habrá coincidencia con el prefijo más largo almacenado en caché, y no habrá un punto de corte independiente después del contenido estático.

1
2
3
4
5
6
7
8
9
10{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "implicit" },
  "input": [
    { "role": "developer", "content": "Static content..." },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

Para resolverlo, coloca un punto de corte explícito después del contenido estático en ambas solicitudes. La primera solicitud escribe el prefijo reutilizable y la siguiente puede reutilizarlo aunque cambie el contenido dinámico. Este ejemplo usa el modo exclusivamente explícito para evitar que el contenido dinámico se escriba en caché.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "Static content...",
        "prompt_cache_breakpoint": { "mode": "explicit" }
      }]
    },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

Supongamos que la solicitud 1 usa el modo implícito y guarda en caché un prefijo hasta el final de un mensaje de usuario. La solicitud de seguimiento 2 conserva ese prefijo, pero cambia a prompt_cache_options.mode: "explicit". Como se explica en Cómo se buscan prefijos coincidentes, la solicitud 2 solo comprueba los puntos de corte explícitos de su propia entrada. Por lo tanto, no reutilizará el prefijo implícito guardado por la solicitud 1, a menos que uno de los puntos de corte explícitos de la solicitud 2 coincida con el final del prefijo que la solicitud 1 guardó en caché.

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message] ▼

- Request 2: explicit-only mode. Does not hit cache.
  [Developer message][User message][Follow-up] ▼

Para reutilizar el prefijo implícito de la solicitud 1, coloca un punto de corte explícito en el límite del bloque de contenido correspondiente de la solicitud 2, o mantén habilitado el modo implícito para que el final del mensaje válido anterior se siga teniendo en cuenta en la búsqueda.

Aunque ambas solicitudes usen el modo implícito, conservar los mismos tokens iniciales no siempre es suficiente. Supongamos que la solicitud 1 termina con un mensaje de usuario que contiene Content A y que la solicitud de seguimiento 2 amplía ese mismo mensaje a Content A + Content B. El límite anterior, después de Content A, ahora queda dentro del mensaje en vez de al final. Como se explica en Cómo se buscan prefijos coincidentes, si no hay un punto de corte explícito en ese límite, la solicitud 2 no reutiliza el prefijo guardado allí.

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message: Content A] ▼

- Request 2: implicit mode. Cannot reuse the prefix through Content A.
  [Developer message][User message: Content A + Content B] ▼

Cuando la estructura de la conversación lo permita, conserva el mensaje original y agrega un mensaje nuevo al final. De lo contrario, mantén el texto reutilizable en un bloque de contenido separado y coloca un punto de corte explícito después de ese bloque en ambas solicitudes.

En el modo implícito, los mensajes de desarrollador que siguen al bloque inicial de mensajes de desarrollador consecutivos no delimitan automáticamente la búsqueda en caché. Agrega un punto de corte explícito al final del mensaje de desarrollador reutilizable para conservar ese punto de corte en solicitudes posteriores. Así OpenAI puede comprobar si hay un prefijo coincidente en caché.

Un prefijo que se puede almacenar en caché en un modelo puede ser demasiado corto para otro. Consulta la comparación de modelos y mide el prefijo reutilizable con el modelo y los ajustes que realmente uses. Cuando cambies de modelo, vuelve a comprobar la longitud en vez de dar por hecho que sigue aplicándose el umbral del modelo anterior.

La compactación reemplaza el contexto anterior de la conversación por una representación más corta. Esto puede cambiar el prefijo, de modo que la primera solicitud después de la compactación podría reutilizar una parte menor de la caché anterior aunque la conversación siga siendo la misma desde el punto de vista lógico.

Cuando sea posible, mantén estables las instrucciones reutilizables y el material de referencia. Luego deja que los turnos posteriores amplíen el contexto compactado. Compara el costo total de entrada antes y después de la compactación. Reducir los tokens de entrada puede ahorrar dinero incluso si baja la tasa de aciertos de caché.

No. El almacenamiento en caché de prompts no cambia la forma en que el modelo genera tokens de salida. El modelo genera una respuesta nueva a partir del prefijo en caché, por lo que no se garantiza que solicitudes idénticas produzcan salidas idénticas.

No. Actualmente no hay una opción para vaciar la caché manualmente. Las entradas vencen según la vigencia de la caché del modelo y sus ajustes de retención.

Sí. Los tokens de entrada en caché siguen contando para los límites de tokens por minuto. El almacenamiento en caché de prompts no cambia la forma en que se calculan los límites de solicitudes.