Claude : un cache hit ne prouve pas une économie

Le tableau de bord annonce 60 % de requêtes servies en partie depuis le cache. Pourtant, la dépense par lot baisse peu, voire augmente sur certains parcours. Le risque vient d’un raccourci : compter les lectures réussies sans payer les écritures qui les ont rendues possibles. Pour une équipe qui utilise Claude dans un assistant documentaire ou un logiciel métier, ce pourcentage ne suffit pas à décider entre cinq minutes et une heure de conservation.

En pratique, l’économie doit se reconstruire avec les compteurs de chaque appel, le tarif applicable et une comparaison à volumes identiques. Une lecture de cache n’est pas gratuite ; une écriture longue peut ne jamais être amortie. Notre accompagnement en IA et automatisation sur mesure relie cette instrumentation aux opérations du logiciel, avant d’en déduire un budget de fonctionnement ou un coût par dossier.

Ce dossier propose cinq appels entièrement fictifs, un calcul décimal exécutable et une décision de durée de cache. Les tarifs Sonnet 5.5 ont été vérifiés le 24 octobre 2026 ; aucun modèle ni compte client n’a été interrogé. L’industrialisation et la gouvernance de l’IA organisent ensuite le rapprochement, les responsabilités et les alertes. Le résultat attendu est un coût explicable, sans confondre performance du cache, qualité des réponses et service réellement rendu.

Dans quel cas le coût du cache mérite une enquête

Un préfixe répété dans plusieurs demandes métier

Imaginez un assistant interne qui reçoit les mêmes consignes de classement et le même référentiel, puis une question différente à chaque appel. Une partie de l’entrée pourrait être réutilisée. Le responsable du logiciel veut savoir si cette répétition réduit la dépense, tandis que le métier attend toujours une réponse correcte et autorisée. Le relevé des consommations doit permettre de discuter ces deux questions séparément, sans attribuer au cache une amélioration de qualité qu’il n’a pas mesurée.

Le sujet devient prioritaire lorsque les coûts estimés ne correspondent plus au relevé fournisseur, lorsque deux environnements affichent des pourcentages de cache comparables mais des dépenses différentes, ou lorsque l’équipe prolonge systématiquement la durée pour obtenir davantage de hits. Commencez par un parcours assez délimité pour retrouver ses appels. Une moyenne réunissant conversation interactive, import nocturne et tests de développement cache les rythmes qui expliquent les écritures répétées.

Un diagnostic inutile si l’entrée change à chaque demande

Une entrée presque entièrement spécifique au dossier offre peu de matière commune. Dans ce cas, la première question porte sur le contenu transmis et sa nécessité, avant une optimisation de durée. Une pièce personnelle ne doit pas être déplacée dans un préfixe partagé pour améliorer un indicateur. Les permissions, la séparation des clients et la fraîcheur des documents restent des contraintes de conception ; un coût inférieur ne justifie aucune extension d’accès aux sources.

Nous étudions ici les jetons d’un profil tarifaire précis. Ni hébergement, ni recherche documentaire, ni travail de contrôle humain ne sont compris. Le diagnostic peut montrer un gain technique et laisser le coût total du processus presque inchangé. Pour le sponsor, le livrable associe donc un registre de consommations à une liste de postes exclus, avec un responsable capable d’expliquer pourquoi ces postes ne figurent pas dans le total.

Ce qui a changé dans le tarif Sonnet 5.5

Une baisse datée, limitée aux lectures concernées

Les notes de version Claude du 7 octobre 2026 annoncent une baisse des lectures de cache Sonnet 5.5 : de 0,20 à 0,10 dollar par million de jetons. Les écritures et les autres prix ne changent pas dans cette annonce. Il s’agit d’une évolution antérieure à la semaine du 16 au 23 octobre, pertinente pour contrôler les estimateurs encore configurés avec l’ancienne valeur.

Notre décision d’intégration consiste à versionner le barème avec le modèle, la date et le profil de facturation. Changer une constante commune à tous les modèles serait une correction trop large. Un historique déjà rapproché doit garder le tarif qui lui correspond ; le recalcul d’un ancien lot avec le prix courant se présente comme une simulation. Cette distinction permet d’expliquer un écart sans réécrire silencieusement les dépenses passées.

Les cinq prix utilisés dans notre exercice

La grille de prix officielle donne, pour Sonnet 5.5, les montants suivants en dollars par million de jetons : entrée ordinaire 2 ; écriture cinq minutes 2,50 ; écriture une heure 4 ; lecture 0,10 ; sortie 10. Notre scénario retient le profil standard global, sans outils facturables, Batch, remise ou surcharge régionale. Ce périmètre est une condition du calcul.

Le programme refuse un autre profil plutôt que lui appliquer ces prix par défaut. Il ne sert donc pas à estimer directement tous les modèles Claude. Dans un logiciel réel, une table de tarifs approuvée prendrait le relais, avec sa date de vérification et ses dimensions. Une ligne non reconnue reste à rapprocher : l’afficher à zéro rendrait le tableau de bord artificiellement favorable et cacherait précisément l’usage à examiner.

Lire les compteurs sans compter deux fois les écritures

Le champ input_tokens ne représente pas toute l’entrée

La documentation du prompt caching distingue l’entrée non mise en cache, la création et la lecture. Le total d’entrée s’obtient en additionnant input_tokens, cache_creation_input_tokens et cache_read_input_tokens. Soustraire les lectures à input_tokens est donc incorrect. Avec 1 000 jetons non cachés et 10 000 lus, cette soustraction donnerait −9 000 jetons au lieu de décrire 11 000 jetons d’entrée.

Pour garder une trace contrôlable, le registre conserve les compteurs bruts reçus et une version de la règle de calcul. Le tableau métier peut afficher des colonnes plus courtes, mais il doit permettre de retrouver la donnée d’origine. Une valeur négative ne se corrige pas en la ramenant à zéro : elle bloque l’estimation et déclenche l’examen de la transformation. Autrement, le symptôme du mauvais calcul disparaîtrait du suivi.

Le détail cinq minutes et une heure répartit un total existant

La référence Create a Message et son objet usage expose les mesures d’utilisation et le détail de création. Dans notre contrat de calcul, la somme de ephemeral_5m_input_tokens et ephemeral_1h_input_tokens doit égaler cache_creation_input_tokens. Le total sert à contrôler la cohérence ; les deux sous-compteurs servent à appliquer leurs prix respectifs. Ils ne constituent pas trois écritures supplémentaires à additionner.

Nous exigeons ici un relevé final complet, avec des entiers positifs ou nuls et un détail explicite des durées, y compris les zéros. C’est une règle du petit vérificateur, pas une affirmation que toutes les réponses possibles de l’API auront cette forme. Un adaptateur de production doit qualifier champs absents ou nuls avant normalisation. Deviner la durée d’une création positive empêcherait de distinguer deux prix réellement différents.

Exemple : cinq appels, deux durées et une lecture partielle

Déclarer les entrées avant de calculer le résultat

Scénario fictif : R1 crée 10 000 jetons pendant cinq minutes ; R2 en lit 10 000. R3 crée 10 000 jetons pendant une heure ; R4 en lit 10 000. R5 combine 6 000 jetons lus, 2 000 écrits cinq minutes et 1 000 écrits une heure. Chaque appel ajoute 1 000 jetons d’entrée ordinaire et produit 500 jetons de sortie. Ces valeurs sont fournies au programme, sans simuler la disponibilité effective d’un cache.

R5 est le cas qui révèle les erreurs de répartition. Son entrée totale vaut 1 000 + 6 000 + 3 000 = 10 000 jetons. Ses créations détaillées valent bien 2 000 + 1 000 = 3 000. Son coût associe 0,002 dollar d’entrée ordinaire, 0,0006 de lecture, 0,005 d’écriture courte, 0,004 d’écriture longue et 0,005 de sortie : 0,0166 dollar. Aucun poste n’est ajouté une seconde fois.

Une comparaison théorique à volumes strictement identiques

Le lot comprend 54 000 jetons d’entrée et 2 500 de sortie. Son coût calculé vaut 0,1116 dollar. Si toute cette entrée était facturée au prix ordinaire, avec les mêmes sorties, le montant serait 0,133 dollar : 0,108 d’entrée plus 0,025 de sortie. L’écart théorique est 0,0214 dollar, soit environ 16,09 %. Cette comparaison fixe les volumes ; elle ne mesure pas deux exécutions réelles du même assistant.

Trois appels sur cinq contiennent une lecture, soit 60 % de hits au niveau des requêtes. Les 26 000 jetons lus représentent environ 48,15 % des 54 000 jetons d’entrée. Aucun de ces taux ne vaut 16,09 %. Donner leurs dénominateurs dans l’écran évite de présenter une part de requêtes comme un pourcentage d’économie. Un petit appel et un appel beaucoup plus long pèsent pareil dans le premier ratio, mais pas dans la dépense.

Choisir une heure seulement si les réutilisations le justifient

Un cache hit peut accompagner une hausse de coût

Paradoxalement, R3 suivi de R4 produit un hit tout en coûtant plus cher que deux appels ordinaires équivalents. Le couple vaut 0,047 + 0,008 = 0,055 dollar ; la référence sans cache vaut 2 × 0,027 = 0,054. L’écart défavorable est de 0,001 dollar. La lecture a bien réduit le prix du second appel, mais pas assez pour compenser l’écriture longue du premier. Le verdict porte sur le couple complet.

Avec une seconde réutilisation identique, le total devient 0,063 dollar contre 0,081 pour trois appels ordinaires, soit environ 22,22 % de moins. Ce seuil appartient à nos volumes et à notre barème. Il ne promet pas que deux futurs hits auront lieu. Pour prendre une décision, l’équipe doit examiner les reprises effectivement observées et le temps qui les sépare, plutôt que compter des demandes prévues comme des lectures déjà obtenues.

Une durée plus courte n’est pas automatiquement préférable

R1 et R2 coûtent ensemble 0,040 dollar contre 0,054 dans la référence, soit environ 25,93 % de moins. Mais cette comparaison suppose la lecture fournie dans R2. La documentation précise que la durée du cache part du début de la requête qui écrit ou lit l’entrée, et non de la fin de sa réponse. Une génération longue peut donc réduire le temps disponible avant l’appel suivant. Le chronométrage du parcours doit utiliser la bonne frontière.

Notre recommandation d’essai est de regrouper les parcours par cadence réelle : série rapide, interaction espacée, reprise imprévisible. Pour chaque groupe, gardez écritures, lectures et appels ordinaires, puis comparez les montants sur une fenêtre déclarée. La politique choisie peut varier selon le groupe. Une durée unique retenue pour simplifier l’administration se chiffre comme un compromis, avec ses réécritures ou ses écritures longues inutilisées, au lieu de masquer ces coûts dans une moyenne.

Rattacher une mesure finale à une seule requête

Rejouer la collecte sans doubler la dépense

Le fichier d’exercice ajoute une identité locale request_key, une date et un profil autour de l’objet usage. Ces noms de métadonnées sont notre convention, pas des champs imposés par Claude. Réimporter exactement le même relevé ne change pas le total. Réimporter la même identité avec 501 jetons de sortie au lieu de 500 provoque un refus. Le programme ne choisit pas silencieusement la version la moins chère ou la dernière arrivée.

En production, l’identité doit être reliée à la tentative fournisseur et à son environnement. Une nouvelle tentative réellement envoyée peut entraîner une nouvelle dépense même si elle répond au même dossier. À l’inverse, un journal recopié n’est pas un nouvel appel. Le contrat de traçabilité doit distinguer ces deux événements. Notre script reçoit uniquement des relevés finaux : il ne traite pas l’assemblage d’un flux d’événements de streaming et ne prétend pas régler cette collecte.

Conserver une estimation incomplète comme telle

Un relevé sans détail de durée n’est pas valorisé arbitrairement au tarif cinq minutes. Il rejoint la liste des mesures incomplètes avec sa cause. Le responsable du rapprochement peut demander le relevé complet ou isoler une estimation documentée. Le seuil de données manquantes acceptable doit être fixé avant la lecture des économies ; dans notre exercice, une seule ligne invalide empêche de déclarer le lot entièrement chiffré.

Le registre de coûts n’a pas besoin de copier le contenu des demandes, les pièces jointes ou les réponses. Identifiants, compteurs, modèle et périmètre suffisent à cette démonstration. Si une enquête nécessite d’autres données, leurs accès et leur conservation doivent être examinés séparément. Éviter les contenus inutiles rend le diagnostic plus facile à partager avec les responsables financiers, sans leur ouvrir les dossiers métier sous-jacents.

Rapprocher l’estimation du relevé fournisseur

Une chaîne décimale en cents n’est pas un montant en dollars

L’Usage and Cost Admin API documente des coûts en chaînes décimales exprimées en cents USD et une granularité quotidienne pour le rapport de coûts. Une valeur fictive "11.16" dans ce format représente 0,1116 dollar, pas 11,16 dollars. Le contrôleur vérifie cette conversion. L’erreur serait d’un facteur cent, bien plus importante que l’optimisation étudiée.

Le rapprochement demande aussi une même journée, un même espace de travail et un périmètre comparable. Si le relevé comprend d’autres usages, il ne doit pas être forcé à égaler nos cinq lignes. La fiche distingue consommations locales estimées, montant fournisseur observé et différence non expliquée. Le rapport permet une investigation ; il ne transforme pas notre sortie JSON en facture ni en montant comptable définitivement validé.

Ne pas distribuer un accès d’administration au calculateur

L’accès au rapport relève de l’API d’administration et de ses autorisations. Le petit exemple téléchargeable n’en a pas besoin : il n’utilise aucun secret et ne contacte aucun service. Dans l’architecture du logiciel, un collecteur autorisé peut fournir un export limité au rapprochement. Le composant qui affiche les coûts n’a pas à recevoir les mêmes droits que celui qui collecte les informations à l’échelle de l’organisation.

Une différence déclenche une recherche ordonnée : période, unité monétaire, modèle, profil, appels manquants, duplications, puis postes exclus. L’équipe conserve le résultat de cette recherche et la version du barème corrigé. Un écart résiduel reste visible au lieu d’être réparti automatiquement sur les dossiers pour faire disparaître la différence. Cette visibilité protège la prochaine décision de budget contre un total apparemment exact mais impossible à expliquer.

Exécuter le calcul et les contre-exemples

Un fichier autonome, sans compte Claude

Le vérificateur Python du coût du cache utilise la bibliothèque standard et Decimal. Téléchargez le fichier, relisez ses cinq relevés, puis lancez python3 cout_cache_claude.py. Il calcule les montants, vérifie les références connues et refuse les entrées incompatibles avec son contrat. Il ne modifie aucun fichier, ne déclenche aucune dépense et ne reproduit pas le mécanisme de cache du fournisseur.

totalUsd       = 0.1116
baselineUsd    = 0.133
differenceUsd  = 0.0214
requestHits    = 3/5
inputReadShare = 26000/54000

L’ordre inverse des cinq relevés donne le même résultat. Une copie exacte du dernier relevé n’ajoute rien. Les cas refusés couvrent notamment identité vide, modèle inconnu, date hors exercice, profil Batch, compteur négatif, fractionnaire ou manquant, détail null et somme de création incohérente. Ces refus vérifient la frontière annoncée du calcul ; ils ne constituent pas une validation générale de toutes les réponses possibles de l’API.

Trois raccourcis qui doivent échouer

Premier témoin : conserver l’ancien prix de lecture porte le lot à 0,1142 dollar au lieu de 0,1116. Deuxième témoin : ajouter les 3 000 créations agrégées de R5 au prix court, en plus de leurs deux détails déjà valorisés, donne 0,0241 au lieu de 0,0166. Troisième témoin : retirer les lectures de l’entrée ordinaire produit −9 000 sur R2. Les valeurs attendues rendent ces erreurs observables sans modèle externe.

La recette réelle doit ensuite vérifier l’adaptateur de collecte : un appel ordinaire, une création, une lecture et une combinaison de durées, avec le modèle et les options réellement déployés. Gardez les réponses d’usage autorisées et comparez les agrégats au relevé fournisseur. Le script établit une arithmétique sur des fixtures ; seuls ces essais complémentaires peuvent établir que le logiciel alimente correctement le registre dans votre environnement.

Erreurs fréquentes dans un tableau de bord de cache

Afficher un taux sans son périmètre

Une courbe peut augmenter parce que l’équipe a ajouté de nombreuses petites requêtes faciles à servir depuis le cache. Le pourcentage de hits progresse alors que les gros appels non cachés continuent de dominer la dépense. Présentez ensemble nombre de requêtes, volumes d’entrée par catégorie et montant. Pour diagnostiquer une régression, gardez aussi les familles métier : le changement de composition du trafic peut expliquer la variation sans aucune modification de code.

Autre erreur : ne retenir que les appels qui ont trouvé le cache. Le coût de leur préparation disparaît et chaque hit semble immédiatement rentable. Conservez les écritures sans réutilisation dans la même période d’analyse. Si une entrée écrite en fin de période est réutilisée au début de la suivante, signalez cette frontière dans la comparaison. Une fenêtre trop courte peut modifier le verdict sans modifier le fonctionnement du système.

Optimiser la dépense en dégradant le service

Retarder une réponse pour regrouper des demandes peut favoriser la répétition, mais imposer une attente inacceptable au métier. Raccourcir les documents transmis peut réduire le coût tout en retirant une information nécessaire. Toute variante de traitement doit donc conserver une évaluation des sorties et du délai. La décision ne repose pas uniquement sur les jetons : elle compare un service autorisé, utile et assez rapide pour les utilisateurs concernés.

Le calcul du coût par dossier correctement traité complète cette lecture. Il rattache tentatives, corrections et reprises humaines au résultat métier. Une baisse de 16,09 % sur notre composante technique fictive ne devient pas une baisse identique du coût du dossier. La part de cette composante dans le processus doit être établie avant toute projection économique.

Plan d’action : décider avec un relevé rapprochable

Préparer une mesure limitée et reproductible

1. Choisir un parcours avec un préfixe stable et une cadence identifiable. Fixer les permissions documentaires, les sorties attendues et le délai acceptable avant de modifier la politique de cache.
2. Écrire le périmètre tarifaire : modèle, date, service, région et postes exclus. Nommer la personne qui vérifie les prix et refuser les profils que le calcul ne connaît pas.
3. Collecter les usages finaux avec une identité de tentative. Contrôler création totale et répartition par durée ; distinguer replay du journal et nouvel appel réellement envoyé.
4. Comparer les montants à volumes déclarés, puis rapprocher le relevé fournisseur. Afficher les écritures non amorties, les mesures incomplètes et les différences encore inexpliquées.
5. Décider par cadence après contrôle du service rendu. Conserver la politique précédente comme repli, et documenter les conditions qui justifient un nouvel essai plutôt qu’une généralisation.

La responsabilité de mise en œuvre revient à l’équipe qui possède l’intégration ; le métier valide que les sorties et les délais restent acceptables. Le responsable financier examine les unités et les postes exclus. Un runbook décrit l’arrêt de l’essai si la collecte devient incomplète, puis le retour à la configuration précédente. Cette réversibilité doit conserver les dépenses engagées, même lorsque la variante est abandonnée.

Le contrat d’entrée du service d’intégration exige un relevé final avant son écriture dans le registre. En sortie, il restitue un montant ou une cause de refus. Une contrainte d’unicité sur l’identité de tentative assure l’idempotence de cette collecte ; un conflit de compteurs conserve les deux traces pour examen sans addition automatique. Ajoutez à la recette un relevé rejoué et une création au détail incomplet. Le journal de contrôle doit expliquer pourquoi le total est inchangé dans le premier cas et pourquoi le lot reste incomplet dans le second.

Livrer une décision explicable au responsable du logiciel

Le compte rendu tient en un périmètre, un barème daté, les relevés contrôlés et une comparaison reconstruisible. Il indique quelle durée est retenue pour quelle famille et ce qui reste à mesurer. Les chiffres d’une journée atypique ne suffisent pas à projeter un mois. La prochaine mesure doit couvrir une cadence représentative, avec ses interruptions et ses reprises, plutôt que sélectionner uniquement la séquence qui montre le meilleur gain.

Pour un agent disposant d’outils, ce relevé n’est qu’une partie du dispositif de maîtrise. Le cache ne limite ni le nombre d’actions ni le montant qu’un outil pourrait engager. Les autorisations et le budget du workflow doivent rester traités à leur propre niveau. Une consommation de jetons bien rapprochée apporte une preuve de coût technique ; elle ne remplace pas les garde-fous du processus auquel le modèle participe.

Guides complémentaires pour budgets, lots et régressions

Prévoir la dépense et rattacher les traitements

Le budget d’exécution d’un agent organise la réservation avant les nouveaux appels. Le rapprochement du cache intervient après consommation : une estimation favorable ne constitue pas une réserve disponible pour toutes les prochaines actions. Les deux mécanismes doivent partager leurs unités et leurs périmètres sans confondre autorisation préalable et coût constaté.

Le rattachement des résultats Claude par lots traite l’identité des demandes et les réponses non ordonnées. Un passage en Batch demande aussi un barème approprié : notre calculateur standard le refuse. Réutiliser ses prix sans adapter le profil ferait perdre le sens du rapprochement, même si chaque résultat était rattaché au bon dossier.

Conserver la qualité comme condition de comparaison

Les évaluations de régression entre versions IA aident à vérifier ce qu’une modification dégrade. Changer les instructions ou les documents pour favoriser leur réutilisation peut modifier les sorties. Avant de rapprocher les économies, comparez les versions sur les mêmes attentes métier et gardez les erreurs critiques visibles. Une réponse moins coûteuse qui impose une correction supplémentaire déplace simplement la dépense.

Conservez donc une version du jeu de demandes et des critères de réception avec chaque variante évaluée. Le tableau de comparaison associe son coût aux résultats acceptés, rejetés ou repris. Une baisse de dépense accompagnée de davantage de corrections devient une hypothèse à examiner avec le métier. Le retour à la version précédente doit rester possible pendant cette observation, sans effacer les mesures défavorables de la variante essayée.

Conclusion : payer les écritures avant de célébrer les hits

Un cache utile se démontre par un calcul qui conserve tous ses coûts. L’entrée ordinaire, les écritures de chaque durée, les lectures et les sorties forment des postes distincts. Le total de création contrôle ses détails sans s’y ajouter. Le tarif dépend du modèle et du contexte ; une mise à jour de prix doit rester datée pour que l’historique et les simulations ne racontent pas des histoires différentes.

Les cinq appels fictifs coûtent 0,1116 dollar contre 0,133 à volumes identiques sans cache. Leur économie théorique de 16,09 % ne se lit ni dans les 60 % de requêtes avec hit ni dans les 48,15 % de jetons d’entrée lus. Le couple écriture longue et unique lecture coûte même davantage que sa référence. Ces calculs montrent une condition de rentabilité, sans mesurer un gain réel de votre assistant.

L’industrialisation et la gouvernance de vos traitements IA prolongent ce travail par le rapprochement, les alertes et la responsabilité de mise à jour des tarifs. La décision utile précise ce qui est économisé, dans quel périmètre, avec quelle qualité et quelles incertitudes restantes. C’est sur cette base que la politique de cache peut évoluer sans rendre la dépense plus opaque.

Dawap accompagne la conception de votre intégration IA sur mesure avec les équipes qui possèdent les sources et les opérations du logiciel. Nous relions usages, tentatives et résultats attendus pour que le budget puisse être expliqué. L’essai doit produire des mesures vérifiables et préserver les contraintes du métier ; un indicateur de cache favorable reste une information à interpréter, pas une autorisation de généraliser.