El diagnóstico del almacenamiento en caché de prompts ayuda a explicar por qué una solicitud reutilizó menos tokens de lo esperado. Compara una solicitud con una respuesta anterior para identificar qué cambios en el modelo, las herramientas, la configuración o la entrada impidieron la reutilización.
La API de Responses ofrece este diagnóstico para GPT-5.6 y los modelos posteriores compatibles. Úsalo para investigar solicitudes individuales y consulta el panel de almacenamiento en caché de prompts para monitorear el rendimiento de la caché en toda tu aplicación.
Cómo funciona
El diagnóstico del almacenamiento en caché de prompts compara tu solicitud actual con una respuesta anterior para ayudarte a entender por qué no se reutilizó el prefijo esperado. El prefijo es el contenido inicial de un prompt. Para reutilizarlo, los prefijos deben coincidir exactamente y las solicitudes deben tener configuraciones compatibles, incluidos el modelo, el nivel de servicio y las herramientas.
- Elige una respuesta de referencia. Usa una respuesta reciente y completada de la misma organización. Elige una cuyo prefijo esperas que reutilice la solicitud actual, como la respuesta del turno anterior de la conversación.
- Solicita una comparación. Asigna a
prompt_cache_options.comparison_response_idel valor deidde la respuesta de referencia. - Lee el resultado. Revisa
prompt_cache_diagnosticsen la respuesta actual. Si el diagnóstico detecta un fallo de caché, el resultado incluye el motivo para ayudarte a investigarlo. Usausage.input_tokens_details.cached_tokenspara medir cuántos tokens se reutilizaron realmente.
Al configurar comparison_response_id, solo solicitas un diagnóstico. Esto no carga la conversación anterior ni cambia el funcionamiento de la caché. La solicitud actual aún puede reutilizar entradas de caché coincidentes de otras solicitudes.
Ejemplo de uso
El siguiente ejemplo envía dos solicitudes con el mismo modelo, las mismas instrucciones y la misma entrada, pero cambia el nombre de una herramienta de tipo función de get_time a get_date. La segunda solicitud toma la primera como referencia para comparar la reutilización de la caché.
Usa tu propio documento de políticas en support-policy.txt. El prefijo reutilizable debe alcanzar la longitud mínima que el modelo puede almacenar en caché, que es de 1024 tokens para GPT-5.6 y los modelos posteriores.
from pathlib import Path
from openai import OpenAI
client = OpenAI()
policy = Path("support-policy.txt").read_text() # At least 1,024 tokens.
first = client.responses.create(
model="gpt-6-astra",
instructions=policy,
input="Reply with exactly OK.",
tools=[{"type": "function", "name": "get_time"}],
)
second = client.responses.create(
model="gpt-6-astra",
instructions=policy,
input="Reply with exactly OK.",
tools=[{"type": "function", "name": "get_date"}],
prompt_cache_options={"comparison_response_id": first.id},
)
diagnostics = second.prompt_cache_diagnostics
if diagnostics is not None and diagnostics.type == "cache_miss":
print(diagnostics.reason)
print(diagnostics.comparison_reusable_tokens)
print(diagnostics.cache_missed_tokens)Si el cambio en la herramienta provoca un fallo de caché, el resultado podría ser similar al siguiente. La cantidad de tokens varía según la entrada.
{
"prompt_cache_diagnostics": {
"type": "cache_miss",
"reason": "tools_changed",
"comparison_reusable_tokens": 5629,
"cache_missed_tokens": 5629
}
}Para seguir reutilizando la caché, mantén las mismas definiciones de herramientas y el mismo orden entre solicitudes. Consulta Administra las herramientas con actualizaciones que solo agregan elementos al final.
Conversaciones de varios turnos
Para comparar turnos consecutivos, guarda el id de cada respuesta completada y pásalo como comparison_response_id en prompt_cache_options de la siguiente solicitud. Omite el ID de comparación en el primer turno.
Cuando pruebes una corrección, sigue usando el ID de la respuesta de referencia como ID de comparación.
Transmisión en tiempo real
Cuando stream=True, lee prompt_cache_diagnostics en event.response del evento response.completed.
Cómo interpretar la respuesta
Lee prompt_cache_diagnostics.type para determinar el resultado de la comparación.
| Tipo | Significado | Qué hacer |
|---|---|---|
cache_hit |
No se detectó ningún fallo de caché en la comparación. | Revisa usage.input_tokens_details.cached_tokens para medir cuántos tokens se reutilizaron realmente. |
cache_miss |
Una diferencia impidió reutilizar el prefijo esperado. El resultado incluye reason y cache_missed_tokens. También puede incluir comparison_reusable_tokens. |
Busca el motivo y la solución sugerida en Cómo corregir un fallo de caché. |
comparison_response_not_found |
No hay un registro de diagnóstico utilizable para la respuesta de referencia. Es posible que el registro no exista o que haya caducado. | Selecciona otra respuesta reciente y completada de la misma organización. |
unavailable |
La comparación no arrojó un resultado concluyente o el modelo no admite el diagnóstico. | Confirma que el modelo admita el diagnóstico y prueba la comparación con otra respuesta reciente. Puedes seguir usando la respuesta con normalidad. |
Cómo interpretar los recuentos de tokens
Un resultado cache_hit indica que no se detectó ningún fallo de caché en la comparación. Es posible que aún sea necesario procesar la entrada nueva. Por ejemplo, una solicitud con 2500 tokens de entrada puede devolver cache_hit si reutiliza el prefijo de 2000 tokens de la respuesta de referencia y procesa 500 tokens nuevos.
Para un resultado cache_miss:
comparison_reusable_tokens, cuando aparece, indica el recuento bruto de tokens del prefijo reutilizable de la respuesta de referencia.cache_missed_tokensestima cuántos de esos tokens no se reutilizaron.
Estos recuentos de diagnóstico pueden diferir de los recuentos de uso. Usa los campos de uso de la respuesta actual para determinar cuántos tokens se reutilizaron según los datos de uso y calcular el importe facturado.
Cómo corregir un fallo de caché
Usa prompt_cache_diagnostics.reason para buscar la causa del fallo de caché y la solución sugerida en la siguiente tabla.
Algunos cambios, como cambiar de modelo o compactar una conversación, son intencionales. Puedes conservarlos aunque reduzcan la reutilización de la caché.
| Motivo | Qué cambió | Cómo mejorar la reutilización |
|---|---|---|
model_changed |
Otro modelo procesó la solicitud, por ejemplo, porque el enrutamiento, una prueba A/B o un mecanismo de respaldo seleccionó un modelo distinto. | Revisa la selección del modelo para detectar cambios involuntarios. Usa el mismo modelo en las solicitudes que deban compartir un prefijo almacenado en caché. Consulta Qué ajustes afectan a la caché. |
prompt_cache_key_changed |
La clave proporcionada cambió entre solicitudes. Este cambio puede registrarse como un fallo de caché en el campo usage de la respuesta aunque no se haya producido un fallo en la caché física. |
Omite prompt_cache_key a menos que tu aplicación necesite contabilizar por separado el uso de la caché por cliente o usuario. Si usas claves, mantén la misma clave dentro de cada grupo. Consulta Contabiliza por separado el uso de la caché con claves. |
service_tier_changed |
Cambió el nivel de servicio que se usó para procesar la solicitud. | Mantén el mismo nivel de servicio en las solicitudes que deban compartir un prefijo. Revisa el valor de service_tier en la respuesta, ya que puede diferir del solicitado. Consulta service_tier para conocer los valores admitidos y su funcionamiento. |
tools_changed |
Se agregaron, eliminaron o reordenaron herramientas, o cambiaron sus descripciones, sus esquemas o su configuración. | Mantén las mismas definiciones de herramientas y el mismo orden. Usa tool_choice: "none" para desactivar las herramientas o allowed_tools para restringir cuáles pueden ejecutarse sin cambiar la lista de herramientas proporcionada. Consulta Administra las herramientas con actualizaciones que solo agregan elementos al final. |
text_format_changed |
Cambió el formato de salida o su esquema. | En los modelos compatibles a partir de GPT-6, mantén el mismo valor de text.format en el nivel superior de la solicitud y agrega una actualización de formato al final de la entrada cuando necesites un esquema diferente. |
reasoning_effort_changed |
Cambió el esfuerzo de razonamiento. | En los modelos compatibles a partir de GPT-6, agrega al final de la entrada un elemento configuration_update para cambiar el esfuerzo de razonamiento durante una conversación y conservar el prefijo anterior almacenado en caché.En los modelos anteriores, mantén el mismo valor de reasoning.effort en las solicitudes que deban compartir un prefijo. |
verbosity_changed |
Cambió el nivel de detalle de la respuesta. | Mantén el mismo valor de text.verbosity en las solicitudes que deban compartir un prefijo. Consulta Qué ajustes afectan a la caché. |
context_compacted |
La compactación reemplazó contenido anterior de la conversación. | Conserva las instrucciones que no cambian y deja que los turnos posteriores partan del contexto compactado. Compara el costo total de entrada: usar menos tokens de entrada puede reducir el costo aunque se reutilice menos la caché. Consulta Compactación. |
input_changed |
Cambió la entrada anterior, por ejemplo, porque las instrucciones contienen una marca de tiempo o un ID de solicitud, o porque se editaron, reordenaron o eliminaron mensajes anteriores. | Coloca el contenido que cambia después del prefijo reutilizable y de su punto de corte en la caché. Conserva los mensajes anteriores y los resultados de las herramientas, y agrega los turnos nuevos al final. Consulta Conserva el historial de la conversación. |
Cómo confirmar la mejora
Después de hacer un cambio:
- Envía otra solicitud representativa y compárala con la respuesta de referencia que elegiste.
- Revisa el resultado del diagnóstico para ver si persiste alguna diferencia.
- Compara
cached_tokens,cache_write_tokensy el costo total de varias solicitudes.
Consulta Monitorea el rendimiento de la caché para conocer las métricas de uso y los cálculos de costos.
Precios y límites de solicitudes
El diagnóstico del almacenamiento en caché de prompts no tiene costo adicional ni se contabiliza por separado para los límites de solicitudes. Las solicitudes adicionales que envíes a la API de Responses para obtener una respuesta de referencia o volver a intentarlo se facturan de la manera habitual y cuentan para esos límites.
Retención cero de datos
El diagnóstico del almacenamiento en caché de prompts es compatible con la retención cero de datos. OpenAI no almacena los prompts originales ni las salidas del modelo para esta función. Los registros de diagnóstico contienen metadatos de configuración, estimaciones del número de tokens y hashes que se usan para comparar el contenido que afecta a la caché. Estos registros se limitan a cada organización, caducan al poco tiempo y solo se usan para explicar los aciertos o fallos del almacenamiento en caché de prompts.
Configurar comparison_response_id no recupera ni guarda el contenido de la respuesta anterior. Consulta Tus datos para conocer los controles de datos de OpenAI.
Limitaciones
- La API de Responses ofrece el diagnóstico para GPT-5.6 y los modelos posteriores compatibles.
- Los registros de diagnóstico caducan al poco tiempo. Si el registro caducó, la comparación devuelve
comparison_response_not_found, aunque la respuesta siga disponible a través de la API. - El diagnóstico indica el primer motivo que pudo clasificar. Corrige la causa y repite la comparación para comprobar si hay otras.
- El diagnóstico intenta clasificar cada fallo de caché, pero puede que no lo logre en todos los casos. El resultado
unavailableno indica un acierto ni un fallo de caché y se devuelve si la comparación aún no está lista. - El diagnóstico nunca bloquea tu solicitud ni hace que falle. Tampoco cambia la forma en que el modelo genera la salida.