Coût, cache et performance#

La même tâche peut coûter 10 fois plus cher selon l'ordre de tes blocs de prompt et le modèle que tu choisis. Voici comment payer le juste prix.

Temps de lecture : 14 min | Niveau : Avancé

Ce que tu sauras faire après#

• Mettre en place le prompt caching et vérifier qu'il fonctionne vraiment.
• Ordonner tes blocs de prompt pour maximiser les hits de cache.
• Utiliser l'API Batch quand la réponse immédiate n'est pas nécessaire.
• Choisir un modèle plus petit sans perdre en qualité sur les tâches simples.
• Estimer le coût mensuel d'un usage quotidien, avec de vrais chiffres.

1. Ce que tu paies#

Trois lignes sur ta facture :

• Tokens d'entrée : tout ce que tu envoies (prompt système, outils, historique, documents).
• Tokens de sortie : ce que le modèle produit, y compris la réflexion (voir 02-extended-thinking.md).
• Tokens de cache : écriture et lecture, à des tarifs différents.

Prix de base au million de tokens (MTok), relevés sur la page Models overview :

Les prix et la gamme de modèles évoluent souvent. Vérifie la page officielle avant de chiffrer un projet.

Première observation, avant toute optimisation technique : la sortie coûte 5 fois l'entrée. Donc la première économie, ce n'est pas le cache. C'est d'arrêter de demander des réponses bavardes.

2. Le prompt caching#

Le principe#

Tu marques un endroit de ton prompt comme "point de reprise". Tout ce qui est avant ce point est mis en cache. Au prochain appel, si le début du prompt est strictement identique, il est relu depuis le cache au lieu d'être retraité.

C'est fait pour les prompts qui ont une grosse partie stable et une petite partie variable. C'est exactement ta situation quand tu envoies le schéma de ton entrepôt à chaque question.

Le paramètre#

{"cache_control": {"type": "ephemeral"}}

Pour une durée de vie d'une heure au lieu de cinq minutes :

{"cache_control": {"type": "ephemeral", "ttl": "1h"}}

Exemple concret#

reponse = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": "Tu es data analyst sur l'entrepot BigQuery d'ACME.",
        },
        {
            "type": "text",
            "text": SCHEMA_COMPLET_DU_DWH,   # 12 000 tokens, ne change jamais
            "cache_control": {"type": "ephemeral"},   # <- point de reprise
        },
    ],
    messages=[{"role": "user", "content": question_du_jour}],
)

u = reponse.usage
print("ecrit en cache :", u.cache_creation_input_tokens)
print("lu depuis cache:", u.cache_read_input_tokens)
print("non cache      :", u.input_tokens)

Vérifier que ça marche#

Le total des tokens d'entrée vaut cache_read_input_tokens + cache_creation_input_tokens + input_tokens.

Premier appel : cache_creation_input_tokens élevé, cache_read_input_tokens à 0. Appels suivants : l'inverse.

Si les deux valent 0, le cache ne s'applique pas. Cause la plus fréquente : ton préfixe est trop court.

3. Ce qui est cachable, et à partir de combien#

Cachable#

• Les définitions d'outils (tableau tools).
• Les blocs du prompt système.
• Les messages texte, utilisateur et assistant.
• Les images et documents dans les tours utilisateur.
• Les blocs tool_use et tool_result.

Non cachable#

• Les blocs thinking ne peuvent pas porter directement un cache_control (mais ils sont cachés avec le reste d'un tour assistant précédent).
• Les sous-blocs comme les citations : il faut cacher le bloc parent.
• Les blocs de texte vides.

Le seuil minimum#

En dessous d'un certain nombre de tokens, rien n'est caché et aucune erreur n'est levée. Le seuil dépend du modèle :

C'est le piège numéro un : tu actives le cache sur un prompt système de 300 tokens, tu ne vois aucun gain, et tu crois que la fonctionnalité ne marche pas.

4. L'ordre des blocs : la règle qui change tout#

Le cache se construit toujours dans cet ordre :

tools  ->  system  ->  messages

Un changement à un niveau invalide ce niveau et tous les suivants.

Conséquence directe, à retenir par cœur :

[1] definitions d'outils      (jamais modifiees)
[2] prompt systeme            (rarement modifie)
[3] schema / documentation    (change une fois par semaine)
    ^--- point de cache ici
[4] historique de conversation
[5] question du jour          (change a chaque appel)

Le plus stable en haut, le plus volatil en bas. Si tu mets la date du jour au début de ton prompt système, tu casses le cache tous les jours pour rien.

Ce qui invalide le cache#

Lecture de la ligne tool_choice : changer tool_choice ne casse ni le cache des définitions d'outils ni celui du prompt système. Seuls les blocs de messages sont à retraiter. C'est plutôt une bonne nouvelle : c'est la partie la plus légère.

Les deux dernières lignes expliquent pourquoi il faut fixer effort au début d'une conversation et ne plus y toucher (voir 02-extended-thinking.md).

Les limites#

• 4 points de cache explicites maximum par requête.
• Fenêtre de recherche : 20 blocs par point de cache.
• Durée de vie par défaut : 5 minutes, comptées à partir du début de la requête, pas de la fin de la réponse. Le temps de génération compte dans le TTL.
• Le cache est rafraîchi gratuitement à chaque réutilisation dans sa durée de vie.

5. Le calcul du gain#

Les tarifs de cache, en multiplicateurs du prix d'entrée de base :

En euros sur Opus 5.5 (base 4 $/MTok en entrée) : écriture 5 min à 5 $/MTok, écriture 1 h à 8 $/MTok, lecture à 0,20 $/MTok.

Le calcul mental : une lecture de cache sur Opus 5.5 coûte 20 fois moins cher qu'un token d'entrée normal. Une écriture coûte 25 % de plus. Donc le cache devient rentable dès que tu relis le même préfixe deux fois.

Quand choisir le cache 1 heure#

Il coûte 2 x au lieu de 1,25 x à l'écriture. Il vaut le coup si tes appels sont espacés de plus de 5 minutes mais restent dans l'heure. Typiquement : une session de travail où tu poses une question toutes les 10 minutes.

La doc suggère aussi le cache 1 heure pour les tâches avec beaucoup de réflexion, qui dépassent souvent les 5 minutes de durée de vie.

6. L'API Batch#

Le principe#

Tu envoies un lot de requêtes, tu reviens plus tard chercher les résultats. Tout l'usage est facturé à 50 % du prix standard.

Les chiffres officiels#

• Réduction : 50 % sur les prix standards.
• Limite par lot : 100 000 requêtes ou 256 Mo, la première limite atteinte.
• Délai : la plupart des lots se terminent en moins d'une heure. Tu accèdes aux résultats quand tout est fini ou après 24 heures, au premier des deux.
• Expiration à 24 heures : les requêtes non traitées expirent et ne sont pas facturées.
• Les résultats restent disponibles 29 jours après la création du lot.
• Chaque requête d'un lot doit avoir max_tokens d'au moins 1. La valeur max_tokens: 0 (préchauffage de cache) n'est pas supportée dans un lot.

Quand l'utiliser en data#

C'est fait pour ton métier. Tout ce qui est "traitement de masse, résultat demain matin" :

• Classifier 80 000 tickets de support.
• Générer la documentation de 400 modèles dbt.
• Extraire des entités de 50 000 descriptions produit.
• Traduire un référentiel entier.
• Faire tourner une campagne d'évaluation de prompts.

Quand ne pas l'utiliser#

Dès qu'un humain attend devant son écran. Un assistant interactif ne passe pas en batch.

7. Choisir un modèle plus petit#

C'est le levier le plus rentable, et le plus souvent oublié.

Passer d'Opus 5.5 (4 $ / 20 $) à Haiku 4.5 (1 $ / 5 $) divise la facture par 4. Sur une tâche simple, la qualité ne bouge pas.

Deux détails à connaître avant de basculer sur Haiku 4.5, sinon tu vas perdre une heure à chercher pourquoi ton code ne marche plus :

• Il ne supporte pas output_config.effort. Enlève le paramètre de ton appel.
• Sa réflexion est en mode enabled + budget_tokens, pas en mode adaptive. C'est le seul mode qu'il accepte (voir 02-extended-thinking.md).

Grille de décision#

La bonne méthode#

Ne devine pas. Fais descendre.

1. Construis un jeu de 20 à 30 cas représentatifs, avec la bonne réponse attendue.
2. Fais tourner sur le gros modèle. C'est ta référence.
3. Fais tourner sur le modèle en dessous. Compare.
4. Si l'écart est acceptable, descends encore.
5. Tu t'arrêtes au niveau où la qualité décroche.

C'est exactement une campagne de tests. Tu sais déjà faire.

Le même raisonnement s'applique au paramètre effort : low sur un gros modèle est parfois meilleur et moins cher que high sur un petit. Teste les deux axes.

Dans une chaîne de prompts (fichier 03), applique ça par étape. L'étape "classer la difficulté" n'a pas besoin du même modèle que l'étape "migrer la requête".

8. Estimer le coût d'un usage quotidien#

Prenons un cas réaliste : un assistant data pour toi, tous les jours.

Hypothèses

• 40 questions par jour ouvré, 22 jours par mois.
• Prompt stable (système + schéma du DWH + définitions d'outils) : 12 000 tokens.
• Question : 500 tokens.
• Réponse : 1 500 tokens.
• Modèle : Claude Opus 5.5 (4 $ entrée / 20 $ sortie).

Scénario A - sans cache#

Entree  : 40 x 12 500 = 500 000 tokens = 0,50 MTok x 4 $  = 2,00 $
Sortie  : 40 x  1 500 =  60 000 tokens = 0,06 MTok x 20 $ = 1,20 $
---------------------------------------------------------------
Par jour : 3,20 $        Par mois (22 j) : environ 70 $

Scénario B - avec cache#

On suppose 8 écritures de cache par jour (le cache expire entre les sessions) et 32 lectures.

Ecritures cache : 8 x 12 000  =  96 000 tokens = 0,096 MTok x 5,00 $ = 0,48 $
Lectures cache  : 32 x 12 000 = 384 000 tokens = 0,384 MTok x 0,20 $ = 0,08 $
Entree variable : 40 x 500    =  20 000 tokens = 0,020 MTok x 4,00 $ = 0,08 $
Sortie          : 40 x 1 500  =  60 000 tokens = 0,060 MTok x 20,00 $ = 1,20 $
---------------------------------------------------------------------------
Par jour : 1,84 $        Par mois (22 j) : environ 40 $

Gain : environ 43 %. Et la sortie représente maintenant les deux tiers du coût.

Scénario C - cache + routage des tâches simples vers Haiku#

On suppose que 25 des 40 questions sont simples et partent sur Haiku 4.5 (1 $ / 5 $), avec un prompt réduit à 3 000 tokens.

Opus 5.5, 15 questions, avec cache
  ecritures cache : 5 x 12 000 =  60 000 = 0,060 MTok x 5,00 $  = 0,30 $
  lectures cache  : 10 x 12 000 = 120 000 = 0,120 MTok x 0,20 $ = 0,02 $
  entree variable : 15 x 500   =   7 500 = 0,0075 MTok x 4,00 $ = 0,03 $
  sortie          : 15 x 1 500 =  22 500 = 0,0225 MTok x 20,00 $ = 0,45 $
                                                       sous-total = 0,80 $

Haiku 4.5, 25 questions, prompt reduit a 3 000 tokens, sans cache
  entree          : 25 x 3 500 =  87 500 = 0,0875 MTok x 1,00 $ = 0,09 $
  sortie          : 25 x 1 500 =  37 500 = 0,0375 MTok x 5,00 $ = 0,19 $
                                                       sous-total = 0,28 $
---------------------------------------------------------------------------
Par jour : environ 1,08 $      Par mois (22 j) : environ 24 $

Note au passage : sur Haiku 4.5 le seuil minimum de cache est de 4 096 tokens. Un prompt réduit à 3 000 tokens n'est donc pas cachable sur ce modèle. C'est normal, et ce n'est pas grave ici : l'entrée Haiku coûte déjà 4 fois moins cher.

On est passé de 70 $ à 24 $ par mois pour le même service.

Le tableau que tu dois construire#

| Usage             | Appels/jour | Tokens in | Tokens out | Modele | Cache | Cout/jour |
|-------------------|-------------|-----------|------------|--------|-------|-----------|
| [USAGE_1]         |             |           |            |        |       |           |
| [USAGE_2]         |             |           |            |        |       |           |

Remplis-le une fois. Tu verras immédiatement quelle ligne représente 80 % de ta facture. C'est la seule qu'il faut optimiser.

9. Ton template prêt à copier#

Template A - Structure de prompt optimisée pour le cache#

reponse = client.messages.create(
    model="[MODELE]",
    max_tokens=[MAX_TOKENS],
    output_config={"effort": "[NIVEAU]"},   # fixe pour toute la conversation
    tools=[MES_OUTILS],                     # [1] le plus stable
    system=[
        {"type": "text", "text": "[ROLE_ET_REGLES_GENERALES]"},   # [2] stable
        {
            "type": "text",
            "text": "[SCHEMA_OU_DOCUMENTATION_VOLUMINEUSE]",      # [3] semi-stable
            "cache_control": {"type": "ephemeral", "ttl": "1h"},  # point de cache
        },
    ],
    messages=[
        # [4] historique
        {"role": "user", "content": "[LA_QUESTION_DU_JOUR]"},     # [5] volatil
    ],
)

u = reponse.usage
total_in = u.cache_read_input_tokens + u.cache_creation_input_tokens + u.input_tokens
print(f"hit cache : {u.cache_read_input_tokens / total_in:.0%}")

Template B - Faire chiffrer un usage#

Je veux estimer le cout mensuel d'un usage IA.

Usage : [DECRIS_L_USAGE].
Volume : [N] appels par jour, [J] jours par mois.
Prompt stable (systeme + schema + outils) : [T_STABLE] tokens.
Partie variable par appel : [T_VAR] tokens.
Sortie moyenne : [T_OUT] tokens.
Modele envisage : [MODELE] a [PRIX_IN] $/MTok en entree et [PRIX_OUT] $/MTok en sortie.

Calcule et presente en tableau :
1. Le cout mensuel sans cache.
2. Le cout mensuel avec prompt caching (5 min), en posant une hypothese explicite sur
   le nombre d'ecritures de cache par jour.
3. Le cout mensuel si [X] % des appels passent sur un modele moins cher.
4. Le cout si l'ensemble passe en API Batch (50 % de reduction).

Detaille chaque calcul ligne par ligne. Indique clairement chaque hypothese.
Termine par les 3 actions classees par gain decroissant.

Template C - Audit d'un prompt trop cher#

Ce prompt coute trop cher. Analyse-le.

<prompt>
[COLLE_TON_PROMPT_COMPLET]
</prompt>

<usage>
Appels par jour : [N]
Ce qui change entre deux appels : [DECRIS]
Modele : [MODELE]
</usage>

Reponds en 4 parties :
1. Quelles parties du prompt sont STABLES et devraient etre en haut, avant le point
   de cache ? Donne l'ordre exact recommande.
2. Quelles parties sont inutiles ou redondantes et peuvent etre supprimees ?
3. La sortie demandee est-elle plus longue que necessaire ? Propose une consigne de
   concision.
4. Cette tache justifie-t-elle ce modele, ou un modele plus petit suffirait-il ?

À retenir#

• La sortie coûte 5 fois l'entrée. Ta première économie, c'est de demander des réponses courtes.
• Le cache se construit dans l'ordre tools -> system -> messages. Le plus stable en haut, le plus volatil en bas.
• En dessous du seuil minimum (512 à 4 096 tokens selon le modèle), rien n'est caché et aucune erreur n'est levée.
• Une lecture de cache coûte 0,1 x le prix d'entrée (0,05 x sur Opus 5.5). Le cache est rentable dès la deuxième lecture.
• Changer effort ou la configuration de thinking casse le cache. Fixe-les au début.
• L'API Batch, c'est 50 % de moins, jusqu'à 100 000 requêtes ou 256 Mo, expiration à 24 h, résultats gardés 29 jours.
• Le plus gros levier reste le choix du modèle. Fais descendre jusqu'à ce que la qualité décroche, avec un jeu de tests.

Sources#

• Prompt caching - Anthropic
• Batch processing - Anthropic
• Models overview - Anthropic
• Effort - Anthropic
• Steering thinking - Anthropic
• Thinking - Anthropic
• anthropics/claude-cookbooks - code d'exemple sur le cache et le batch : misc/prompt_caching.ipynb, misc/batch_processing.ipynb, cost_optimization/cost_optimization.ipynb