Règles du prompt caching : breakpoints et bonnes pratiques

Le prompt caching stocke le travail de calcul effectue sur vos messages pour le réutiliser dans les requêtes suivantes. Le résultat : des requêtes plus rapides et moins coûteuses, à condition de bien comprendre les règles du jeu.

Le principe est simple : la première requête écrit dans le cache, les requêtes suivantes lisent depuis ce cache. La durée de vie par défaut est de 5 minutes, réinitialisée à chaque lecture — un service sollicité régulièrement garde donc son cache chaud en continu, et une option de cache étendu à une heure existe pour les usages plus espacés.

Les points d’arrêt (cache breakpoints)

Le caching n’est pas automatique. Vous devez manuellement placer des points d’arrêt (breakpoints) sur des blocs spécifiques de vos messages. Voici les règles :

• Le travail de prétraitement n’est pas cache par défaut
• Vous devez ajouter un cache breakpoint à un bloc
• Tout le contenu avant et y compris le breakpoint sera mis en cache
• Le cache ne sera réutilisé 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’arrêt.

Fonctionnement des breakpoints

Quand vous placez un breakpoint dans un message, Claude met en cache tout le travail de prétraitement jusqu’à ce point inclus. Le contenu après le breakpoint est traité normalement, sans cache.

Attention à l’identité stricte : pour que le cache soit utile dans les requêtes suivantes, le contenu doit être rigoureusement identique jusqu’au breakpoint. Même un petit changement comme ajouter le mot “s’il vous plaît” invalidera le cache et forcera Claude à tout retraiter.

Cache inter-messages

Les breakpoints peuvent s’étendre à travers plusieurs messages et types de messages. Si vous placez un breakpoint dans un message tardif, tous les messages précédents (utilisateur, assistant, etc.) seront inclus dans le contenu mis en cache.

C’est particulièrement utile pour les conversations où vous voulez mettre en cache tout le contexte jusqu’à un certain point.

Prompts système et outils

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

• Prompts système
• Définitions d’outils (tools)
• Blocs image
• Blocs tool_use et tool_result

Les prompts système et les définitions d’outils sont d’excellents candidats pour le caching car ils changent rarement entre les requêtes. C’est souvent la où vous obtiendrez le meilleur retour sur investissement.

Ordre de traitement du cache

En coulisses, Claude traite les composants de votre requête dans un ordre précis :

1. Outils (tools) en premier
2. Prompt système ensuite
3. Messages en dernier

Comprendre cet ordre vous aide à placer vos breakpoints efficacement.

Vous pouvez ajouter jusqu’à 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 flexibilité quand différentes parties de votre requête changent.

Longueur minimale

Il existe un seuil minimum pour le caching : le contenu doit faire au moins 1024 tokens pour être 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 système de 200 lignes ou un document complet le depassera largement.

En résumé

La clé d’un prompt caching efficace : identifier les parties stables de vos requêtes et placer les breakpoints stratégiquement pour maximiser la réutilisation tout en minimisant les invalidations de cache.