Prompt caching : 8 règles pour Claude, OpenAI et Gemini

Que stocke le prompt caching ?

Un modèle de langage ne se souvient de rien d’une requête à l’autre. Si vous envoyez cent fois les mêmes instructions système, le même document ou le même contexte de code, ils sont traités cent fois et facturés cent fois. Le prompt caching (mise en cache du prompt) change cela : le fournisseur traite une fois la partie fixe qui ouvre la requête et la conserve ; les requêtes suivantes qui commencent de la même façon la relisent depuis le cache.

Ce qui est conservé n’est pas le texte lui-même, mais les états intermédiaires que le modèle calcule en traitant ce texte ; la section suivante l’explique. C’est pourquoi la correspondance doit être exacte : un préfixe qui n’est pas identique octet pour octet ne peut pas être lu depuis le cache.

Trois notions sont souvent confondues :

Source : documentation d’OpenAI, d’Anthropic, de vLLM et de GPTCache, 15 octobre 2026.

C’est notre quotidien : quand diffox examine une pull request, de nombreux agents spécialisés lisent le même contexte dans des appels séparés (son fonctionnement fait l’objet d’un article à part).

Comment fonctionne le cache

Avant de commencer à produire une réponse, un modèle de langage lit toute l’entrée ; cette phase s’appelle le préremplissage (prefill). Pendant ce temps, il calcule pour chaque token des états intermédiaires appelés clé (key) et valeur (value). La documentation d’OpenAI les appelle états KV : en produisant la réponse, le modèle s’appuie sur ces états pour revenir aux tokens précédents. C’est cela que le prompt caching conserve : non pas le texte, mais les tenseurs que le modèle a calculés en le traitant.

L’avantage vient de là. Si le préfixe est en cache, le modèle saute le calcul de cette partie et ne traite que les nouveaux tokens. La documentation de vLLM précise aussi où s’arrête le gain : le cache raccourcit le traitement de l’entrée, pas la génération des nouveaux tokens. Un long préfixe suivi d’une réponse courte est donc le cas qui profite le plus du cache. L’article Prompt Cache a mesuré un délai avant le premier token jusqu’à 8 fois plus court sur GPU et 60 fois plus court sur CPU.

Cette structure explique aussi pourquoi le préfixe doit être identique octet pour octet. Le document de conception de vLLM identifie chaque bloc du cache par deux choses : les tokens du bloc lui-même et ceux du préfixe qui le précède. La même phrase, précédée d’un autre texte, est donc un autre bloc. Ajoutez une seule date au début, et tous les blocs qui suivent deviennent de nouveaux blocs ; le cache ne sert que jusqu’à l’endroit du changement.

Ces états sont loin d’être petits. L’article PagedAttention écrit que la mémoire du KV cache de chaque requête est énorme et qu’elle grandit et rétrécit au fil de la requête. C’est pour cela que les fournisseurs limitent le cache à quelques minutes : selon la documentation de Google Cloud, le cache en mémoire est limité et des entrées sont évincées dès que la place manque. Anthropic précise aussi que ces états restent uniquement en mémoire et ne sont pas stockées de façon permanente.

Activation et prix chez quatre fournisseurs

Les quatre fournisseurs prennent en charge le cache, mais pas de la même façon : l’activation, la taille minimale du préfixe et le prix diffèrent. Nous avons tiré le tableau de la documentation de chaque fournisseur, le 15 octobre 2026.

Source : documentation des fournisseurs, 15 octobre 2026. Les multiplicateurs se rapportent au prix de l’entrée sans cache. La ligne Google Cloud vaut pour Gemini 2.5 et les modèles suivants.

Chez Anthropic et sur les modèles d’OpenAI à partir de GPT-5.6, écrire dans le cache coûte plus cher qu’envoyer le même token sans cache, et lire coûte beaucoup moins. Un cache qui écrit à 1,25× est donc rentabilisé dès la première lecture, et le cache d’une heure d’Anthropic, qui écrit à 2×, à la deuxième. Dans le cache explicite de Gemini, l’écriture est au prix standard, mais des frais de stockage sont facturés pour chaque heure où le cache existe ; la rentabilité dépend alors du nombre de lectures et de la durée de conservation.

Avec l’API Claude, quand de nombreux appels lisent le même contexte, placez le marqueur sur le bloc commun et l’instruction propre à chaque appel après lui. ephemeral est aujourd’hui le seul type de cache pris en charge ; le nom du modèle est celui de l’exemple de la documentation :

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<contexte commun, le même texte à chaque appel>",
      "cache_control": {"type": "ephemeral"}
    },
    {
      "type": "text",
      "text": "<instruction propre à cet appel>"
    }
  ],
  "messages": [
    {"role": "user", "content": "<la question de cet appel>"}
  ]
}

Combien de temps le cache reste-t-il chaud ?

Une entrée du cache ne reste pas indéfiniment. La documentation de Claude Code résume la situation en deux mots : tant que l’entrée est dans sa durée de vie (TTL), le cache est chaud (warm) ; une fois celle-ci écoulée, il est froid (cold). Avec un cache chaud, la requête suivante lit le préfixe à bas prix ; avec un cache froid, elle le retraite entièrement et paie l’écriture.

Source : documentation des fournisseurs, 15 octobre 2026. La durée du cache implicite de Gemini n’est pas précisée dans la documentation ; sur Google Cloud, elle est de 24 heures au plus et la plupart des entrées disparaissent avant.

Cette durée fonctionne comme un compte à rebours, avec deux subtilités. Chez Anthropic, il part du début de la requête, pas de la fin de la réponse : si le streaming de la réponse a duré 4 minutes, la requête suivante sur le même préfixe doit partir dans un délai d’environ 1 minute. Chez Anthropic, OpenAI et Bedrock, chaque succès de cache relance le compte à rebours ; un trafic régulier garde donc le cache chaud de lui-même.

La plupart des fournisseurs n’ont pas d’endpoint qui dise si le cache est encore chaud. L’exception est le cache explicite de Gemini : cachedContents.get renvoie toujours l’heure d’expiration (expireTime), jamais le contenu. Chez Anthropic, OpenAI et Bedrock, seule la réponse suivante vous renseigne : si le nombre de tokens lus depuis le cache tombe à zéro, soit le préfixe a changé, soit l’entrée a refroidi. L’outil cache diagnostics d’Anthropic distingue les deux : si les requêtes sont identiques et que la lecture vaut zéro, l’entrée a expiré.

Dans Claude Code, la durée dépend de la façon dont vous payez. Selon la documentation, avec un abonnement Claude, la conversation principale utilise un cache d’une heure tant que vous restez dans l’usage inclus dans votre forfait. Avec des crédits d’utilisation, une clé d’API ou un fournisseur cloud, elle passe à un cache de 5 minutes. Les subagents ont 5 minutes, même avec un abonnement. Vous pouvez changer la durée avec le paramètre promptCacheTtl ou la variable CLAUDE_CODE_PROMPT_CACHE_TTL.

L’état du cache s’affiche à trois endroits. /usage indique si le cache est chaud ou froid, avec la durée en vigueur. Dans le JSON transmis à la ligne d’état (status line), l’objet prompt_cache contient les champs warm, ttl et expires_at ; ce dernier donne le moment où le cache refroidira. L’horloge du cache dans l’extension VS Code décompte enfin une durée de vie de 5 minutes ou d’une heure et affiche les minutes restantes ; avec un cache d’une heure, elle part de 60 minutes.

Trois points à surveiller :

• L’écart entre deux requêtes doit rester inférieur à la durée. Chaque requête qui arrive plus de 5 minutes après la précédente réécrit le préfixe. Anthropic conseille de rester sur le cache de 5 minutes si le préfixe est réutilisé plus souvent que toutes les 5 minutes, car son renouvellement est gratuit.
• Une durée longue n’est pas gratuite. Chez Anthropic, écrire dans le cache d’une heure coûte 2 fois le prix de base, et ce n’est rentable qu’à partir de deux lectures du préfixe ; dans le cache explicite de Gemini, des frais de stockage sont payés pour chaque heure.
• La première requête après une longue pause coûte cher. Avec un cache refroidi, la première requête écrit tout le préfixe. Vous pouvez préchauffer le cache avant l’arrivée de la vraie requête : chez Anthropic avec max_tokens: 0, sur les modèles d’OpenAI à partir de GPT-5.6 avec prompt_cache_options.prewarm.

Dans un exemple à dix appels, le préfixe coûte 78,5 % de moins

Les chiffres sont ronds et hypothétiques ; ils servent seulement à illustrer les multiplicateurs de la documentation. Prenons dix appels qui lisent un préfixe commun de 50 000 tokens. L’unité est un token facturé au prix d’entrée de base ; l’écriture est comptée à 1,25×, la lecture à 0,1×. Le cache de 5 minutes d’Anthropic et la plupart des modèles d’OpenAI à partir de GPT-5.6 appliquent ces multiplicateurs.

sans cache     10 × 50 000 × 1      = 500 000

avec cache      1 × 50 000 × 1,25   =  62 500   le premier appel écrit
              + 9 × 50 000 × 0,1    =  45 000   neuf appels lisent
                                    = 107 500

Lancés l’un après l’autre, les dix appels paient pour le préfixe l’équivalent de 107 500 tokens, soit 78,5 % de moins que les 500 000 sans cache. Sur un modèle dont la lecture coûte 0,05×, le total descend à 85 000. Avec le cache d’une heure, l’écriture monte à 100 000 et le total atteint 145 000.

La troisième barre montre le pire cas : les dix mêmes appels partent en même temps. Aucun ne peut lire ce qu’un autre a écrit, et si chacun écrit lui-même le préfixe, le total atteint 625 000. C’est 25 % plus cher que de ne pas activer le cache du tout. La raison est expliquée plus bas, dans la section sur les appels parallèles.

Les 8 règles pour un bon taux de succès du cache

Les documentations des quatre fournisseurs disent la même chose sur les succès de cache. Chacune des règles ci-dessous figure dans la documentation d’au moins deux fournisseurs.

La règle la plus souvent négligée est la deuxième. Une ligne des notes de version de Claude Code le montre : retirer la date du prompt système a amélioré le taux de succès. La date change chaque jour, et si elle se trouve au début du préfixe, la première requête de chaque nouvelle journée réécrit tout le préfixe.

Deux règles sont propres à un seul fournisseur. Sur les modèles d’OpenAI antérieurs à GPT-5.6, on donne une prompt_cache_key fixe aux requêtes qui partagent le même préfixe. Elle aide à les diriger vers le même cache, et la documentation recommande environ 15 requêtes par minute et par clé. Anthropic, de son côté, demande que l’ordre des clés JSON dans les appels d’outils reste stable. Selon sa documentation, certains langages comme Swift et Go mélangent l’ordre des clés, et le même contenu est alors envoyé sous forme d’octets différents.

Ce qui invalide le cache

Chez Anthropic et Bedrock, le cache suit une hiérarchie : tools, system, messages. Un changement à un niveau invalide ce niveau et tous les niveaux suivants. Voici six cas parmi ceux qu’énumère la documentation d’Anthropic :

Activer ou désactiver les citations a le même effet que la recherche web ; ajouter ou retirer une image du prompt, le même effet que tool_choice. Le cas que la documentation présente comme une « erreur courante » est la quatrième carte : si le breakpoint se trouve sur un bloc qui contient un horodatage ou le message de l’utilisateur, chaque requête écrit une nouvelle entrée et aucune ne peut la lire. Le système remonte au plus 20 blocs en arrière ; mais ce qu’il cherche n’est pas du contenu inchangé, c’est une entrée écrite par une requête précédente. L’écriture n’a lieu qu’au breakpoint. C’est pourquoi le marqueur se place sur le dernier bloc qui reste identique d’une requête à l’autre.

Appels parallèles et cache

Lancer en même temps des appels qui lisent le même préfixe paraît naturel. La documentation d’Anthropic est claire sur ce point : pour des requêtes simultanées, une entrée du cache n’est utilisable qu’une fois la première réponse commencée ; si vous voulez que des requêtes parallèles lisent le cache, attendez la première réponse avant d’envoyer les suivantes. OpenAI écrit aussi que le cache se trouve sur des machines individuelles et qu’au-delà de 15 requêtes par minute, le trafic peut partir vers d’autres machines.

La première réponse n’a pas besoin d’être terminée : il suffit qu’elle ait commencé. Les documentations proposent trois façons de faire :

• Envoyez le premier appel seul. Claude Code le fait lui-même quand un workflow lance ensemble des agents qui partagent le même préfixe : il retient tous les agents sauf le premier jusqu’à ce que la réponse du premier commence ; l’attente est par défaut de 5 000 millisecondes au plus.
• Préchauffez le cache. Une requête envoyée avec max_tokens: 0 écrit dans le cache au breakpoint et revient sans produire de sortie ; aucun token de sortie n’est facturé. Le marqueur doit être sur le bloc commun, et le paramètre de réflexion (thinking) comme la valeur output_config.effort doivent être ceux des vrais appels. La requête est refusée si elle est combinée à une option qui exige une sortie (par exemple stream: true).
• En traitement par lots, utilisez le cache d’une heure. Dans la Batch API, les requêtes sont traitées dans n’importe quel ordre et la lecture n’est pas garantie. La documentation conseille d’envoyer d’abord, avec le cache d’une heure, une seule requête qui porte le préfixe commun, puis le reste une fois celle-ci terminée.

Comment mesurer le taux de succès

Ne supposez pas que le cache fonctionne : vérifiez-le dans la réponse. Les quatre fournisseurs indiquent les tokens lus depuis le cache dans un champ à part des informations d’usage de la réponse :

Source : documentation des fournisseurs, 15 octobre 2026.

Le taux de succès est la part des tokens lus depuis le cache dans l’entrée totale ; OpenAI le définit ainsi et conseille de l’agréger par utilisateur, par espace de travail ou par jour. Encore faut-il calculer correctement l’entrée totale : chez Anthropic et Bedrock, le champ d’entrée ne compte pas les tokens qui passent par le cache, et le total est la somme des trois champs ; chez Gemini, promptTokenCount inclut déjà les tokens lus depuis le cache.

L’entrée totale est la somme des trois champs. input_tokens seul ne montre pas toute l’entrée ; il ne compte que ce qui suit le dernier breakpoint. Quand tout fonctionne, le champ d’écriture vaut la taille du préfixe au premier appel, puis ce même nombre passe dans le champ de lecture aux appels suivants. Si les deux champs valent zéro, le prompt n’a pas été mis en cache ; la cause la plus probable est un préfixe sous la longueur minimale. Si le champ d’écriture reste haut à chaque appel, quelque chose change dans le préfixe.

Nous enregistrons séparément les trois champs de chaque appel. Un appel sans informations d’usage est compté comme non mesuré, pas comme zéro : un vide noté zéro se lit comme un appel gratuit.

Quand le cache n’est pas rentable

Le cache ne convient pas à toutes les charges de travail. Avant de l’activer, vérifiez ces quatre cas :

• Le préfixe n’est lu qu’une fois. Si l’écriture coûte 1,25 fois le prix et qu’aucun deuxième appel ne le lit, vous payez 25 % de plus.
• L’écart entre les appels dépasse la durée. Le cache est froid à chaque fois et le préfixe est réécrit.
• Le préfixe est sous la longueur minimale. La requête fonctionne, le cache non ; et aucune erreur n’est renvoyée.
• Le préfixe change à chaque requête. Une date au début oblige chaque requête à réécrire le cache.

Le gain ne se limite pas au prix : sur les longs préfixes, le délai avant le premier token raccourcit aussi. Sur les limites de débit, les fournisseurs divergent : selon Anthropic et Bedrock, les tokens lus depuis le cache ne sont pas décomptés de la limite de débit pour Claude ; chez OpenAI, ils comptent dans la limite de tokens par minute.

Dans diffox, les agents spécialisés d’une review lisent le même contexte commun : le diff du changement et le contexte des fichiers. Ce contexte se trouve dans un seul bloc au début de la requête, et c’est ce bloc qui porte le marqueur de cache ; le premier appel part seul, les autres démarrent ensuite en parallèle. Les tokens écrits et lus par chaque appel sont enregistrés séparément.