Seuils du prompt cache : la doc les sous-estime de 1,4 à 2,4x

Un client nous a signalé que le cache de prompts ne s’activait pas sur notre gateway au nombre de tokens annoncé dans la documentation du modèle. Nous avons reproduit le problème, puis testé chaque modèle via un second chemin de serving indépendant, l’une des plus grandes gateways d’IA. Nous y avons retrouvé exactement les mêmes écarts, au token près. Ce n’était donc pas une gateway en particulier qui était en cause, mais une documentation trop optimiste : le minimum publié correspond au seuil à partir duquel un prompt peut entrer dans le cache, pas à la longueur qui produit effectivement un cache hit. Pour les familles à cache automatique, l’écart va de 1,4 à 2,4 fois. Chez OpenAI, le premier hit effectif se situait autour de 1,456 tokens, contre 1,024 dans la documentation. Gemini 2.5 Flash a commencé à lire depuis le cache vers 5,000 tokens, contre 2,048 annoncés. Claude, qui ne met en cache que les segments marqués explicitement, respectait à quelques pour cent près le minimum documenté pour chaque modèle.

TL;DR

• Le minimum de 1,024 tokens documenté par OpenAI sous-estime le seuil effectif, qui se situe autour de 1,456 tokens sur les deux chemins testés.
• Gemini 2.5 Flash annonce 2,048 tokens, mais la première lecture apparaît vers 5,000 tokens, soit environ 2,4 fois plus.
• Le cache_control explicite de Claude respecte le minimum documenté à quelques pour cent près (Opus : 1,073 contre 1,024).
• GLM 5.2 et DeepSeek V4 ne publient aucun minimum et commencent à lire vers 800 tokens ; MiniMax M3 déclare environ 114 tokens en cache quelle que soit la longueur.
• Les caches automatiques ont aussi besoin de 2 à 8 appels de chauffe avant la première lecture.

Nous avons effectué chaque mesure sur deux chemins de serving : notre propre gateway et l’une des plus grandes gateways d’IA indépendantes. Nous n’avons attribué un résultat au modèle que lorsque les deux chemins concordaient. Ce second chemin permet d’identifier l’origine du comportement : si l’écart se reproduit sur la stack d’un autre fournisseur, il vient du modèle, pas de notre infrastructure. La vérification a été concluante pour OpenAI, Gemini et GLM, avec une mise en cache sur les deux chemins aux mêmes seuils effectifs. Elle n’est toutefois pas possible pour tous les modèles. Sur la seconde gateway, les modèles à poids ouverts passent principalement par des hébergeurs GPU qui n’implémentent pas le cache de prompts du fournisseur, ce que confirment les métadonnées de ses endpoints pour chaque provider. De plus, sans routage épinglé, les requêtes circulent entre ces hébergeurs et perdent l’affinité avec le cache. Lorsque le second chemin ne permettait pas de confirmer le résultat, les chiffres ci-dessous proviennent du chemin qui appelle directement l’API de cache du fournisseur concerné. Les longueurs sont exprimées dans les tokens propres à chaque modèle, calibrés à partir du champ usage renvoyé, et non en caractères. Pour chaque série, nous avons utilisé un préfixe neuf et relevé l’indice du premier appel produisant une lecture depuis le cache, plutôt qu’un simple résultat hit-or-miss.

Écart entre le seuil documenté et le seuil effectif

Le minimum documenté indique à partir de quand un prompt peut être mis en cache. Le seuil effectif correspond à la longueur à partir de laquelle la répétition du prompt produit réellement une lecture. Pour les familles à cache automatique, ces deux valeurs sont différentes.

Le résultat OpenAI était identique au token près sur les deux chemins : un prompt de 1,356 tokens ne produisait jamais de lecture, tandis qu’un prompt de 1,456 tokens en produisait une. L’écart le plus important concernait Gemini. Une première série plafonnant à 3,300 tokens n’a produit aucune lecture, ce qui donnait l’impression que le cache était désactivé. En poussant la série jusqu’à 5,000 tokens, nous avons obtenu une lecture nette à la même longueur sur les deux chemins. Le seuil documenté de 2,048 indique seulement à partir de quand le prompt devient éligible au cache, pas à partir de quand le cache sert effectivement des lectures.

Le constat est constant sur l’ensemble de l’étude : les caches marqués explicitement respectent leur spécification, contrairement aux caches automatiques.

Le minimum n’est pas la seule variable non documentée

Dépasser le seuil effectif est nécessaire, mais ne suffit pas. Les familles à cache automatique ont besoin d’une phase de chauffe : la première lecture intervient plusieurs appels plus tard, pas dès le deuxième.

• OpenAI : première lecture au 2e ou 3e appel.
• Gemini : première lecture entre le 4e et le 8e appel.

Cette latence doit entrer dans le calcul des coûts. Un prompt de 6,000 tokens dépasse tous les seuils Gemini, documentés comme effectifs. Pourtant, une charge qui l’envoie deux fois avant de passer à autre chose peut payer le plein tarif sur les deux appels, car le cache n’a pas encore chauffé. Un trafic court ou en rafales reste donc facturé au tarif hors cache même lorsque la longueur requise est atteinte. Nous n’avons conclu à l’absence de cache qu’après au moins douze appels répétés, avec un délai de stabilisation entre les appels. Sur Gemini, une série plus courte avait produit un faux négatif, invalidé par une série plus longue.

Les nombres de tokens en cache sont également arrondis à des blocs fixes, ce qu’il faut prendre en compte lors du rapprochement des factures : blocs de 128 tokens chez OpenAI, de 64 tokens chez DeepSeek. Une lecture indiquant 4,073 tokens en cache pour un prompt de 5,014 tokens correspond à un hit partiel sur le préfixe, arrondi à la limite d’un bloc, pas à un bug.

Les caches que vous contrôlez sont prévisibles

Claude ne met en cache que les segments marqués avec cache_control, et cette approche s’accompagne d’une spécification fiable. Toutes les affirmations d’Anthropic que nous avons testées se sont vérifiées :

• Minimum propre à chaque modèle, au token près. Opus 4.8 et Sonnet 5 ont produit leur première lecture à 1,073 tokens, contre 1,024 documentés ; Haiku 4.5 à 4,206, contre 4,096. Le léger dépassement vient de l’arrondi par blocs, pas d’une dérive du seuil.
• Tarif de lecture égal à 0.1x celui de l’input. Nous avons calculé le prix d’input de chaque modèle à partir de ses propres lignes sans cache, puis déduit le tarif du cache à partir d’une ligne avec hit. Pour Opus 4.8 comme pour Haiku 4.5, nous avons obtenu 0.10, conformément au multiplicateur documenté.
• Rafraîchissement gratuit de cinq minutes à chaque lecture. Après avoir initialisé un préfixe, nous l’avons relu après deux, quatre et six minutes. Chaque lecture a produit un hit. Une lecture effectuée dans chaque fenêtre de cinq minutes maintient l’entrée en vie sans nouvelle écriture payante.
• Invalidation en cascade. Avec un préfixe système stable et un outil défini, la seule modification de la description de l’outil a forcé la réécriture complète du cache système situé en aval. Modifier la définition d’un outil invalide les caches système et message, conformément à la hiérarchie documentée.

Nous avons aussi relevé une contradiction entre deux documentations. Un tableau tiers indiquait un minimum de 4,096 tokens pour Claude Opus. La lecture s’est produite à 1,073 tokens : la valeur de 1,024 publiée par Anthropic est la bonne.

Les familles à poids ouverts ne documentent généralement aucun minimum

Les familles précédentes publient au moins un chiffre, même s’il est inexact. Les modèles à poids ouverts et ceux issus de laboratoires chinois ne publient généralement aucun minimum. La mesure reste donc la seule option. Notre comparatif des caches par fournisseur examine la concordance entre les tarifs publiés et les tarifs observés une fois le hit obtenu. Ici, nous nous intéressons uniquement à la longueur à laquelle apparaît la première lecture.

GLM 5.2 ne publie aucune longueur minimale et commence à utiliser le cache vers 800 tokens, avec des blocs de 64 tokens sur les deux chemins. Son seuil est inférieur à celui de toutes les familles qui en documentent un. DeepSeek V4 ne publie pas non plus de minimum et commence également à lire vers 800 tokens, avec la même granularité de 64 tokens, mais uniquement via sa propre API de cache. La documentation de DeepSeek présente ce cache comme un mécanisme best effort, sans garantie de taux de hit. C’est exactement ce qu’on observe en passant par un intermédiaire : l’autre gateway sert DeepSeek depuis plusieurs hébergeurs GPU, mais seul l’endpoint de DeepSeek implémente le cache. Si le routage n’est pas épinglé sur cet endpoint, aucune lecture n’est renvoyée.

MiniMax M3 illustre un autre problème : c’est la valeur remontée elle-même qui induit en erreur. La documentation annonce un minimum de 512 tokens, mais le modèle déclare un nombre constant d’environ 114 tokens en cache dès le premier appel, pour toutes les longueurs comprises entre 200 et 5,000 tokens. Cette valeur ne suit pas la longueur du prompt et apparaît même sur des chemins qui n’effectuent aucune mise en cache. Il s’agit donc d’une comptabilité interne au modèle, pas d’un indicateur des données réellement réutilisées. Les modèles OpenAI les plus récents enseignent la même leçon sous un autre angle : les champs de tokens dans usage peuvent diverger du comportement réel du cache. Si les économies sont significatives, effectuez le rapprochement à partir de usage.cost, pas du nombre de tokens.

Les modèles les plus récents changent les règles

Deux évolutions documentaires doivent être prises en compte avant d’extrapoler le comportement des anciens modèles. Pour la famille GPT-5.6, le guide d’OpenAI indique que les écritures dans le cache coûtent 1.25x le tarif de l’input hors cache, alors qu’elles étaient gratuites sur les familles précédentes. Le même guide décrit le cache implicite comme un breakpoint placé sur le dernier message. Ce fonctionnement diffère d’un cache de préfixe qui réutilise un bloc système stable entre plusieurs tours. Si vous voulez réutiliser un préfixe stable sur ces modèles malgré des messages utilisateur différents, marquez-le avec un breakpoint explicite au lieu de compter sur le chemin implicite. Vérifiez pour chaque modèle le multiplicateur d’écriture et la longueur minimale : ces deux paramètres varient désormais selon la famille, alors qu’une page de documentation unique donne l’impression qu’ils sont uniformes.

Recommandations

• Mesurez votre propre seuil effectif. Faites varier la longueur du prompt dans les tokens de votre modèle et relevez la première longueur qui renvoie une lecture depuis le cache. Ne supposez pas que les hits commencent au minimum documenté.
• Intégrez la chauffe au budget. Dans votre modèle de coûts, considérez les deux à huit premiers appels sur un nouveau préfixe comme non mis en cache chez les fournisseurs à cache automatique.
• Préférez les marqueurs explicites lorsque le fournisseur les propose. Le cache_control de Claude fournit une spécification fiable et testable : minimum, tarif de lecture, TTL et règle d’invalidation connus. Cette prévisibilité vaut davantage qu’un seuil documenté plus bas sur lequel vous ne pouvez pas compter.
• Refaites vos mesures pour chaque nouvelle famille de modèles. Au cours de cette étude, les minimums, le prix des écritures et le comportement des breakpoints ont changé au sein de la gamme d’un même fournisseur.

Pour les tarifs de lecture, les TTL et les règles de clé associées à ces seuils, notre guide du cache de prompts détaille le fonctionnement propre à chaque fournisseur.

En bref : le minimum documenté correspond au seuil d’éligibilité, pas au seuil de hit. Pour les caches automatiques, l’écart va de 1,4 à 2,4 fois. Mesurez le chiffre qui détermine votre facture avec les tokens de vos modèles et votre propre trafic.

← Retour au blog