Les diagnostics de mise en cache des prompts permettent de comprendre pourquoi une requête a réutilisé moins de tokens que prévu. Comparez la requête à une réponse antérieure pour repérer les changements de modèle, d’outils, de paramètres ou de contenu d’entrée qui ont empêché cette réutilisation.
Les diagnostics sont disponibles dans l’API Responses pour GPT-5.6 et les modèles ultérieurs compatibles. Utilisez-les pour examiner une requête en particulier. Pour suivre les performances du cache dans l’ensemble de votre application, consultez le tableau de bord de la mise en cache des prompts.
Fonctionnement
Les diagnostics de mise en cache des prompts comparent la requête en cours à une réponse antérieure pour vous aider à comprendre pourquoi le préfixe de prompt attendu n’a pas été réutilisé. Le préfixe est le contenu situé au début du prompt. Pour le réutiliser, il faut que les préfixes soient identiques et que les paramètres des requêtes soient 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 la requête en cours devrait réutiliser le préfixe, par exemple celle du tour de conversation précédent.
- Demandez une comparaison. Attribuez à
prompt_cache_options.comparison_response_idla valeur du champidde la réponse de référence. - Consultez le résultat. Vérifiez le champ
prompt_cache_diagnosticsde la réponse en cours. Si les diagnostics détectent un défaut de cache, le résultat en indique la cause pour orienter votre analyse. Utilisezusage.input_tokens_details.cached_tokenspour mesurer la réutilisation effective du cache.
Renseigner comparison_response_id sert uniquement à demander des diagnostics. Cela ne charge pas la conversation antérieure et ne modifie pas le fonctionnement du cache. La requête en cours peut toujours réutiliser des entrées de cache correspondantes issues 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 le même contenu d’entrée. Seul le nom d’un outil de type fonction passe de get_time à get_date. La seconde requête prend la première comme référence pour comparer la réutilisation du cache.
Placez votre propre document de politique d’assistance dans support-policy.txt. Le préfixe réutilisable doit atteindre la longueur minimale de 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 entraîne un défaut de cache, vous pouvez obtenir un résultat comme celui-ci. Le nombre de tokens varie selon le contenu 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 du préfixe, conservez les mêmes définitions d’outils et le même ordre d’une requête à l’autre. Consultez Gérer les outils par ajouts successifs en fin de liste.
Conversations à plusieurs tours
Pour comparer deux tours consécutifs, enregistrez le champ id de chaque réponse terminée et transmettez sa valeur dans le champ comparison_response_id de prompt_cache_options à la requête suivante. Au premier tour, omettez l’identifiant de comparaison.
Lorsque vous testez une correction, gardez 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 à la réception 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 |
La comparaison n’a détecté aucun défaut de cache. | 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 contient reason et cache_missed_tokens. Il peut aussi contenir comparison_reusable_tokens. |
Retrouvez la cause et la correction proposée dans Corriger un défaut de cache. |
comparison_response_not_found |
Aucun enregistrement de diagnostic exploitable n’est disponible pour la réponse de référence. Il est peut-être absent ou a expiré. | Choisissez une autre réponse récente et terminée de la même organisation. |
unavailable |
La comparaison n’a pas permis de conclure, ou le modèle ne prend pas en charge les diagnostics. | Vérifiez que le modèle prend en charge les diagnostics, puis relancez la comparaison avec une autre réponse récente. Vous pouvez toujours utiliser la réponse normalement. |
Interpréter le nombre de tokens
Le résultat cache_hit indique que la comparaison n’a détecté aucun défaut de cache. Le modèle peut toutefois avoir de nouvelles données d’entrée à traiter. Par exemple, une requête de 2 500 tokens d’entrée peut renvoyer cache_hit si elle réutilise le préfixe de 2 000 tokens de la réponse de référence 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 de référence.cache_missed_tokensestime combien de ces tokens n’ont pas été réutilisés.
Ces chiffres peuvent différer de ceux des statistiques d’utilisation. Pour mesurer la réutilisation du cache déclarée et déterminer les coûts facturés, consultez les champs d’utilisation de la réponse en cours.
Corriger un défaut de cache
Recherchez la valeur de prompt_cache_diagnostics.reason dans le tableau suivant pour identifier la cause du défaut de cache et la correction proposée.
Certains changements sont intentionnels, comme le passage à un autre modèle ou le compactage d’une conversation. Vous pouvez 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 à la suite d’une décision de routage, d’un test A/B ou du recours à un modèle de secours. | Vérifiez si la sélection du modèle a entraîné un changement involontaire. Utilisez le même modèle pour les requêtes qui doivent partager un préfixe en cache. Consultez les paramètres qui influent sur le préfixe en cache. |
prompt_cache_key_changed |
La clé fournie a changé d’une requête à l’autre. Le champ usage de la réponse peut alors signaler un défaut de cache même si le préfixe a bien été trouvé dans le cache. |
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 la même clé 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 qui doivent partager un préfixe. Vérifiez la valeur renvoyée dans service_tier, qui peut différer de la valeur demandée. Consultez la référence de service_tier pour connaître les valeurs prises en charge et leur effet. |
tools_changed |
Des outils ont été ajoutés, supprimés ou réordonnés, ou leurs descriptions, leurs schémas ou leur configuration ont changé. | Conservez les mêmes définitions d’outils et le même ordre. Utilisez tool_choice: "none" pour désactiver les outils ou allowed_tools pour limiter ceux qui peuvent s’exécuter sans modifier la liste fournie. Consultez Gérer les outils par ajouts successifs en fin de liste. |
text_format_changed |
Le format de sortie ou son schéma a changé. | Avec les modèles compatibles à partir de GPT-6, conservez la même valeur pour le paramètre de premier niveau text.format et ajoutez une mise à jour du format à la fin des données d’entrée si vous avez besoin d’un autre schéma. |
reasoning_effort_changed |
L’effort de raisonnement a changé. | Avec les modèles compatibles à partir de GPT-6, ajoutez un élément configuration_update à la fin des données d’entrée pour modifier l’effort de raisonnement en cours de conversation tout en conservant le préfixe déjà en cache.Avec les modèles plus anciens, conservez la même valeur de reasoning.effort pour les requêtes qui doivent partager un préfixe. |
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 qui doivent partager un préfixe. Consultez les paramètres qui influent sur le préfixe en cache. |
context_compacted |
Le compactage a remplacé le contenu des tours précédents. | Conservez les instructions qui restent valables et utilisez le contexte compacté comme point de départ des tours suivants. Comparez le coût total des entrées : un nombre réduit de tokens d’entrée peut vous faire économiser de l’argent même si la réutilisation du cache diminue. 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éordonnés ou supprimés. | Placez le contenu variable après le préfixe réutilisable et son point de rupture de cache. Conservez les messages et les résultats d’outils précédents, puis ajoutez les nouveaux tours à la suite. Consultez Préserver l’historique de la conversation. |
Vérifier l’amélioration
Après avoir apporté une modification :
- Envoyez une autre requête représentative et comparez-la à la réponse de référence choisie.
- Vérifiez si le résultat du diagnostic signale encore une différence.
- Comparez
cached_tokens,cache_write_tokenset le coût total sur plusieurs requêtes.
Consultez Suivre les performances du cache pour connaître les métriques d’utilisation et le mode de calcul des coûts.
Tarification et limites de débit
Les diagnostics de mise en cache des 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 obtenir une réponse de référence ou réessayer est facturée au tarif habituel et compte dans les limites de débit.
Politique de non-conservation des données
Les diagnostics de mise en cache des prompts sont compatibles avec la politique de non-conservation des données. Pour cette fonctionnalité, OpenAI ne stocke ni les prompts bruts ni les sorties du modèle. Les enregistrements de diagnostic contiennent des métadonnées de configuration, des estimations du nombre de tokens et des empreintes de hachage qui permettent de comparer les contenus dont dépend la réutilisation du cache. Ces enregistrements sont propres à chaque organisation, expirent rapidement et servent uniquement à expliquer pourquoi un préfixe de prompt a été trouvé ou non dans le cache.
Renseigner comparison_response_id ne récupère pas le contenu de la réponse antérieure et ne l’enregistre pas. Consultez Vos données pour connaître les options de contrôle des données proposées par OpenAI.
Limites
- Les diagnostics sont disponibles dans l’API Responses pour GPT-5.6 et les modèles ultérieurs compatibles.
- Les enregistrements de diagnostic expirent rapidement. Si l’enregistrement a expiré, la comparaison renvoie
comparison_response_not_found, même si la réponse reste accessible via l’API. - Les diagnostics signalent la première cause qu’ils parviennent à classer. Corrigez-la, puis répétez la comparaison pour rechercher d’autres causes.
- Les diagnostics tentent de classer chaque défaut de cache sans garantie d’y parvenir. Le résultat
unavailablene permet pas de savoir si le préfixe a été trouvé dans le cache. C’est aussi le résultat renvoyé si la comparaison n’est pas prête. - Les diagnostics ne bloquent jamais la requête, ne la font jamais échouer et ne modifient pas la façon dont le modèle génère sa sortie.