Les diagnostics du cache de prompts permettent de comprendre pourquoi une requête a réutilisé moins de tokens que prévu. Comparez une requête à une réponse antérieure pour repérer les changements de modèle, d’outils, de paramètres ou de données d’entrée qui ont empêché la réutilisation.
Les diagnostics sont disponibles dans l’API Responses pour GPT-5.6 et les modèles ultérieurs compatibles. Utilisez-les pour analyser des requêtes individuelles, et utilisez le tableau de bord de mise en cache des prompts pour suivre les performances du cache dans l’ensemble de votre application.
Fonctionnement
Les diagnostics du cache de prompts comparent votre requête actuelle à une réponse antérieure pour expliquer pourquoi un préfixe de prompt n’a pas été réutilisé comme prévu. Un préfixe est le contenu situé au début d’un prompt. La réutilisation exige une correspondance exacte du préfixe et des paramètres de requête compatibles, notamment le modèle, l’offre et les outils.
- Choisissez une réponse de référence. Utilisez une réponse récente et terminée de la même organisation, dont vous vous attendez à ce que la requête actuelle réutilise le préfixe, par exemple celle du tour de conversation précédent.
- Demandez une comparaison. Définissez
prompt_cache_options.comparison_response_idsur la valeuridde la réponse de référence. - Consultez le résultat. Vérifiez
prompt_cache_diagnosticsdans la réponse actuelle. Si les diagnostics détectent un défaut de cache, le résultat en indique la cause pour vous aider à l’analyser. Utilisezusage.input_tokens_details.cached_tokenspour mesurer la réutilisation effective du cache.
Définir comparison_response_id sert uniquement à demander des diagnostics. Cela ne charge pas la conversation antérieure et ne modifie pas le comportement de mise en cache. La requête actuelle peut toujours réutiliser les entrées de cache correspondantes provenant d’autres requêtes.
Exemple d’utilisation
L’exemple suivant envoie deux requêtes avec le même modèle, les mêmes instructions et les mêmes données d’entrée, mais remplace le nom d’un outil de type fonction, get_time, par get_date. La seconde requête compare la réutilisation du cache à celle de la première.
Utilisez votre propre document de politique dans support-policy.txt. Le préfixe réutilisable doit atteindre la longueur minimale permettant la mise en cache du modèle, soit 1 024 tokens pour GPT-5.6 et les modèles ultérieurs.
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 le changement d’outil provoque un défaut de cache, le résultat peut ressembler à ceci. Le nombre de tokens varie selon les données d’entrée.
{
"prompt_cache_diagnostics": {
"type": "cache_miss",
"reason": "tools_changed",
"comparison_reusable_tokens": 5629,
"cache_missed_tokens": 5629
}
}Pour préserver la réutilisation, conservez les mêmes définitions et le même ordre des outils d’une requête à l’autre. Consultez Gérer les outils avec des mises à jour par ajout uniquement.
Conversations à plusieurs tours
Pour comparer des tours consécutifs, enregistrez la valeur id de chaque réponse terminée et transmettez-la comme comparison_response_id dans prompt_cache_options lors de la requête suivante. Ne fournissez pas d’identifiant de comparaison au premier tour.
Lorsque vous testez une correction, conservez l’identifiant de la réponse de référence comme identifiant de comparaison.
Diffusion en continu
Lorsque stream=True, lisez prompt_cache_diagnostics dans event.response, au sein de l’événement response.completed.
Comprendre la réponse
Consultez prompt_cache_diagnostics.type pour connaître le résultat de la comparaison.
| Type | Signification | Action à effectuer |
|---|---|---|
cache_hit | Aucun défaut de cache n’a été détecté lors de la comparaison. | Consultez usage.input_tokens_details.cached_tokens pour mesurer la réutilisation effective. |
cache_miss | Une différence a empêché la réutilisation du préfixe attendu. Le résultat comprend reason et cache_missed_tokens. Il peut également comprendre comparison_reusable_tokens. | Retrouvez la cause et la correction suggérée dans Corriger un défaut de cache. |
comparison_response_not_found | Aucun enregistrement de diagnostic exploitable n’est disponible pour la réponse utilisée pour la comparaison. Il peut être manquant ou avoir expiré. | Sélectionnez une autre réponse récente et terminée de la même organisation. |
unavailable | La comparaison n’a pas permis d’obtenir un résultat concluant, ou le modèle ne prend pas en charge les diagnostics. | Vérifiez que le modèle prend en charge les diagnostics et essayez une comparaison avec une autre réponse récente. Vous pouvez toujours utiliser la réponse normalement. |
Interpréter les nombres de tokens
Un résultat cache_hit signifie qu’aucun défaut de cache n’a été détecté lors de la comparaison. Les nouvelles données d’entrée peuvent tout de même nécessiter un traitement. Par exemple, une requête contenant 2 500 tokens d’entrée peut renvoyer cache_hit lorsqu’elle réutilise le préfixe de 2 000 tokens de la réponse utilisée pour la comparaison et traite 500 nouveaux tokens.
Pour un résultat cache_miss :
comparison_reusable_tokens, lorsqu’il est présent, indique le nombre brut de tokens du préfixe réutilisable de la réponse utilisée pour la comparaison.cache_missed_tokensestime combien de ces tokens n’ont pas été réutilisés.
Ces nombres de tokens issus des diagnostics peuvent différer de ceux des données d’utilisation. Utilisez les champs d’utilisation de la réponse actuelle pour mesurer la réutilisation du cache déclarée et les coûts facturés.
Corriger un défaut de cache
Utilisez prompt_cache_diagnostics.reason pour trouver la cause d’un défaut de cache et une correction suggérée dans le tableau suivant.
Certains changements, comme le changement de modèle ou le compactage d’une conversation, sont intentionnels. Vous pouvez choisir de les conserver même s’ils réduisent la réutilisation du cache.
| Cause | Ce qui a changé | Comment améliorer la réutilisation |
|---|---|---|
model_changed | Un autre modèle a traité la requête, par exemple parce que le routage, un test A/B ou un mécanisme de repli l’a sélectionné. | Vérifiez la sélection du modèle pour repérer les changements involontaires. Utilisez le même modèle pour les requêtes censées partager un préfixe mis en cache. Consultez les paramètres qui influent sur le cache. |
prompt_cache_key_changed | La clé fournie a changé entre les requêtes. Cela peut être signalé comme un défaut de cache dans le champ usage de la réponse, sans défaut de cache physique. | Omettez prompt_cache_key, sauf si votre application doit comptabiliser séparément l’utilisation du cache par client ou par utilisateur. Si vous utilisez des clés, conservez une clé stable au sein de chaque groupe. Consultez Comptabiliser séparément l’utilisation du cache à l’aide de clés. |
service_tier_changed | L’offre utilisée pour traiter la requête a changé. | Conservez la même offre pour les requêtes censées partager un préfixe. Vérifiez la valeur renvoyée dans service_tier, qui peut différer de la valeur demandée. Consultez service_tier pour connaître les valeurs prises en charge et le comportement associé. |
tools_changed | Des outils ont été ajoutés, supprimés ou réordonnés, ou leurs descriptions, schémas ou configurations ont changé. | Conservez les mêmes définitions et le même ordre des outils. Utilisez tool_choice: "none" pour désactiver les outils ou allowed_tools pour limiter les outils autorisés à s’exécuter sans modifier la liste d’outils fournie. Consultez Gérer les outils avec des mises à jour par ajout uniquement. |
text_format_changed | Le format de sortie ou son schéma a changé. | Conservez les mêmes valeurs pour text.format et le schéma lorsque la structure de sortie requise reste inchangée. Consultez Sorties structurées. |
reasoning_effort_changed | L’effort de raisonnement a changé. | Conservez la même valeur de reasoning.effort pour les requêtes censées partager un préfixe. Consultez les paramètres qui influent sur le cache. |
verbosity_changed | Le niveau de détail de la réponse a changé. | Conservez la même valeur de text.verbosity pour les requêtes censées partager un préfixe. Consultez les paramètres qui influent sur le cache. |
context_compacted | Le compactage a remplacé le contenu antérieur de la conversation. | Conservez des instructions stables et laissez les tours suivants s’appuyer sur le contexte compacté. Comparez le coût total des tokens d’entrée : un nombre réduit de tokens d’entrée peut permettre de réaliser des économies malgré une moindre réutilisation du cache. Consultez Compactage. |
input_changed | Le contenu d’entrée antérieur a changé, par exemple parce que les instructions contiennent un horodatage ou un identifiant de requête, ou que des messages précédents ont été modifiés, réorganisés ou supprimés. | Déplacez le contenu variable après le préfixe réutilisable et son point de coupure du cache. Conservez les messages précédents et les résultats des outils, puis ajoutez les nouveaux tours à la suite. Consultez Conserver l’historique de la conversation. |
Confirmez l’amélioration
Après avoir effectué une modification :
- Envoyez une autre requête représentative et comparez-la à la réponse de référence prévue.
- Vérifiez le résultat du diagnostic pour repérer les différences restantes.
- Comparez
cached_tokens,cache_write_tokenset le coût total sur plusieurs requêtes.
Consultez Surveiller les performances du cache pour en savoir plus sur les métriques d’utilisation et le calcul des coûts.
Tarifs et limites de débit
Les diagnostics du cache de prompts n’entraînent aucun coût supplémentaire et ne sont pas comptabilisés séparément dans les limites de débit. Toute requête supplémentaire envoyée à l’API Responses pour établir une référence ou effectuer une nouvelle tentative est facturée normalement et compte dans les limites de débit.
Politique de non-conservation des données
Les diagnostics du cache de prompts sont compatibles avec la politique de non-conservation des données. OpenAI ne stocke ni les prompts bruts ni les sorties du modèle pour cette fonctionnalité. Les enregistrements de diagnostic contiennent des métadonnées de configuration, des estimations du nombre de tokens et des hachages servant à comparer les contenus qui influent sur la réutilisation du cache. Ces enregistrements sont limités à l’organisation, expirent après une courte période et servent uniquement à expliquer les succès ou les échecs d’accès au cache de prompts.
Définir comparison_response_id ne récupère ni ne conserve le contenu de la réponse précédente. Consultez Vos données pour en savoir plus sur les contrôles des données proposés par OpenAI.
Limites
- Les diagnostics sont disponibles dans l’API Responses pour GPT-5.6 et les modèles ultérieurs pris en charge.
- Les enregistrements de diagnostic expirent après une courte période. Un enregistrement expiré renvoie
comparison_response_not_found, même si la réponse reste accessible via l’API. - Les diagnostics indiquent la première cause qu’ils ont pu classer. Corrigez-la, puis répétez la comparaison pour rechercher d’autres causes.
- Les diagnostics sont fournis dans la mesure du possible et peuvent ne pas classer tous les échecs d’accès au cache. Un résultat
unavailablen’indique ni un succès ni un échec d’accès au cache et est renvoyé si la comparaison n’est pas prête. - Les diagnostics ne bloquent jamais votre requête, ne la font jamais échouer et ne modifient pas la façon dont le modèle génère sa sortie.