Une étude de cas sur la manière dont Claude atteint un taux de hit de cache de 92 %
Chaque fois qu'un agent IA effectue une étape, il paie une taxe.
Il relit tout depuis le début.
Les instructions système. Les définitions des outils. Le contexte du projet qu'il a déjà chargé trois tours plus tôt. Tout ça. À chaque tour.
C'est la taxe de contexte. Et pour les workflows agentiques de longue durée, c'est souvent le poste de dépenses le plus coûteux de toute votre infrastructure IA.
Voici le calcul un prompt système de 20 000 tokens sur 50 tours représente 1 million de tokens de calcul redondant facturé au plein tarif, sans produire aucune valeur nouvelle.
La solution est la mise en cache du prompt. Mais pour bien l'utiliser, il faut comprendre ce qui se passe réellement sous le capot.
Commencez par ce qui change et ce qui ne change pas
Avant d'optimiser quoi que ce soit, il faut réfléchir clairement à la structure du prompt (contexte) d'un agent.
Chaque requête envoyée par votre agent comporte deux parties fondamentalement différentes :
Le préfixe statique : il comprend les instructions système, les définitions des outils, le contexte du projet, les directives comportementales. Ce contenu est identique à chaque tour d'une session.
La queue dynamique : messages utilisateur, sorties des outils, observations du terminal. C'est unique à chaque requête et cela grandit au fil de la conversation.
Cette distinction est essentielle. Le préfixe statique est la partie coûteuse que vous recalculez sans raison. La queue dynamique est la seule partie qui nécessite réellement un calcul frais.
La mise en cache du prompt fonctionne en stockant l'état mathématique du préfixe statique afin que les requêtes futures puissent l'ignorer complètement. Vous payez une fois pour traiter ce préfixe. Chaque tour suivant le lit depuis la mémoire.
Pourquoi ça marche : ce que fait réellement un Transformer
Pour vraiment comprendre pourquoi la mise en cache est si efficace, il faut comprendre ce qui se passe à l'intérieur du modèle lorsqu'il lit votre prompt.
Chaque requête d'inférence LLM comporte deux phases :
Phase 1 : Prefill
C'est là que le modèle traite votre prompt d'entrée complet. Il est limité par le calcul, ce qui signifie qu'il exécute des multiplications matricielles denses sur chaque token de votre contexte. Le modèle lit tout et construit une représentation. C'est la phase lente et coûteuse.
Phase 2 : Decode
C'est là que le modèle génère les tokens de sortie, un par un. Elle est limitée par la mémoire plutôt que par le calcul, car le modèle passe la plupart de son temps à lire l'état précédemment calculé plutôt qu'à effectuer des calculs lourds.
Pendant la phase de prefill, le transformer construit trois vecteurs pour chaque token : une Query, une Key et une Value. Le mécanisme d'attention les utilise pour déterminer comment chaque token se rapporte à tous les autres tokens de la séquence.
Voici la découverte cruciale : les vecteurs Key et Value ne dépendent que des tokens qui les précèdent. Une fois qu'ils sont calculés pour un préfixe donné, ils n'ont jamais besoin de changer.
L'illustration ci-dessous explique visuellement ce que nous venons de décrire :
Sans mise en cache, ces tenseurs Key-Value sont jetés dès qu'une requête se termine. La requête suivante repart de zéro et les recalcule pour tous les 20 000 tokens.
Le KV caching résout ce problème en stockant ces tenseurs. L'infrastructure les conserve sur les serveurs d'inférence, indexés par un hachage cryptographique du texte d'entrée. Lorsqu'une nouvelle requête arrive avec le même préfixe, le hachage correspond, les tenseurs sont récupérés immédiatement, et le modèle ignore tout ce calcul.
Cela réduit la complexité algorithmique de O(n²) par token généré à O(n). Pour un préfixe de 20 000 tokens répété sur 50 tours, c'est une réduction énorme.
L'économie
Comprendre la structure de tarification rend cette décision architecturale d'autant plus importante.
Voici comment Anthropic tarifie la mise en cache dans ses familles de modèles :
Trois chiffres à retenir :
- Les lectures de cache coûtent 10 % du prix de base de l'entrée, soit une réduction de 90 % sur chaque token lu depuis le cache.
- Les écritures de cache coûtent 25 % de plus que le prix de base de l'entrée, soit une prime modeste pour stocker les tenseurs KV.
- Le cache étendu d'une heure coûte 2x le prix de base.
Le calcul n'est rentable que si votre taux de hit de cache reste élevé. Ce qui nous amène au meilleur exemple concret de ce à quoi cela ressemble en pratique.
Claude Code : visite guidée d'une session de 30 minutes
Claude Code est entièrement construit autour d'un objectif : garder le cache chaud.
Pour comprendre concrètement ce que cela signifie, parcourons une session de codage typique de 30 minutes et suivons exactement ce qui est facturé et ce qui ne l'est pas.
Minute 0 : Début de session
Claude Code charge son prompt système et ses définitions d'outils. Il lit également le fichier CLAUDE.md à la racine de votre projet, qui décrit la base de code et les conventions. Cette charge utile dépasse régulièrement 20 000 tokens.
C'est le moment le plus coûteux de toute la session. Chaque token est nouveau. Mais vous ne payez ce coût qu'une seule fois.
Minutes 1 à 5 : Premières commandes
Vous tapez votre première instruction, du genre « regarde le module d'authentification et propose des améliorations ».
Claude Code envoie un Explore Subagent. Il parcourt la base de code, ouvre des fichiers, exécute des commandes grep et construit une image du code pertinent. Tout cela est ajouté à la queue dynamique.
Les 20 000 tokens de base statique ? Déjà en cache. Lus à 0,30 $/MTok au lieu de 3,00 $/MTok. Vous ne payez que pour les nouvelles sorties des outils et votre message.
Minutes 6 à 15 : Travail en profondeur
Le Plan Subagent reçoit les résultats de l'Explore Subagent. Plutôt que de transmettre les résultats bruts textuellement (ce qui gonflerait inutilement la queue dynamique), Claude Code transmet un résumé concis. Cela maintient le suffixe gérable et le cache efficace.
Le planificateur produit un plan d'implémentation structuré. Vous le révisez, vous l'approuvez, et Claude Code commence à apporter des modifications. Chaque tour de cette boucle lit le préfixe de 20 000 tokens depuis le cache. Chaque hit de cache réinitialise le TTL, gardant le cache chaud pour les tours suivants.
Minutes 16 à 25 : Itération
Vous demandez des ajustements. Claude Code révise son approche. Davantage d'appels d'outils, davantage de sorties terminal. La queue dynamique grandit, mais elle représente uniquement le contenu nouveau et unique de cette session.
À ce stade, la session a traité des centaines de milliers de tokens au total. Mais la base de 20 000 tokens a été lue depuis le cache à chaque tour.
Minute 28 : Exécution de /cost
Sans mise en cache, une session comme celle-ci dépasse facilement les 2 millions de tokens. Au tarif Sonnet 4.5, cela représente environ 6,00 $.
Avec une mise en cache à haut rendement :
- La grande majorité des tokens sont lus depuis le cache à 0,30 $/MTok
- Seuls les nouveaux tokens de la queue dynamique sont calculés à neuf
En pratique, attendez-vous à une réduction des coûts de 80 % ou plus sur une tâche donnée. Multipliez maintenant cela par chaque utilisateur, chaque jour.
Pour résumer, voici à quoi ressemble la disposition du prompt système au fur et à mesure de la session :
La règle qui brise tout
Voici la chose la plus contre-intuitive à propos de la mise en cache du prompt.
1 + 2 = 3. Mais 2 + 1 est un échec de cache.
L'infrastructure hache le prompt. Le hachage est un identifiant cryptographique. Le hachage change si quoi que ce soit dans cet ordre change, même si deux éléments sont dans un ordre différent. Le cache est vide. Tout le préfixe est recalculé au plein tarif.
Trois règles qui en découlent :
- N'ajoutez ni ne retirez d'outils en cours de session. Le préfixe mis en cache inclut les outils. Changer les outils rend tout ce qui suit inutile.
- Ne changez jamais de modèle en milieu de session. Les caches sont spécifiques à chaque modèle. Passer à un modèle moins cher en cours de conversation nécessite de reconstruire tout le cache.
- Ne modifiez jamais le préfixe pour changer l'état. À la place, Claude Code ajoute une balise au prochain message utilisateur qui rappelle la consigne au système. Le préfixe ne change jamais.
Ce que ça signifie pour vous
Tout ce qui précède explique comment Claude Code gère la mise en cache. Les mêmes règles s'appliquent si vous créez votre propre agent.
Voici comment structurer vos prompts :
- En haut, les instructions système et les règles. Ne les modifiez pas en cours de route.
- Chargez tous les outils dont vous aurez besoin à l'avance. N'en ajoutez ni n'en retirez.
- Le contexte récupéré et les documents ensuite. Statiques pendant toute la durée.
- En bas, l'historique de la conversation et les sorties des outils.
Avec le cache automatique activé, le point de rupture avance automatiquement au fur et à mesure de la conversation.
Claude Code gère son propre cache. Anthropic vient d'ajouter le cache automatique à son API, vous pouvez donc faire de même pour votre propre agent.
Sans cache automatique, vous deviez vous souvenir où se trouvaient les limites des tokens. Une mauvaise limite signifiait ne pas atteindre le cache.
Utilisez le forking compatible avec le cache pour compacter en fonction de la limite de contexte. Utilisez le même prompt système, les mêmes outils et la même conversation, puis ajoutez la compaction comme nouveau message.
L'appel de compaction ressemble presque exactement au précédent. Le préfixe mis en cache est réutilisé. La seule chose qui est facturée comme nouvelle est l'instruction de compaction.
Pour vérifier si une API fonctionne, surveillez ces trois champs dans chaque réponse :
- cache_creation_input_tokens : tokens mis en mémoire
- cache_read_input_tokens : tokens lus depuis la mémoire
- input_tokens : tokens traités comme d'habitude
Votre score d'efficacité du cache est le nombre de tokens lus par rapport au nombre de tokens créés. Surveillez-le comme vous surveillez la disponibilité.
Points clés à retenir
La mise en cache du prompt n'est pas une fonctionnalité que l'on active. C'est une discipline architecturale autour de laquelle on construit.
Claude Code est le meilleur exemple de ce à quoi cela ressemble lorsqu'elle est appliquée à grande échelle.
Un taux de hit de cache de 92 %. Une réduction des coûts de 81 %.
Voici le plan si vous créez des agents. Vous ne pouvez pas ignorer la taxe, elle existe. La seule chose qui importe est de savoir si vous la payez ou si vous vous en débarrassez.
