Règles du prompt caching

Le cache de prompts tient en quelques règles simples, mais strictes : un seul caractère changé avant le point de cache, et le cache ne sert plus. Cette leçon les passe en revue avec l’API Converse.

Les points de cache

Le cache n’est pas automatique sur Claude Haiku 5.5 : vous ajoutez des blocs cachePoint là où il faut couper. Tout ce qui précède un point de cache est mis en cache ; ce qui le suit ne l’est pas.

user_message = {
    "role": "user",
    "content": [
        {"text": long_document},
        {"cachePoint": {"type": "default"}},
        {"text": "Quels sont les risques mentionnés ?"},
    ],
}

À la requête suivante, si tout ce qui précède le point de cache est identique, Claude relit le travail depuis le cache au lieu de tout recalculer. Le moindre changement l’empêche : ajouter « S’il te plaît » au début du prompt, ou y inscrire l’heure de la requête, suffit à tout invalider.

Ce qu’on peut mettre en cache

Trois champs de la requête acceptent des points de cache : system, messages et tools. Le prompt système et la liste d’outils sont les meilleurs candidats, car ils changent rarement :

system = [
    {"text": "Tu es un ingénieur logiciel senior..."},
    {"cachePoint": {"type": "default"}},
]

tools = [
    get_current_datetime_schema,
    add_duration_to_datetime_schema,
    set_reminder_schema,
    {"cachePoint": {"type": "default"}},
]

Le cours officiel enveloppe à nouveau chaque schéma dans {"toolSpec": ...} ; nos schémas contiennent déjà cette clé, on les met donc tels quels dans la liste. Un point de cache peut aussi couvrir plusieurs messages, y compris des réponses de Claude : on met alors en cache tout le début d’une conversation.

L’ordre compte

Le modèle reçoit toujours la requête dans le même ordre : les outils, puis le prompt système, puis les messages. Un point de cache couvre tout ce qui le précède dans cet ordre. Conséquence : modifier un outil invalide aussi le cache du prompt système et des messages qui suivent ; modifier un message n’invalide pas le cache des outils.

La longueur minimale

Le contenu situé avant un point de cache doit atteindre un minimum de tokens, qui dépend du modèle. D’après les fiches AWS au 5 novembre 2026 :

Le cours officiel annonce 1 024 tokens, une valeur d’une génération précédente. Sous le minimum, aucun point de cache n’est créé : la requête passe, sans cache. Vérifiez donc dans usage que le cache a bien servi.

La durée

Le cache dure 5 minutes par défaut, prolongées à chaque lecture. Les deux modèles du tableau acceptent aussi une durée d’une heure :

{"cachePoint": {"type": "default", "ttl": "1h"}}

D’après la documentation AWS, envoyer ttl à un modèle qui n’accepte que 5 minutes peut provoquer une ValidationException.

À vous de jouer

Casser le cache exprès. Envoyez deux fois de suite une requête avec un prompt système de plus de 512 tokens suivi d’un point de cache, et affichez usage : écriture puis lecture. Recommencez en ajoutant l’heure courante au début du prompt système : que deviennent les lectures ?

Sources officielles : Rules of prompt caching (Claude Academy) · Prompt caching for faster model inference, fiche Claude Haiku 5.5 et fiche Claude Haiku 4.5 (documentation AWS) · Prompt caching (documentation Claude)

Points clés à retenir

• Un bloc cachePoint met en cache tout ce qui le précède, à condition que ce contenu revienne identique.
• Points de cache possibles dans system, messages et tools ; quatre au plus par requête.
• Ordre : outils, système, messages ; un changement invalide tout ce qui suit.
• Minimum par point de cache : 512 tokens sur Haiku 5.5, 4 096 sur Haiku 4.5 ; en dessous, pas de cache, sans erreur.
• 5 minutes par défaut, prolongées à chaque lecture ; "ttl": "1h" sur les modèles qui l’acceptent.