Regles du prompt caching : breakpoints et bonnes pratiques

Le prompt caching stocke le travail de calcul effectue sur vos messages pour le reutiliser dans les requetes suivantes. Le resultat : des requetes plus rapides et moins couteuses, a condition de bien comprendre les regles du jeu.

Le principe est simple : la premiere requete ecrit dans le cache, les requetes suivantes lisent depuis ce cache. Le cache vit 1 heure — il n’est utile que si vous renvoyez le meme contenu dans ce delai.

Les points d’arret (cache breakpoints)

Le caching n’est pas automatique. Vous devez manuellement placer des points d’arret (breakpoints) sur des blocs specifiques de vos messages. Voici les regles :

• Le travail de pretraitement n’est pas cache par defaut
• Vous devez ajouter un cache breakpoint a un bloc
• Tout le contenu avant et y compris le breakpoint sera mis en cache
• Le cache ne sera reutilise que si le contenu jusqu’au breakpoint est strictement identique

Syntaxe longue obligatoire

Pour ajouter un breakpoint, vous devez utiliser la forme longue des blocs texte (pas la forme raccourcie) :

# Forme raccourcie — PAS de place pour le cache_control
"content": "Votre texte ici"

# Forme longue — permet d'ajouter le champ cache_control
"content": [
    {
        "type": "text",
        "text": "Votre texte ici",
        "cache_control": {"type": "ephemeral"}
    }
]

Le champ cache_control avec la valeur {"type": "ephemeral"} marque le point d’arret.

Fonctionnement des breakpoints

Quand vous placez un breakpoint dans un message, Claude met en cache tout le travail de pretraitement jusqu’a ce point inclus. Le contenu apres le breakpoint est traite normalement, sans cache.

Attention a l’identite stricte : pour que le cache soit utile dans les requetes suivantes, le contenu doit etre rigoureusement identique jusqu’au breakpoint. Meme un petit changement comme ajouter le mot “s’il vous plait” invalidera le cache et forcera Claude a tout retraiter.

Cache inter-messages

Les breakpoints peuvent s’etendre a travers plusieurs messages et types de messages. Si vous placez un breakpoint dans un message tardif, tous les messages precedents (utilisateur, assistant, etc.) seront inclus dans le contenu mis en cache.

C’est particulierement utile pour les conversations ou vous voulez mettre en cache tout le contexte jusqu’a un certain point.

Prompts systeme et outils

Les breakpoints ne sont pas limites aux blocs texte. Vous pouvez les ajouter a :

• Prompts systeme
• Definitions d’outils (tools)
• Blocs image
• Blocs tool_use et tool_result

Les prompts systeme et les definitions d’outils sont d’excellents candidats pour le caching car ils changent rarement entre les requetes. C’est souvent la ou vous obtiendrez le meilleur retour sur investissement.

Ordre de traitement du cache

En coulisses, Claude traite les composants de votre requete dans un ordre precis :

1. Outils (tools) en premier
2. Prompt systeme ensuite
3. Messages en dernier

Comprendre cet ordre vous aide a placer vos breakpoints efficacement.

Vous pouvez ajouter jusqu’a 4 breakpoints au total. Par exemple, vous pourriez mettre en cache vos outils, puis ajouter un autre breakpoint au milieu de votre historique de conversation. Cela vous donne de la flexibilite quand differentes parties de votre requete changent.

Longueur minimale

Il existe un seuil minimum pour le caching : le contenu doit faire au moins 1024 tokens pour etre mis en cache. C’est la somme de tous les messages et blocs que vous essayez de mettre en cache, pas les blocs individuels.

Un simple “Bonjour !” ne franchira pas ce seuil. Mais un prompt systeme de 200 lignes ou un document complet le depassera largement.

En resume

La cle d’un prompt caching efficace : identifier les parties stables de vos requetes et placer les breakpoints strategiquement pour maximiser la reutilisation tout en minimisant les invalidations de cache.