Les règles du cache

La mise en cache tient en quelques règles simples, mais strictes : un seul caractère changé dans le préfixe, et le cache ne sert plus. Cette leçon les passe en revue : comment déclencher la mise en cache, ce qui entre dans le préfixe, dans quel ordre, et à partir de quelle taille.

Deux façons de mettre en cache

La mise en cache automatique. On ajoute un seul champ cache_control au niveau de la requête : l’API place elle-même le point d’arrêt sur le dernier bloc qui peut être mis en cache. C’est la façon la plus simple de commencer, en particulier pour une conversation qui s’allonge.

Les points d’arrêt explicites. On place cache_control sur un bloc précis : tout ce qui précède, ce bloc compris, est mis en cache. C’est ce qui permet, par exemple, de mettre en cache les outils et le prompt système séparément.

Le cours officiel affirme que la mise en cache n’est jamais automatique : c’était vrai avant l’arrivée de la mise en cache automatique, que la documentation présente désormais comme le point de départ le plus simple.

La forme longue des blocs

Pour poser un point d’arrêt sur un texte, il faut la forme longue du bloc : la forme courte n’a pas de place pour le champ.

# Forme courte : pas de place pour cache_control
{"role": "user", "content": "Votre texte"}

# Forme longue : le bloc peut porter cache_control
{"role": "user", "content": [
    {"type": "text", "text": "Votre texte", "cache_control": {"type": "ephemeral"}}
]}

La valeur {"type": "ephemeral"} donne un cache de 5 minutes ; {"type": "ephemeral", "ttl": "1h"}, un cache d’une heure.

L’ordre du préfixe

L’API assemble toujours la requête dans le même ordre : les outils, puis le prompt système, puis les messages. Un point d’arrêt met en cache tout ce qui le précède dans cet ordre. On peut donc en poser sur :

• la dernière définition d’outil, pour mettre en cache tous les outils ;
• un bloc du prompt système ;
• un bloc d’un message : texte, image, document, appel ou résultat d’outil.

Une requête accepte jusqu’à 4 points d’arrêt. Ce qui suit le dernier point d’arrêt est traité normalement.

L’identité stricte du préfixe

Le cache ne sert que si le contenu est identique, caractère pour caractère, jusqu’au point d’arrêt. Ajouter « s’il vous plaît » dans le prompt système, ou y inscrire l’heure de la requête, suffit à tout invalider. Changer un outil invalide aussi tout ce qui suit, prompt système compris, puisque les outils viennent en premier. La documentation signale d’autres causes moins visibles : un tool_choice, une configuration de réflexion ou un niveau d’effort qui changent d’une requête à l’autre. Gardez-les constants pendant la vie d’une conversation mise en cache.

Placez donc ce qui ne change jamais au début, et ce qui change à chaque requête, comme la question de l’utilisateur, après le dernier point d’arrêt.

La taille minimale

En dessous d’une certaine taille, le préfixe n’est pas mis en cache, et l’API ne renvoie aucune erreur :

Le seuil porte sur tout ce qui précède le point d’arrêt, pas sur un bloc isolé. Le cours officiel, qui utilise Claude Haiku 4.5, cite donc 4 096 jetons ; avec Sonnet 5.5, le seuil est de 512. Pour savoir si la mise en cache a eu lieu, regardez l’usage de la réponse : si cache_creation_input_tokens et cache_read_input_tokens valent tous deux 0, rien n’a été mis en cache.

À vous de jouer

Trouver ce qui casse le cache. Écrivez un prompt système d’au moins 600 jetons, posez-y un point d’arrêt, et envoyez deux questions de suite : la seconde doit lire le cache. Ajoutez ensuite la date et l’heure au début du prompt système, relancez, et observez cache_read_input_tokens retomber à 0.

Sources officielles : Rules of prompt caching (Claude Academy) · Prompt caching (documentation Claude : automatique et explicite, seuils, points d’arrêt) · Troubleshooting tool use (ce qui invalide le cache)

Points clés à retenir

• Deux façons : un cache_control au niveau de la requête (automatique), ou sur des blocs précis (explicite).
• Ordre du préfixe : outils, prompt système, messages ; jusqu’à 4 points d’arrêt.
• Le préfixe doit être identique au caractère près : le variable va après le dernier point d’arrêt.
• Seuil minimal : 512 jetons sur les modèles Claude 5 actuels, plus sur les modèles plus anciens.
• Deux compteurs à 0 dans usage : rien n’a été mis en cache.