Reduce la latencia y el costo con el almacenamiento de prompts en caché.
Por qué es importante el almacenamiento de prompts en caché
El almacenamiento de prompts en caché reutiliza el trabajo realizado cuando las solicitudes comparten el mismo prefijo de prompt. Esto ofrece tres beneficios principales:
Uso eficiente del cómputo: evita volver a calcular un prefijo de prompt que el modelo ya procesó.
Tokens de entrada más económicos: paga la tarifa reducida del modelo para entradas en caché por los tokens reutilizados, con descuentos de hasta el 90 %.
Mayor rapidez: reduce el tiempo dedicado a procesar la entrada antes de que comience la respuesta.
Las llamadas a modelos de la API de agentes usan el mismo comportamiento de almacenamiento de prompts en caché que la API Responses. Reutilizar el contexto dentro de una sesión puede preservar un prefijo de prompt compartido, pero mantener una sesión no garantiza un acierto de caché. Consulta Observabilidad y uso para conocer los campos de uso de la sesión y la contabilización del uso de los subagentes.
Los precios del almacenamiento de prompts en caché varían según el modelo. Consulta los precios de la API para conocer las tarifas vigentes de entrada en caché y escritura en caché. La tarifa de escritura en caché no es un cargo adicional: a los tokens de entrada se les aplica la tarifa de entrada sin caché, entrada en caché o escritura en caché.
¿Qué es la caché de prompts?
Cuando el modelo procesa tokens de entrada, debe calcular estados intermedios, conocidos como estados de clave-valor (KV). Estos estados permiten al modelo consultar tokens anteriores mientras procesa nuevas entradas y genera tokens de salida.
El almacenamiento de prompts en caché conserva ese estado para un prefijo reutilizable: los tokens al inicio de un prompt que no cambian. Cuando una solicitud posterior tiene el mismo prefijo y encuentra una entrada de caché coincidente, el modelo puede reutilizar el estado guardado en lugar de volver a procesar esos tokens. Aun así, debe procesar cualquier entrada nueva para generar una nueva respuesta.
La caché de prompts almacena tensores de clave-valor (KV), no los tokens en sí.
Para reutilizar la caché, todo el prefijo renderizado debe coincidir. Si el contenido o una opción de configuración relevante cambia antes de un punto de corte, el prefijo a partir de ese cambio no puede coincidir con la entrada de caché existente.
Mensaje de sistema oculto
Instrucciones proporcionadas por OpenAI
Herramientas
Definiciones y esquemas
Mensaje del desarrollador
Instrucciones de la aplicación
Historial de contexto
Mensajes de la conversación, llamadas a herramientas y sus resultados, texto y contenido multimodal
Cambiar una solicitud no necesariamente descarta una entrada de caché existente. Lo que importa es si una solicitud posterior tiene el mismo prefijo y puede encontrar un punto de corte válido que coincida. Las principales opciones de configuración que debes revisar son:
Puede cambiar las instrucciones de razonamiento del modelo. En los modelos compatibles, usa una actualización de configuración para cambiar el esfuerzo sin modificar el prefijo anterior.
Reemplaza el contenido anterior de la conversación por un contexto compactado que puede impedir la reutilización a partir del primer token modificado.
Cómo funciona el almacenamiento en caché
Un punto de corte de caché marca el final de un prefijo de prompt que OpenAI puede guardar en caché y reutilizar en solicitudes posteriores. La primera solicitud escribe en caché un prefijo que cumple los requisitos y las solicitudes posteriores buscan el prefijo coincidente más largo que esté disponible en caché, recorriendo hacia atrás los puntos de corte válidos hasta encontrar una coincidencia.
Un prefijo de prompt debe alcanzar la longitud mínima de tokens que el modelo puede almacenar en caché antes de poder guardarse en ella. Los tokens del contenido de sistema oculto proporcionado por OpenAI no cuentan para este mínimo. La longitud mínima de un prompt que puede almacenarse en caché es de 1024 tokens para GPT-5.6 y versiones posteriores; en los modelos anteriores, varía según la configuración de la solicitud. Consulta la comparación de modelos para obtener más información.
Una vez alcanzada la longitud mínima de tokens que se puede almacenar en caché, puedes elegir explícitamente dónde colocar los puntos de corte de caché o dejar que OpenAI elija sus ubicaciones de forma implícita. Las opciones disponibles dependen del modelo.
En GPT-5.6 y versiones posteriores, las escrituras en caché cuestan 1,25× la tarifa estándar de tokens de entrada sin caché. Vale la pena pagar este cargo cuando sabes que se reutilizará un prefijo, porque las lecturas posteriores cuestan solo 0,1× esa tarifa. Escribir un prefijo una vez y reutilizarlo por completo una vez cuesta 1,35× su costo de entrada habitual, frente a 2× por procesarlo dos veces sin caché. El ahorro aumenta con cada lectura adicional de caché: en diez solicitudes, una escritura y nueve lecturas completas cuestan 2,15×, frente a 10× sin caché.
Se admite el almacenamiento en caché tanto implícito como explícito. El explícito te da más control sobre qué contexto se escribe en caché.
Modo explícito: tú eliges dónde colocar los puntos de corte de caché según cómo gestiones el contexto.
Establece prompt_cache_options.mode en explicit para usar solo los puntos de corte seleccionados por el desarrollador y marca cada punto de corte deseado agregando prompt_cache_breakpoint: { "mode": "explicit" } a un bloque de contenido compatible dentro de un mensaje de entrada.
Si no se colocan puntos de corte explícitos, la solicitud no usa el almacenamiento de prompts en caché ni realiza 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 en caché. Así puedes evitar escribir contenido cambiante que probablemente no se reutilice.
Varios puntos de corte explícitos pueden conservar prefijos que cambian con distinta frecuencia. Cada solicitud puede realizar hasta cuatro escrituras en caché.
Los elementos de entrada additional_tools actualmente no aceptan prompt_cache_breakpoint.
El campo instructions de nivel superior no puede contener un punto de corte explícito. Para marcar instrucciones reutilizables del desarrollador, colócalas en un bloque input_text dentro de un mensaje del desarrollador.
Modo implícito: OpenAI elige de forma predeterminada 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 más reciente que cumple los requisitos. Los mensajes que cumplen los requisitos son:
los mensajes del usuario
la última respuesta de herramienta de un grupo de respuestas de herramientas consecutivas
el último mensaje del desarrollador del grupo inicial de mensajes del desarrollador consecutivos.
Puedes agregar puntos de corte explícitos sin desactivar el punto de corte implícito; este utiliza uno de los cuatro espacios de escritura en caché y deja tres disponibles para escrituras explícitas en caché.
Solo se admite el almacenamiento implícito en caché. 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 almacenar en caché (contada desde el final del contexto oculto).
El valor informado de cached_tokens se calcula restando los tokens de sistema ocultos de la posición del último punto de corte coincidente y luego redondeando hacia abajo al múltiplo de 128 más cercano.
Cómo funciona la coincidencia de prefijos
OpenAI recorre únicamente los límites de consulta de caché (explicados a continuación) de la solicitud entrante, desde el prefijo más largo hasta el más corto, en busca de un prefijo coincidente que ya esté almacenado en caché y disponible en la máquina.
Para GPT-5.6 y modelos posteriores, los límites de consulta de caché de la solicitud entrante son:
Modo exclusivamente explícito: los primeros 2 y los últimos 50 puntos de corte explícitos.
Modo implícito: los primeros 2 y los últimos 50 puntos de corte explícitos, el punto de corte implícito, los finales de hasta 20 mensajes anteriores que cumplan los requisitos y el final del bloque inicial de mensajes consecutivos del desarrollador. Esto permite que el modo implícito reutilice un prefijo que termina en un mensaje anterior sin que haya puntos de corte explícitos en esa posición.
Generación del modelo
Modo de almacenamiento en caché
Los puntos de corte implícitos se colocan en el último mensaje del usuario que cumple los requisitos.
Sistema ocultoHerramientasDesarrolladorHistorial de contextoSeguimientoEntrada en cachéEntrada sin caché
Longitud mínima para almacenar en caché (varía según el modelo)
Solicitud 1
12,000 tokens de entrada
3,000 tokens(ilustrativo)
▼
Solicitud 2
15,000 tokens de entrada
3,000 tokens(ilustrativo)
▼
0
2.5k
5k
7.5k
10k
12.5k
15k
17.5k
20k
Tokens de entrada (incluidos los tokens ocultos ilustrativos)
Las entradas de caché no se almacenan indefinidamente. Una solicitud posterior puede reutilizar un prefijo almacenado en caché solo mientras su entrada siga disponible, y reutilizar el prefijo renueva su tiempo de vida sin otro cargo por escritura en caché. La configuración del tiempo de vida y de la retención depende del modelo.
Usa prompt_cache_options.ttl para controlar el tiempo de vida mínimo de la caché. El único valor admitido, 30m, también es el predeterminado. Un prefijo almacenado en caché se puede reutilizar durante 30 minutos después de su escritura o reutilización más reciente, aunque OpenAI puede conservarlo por más tiempo.
Usa prompt_cache_retention, cuyos valores admitidos dependen del modelo:
in_memory: las entradas suelen permanecer activas durante unos 5 a 10 minutos de inactividad, hasta un máximo de una hora.
24h: la retención extendida suele mantener las entradas disponibles durante unos 30 minutos y puede conservarlas hasta por 24 horas.
Valores predeterminados de retención y retención cero de datos
El almacenamiento de prompts en caché puede guardar tensores cifrados de clave/valor en el almacenamiento local de la GPU como estado de la aplicación. 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:
Las organizaciones sin retención cero de datos habilitada usan 24h de forma predeterminada.
Las organizaciones con retención cero de datos habilitada usan in_memory de forma predeterminada.
Verifica las políticas de retención disponibles para tu modelo y organización antes de seleccionar un valor.
Ubicación de la caché
Los estados almacenados en caché residen en máquinas individuales, donde un tráfico superior a 15 solicitudes por minuto puede hacer que las solicitudes se enruten a otras máquinas por exceso de carga. Una solicitud puede reutilizar un prefijo almacenado en caché solo si llega a una máquina que tiene una entrada coincidente que no haya vencido. Por eso, enrutar las solicitudes a la máquina adecuada es importante para reutilizar la caché.
Las cachés no se comparten entre organizaciones ni se pueden reutilizar entre distintas regiones de procesamiento.
OpenAI gestiona el enrutamiento automáticamente. Dentro de una organización y una región de procesamiento, el enrutamiento para un modelo determinado depende de:
La carga actual de la máquina y su capacidad disponible.
Un hash de los tokens iniciales que siguen al contenido oculto de OpenAI, incluidas las definiciones de herramientas cuando están presentes. La cantidad de tokens que se usan para calcular el hash varía según el modelo.
Una clave prompt_cache_key proporcionada, que separa la reutilización de la caché entre grupos de solicitudes y ayuda a optimizar el enrutamiento de caché en los modelos anteriores a GPT-5.6.
En los modelos anteriores a GPT-5.6, usa una clave prompt_cache_key estable para las solicitudes que comparten un prefijo reutilizable, a fin de ayudar a dirigir las solicitudes relacionadas a la misma caché. Para los grupos con mucho tráfico, procura mantener un total de unas 15 solicitudes por minuto entre todos los prefijos que usan cada clave. Distribuye el tráfico de mayor volumen entre varias claves mediante una asignación estable y determinista. Mantén las solicitudes relacionadas en la misma prompt_cache_key para que puedan reutilizar su caché. Las claves influyen en el enrutamiento; no fijan las solicitudes a una máquina ni garantizan un acierto de caché.
En GPT-5.6 y modelos posteriores, OpenAI gestiona el enrutamiento de caché automáticamente; la clave no es necesaria para optimizar el almacenamiento en caché. Puedes usar claves distintas para contabilizar por separado el uso de la caché de los clientes o usuarios de tu aplicación.
Usar claves distintas puede facilitar la explicación del uso de tokens en caché y la facturación de cada cliente o usuario. Por ejemplo, las claves distintas ayudan a prevenir el sondeo de aciertos de caché entre usuarios: enviar prompts de prueba y observar los aciertos de caché para averiguar si antes se almacenó contenido coincidente en caché. Consulta Contabilizar por separado el uso de la caché con claves.
Resumen de las diferencias entre modelos
Comportamiento
GPT-5.6 y posteriores
GPT-5.5 y GPT-5.5 Pro
Otros modelos anteriores
Puntos de corte implícitos
Al final del mensaje más reciente que cumple los requisitos.
Espaciados a intervalos regulares de 2048 tokens.
Espaciados a intervalos regulares que dependen del modelo.
Puntos de corte explícitos
Admitidos
No admitidos
No admitidos
prompt_cache_key
Opcional para contabilizar por separado el uso de la caché
Usa una clave estable para optimizar el enrutamiento de caché
Usa una clave estable para optimizar el enrutamiento de caché
Prefijo mínimo que se puede almacenar en caché
1024 tokens de entrada visibles
Varía según la configuración de la solicitud
Varía según la configuración de la solicitud
Recuento de tokens en caché
Límite exacto que cumple los requisitos, sin incluir los tokens ocultos
Excluye los tokens ocultos y redondea hacia abajo a un múltiplo de 128
Excluye los tokens ocultos y redondea hacia abajo a un múltiplo de 128
Al menos 30 minutos después de la escritura o reutilización más reciente
Por lo general, unos 30 minutos, hasta un máximo de 24 horas
Por lo general, de 5 a 10 minutos de inactividad para in_memory, o hasta 24 horas para 24h
* La retención extendida es compatible con gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5.2, gpt-5.1-codex-max, gpt-5.1, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5.1-chat-latest, gpt-5, gpt-5-codex y gpt-4.1.
En los modelos anteriores a GPT-5.6, la longitud mínima de entrada que se puede almacenar en caché varía según la configuración de la solicitud, incluidas las herramientas, las imágenes, los esquemas de salida, el esfuerzo de razonamiento y el nivel de detalle.
En aplicaciones de varios turnos, reutilizar el historial de conversación a medida que crece puede ahorrar más tokens de entrada que almacenar 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 del desarrollador y el material de referencia compartido que no cambian. Si contienen marcas de tiempo, contenido específico del usuario u otro contenido dinámico, coloca esos elementos al final en lugar de al principio, o muévelos a mensajes posteriores de la conversación.
Conserva el historial de conversación. Agrega nuevos mensajes al final en lugar de reescribir los turnos anteriores. Los resúmenes, la compactación o el truncamiento del contexto pueden cambiar el prefijo y hacer que la reutilización de la caché tenga que comenzar de nuevo.
Cambia el esfuerzo de razonamiento sin reescribir el prefijo. En GPT-6 Astra, agrega un elemento de entrada configuration_update al final para cambiar el esfuerzo de razonamiento entre respuestas sin modificar reasoning.effort a nivel de la solicitud. Esto conserva el prefijo original para reutilizar la caché. Consulta Cambiar el razonamiento durante una conversación para ver ejemplos y límites de compatibilidad.
Mantén el contenido variable después del punto de corte
En los modelos compatibles de GPT-6 y posteriores, agrega un elemento de entrada configuration_update al final para cambiar el esfuerzo de razonamiento durante una conversación y conservar el prefijo anterior almacenado en caché. Mantén el valor original de reasoning.effort de nivel superior, ya que cambiar esa configuración puede reescribir parte de las instrucciones ocultas del sistema.
La actualización de configuración más reciente controla el esfuerzo de razonamiento de las respuestas posteriores. Por ejemplo, agrega este elemento al final del arreglo input existente para usar el nivel de razonamiento high en las solicitudes posteriores:
Cuando las herramientas que necesita tu aplicación varíen entre solicitudes, cambia cuáles se pueden llamar y mantén sus definiciones estables para conservar los prefijos reutilizables.
Mantén las herramientas sin cambios. Conserva sus definiciones, orden y esquemas.
Desactiva el uso de herramientas para una solicitud. Establece tool_choice en "none" en lugar de eliminar las definiciones de las herramientas.
Habilita solo las herramientas seleccionadas. Usa allowed_tools para restringir qué herramientas se pueden llamar sin modificar la lista tools proporcionada.
Carga las herramientas cuando sean necesarias. Usa la búsqueda de herramientas con defer_loading: true para reducir los tokens de entrada destinados a las definiciones de herramientas en las primeras solicitudes de hilos de varios turnos. Las herramientas descubiertas 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 rol de desarrollador para agregar herramientas durante un hilo según la lógica de tu aplicación.
En GPT-5.6 y posteriores, dos controles determinan dónde se colocan los puntos de corte de caché: prompt_cache_options.mode selecciona el almacenamiento en caché implícito o exclusivamente explícito, y prompt_cache_breakpoint marca un límite que tú eliges.
Coloca los puntos de corte automáticamente. Usa el almacenamiento en caché implícito para colocar un punto de corte al final del último mensaje que cumpla los requisitos. Esto resulta práctico para los hilos de varios turnos que agregan contenido al final del contexto existente.
Elige los puntos de corte con cuidado. Coloca marcadores explícitos al final del contenido estable. Usa el modo exclusivamente explícito para evitar escrituras en caché innecesarias de sufijos variables.
Prefijo compartido almacenado en caché para el punto de corte 2
Mensaje oculto del sistema
Herramientas
Mensaje del desarrollador · prefijo estable
Mensaje del desarrollador · sufijo variable A
Mensaje del usuario
Llamada a herramienta
Resultado de herramienta
Mensaje del asistente
Mensaje del desarrollador · sufijo variable B
Nueva entrada del usuario A
Nueva entrada del usuario B
Punto de corte 1
Punto de corte 2
Prefijo compartido almacenado en caché para el punto de corte 1
Sufijo no reutilizado: sin cargo por escritura en caché
Nuevas entradas del usuario: sin cargo por escritura en caché
En GPT-5.6 y modelos posteriores, usa prompt_cache_key cuando quieras contabilizar por separado el uso de la caché de los clientes, usuarios o espacios de trabajo de tu aplicación. Esto puede facilitar la explicación del uso de tokens en caché y la facturación dentro de cada grupo. La clave es opcional y no es necesaria 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 contabilizar por separado el uso de la caché de dos clientes, incluso cuando sus solicitudes contienen 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 su uso de la caché deba contabilizarse por separado.
Aplica las claves de forma coherente. Usa la clave del cliente en todas sus solicitudes para seguir contabilizando su uso de la caché por separado. Esto también ayuda a prevenir el sondeo de aciertos de caché entre clientes.
En los modelos anteriores a GPT-5.6, prompt_cache_key es importante para optimizar las tasas de aciertos de caché. Usa una clave estable para las solicitudes que comparten un prefijo reutilizable, a fin de ayudar a dirigirlas a la misma caché. Para los grupos con mucho tráfico, sigue las recomendaciones para distribuir el tráfico entre más claves.
En los modelos anteriores, es preferible establecer prompt_cache_retention en "24h" para obtener una retención extendida cuando el modelo y tus requisitos de retención de datos lo permitan. Consulta Tiempo de vida de la caché para conocer las opciones compatibles y los valores predeterminados.
Si muchas solicitudes reutilizan las mismas instrucciones del desarrollador y definiciones de herramientas, pero ese prefijo compartido no alcanza la longitud mínima para almacenar en caché del modelo, considera acortarlo o ampliarlo con instrucciones, ejemplos o material de referencia útiles y estables. Mide si la reutilización de la caché compensa los tokens de entrada adicionales y los cargos por escritura en caché, y asegúrate de que las evaluaciones y el comportamiento se mantengan estables.
El gráfico destaca la trampa de costos de la longitud mínima para almacenar en caché: los prefijos cortos sin caché pueden costar más que ampliarlos hasta alcanzar la cantidad mínima de tokens necesaria para almacenarlos en caché.
Longitud del prompt y costo de entrada
0
500
1,000
1,500
2,000
Longitud del prefijo reutilizable (tokens)
Para comparar solo los costos, sea M la longitud mínima que se puede almacenar en caché, L<M la longitud original del prefijo, r el multiplicador de lectura de caché, w el multiplicador de escritura en caché y N el número total de solicitudes. Supongamos que el prefijo ampliado tiene exactamente M tokens, se escribe una vez y se reutiliza por completo en cada solicitud posterior. En equivalentes de tokens de entrada sin caché, conservar el prefijo original cuesta N×L, mientras que ampliarlo cuesta M[w+(N−1)r]. La longitud original en el punto de equilibrio es:
Lbreak-even=M(r+Nw−r)
Amplía el prefijo cuando L>Lbreak-even; conservar el prefijo más corto cuesta menos cuando L<Lbreak-even. En el punto de igualdad, los costos son los mismos. La menor longitud en tokens enteros para la que ampliar el prefijo resulta más barato es ⌊Lbreak-even⌋+1. Por el contrario, reducir un prefijo que se puede almacenar en caché a menos de M impide usar la caché: bajo los mismos supuestos, el prefijo más corto sin caché debe tener una longitud inferior a Lbreak-even para costar menos que almacenar en caché M tokens. No existe una longitud de prompt universal que genere el costo máximo; el punto de cruce depende de la reutilización y los precios.
Por ejemplo, con M=1,024, r=0.1 y w=1.25, el punto de cruce es de 102.4+N1,177.6 tokens. Para un total de 10 solicitudes, ampliar un prefijo original de al menos 221 tokens a 1024 tokens resulta más barato. A medida que aumenta la reutilización, el punto de cruce se aproxima a 102,4 tokens. Un prefijo de 103 tokens necesita al menos 1963 solicitudes en total para que la ampliación resulte beneficiosa; uno de 102 tokens o menos nunca se beneficia bajo estos supuestos. Esta comparación excluye el rendimiento, los tokens de salida y los costos de las solicitudes que permanecen sin cambios. Las lecturas sin coincidencia en caché, las escrituras adicionales o las tarifas de otros modelos cambian el resultado.
Mide el rendimiento real de la caché. Monitorea usage.input_tokens_details.cached_tokens, usage.input_tokens_details.cache_write_tokens, la cantidad de tokens de entrada, la latencia y el costo efectivo. Calcula la tasa de aciertos de caché por token dividiendo el total de tokens en caché entre el total de tokens de entrada y sumando ambos recuentos por usuario, espacio de trabajo, día u otra agrupación útil.
Calcula el costo de entrada. Usa los recuentos de tokens de response.usage y los precios por millón de tokens del modelo.
Los siguientes ejemplos se aplican a GPT-5.6 y modelos posteriores.
Considera un LLM que actúa como juez en un solo turno para determinar 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 diferente.
Conservar el prefijo: la rúbrica fija y los ejemplos se colocan primero. Su longitud combinada se mantiene deliberadamente apenas por encima de la longitud mínima que se puede almacenar en caché del modelo, con material que ayuda a calibrar al juez. La interacción que se evalúa se coloca al final.
Modo de almacenamiento en caché y punto de corte: se habilita el almacenamiento en caché 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 se coloca después de ese punto de corte y no se escribe en caché, lo que evita un cargo de escritura por contenido que probablemente no se reutilice.
Un ejemplo de implementación que aplicó estos principios registró una tasa de aciertos de caché por token de ~70 %. Esta cifra ilustra un resultado posible. Las tasas máximas reales de aciertos de caché dependerán de tu contexto y del uso de la aplicación.
Solicitud a la API Responses para un juez de un solo turno
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{"model": "gpt-5.6-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 con instrucciones del desarrollador extensas y compartidas, y llamadas frecuentes a herramientas. En el uso habitual, los usuarios ejecutan varias sesiones con el agente a la vez y suelen crear forks de los hilos.
Conservar el prefijo: cada turno agrega nuevos mensajes, llamadas a herramientas y resultados sin reescribir el contexto anterior, por lo que el prefijo reutilizable crece con el tiempo.
Clave opcional de 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 la explicación de su uso de tokens en caché y su facturación. Esto también ayuda a prevenir el sondeo de aciertos de caché entre usuarios. La clave se mantiene igual en todas las sesiones y los 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 almacenamiento en caché implícito para que el último mensaje apto del usuario o de una 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 mejorar la eficiencia de la caché al crear forks.
Una implementación de ejemplo que aplicó estos principios registró una tasa de aciertos de caché de tokens >90 %. Esta cifra ilustra un resultado posible. Las tasas máximas de aciertos de caché que se alcancen dependerán del contexto y del uso de la aplicación.
Solicitud a la API Responses para un agente de varios turnos
Esto es especialmente frecuente al migrar de modelos anteriores a GPT-5.6 o versiones posteriores, debido al cambio en el comportamiento del almacenamiento implícito en caché. Si las solicitudes comparten un prefijo largo, pero tienen sufijos diferentes, almacenar en caché la primera solicitud completa usando solo el modo implícito no permite reutilizar el prefijo compartido más corto.
Considera un mensaje de desarrollador estático seguido de un mensaje de usuario dinámico en cada solicitud. Esta solicitud escribe en caché hasta el final del contenido dinámico. Al cambiar ese contenido en la siguiente solicitud, deja de coincidir con el prefijo más largo almacenado en caché, y no hay un punto de corte independiente después del contenido estático.
Sin un punto de corte después del contenido estático
Para solucionarlo, coloca un punto de corte explícito después del contenido estático en ambas solicitudes. La primera solicitud escribe el prefijo reutilizable en caché; la siguiente puede reutilizarlo incluso si cambia el contenido dinámico. Este ejemplo usa el modo exclusivamente explícito para evitar escribir el contenido dinámico en caché.
Con un punto de corte después del contenido estático
Supongamos que la solicitud 1 usa el modo implícito y almacena en caché un prefijo hasta el final de un mensaje de usuario. Luego, la solicitud de seguimiento 2 conserva ese prefijo, pero cambia a prompt_cache_options.mode: "explicit". Como se explica en Cómo funciona la coincidencia de prefijos, la solicitud 2 comprueba solo los puntos de corte explícitos de su propia entrada, por lo que no reutilizará ese 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 punto final almacenado en caché por la solicitud 1).
▼ = 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 en la solicitud 2, o mantén habilitado el modo implícito para que el final del mensaje anterior apto siga siendo un candidato para la búsqueda.
Incluso cuando ambas solicitudes usan 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, luego, la solicitud de seguimiento 2 amplía ese mismo mensaje a Content A + Content B. El punto final anterior, después de Content A, ahora está dentro de un mensaje, en lugar de estar al final. Como se explica en Cómo funciona la coincidencia de prefijos, sin 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 en lugar de ampliarlo. 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 posteriores al bloque inicial de mensajes de desarrollador consecutivos no son límites automáticos de búsqueda en caché. Agrega un punto de corte explícito al final del mensaje de desarrollador reutilizable y consérvalo en las solicitudes posteriores para que OpenAI pueda buscar un prefijo coincidente en caché.
Un prefijo que cumple los requisitos para almacenarse en caché en un modelo puede ser demasiado corto en otro. Consulta la comparación de modelos y mide el prefijo reutilizable con el modelo y la configuración que realmente usas. Cuando cambies de modelo, repite esa comprobación en lugar de suponer que el umbral del modelo anterior sigue siendo válido.
La compactación reemplaza el contexto anterior de la conversación por una representación más breve. Esto puede cambiar el prefijo, por lo que la primera solicitud después de la compactación podría reutilizar una porción menor de la caché anterior, aunque la conversación siga siendo la misma desde el punto de vista lógico.
Mantén estables las instrucciones y el material de referencia reutilizables siempre que sea posible y, luego, deja que los turnos posteriores se construyan sobre 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é.
Preguntas frecuentes
No. El almacenamiento de prompts en caché no cambia la forma en que el modelo genera los tokens de salida. El modelo genera una nueva respuesta usando el prefijo almacenado en caché, por lo que no se garantiza que solicitudes idénticas produzcan salidas idénticas.
No. Actualmente no se puede vaciar la caché manualmente. Las entradas de caché vencen según la duración de la caché y la configuración de retención del modelo.
Sí. Los tokens de entrada almacenados en caché siguen contando para los límites de tokens por minuto. El almacenamiento de prompts en caché no cambia la forma en que se calculan los límites de solicitudes.