Mise en cache des prompts et optimisation des coûts

Avancé

Si beaucoup de vos requêtes partagent un gros bloc invariable — un long prompt système, un document volumineux, un catalogue d'outils — la mise en cache des prompts permet à l'API de réutiliser le préfixe déjà traité au lieu de le relire à chaque appel. Cela réduit à la fois le coût et la latence sur la partie mise en cache.

What you'll learn

Le modèle mental : un point de rupture de cache après un préfixe stable, réutilisé d'un appel à l'autre
Comment marquer le point de rupture en Python et TypeScript avec cache_control
L'invariant unique qui fait ou défait tout — le préfixe doit être identique octet pour octet
Comment lire les champs usage pour confirmer que vous obtenez bien des hits de cache
Où la mise en cache paie le plus, et comment la combiner avec le traitement par lots et le bon dimensionnement

Comment ça marche (le modèle mental)

Vous marquez un point de rupture de cache après le préfixe stable. Au premier appel, il est traité et mis en cache ; les appels suivants qui partagent exactement le même préfixe touchent le cache et le paient bien moins cher.

Vocabulaire de la mise en cache

Appuyez sur Entrée ou Espace pour retourner la carte. Utilisez les flèches gauche et droite pour naviguer entre les cartes.Terme affiché.

1 / 4

Marquer le point de rupture (copier-coller)

Ajoutez cache_control au dernier bloc stable — ici, un grand prompt système. Le tour de l'utilisateur vient après et varie librement ; tout jusqu'au bloc marqué inclus est mis en cache.

Guided walkthrough1 of 4

Trouvez le gros bloc invariable — un long prompt système, un document volumineux ou un catalogue d'outils réutilisé sur de nombreuses requêtes.

Python
TypeScript

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LARGE_STABLE_PROMPT,  # long, unchanging — the cached prefix
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Summarize the key points."}],  # varies per call
)

print(message.usage.cache_read_input_tokens)  # > 0 means you got a hit

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: LARGE_STABLE_PROMPT, // long, unchanging — the cached prefix
      cache_control: { type: "ephemeral" },
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points." }], // varies per call
});

console.log(message.usage.cache_read_input_tokens); // > 0 means you got a hit

Le premier appel paie un petit surcoût d'écriture pour peupler le cache ; chaque appel ultérieur avec le même préfixe le relit à une fraction du prix d'entrée. Le préfixe doit être assez long pour être éligible — quelques milliers de tokens, selon le modèle — sinon il ne sera silencieusement pas mis en cache.

L'invariant qui fait ou défait tout

:::warning La mise en cache est exacte au préfixe Un hit de cache exige que le préfixe mis en cache soit identique octet pour octet. Le bug le plus courant : un invalidateur silencieux près du haut du prompt — un horodatage, un nom d'utilisateur changeant, une liste d'outils réordonnée — qui modifie le préfixe et fait discrètement chuter votre taux de hits à zéro. :::

Mettez tout ce qui est stable en premier, tout ce qui est variable en dernier, et gardez le préfixe vraiment constant.

Vérifier que ça marche vraiment

Ne présumez pas — relisez-le depuis le usage de la réponse :

cache_creation_input_tokens — tokens écrits dans le cache lors de cet appel (la première requête).
cache_read_input_tokens — tokens servis depuis le cache (les économies).
input_tokens — le reste non mis en cache, facturé au plein tarif.

Si cache_read_input_tokens reste à zéro sur des requêtes répétées censées partager un préfixe, un invalidateur silencieux est à l'œuvre — comparez les octets du prompt rendu entre deux appels pour le trouver.

Où ça paie le plus

Les longs prompts système réutilisés entre utilisateurs.
Le RAG / Q&R sur documents où le même texte source est interrogé de façon répétée.
Les agents avec un catalogue d'outils et des instructions fixes sur de nombreux tours.

Combinez la mise en cache avec le traitement par lots pour les charges hors ligne, et avec le bon dimensionnement du modèle (Choisir un modèle) pour les plus grosses économies combinées — voir Coût et latence.

Testez-vous

0/3

Qu'exige un hit de cache du préfixe mis en cache ?
Quel champ usage vous indique que des tokens ont été servis depuis le cache (vos économies) ?
Où le contenu variable, propre à chaque appel, doit-il aller par rapport au point de rupture de cache ?

Key takeaways

Marquez un point de rupture de cache après le préfixe stable ; le premier appel l'écrit, les appels suivants le relisent à bas prix.
Un hit de cache nécessite un préfixe identique octet pour octet — gardez le contenu stable en premier, le contenu variable en dernier.
Les invalidateurs silencieux près du haut du prompt (horodatages, noms, outils réordonnés) font discrètement chuter le taux de hits à zéro.
Vérifiez avec usage : cache_read_input_tokens > 0 signifie un hit ; zéro sur des requêtes répétées signifie qu'un invalidateur est à l'œuvre.
La mise en cache paie le plus pour les prompts système réutilisés, le RAG et les agents ; combinez-la avec le traitement par lots et le bon dimensionnement du modèle.

Comment ça marche (le modèle mental)​

Marquer le point de rupture (copier-coller)​

L'invariant qui fait ou défait tout​

Vérifier que ça marche vraiment​

Où ça paie le plus​