Minimums de prompt cache : la doc sous-estime d'un facteur 1,4 à 2,4x

Un client nous a signalé que le prompt caching de notre gateway ne se déclenchait pas au nombre de tokens promis par la documentation du modèle. On a reproduit le problème, puis rejoué chaque modèle sur un second chemin de service indépendant, l’un des plus gros AI gateways, où les mêmes écarts se reproduisaient au token près. C’est la documentation, et non tel ou tel gateway, qui pèche par optimisme : le minimum publié est un seuil d’éligibilité, pas la longueur nécessaire pour obtenir un cache hit. Pour les familles à cache automatique, l’écart entre les deux va de 1,4 à 2,4x. Le seuil effectif du premier hit chez OpenAI se situe autour de 1 456 tokens pour 1 024 documentés ; Gemini 2.5 Flash lit pour la première fois depuis le cache vers 5 000 tokens contre 2 048 documentés ; Claude, qui ne cache que là où vous placez un marqueur explicite, atteint son minimum documenté par modèle à quelques pour cent près.

TL;DR

• Le minimum de cache de 1 024 tokens documenté par OpenAI sous-estime le seuil effectif d’environ 1 456 tokens, mesuré sur les deux chemins.
• Gemini 2.5 Flash documente 2 048 mais lit pour la première fois vers 5 000 tokens, soit environ 2,4x plus.
• Le cache_control explicite de Claude atteint son minimum documenté à quelques pour cent près (Opus 1 073 contre 1 024).
• GLM 5.2 et DeepSeek V4 ne publient aucun minimum et lisent à partir d’environ 800 tokens ; MiniMax M3 rapporte environ 114 tokens en cache quelle que soit la longueur.
• Les caches automatiques ont aussi besoin d’un warm-up de 2 à 8 appels avant la première lecture.

On a fait passer chaque mesure par deux chemins de service, notre propre gateway et l’un des plus gros AI gateways indépendants, et on n’a retenu un résultat comme comportement du modèle que là où les deux chemins concordaient. Le second chemin sert à l’attribution : un écart qui se reproduit sur la stack d’un fournisseur sans lien avec nous vient du modèle, pas de nous. Ce recoupement a fonctionné proprement pour OpenAI, Gemini et GLM, qui cachaient sur les deux chemins, aux mêmes seuils effectifs. Il ne fonctionne pas pour tous les modèles : sur ce second gateway, les modèles open-weight sont largement servis par des hôtes GPU qui n’implémentent pas le prompt cache du fournisseur, ce que confirme la métadonnée d’endpoint du gateway pour chaque provider, et le routage non épinglé se déplace entre ces hôtes, ce qui fait perdre l’affinité de cache. Là où le second chemin ne pouvait pas corroborer, les chiffres ci-dessous proviennent du chemin qui atteint l’API de caching propre à chaque fournisseur. Les longueurs sont exprimées dans les tokens propres à chaque modèle, calibrés à partir du usage retourné, pas en caractères. Chaque test partait d’un préfixe neuf et enregistrait l’indice du premier appel ayant produit une lecture depuis le cache, pas un simple succès ou échec.

L’é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, lui, correspond à la longueur à laquelle un prompt répété revient réellement sous forme de lecture. Pour les familles à cache automatique, ces deux nombres ne coïncident pas.

Le chiffre d’OpenAI a tenu au token près sur les deux chemins : un prompt de 1 356 tokens n’a jamais été relu, un prompt de 1 456 tokens l’a été. C’est Gemini qui a montré le plus grand écart. Un balayage plafonnant à 3 300 tokens n’a produit aucune lecture et laissait croire que le cache était désactivé ; en étendant le balayage à 5 000, on obtient une lecture nette sur les deux chemins à cette même longueur. Les 2 048 documentés sont un plancher d’éligibilité au cache, pas un seuil à partir duquel il sert des lectures.

Le schéma se répète tout au long de l’étude : le cache que l’on marque explicitement a une spec fidèle, celui qui se déclenche automatiquement, non.

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

Passer le seuil effectif est nécessaire, mais pas suffisant. Les familles à cache automatique ont besoin d’une phase de chauffe : la première lecture arrive sur un appel plus tardif, pas sur le deuxième.

• OpenAI : première lecture aux appels 2 à 3.
• Gemini : première lecture aux appels 4 à 8.

C’est important pour la modélisation des coûts. Un prompt de 6 000 tokens dépasse tous les seuils Gemini, documentés comme effectifs, mais une charge qui l’envoie deux fois avant de passer à autre chose peut quand même payer le plein tarif les deux fois, faute d’un cache chaud. Un trafic court ou en rafales paie le tarif non mis en cache même quand la longueur qualifie. Nous n’avons conclu à « pas de mise en cache » qu’après au moins douze appels répétés espacés d’une pause ; un balayage plus court a produit un faux négatif sur Gemini qu’un balayage plus poussé a démenti.

Les compteurs de tokens en cache s’alignent aussi sur des blocs fixes, ce qu’il faut savoir au moment de rapprocher une facture : blocs de 128 tokens chez OpenAI, de 64 tokens chez DeepSeek. Une lecture de 4 073 tokens en cache sur un prompt de 5 014 tokens est un hit partiel de préfixe arrondi à une limite de bloc, pas un bug.

Les caches que vous contrôlez sont exacts

Claude ne met en cache que les segments que vous marquez avec cache_control, et ce contrôle s’accompagne d’une spec fidèle. Toutes les affirmations d’Anthropic que nous avons testées se sont vérifiées :

• Minimum par modèle, au token près. Opus 4.8 et Sonnet 5 lisent pour la première fois à 1 073 tokens face à 1 024 documentés ; Haiku 4.5 à 4 206 face à 4 096. Le léger dépassement est un arrondi de bloc, pas une dérive.
• Taux de lecture à 0,1x de l’input. Nous avons dérivé le prix d’input de chaque modèle à partir de ses propres lignes à froid, puis résolu le tarif en cache depuis une ligne de hit. Opus 4.8 et Haiku 4.5 ressortent tous deux à 0,10, conformément au multiplicateur documenté.
• Rafraîchissement de cinq minutes, gratuit à chaque lecture. En amorçant un préfixe et en le relisant à deux, quatre et six minutes, on obtient un hit à chaque lecture. Une lecture à l’intérieur de chaque fenêtre de cinq minutes maintient l’entrée en vie sans écriture supplémentaire.
• Invalidation en cascade. Avec un préfixe système stable et un outil défini, modifier uniquement la description de l’outil a forcé une réécriture complète du cache système en dessous. Modifier une définition d’outil invalide les caches système et messages, conformément à la hiérarchie documentée.

Un conflit doc-contre-doc en est ressorti. Un tableau tiers indiquait le minimum de Claude Opus à 4 096 tokens ; la mesure a lu à 1 073, et c’est le chiffre de 1 024 d’Anthropic qui est correct.

Les familles open-weight ne documentent généralement rien

Les familles précédentes publient au moins un chiffre, même s’il est erroné. Les modèles open-weight et ceux des laboratoires chinois ne publient le plus souvent aucun minimum, ce qui ne laisse que la mesure comme option. Notre comparatif du caching par fournisseur explique comment leurs taux annoncés se vérifient une fois qu’un hit se produit ; ici, la seule question est la longueur à partir de laquelle la première lecture apparaît.

GLM 5.2 ne publie aucune longueur minimale et cache à partir d’environ 800 tokens, avec une granularité de blocs de 64 tokens sur les deux chemins, soit un seuil plus bas que toutes les familles documentées. DeepSeek V4 ne publie pas non plus de minimum et lit à partir d’environ 800 tokens avec la même granularité de 64 tokens, mais uniquement sur sa propre API de caching. La doc de DeepSeek qualifie le cache de best-effort sans aucune garantie de taux de hit, et c’est exactement ce qu’expose un intermédiaire : l’autre gateway sert DeepSeek via un ensemble d’hôtes GPU où seul l’endpoint DeepSeek implémente le cache, donc un routage qui n’est pas épinglé sur cet endpoint ne renvoie aucune lecture.

MiniMax M3 est le cas où le chiffre annoncé induit lui-même en erreur. Il documente un minimum de 512 tokens, mais signale un nombre constant d’environ 114 tokens cachés dès le premier appel, à toutes les longueurs de 200 à 5 000 tokens. Ce nombre ne suit pas la longueur du prompt, et il apparaît même sur des chemins qui n’effectuent aucun caching : il s’agit donc de la comptabilité interne du modèle plutôt que d’un signal de ce qui a été réutilisé. C’est la même leçon que les modèles OpenAI récents enseignent dans l’autre sens : les champs de tokens d’usage et le caching réel peuvent diverger, donc quand les économies comptent, réconcilie sur usage.cost et non sur le nombre de tokens.

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

Deux changements au niveau de la doc méritent d’être signalés avant de supposer que le comportement des anciens modèles se prolonge. Sur la famille GPT-5.6, le guide OpenAI indique que les écritures dans le cache coûtent 1,25x le tarif d’entrée non caché, alors que les familles précédentes écrivaient gratuitement. Le même guide décrit le caching implicite comme le placement d’un breakpoint sur le dernier message, ce qui diffère du prefix caching d’un bloc système stable réutilisé d’un tour à l’autre. Si tu veux réutiliser un préfixe stable sur des tours utilisateur différents avec ces modèles, marque-le avec un breakpoint explicite plutôt que de compter sur le chemin implicite. Vérifie le multiplicateur d’écriture et le minimum pour chaque modèle, car les deux varient désormais selon la famille d’une manière qu’une page de doc unique aplatit.

Quoi en faire

• Mesurez votre propre seuil effectif. Faites varier la longueur du prompt dans vos propres tokens et notez la première longueur qui déclenche une lecture de cache. Ne partez pas du principe que les hits commencent au minimum documenté.
• Prévoyez la montée en charge. Dans votre modèle de coût, considérez les deux à huit premiers appels sur un nouveau préfixe comme non mis en cache pour les providers à cache automatique.
• Privilégiez les marqueurs explicites quand le provider les propose. Le cache_control de Claude fournit une spec précise et testable : un minimum connu, un taux de lecture connu, un TTL connu et une règle d’invalidation connue. Cette prévisibilité vaut mieux qu’un plancher documenté plus bas sur lequel vous ne pouvez pas compter.
• Refaites vos mesures de référence sur les nouvelles familles de modèles. Les minimums, la tarification en écriture et le comportement des breakpoints ont changé au sein d’une même gamme d’un fournisseur pendant cette étude.

Pour les taux de lecture, les TTL et les règles de clé qui se cachent derrière ces seuils, notre guide du prompt caching détaille les mécanismes par provider.

En résumé : le minimum documenté est un plancher d’éligibilité, pas un seuil de hit, et pour les caches automatiques les deux diffèrent d’un facteur 1,4 à 2,4. Vérifiez le chiffre qui pèse sur votre facture, dans vos propres tokens, sur votre propre trafic.

← Retour au blog