Réduire les coûts et améliorer les performances avec Claude Platform

L'optimisation du cache de prompt, des instructions et de l'effort peut réduire le coût de Claude sans sacrifier les performances de l'application.

La performance et le coût sont souvent considérés comme un compromis : pour dépenser moins, vous acceptez de moins bons résultats. En pratique, nous avons constaté que de nombreuses applications utilisant Claude Platform peuvent réduire leurs coûts sans sacrifier les performances grâce à trois correctifs : maximiser le taux de succès du cache de prompt, supprimer les anti-patrons de vos prompts lors de la migration vers les modèles Claude de pointe, et calibrer l'effort à la tâche. Nous avons intégré ces conseils dans la compétence claude-api. Dans cet article, nous montrons comment Claude Code avec la compétence claude-api peut souvent trouver des moyens de réduire les coûts tout en maintenant ou en améliorant les performances.

Cache de prompt

Avant que Claude ne génère une réponse, il traite d'abord votre prompt dans un état de travail interne. Cette étape, appelée prefill, est la partie coûteuse du traitement de l'entrée. Le cache de prompt enregistre cet état (le cache clé-valeur, ou KV) : lorsqu'une requête commence par le même préfixe, Claude le relit au lieu de le recalculer. Les lectures du cache sont facturées à une fraction du prix d'entrée complet.

Il y a quelques considérations pratiques pour garantir une utilisation efficace du cache de prompt. Premièrement, le cache de prompt est lié à un modèle spécifique. Deuxièmement, les lectures du cache de prompt doivent être exactes au niveau de l'octet sur le préfixe. Enfin, le cache de prompt a une durée de vie limitée (TTL).

Avec ces points à l'esprit, voici quelques conseils pratiques :

• Soyez prudent lorsque vous modifiez le paramètre d'effort en cours de conversation. Ces paramètres sont rendus dans le prompt avant votre contenu, ils font donc partie du préfixe mis en cache. Seulement avec certains modèles Claude, y compris Opus 5 et Fable 5.1, pouvez-vous mettre à jour l'effort en cours de conversation sans casser le cache.
• Gardez les valeurs volatiles hors du préfixe. Un horodatage ou un ID dynamique dans le prompt système peut changer entre les appels de modèle et casser le cache.
• Évitez les définitions d'outils qui se réorganisent. Lorsque vous utilisez l'API messages de Claude, le prompt est assemblé dans un ordre fixe avec les définitions d'outils rendues en haut. Tout changement dans la définition de l'outil cassera le cache.
• Soyez prudent lorsque vous bifurquez des conversations. Les sous-agents et les branches ne partagent le cache du parent que lorsque le préfixe de la bifurcation est identique au niveau de l'octet, sur le même modèle et en utilisant le même effort.

Comment y remédier

Nous avons accumulé quelques leçons pour la gestion du cache de prompt :

• Surveillez attentivement votre taux de succès du cache de prompt. Claude Console et l'API de diagnostic du cache fournissent des diagnostics du cache de prompt, y compris les raisons des échecs du cache de prompt (Figure 1) et exactement où deux requêtes ont divergé.

• Reportez les outils rarement utilisés. Déclarez tous vos outils à l'avance mais marquez ceux rarement utilisés comme defer_loading : ils restent en dehors du préfixe mis en cache et sont ajoutés à la conversation uniquement lorsque Claude les recherche avec la recherche d'outils, préservant ainsi le cache.
• Appliquez les mises à jour du prompt système sous forme de messages. Certains modèles Claude vous permettent d'ajouter une instruction système sous forme de message en cours de conversation au lieu de modifier le prompt système, ce qui préserve le cache.
• Organisez la requête de sorte que la partie stable reste stable. Ajoutez d'abord le contexte statique (définitions d'outils et prompt système) et la conversation croissante derrière eux (Figure 2).

• Apportez des modifications au modèle ou à l'effort lorsque le cache de prompt sera déjà cassé. Certaines opérations, comme la compaction, réécrivent déjà une grande partie du cache (la conversation). C'est un bon moment pour changer de modèle ou d'effort, car vous payez de toute façon pour un échec.
• Déplacez le point de rupture du cache à mesure que la conversation s'allonge. Avec Claude Platform, vous pouvez définir la mise en cache automatique pour appliquer le point de rupture du cache au dernier bloc pouvant être mis en cache.
• Préchauffez le cache. Pour réduire la latence, envoyez une requête avec max_tokens: 0 et un point de rupture de cache explicite, en utilisant le même paramètre d'effort que votre trafic réel. Cela traite le prompt et l'écrit dans le cache sans rien générer. Si vous l'exécutez au début de la session (par exemple, pendant qu'un utilisateur tape), la première requête réelle atteint un cache chaud.
• Ne dépassez pas la TTL du cache de prompt. La TTL du cache de 5 minutes commence à compter à partir du début de la requête. Si un agent bloque sur des appels d'outils ou des requêtes de sous-agents qui durent plus de 5 minutes, le cache du parent expire avant que le résultat ne revienne. Dans de tels cas, envisagez de définir une TTL d'une heure sur le préfixe à la place.

Instructions

Les prompts peuvent accumuler des instructions qui corrigent les faiblesses du modèle. Ces instructions peuvent dériver par rapport aux capacités des derniers modèles Claude. Voici des « anti-patrons » de prompting courants qui entravent les modèles Claude de pointe et peuvent augmenter involontairement les coûts :

• Rituels de vérification. Des instructions comme « vérifie ton travail » ou « vérifie deux fois avant de répondre » sont souvent prises au pied de la lettre par les modèles de pointe et peuvent gaspiller des tokens.
• Amplificateurs de minutie et d'emphase. « Sois extrêmement minutieux », « CRITIQUE : TU DOIS TOUJOURS… » peuvent conduire à de la verbosité et à des appels d'outils supplémentaires avec les modèles de pointe.
• Procédures obligatoires et échafaudages de bloc-notes. Les processus à étapes fixes (par exemple, « réfléchis étape par étape dans un bloc-notes ») ou les modèles de raisonnement sont des rituels dont les modèles de pointe n'ont pas besoin. Cet échafaudage peut s'empiler sur le raisonnement natif et utiliser des tokens inutiles.
• Exemples obsolètes. Les exemples few-shot adaptés aux modes de défaillance d'un modèle plus ancien peuvent apprendre à un modèle de pointe à imiter de longues chaînes de raisonnement sur des requêtes qui n'en ont pas besoin.
• Règles contradictoires. Les modèles de pointe sont meilleurs pour suivre les instructions. Les instructions contradictoires (« toujours rembourser selon la politique » vs. « ne jamais rembourser sans escalade ») peuvent être suivies plus littéralement par les modèles de pointe, entraînant une dégradation des performances.
• Configuration obsolète. Les paramètres écrits pour une génération plus ancienne de Claude (par exemple, les budgets de réflexion manuels) peuvent être rejetés par Claude Platform avec les modèles plus récents.

Comment y remédier

Nous avons mis à jour la compétence claude-api avec une nouvelle commande qui surveille ces anti-patrons. Dans Claude Code, exécutez /claude-api prompt-audit sur vos prompts, compétences ou descriptions d'outils. L'audit couvre tout ce qui se trouve dans votre répertoire de travail, y compris le code d'application qui appelle l'API Claude et la propre configuration de Claude Code (par exemple, CLAUDE.md ou les compétences).

Par exemple, nous avons testé une migration de modèle d'Opus 4.8 à Opus 5 sur un benchmark de support client. Nous sommes partis d'un prompt propre et avons introduit un anti-patron à la fois (un paramètre de réflexion retiré, une paire de règles de remboursement contradictoires, un bloc-notes manuel, « vérifie deux fois », « sois extrêmement minutieux » et une procédure obligatoire en six étapes), donnant six prompts hérités.

Nous avons exécuté chacun sur Opus 4.8, sur Opus 5 avec seulement l'ID du modèle modifié, et sur Opus 5 après avoir exécuté /claude-api prompt-audit une fois par prompt (la Figure 3 montre la moyenne des six).

Avec Opus 5, les rituels de vérification (« vérifie deux fois ») utilisent des tokens inutiles en dupliquant la recherche de commande à chaque remboursement. Les amplificateurs d'emphase (« sois extrêmement minutieux ») sont devenus des dizaines de recherches inutiles dans la base de connaissances.

L'exécution de /claude-api prompt-audit a supprimé les anti-patrons, réduisant les coûts de 14,6 % et augmentant la précision de 5,3 % en moyenne. Le coût a baissé car les appels d'outils supplémentaires et le raisonnement dupliqué ont été éliminés. La précision a augmenté pour trois raisons. Le paramètre de réflexion retiré a fait rejeter catégoriquement chaque demande de routage par l'API. Les règles de remboursement contradictoires ont conduit Opus 5 à retenir quatre remboursements qu'il devait tout en demandant au client de confirmer. Et le bloc-notes manuel est entré en collision avec la réflexion intégrée d'Opus 5 : sur trois tickets, il a écrit l'appel d'outil dans son raisonnement et ne l'a jamais exécuté.

Effort

L'effort indique à Claude « à quel point travailler dur ». À faible effort, Claude parvient généralement à des conclusions plus rapidement. À effort élevé, Claude délibère, vérifie et explore des alternatives avant de répondre.

Le rapport coût-performance entre les niveaux d'effort sur un seul modèle peut varier. Par exemple, Claude Fable 5 obtient un score de 11,5 % à faible effort pour 5,35 $ par tâche sur FrontierCode Diamond (les 50 tâches les plus difficiles). À effort maximal, Fable 5 obtient 30,9 % pour 19,00 $ par tâche ; changer l'effort augmente le score d'environ 2,7x (+19 points) pour environ 3,5x le coût (Figure 4).

Sur Claude Fable 5.1, Humanity's Last Exam (sans outils) montre une courbe raide avec une dernière étape décroissante. Il obtient un score d'environ 53 % à faible effort pour environ 0,30 $ par question et environ 61 % à effort maximal pour environ 2,23 $ ; la dernière étape jusqu'au maximum ajoute environ un demi-point pour 46 % de coût supplémentaire. Le gain se situe dans le bruit de run à run du benchmark, donc vous payez plus pour aucun gain mesurable.

L'effort peut être mal calibré dans les deux sens :

• Supposer que plus élevé est toujours meilleur. Un effort élevé peut provoquer une sur-réflexion. Claude passe plus de temps à délibérer que la tâche ne le justifie, ce qui ajoute du coût et de la latence, et peut dégrader la qualité de la réponse. La délibération n'aide que tant qu'il reste des preuves à trouver.
• Biaiser vers un faible effort. Réglé trop bas, Claude s'arrête avant d'avoir suffisamment de preuves. Il fait moins d'appels d'outils, il peut donc répondre à partir du premier résultat de recherche au lieu du troisième. Il réfléchit moins sur les étapes difficiles et saute la vérification qu'il exécuterait normalement sur lui-même. La réponse semble terminée, mais elle est construite sur des informations partielles.

Comment y remédier

Il existe quelques façons utiles de calibrer l'effort :

• Testez des modèles plus puissants à un effort plus faible. Un modèle plus puissant à faible effort peut être moins cher qu'un modèle plus faible travaillant dur (effort élevé). Par exemple, sur CursorBench 3.2, Claude Fable 5.1 à faible effort correspond aux performances de Fable 5 à effort élevé pour un tiers du coût (Figure 5). Deux choses rendent le nouveau modèle moins cher : à faible effort, il fait moins de travail par tâche, et les lectures du cache de prompt de Fable 5.1 sont facturées à 0,25 $ par million de tokens contre 1,00 $ pour Fable 5. Même aux prix de Fable 5, Fable 5.1 à faible effort coûterait environ 40 % de moins.

• Comprenez la forme de votre tâche. Mesurer les performances de l'application sur une gamme de niveaux d'effort est un moyen utile de comprendre le compromis coût-performance pour votre tâche particulière. Sur une évaluation non saturée, une courbe coût-performance plate à travers les niveaux d'effort suggère que la tâche n'est pas limitée par le calcul de réflexion ; augmenter l'effort n'est pas bénéfique.

Cet étalonnage implique souvent d'exécuter une évaluation sur plusieurs modèles et niveaux d'effort. Dans Claude Code, /claude-api hillclimb effectue cette recherche pour vous : il divise votre évaluation en ensembles d'entraînement et de test, propose des changements de configuration et lit les exemples d'entraînement en échec pour corriger ce qu'il trouve.

Nous l'avons exécuté sur un benchmark de support client, en partant d'Opus 4.8 à son effort par défaut (élevé). L'algorithme d'escalade a d'abord essayé Opus 5 à faible effort, en appliquant prompt-audit pour supprimer les rituels d'appel d'outils obligatoires, les étapes de bloc-notes et les règles contradictoires. Cela a dépassé la référence Opus 4.8 avec une précision d'entraînement de 98,9 % et a réduit le coût à 2,6 cents par ticket (Figure 6).

Il est ensuite descendu à Sonnet 5 à faible effort, qui était encore moins cher à 1 cent par ticket, mais la précision est tombée à 88,9 %. En lisant les tickets d'entraînement en échec, Claude a ajouté des règles de routage et une référence croisée de plafond de remboursement au prompt, ramenant Sonnet 5 à 98,9 % au même coût.

Sur les 14 tickets retenus que la recherche n'a jamais vus, la configuration finale a obtenu un score de 90,5 % contre 78,6 % pour la configuration d'origine, pour environ un cinquième du coût.

Automatisation de la réduction des coûts

Le cache de prompt, les instructions et l'effort sont des leviers courants pour réduire les coûts. Notre documentation en couvre encore plus. Pour effectuer un audit de coûts holistique du code d'application qui utilise l'API Claude, nous avons ajouté /claude-api cost-optimize : il profile où va votre dépense, applique des réductions de coûts et, si vous fournissez une évaluation, montre comment les économies se comparent aux performances.

cost-optimize commence par trouver où vont vos tokens : à partir des rapports d'utilisation et de coûts de votre organisation si vous avez une clé API Admin Claude, à partir de l'objet d'utilisation sur chaque réponse API si votre application le journalise, ou, à défaut des deux, en lisant votre code de construction de requête et en estimant.

Il classe ensuite les économies disponibles, en commençant par le cache de prompt, en réduisant ce que chaque requête transporte (y compris un prompt-audit), en limitant la sortie et en traitant par lots le travail non supervisé. Si vous fournissez une évaluation, il va plus loin et calcule le coût et les performances sur les niveaux d'effort et les choix de modèles. Nous avons exécuté cela sur quatre benchmarks publics avec Sonnet 5 comme référence (Figure 7) :

• LegalBench (~58 % de coût en moins) : cost-optimize a proposé de mettre en cache un préfixe partagé entre les tâches, de définir un faible effort et de traiter les tâches via l'API Batch. Les tokens de réflexion sont passés de 102 779 à 8 284 et le taux de réussite est resté dans le bruit et le coût a baissé d'environ 58 %.
• tau2-bench retail (~73 % de coût en moins) : En implémentant le cache de prompt avec un placement explicite du point de rupture, cost-optimize a réduit les dépenses de 72 % tout en maintenant le taux de réussite stable.
• OfficeQA Pro (~52 % de coût en moins) : cost-optimize a ajouté le traitement par lots et la mise en cache des documents, ce qui a réduit le coût de 136,20 $ à 64,87 $.
• SWE-bench Verified (~55 % de coût en moins) : cost-optimize a constaté que la configuration par défaut met déjà en cache correctement. Les économies proviennent du réglage de l'effort à moyen et de la limitation de la sortie de l'agent à seulement quelques phrases concises. Le nombre médian d'étapes par tâche est passé de 29 à 17 et les tokens de prompt sont passés de 75,2 M à 33,7 M.

Pour commencer

Commencez par /claude-api prompt-audit lorsque vous avez migré vers un modèle Claude de pointe et que vous souhaitez vérifier vos prompts existants. Il analyse les prompts, les compétences et les descriptions d'outils dans votre répertoire de travail. Cela peut être du code d'application qui appelle l'API Claude ou la configuration de Claude Code (CLAUDE.md, compétences). Il supprime les anti-patrons courants qui entravent les modèles de pointe.

Utilisez /claude-api cost-optimize lorsque votre application utilise l'API Claude et que vous souhaitez un audit des coûts. Il profile la dépense en tokens, puis teste différents leviers : il applique prompt-audit, mais vérifie également les moyens de réduire les coûts via le cache de prompt, le traitement par lots du travail non supervisé ou la limitation de la sortie. Si vous fournissez une évaluation, il mesure les compromis entre l'effort et la sélection du modèle.

Enfin, utilisez /claude-api hillclimb pour une recherche sur le coût et les performances. Étant donné une évaluation, Claude la divise en ensembles d'entraînement et de test, puis propose des mises à jour de votre application visant à réduire les coûts tout en maintenant les performances de base. Claude lit les cas d'entraînement en échec pour guider la recherche, et la configuration finale est notée sur l'ensemble de test retenu.

Pour en savoir plus :

• Consultez notre documentation ici
• Consultez notre livre de recettes sur la réduction des coûts ici
• Consultez la compétence claude-api ici ; la compétence est également intégrée à Claude Code
• Consultez cet article sur le blog Claude ici

Écrit par Lance Martin (@RLanceMartin), Brad Abrams (@brada), Isabella He (@IsabellaKHe) et Ben Lehrburger (@benlehrburger).