El diagnóstico de la 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 cambios en el modelo, las herramientas, la configuración o la entrada que impidieron la reutilización.
El diagnóstico está disponible en la API Responses para GPT-5.6 y modelos posteriores compatibles. Úsalo para investigar solicitudes individuales y usa el panel de almacenamiento de prompts en caché para monitorear el rendimiento de la caché en toda tu aplicación.
Cómo funciona
El diagnóstico de la caché de prompts compara tu solicitud actual con una respuesta anterior para ayudar a explicar por qué no se reutilizó el prefijo del prompt que se esperaba reutilizar. Un prefijo es el contenido al principio de un prompt. Para reutilizarlo, el prefijo debe coincidir exactamente y la configuración de las solicitudes debe ser compatible, 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 cuyo prefijo esperas que reutilice la solicitud actual, como el turno anterior de la conversación.
- Solicita una comparación. Establece
prompt_cache_options.comparison_response_iden el valor deidde la respuesta de referencia. - Lee el resultado. Revisa
prompt_cache_diagnosticsen la respuesta actual. Si el diagnóstico identifica un fallo de caché, el resultado incluye un motivo para ayudarte a investigar. Usausage.input_tokens_details.cached_tokenspara medir la reutilización real de la caché.
Establecer comparison_response_id solo solicita un diagnóstico. No carga la conversación anterior ni cambia el comportamiento del almacenamiento en 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 función de get_time a get_date. La segunda solicitud compara la reutilización de la caché con la primera.
Usa tu propio documento de políticas en support-policy.txt. El prefijo reutilizable debe cumplir con la longitud mínima que se puede almacenar en caché del modelo, que es de 1024 tokens para GPT-5.6 y 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 verse así. Los recuentos de tokens varían según la entrada.
{
"prompt_cache_diagnostics": {
"type": "cache_miss",
"reason": "tools_changed",
"comparison_reusable_tokens": 5629,
"cache_missed_tokens": 5629
}
}Para mantener la reutilización, no cambies las definiciones ni el orden de las herramientas entre solicitudes. Consulta Administrar 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 en la siguiente solicitud. Omite el ID de comparación en el primer turno.
Al probar una corrección, mantén el ID de comparación establecido en el de la respuesta de referencia.
Transmisión continua
Cuando stream=True, lee prompt_cache_diagnostics de event.response en el evento response.completed.
Entender 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 la reutilización real. |
cache_miss | Una diferencia impidió reutilizar el prefijo esperado. El resultado incluye reason y cache_missed_tokens. También puede incluir comparison_reusable_tokens. | Encuentra el motivo y la corrección sugerida en Corregir un fallo de caché. |
comparison_response_not_found | No hay un registro de diagnóstico utilizable para la respuesta de comparación. Es posible que no exista o haya vencido. | Selecciona otra respuesta reciente y completada de la misma organización. |
unavailable | La comparación no pudo producir un resultado concluyente o el modelo no admite el diagnóstico. | Confirma que el modelo admita el diagnóstico y prueba otra comparación reciente. Puedes seguir usando la respuesta normalmente. |
Interpretar los recuentos de tokens
Un resultado cache_hit significa que no se detectó ningún fallo de caché en la comparación. Es posible que la entrada nueva aún requiera procesamiento. Por ejemplo, una solicitud con 2500 tokens de entrada puede indicar cache_hit cuando reutiliza el prefijo de 2000 tokens de la respuesta de comparación y procesa 500 tokens nuevos.
Para un resultado cache_miss:
comparison_reusable_tokens, cuando está presente, es el recuento bruto de tokens del prefijo reutilizable de la respuesta de comparación.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 medir la reutilización de la caché y la facturación reportadas.
Corregir un fallo de caché
Usa prompt_cache_diagnostics.reason para encontrar la causa de un fallo de caché y una corrección sugerida en la siguiente tabla.
Algunos cambios, como cambiar de modelo o compactar una conversación, son intencionales. Puedes optar por mantenerlos aunque reduzcan la reutilización de la caché.
| Motivo | Qué cambió | Cómo mejorar la reutilización |
|---|---|---|
model_changed | Un modelo diferente procesó la solicitud, por ejemplo, porque el enrutamiento, una prueba A/B o un mecanismo de respaldo seleccionó otro modelo. | Revisa la selección de modelos para detectar cambios involuntarios. Usa el mismo modelo para las solicitudes que deban compartir un prefijo almacenado en caché. Consulta la configuración que afecta a la caché. |
prompt_cache_key_changed | La clave proporcionada cambió entre solicitudes. Esto puede reportarse como un fallo de caché en usage de la respuesta sin que haya un fallo físico de caché. | Omite prompt_cache_key a menos que tu aplicación necesite contabilizar el uso de la caché por separado para cada cliente o usuario. Si usas claves, mantén una clave estable dentro de cada grupo. Consulta Contabilizar el uso de la caché por separado mediante claves. |
service_tier_changed | Cambió el nivel de servicio utilizado para procesar la solicitud. | Mantén el mismo nivel de servicio para las solicitudes que se espera que compartan un prefijo. Revisa el valor devuelto de service_tier, que puede diferir del valor solicitado. Consulta service_tier para conocer los valores admitidos y su comportamiento. |
tools_changed | Se agregaron, eliminaron o reordenaron herramientas, o cambiaron sus descripciones, esquemas o configuración. | Mantén estables las definiciones y el orden de las herramientas. 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 Administrar herramientas con actualizaciones que solo agregan elementos al final. |
text_format_changed | Cambió el formato de salida o su esquema. | Mantén text.format y el esquema sin cambios cuando la estructura de salida requerida no cambie. Consulta Resultados estructurados. |
reasoning_effort_changed | Cambió el esfuerzo de razonamiento. | Mantén el mismo valor de reasoning.effort en las solicitudes que deban compartir un prefijo. Consulta la configuración que afecta a la caché. |
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 la configuración que afecta a la caché. |
context_compacted | La compactación reemplazó contenido anterior de la conversación. | Conserva las instrucciones estables y permite que los turnos posteriores se basen en el contexto compactado. Compara el costo total de entrada: una menor cantidad de tokens de entrada puede ahorrar dinero incluso si se reutiliza 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 de la caché. Conserva los mensajes anteriores y los resultados de las herramientas, y agrega los nuevos turnos al final. Consulta Conservar el historial de la conversación. |
Confirmar la mejora
Después de realizar un cambio:
- Envía otra solicitud representativa y compárala con la respuesta de referencia prevista.
- Revisa el resultado del diagnóstico para detectar cualquier diferencia que persista.
- Compara
cached_tokens,cache_write_tokensy el costo total de varias solicitudes.
Consulta Monitorear 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 de la caché de prompts no tiene costo adicional ni se contabiliza por separado para los límites de solicitudes. Las solicitudes adicionales a la API Responses que se hagan como referencia o como reintentos se facturan de la forma habitual y cuentan para los límites de solicitudes.
Retención cero de datos
El diagnóstico de la caché de prompts es compatible con la retención cero de datos. OpenAI no almacena prompts sin procesar ni salidas del modelo para esta función. Los registros de diagnóstico contienen metadatos de configuración, estimaciones de la cantidad de tokens y hashes que se usan para comparar el contenido que afecta a la caché. Estos registros se limitan a la organización, caducan al poco tiempo y se usan únicamente para explicar los aciertos o fallos de la caché de prompts.
Configurar comparison_response_id no recupera ni almacena de forma persistente el contenido de la respuesta anterior. Consulta Tus datos para conocer los controles de datos de OpenAI.
Limitaciones
- Los diagnósticos están disponibles en la API Responses para GPT-5.6 y los modelos posteriores compatibles.
- Los registros de diagnóstico caducan al poco tiempo. Un registro caducado devuelve
comparison_response_not_found, incluso si la respuesta sigue disponible a través de la API. - Los diagnósticos informan el primer motivo clasificado. Resuélvelo y luego repite la comparación para comprobar si hay otras causas.
- Los diagnósticos se realizan en la medida de lo posible y puede que no clasifiquen todos los fallos de caché. Un resultado
unavailableno indica un acierto ni un fallo de caché y se devuelve si la comparación aún no está lista. - Los diagnósticos nunca bloquean tu solicitud, hacen que falle ni cambian la forma en que el modelo genera la salida.