Mise en cache des prompts Claude — tarifs, objet d’utilisation et raisons de la baisse des taux de réussite derrière une passerelle

La mise en cache des invites est le plus grand levier individuel sur la facture d’un agent, et celui qui a le plus de chances de ne pas fonctionner silencieusement. Lorsqu’elle est correctement marquée, la partie répétée de votre requête est facturée à un dixième du tarif d’entrée. Lorsqu’elle est mal marquée — ou qu’elle passe par un élément qui réécrit votre préfixe — elle est facturée au-delà du tarif normal, car vous payez pour écrire des entrées de cache que personne ne lit.

Le mécanisme est bien documenté ailleurs. En revanche, les changements lorsque la requête passe par une passerelle ne sont documentés nulle part ; c’est pourtant la situation de la plupart des lecteurs de cette page. Les deux aspects sont présentés ci-dessous.

Le mécanisme, en bref

Vous marquez un préfixe stable — une invite système, un schéma d’outil, un document — et le fournisseur en stocke la forme traitée. La requête suivante dont le préfixe correspond exactement le relit au lieu de le retraiter.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

Deux propriétés font tout le travail et causent tous les problèmes. La correspondance porte sur un préfixe ; toute modification au début invalide donc tout ce qui suit. Et une entrée possède une durée de vie ; une conversation avec de longs intervalles entre les tours reconstruit donc l’entrée au lieu de la relire.

Ce que cela coûte

La troisième colonne correspond au ratio standard : une lecture coûte un dixième de l’entrée. La quatrième est également standard — une écriture de cache coûte 1,25× l’entrée, le multiplicateur indiqué par Anthropic pour une entrée de cinq minutes — et, puisque les deux ratios s’appliquent au prix d’entrée de Kunavo, chacune bénéficie de la même remise par rapport au tarif catalogue d’Anthropic que l’entrée du modèle. Kunavo diverge d’Anthropic pour l’entrée d’une heure : Anthropic indique une écriture à 2× l’entrée, tandis que Kunavo la facture au même tarif de 1,25×. Cela importe particulièrement pour les charges qui reconstruisent souvent le cache — agents de longue durée, conversations lentes, tout ce dont le préfixe change fréquemment — car ce sont les charges où les écritures, et non les lectures, dominent la ligne cache de la facture.

Les deux chiffres sont lus dans le catalogue au moment du rendu, depuis la même source que consultent le tableau des tarifs et le calculateur Claude — aucun tarif n'est saisi manuellement sur cette page.

Lire l'objet d'utilisation

Ne déduisez pas le comportement du cache à partir de la facture ; chaque réponse vous l'indique directement, et les trois décomptes de tokens constituent tout le diagnostic.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

Pourquoi les taux de réussite baissent derrière une passerelle

Un cache réside auprès du serveur amont qui l'a créé, et la correspondance du préfixe est exacte. Ces deux faits réunis produisent trois modes d'échec qui ne surviennent jamais lorsque vous appelez directement un seul fournisseur :

Le routage a changé. Si des requêtes consécutives aboutissent à des serveurs amont différents, la seconde ne trouve aucun cache — l'entrée écrite par la première n'est pas visible depuis l'endroit où la seconde s'est exécutée. Cela est invisible dans vos propres journaux et n'apparaît que sous la forme d'un nombre de créations de cache qui aurait dû correspondre à une lecture. C'est la cause la plus fréquente, et c'est pourquoi une passerelle qui réachemine librement entre plusieurs serveurs amont peut être moins chère par token et plus chère par session.

Quelque chose a été injecté avant votre préfixe. Une couche qui réécrit le message système, normalise les définitions d'outils ou réorganise les champs produit un préfixe différent, et un préfixe différent entraîne un échec de cache. Rien ne génère d'erreur ; la facture augmente simplement.

L'intervalle a dépassé la durée de vie de l'entrée. Un agent qui réfléchit plusieurs minutes entre deux tours peut tout reconstruire à chaque fois. Il s'agit d'une propriété de votre charge de travail plutôt que de la passerelle, mais elle interagit mal avec le premier point : une reconstruction est également une occasion de réacheminement.

Le diagnostic est le même pour les trois cas — observez cache_creation_input_tokens pendant une session. Une valeur stable et élevée signifie que vous reconstruisez. Une valeur élevée une seule fois, puis nulle, signifie que cela fonctionne. Dans Kunavo, le coût au niveau de la requête et les nombres de tokens mis en cache figurent dans la vue d'utilisation, et la référence de mise en cache contient les détails au niveau du point de terminaison.

Que faire

Gardez le préfixe mis en cache réellement stable — placez tout ce qui change à chaque requête après le bloc marqué, jamais avant. Regroupez les tours d'un agent plus rapprochés lorsque c'est possible, car le temps d'inactivité est l'ennemi d'une entrée à durée de vie courte. Et mesurez une session de bout en bout plutôt qu'une requête : la mise en cache est une propriété d'une séquence, et une estimation par requête ne peut pas la détecter. Le calculateur de coût des tokens Claude comporte un champ de tokens mis en cache précisément pour cette raison — définissez-le sur la fraction de votre prompt qui se répète réellement, et le montant mensuel cesse d'être fictif.

Questions fréquentes