Mise en cache des prompts

La mise en cache des prompts est une fonctionnalité puissante qui optimise votre utilisation de l’API en permettant de reprendre à partir de préfixes spécifiques dans vos prompts. Cette approche réduit considérablement le temps de traitement et les coûts pour les tâches répétitives ou les prompts avec des éléments constants.

Voici un exemple de mise en œuvre de la mise en cache des prompts avec l’API Messages en utilisant un bloc cache_control :

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

Dans cet exemple, le texte intégral de “Pride and Prejudice” est mis en cache à l’aide du paramètre cache_control. Cela permet de réutiliser ce texte volumineux à travers plusieurs appels API sans le retraiter à chaque fois. En ne modifiant que le message utilisateur, vous pouvez poser diverses questions sur le livre tout en utilisant le contenu mis en cache, ce qui conduit à des réponses plus rapides et une meilleure efficacité.

​

Comment fonctionne la mise en cache des prompts

Lorsque vous envoyez une requête avec la mise en cache des prompts activée :

1. Le système vérifie si un préfixe de prompt, jusqu’à un point de rupture de cache spécifié, est déjà mis en cache à partir d’une requête récente.
2. Si trouvé, il utilise la version mise en cache, réduisant le temps de traitement et les coûts.
3. Sinon, il traite le prompt complet et met en cache le préfixe une fois que la réponse commence.

Cela est particulièrement utile pour :

• Les prompts avec de nombreux exemples
• De grandes quantités de contexte ou d’informations de fond
• Des tâches répétitives avec des instructions cohérentes
• De longues conversations à plusieurs tours

Par défaut, le cache a une durée de vie de 5 minutes. Le cache est rafraîchi sans coût supplémentaire chaque fois que le contenu mis en cache est utilisé.

​

Tarification

La mise en cache des prompts introduit une nouvelle structure tarifaire. Le tableau ci-dessous montre le prix par million de tokens pour chaque modèle pris en charge :

Remarque :

• Les tokens d’écriture en cache de 5 minutes coûtent 1,25 fois le prix des tokens d’entrée de base
• Les tokens d’écriture en cache d’1 heure coûtent 2 fois le prix des tokens d’entrée de base
• Les tokens de lecture en cache coûtent 0,1 fois le prix des tokens d’entrée de base
• Les tokens d’entrée et de sortie réguliers sont facturés aux tarifs standard

​

Comment implémenter la mise en cache des prompts

​

Modèles pris en charge

La mise en cache des prompts est actuellement prise en charge sur :

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

Structurer votre prompt

Placez le contenu statique (définitions d’outils, instructions système, contexte, exemples) au début de votre prompt. Marquez la fin du contenu réutilisable pour la mise en cache à l’aide du paramètre cache_control.

Les préfixes de cache sont créés dans l’ordre suivant : tools, system, puis messages.

En utilisant le paramètre cache_control, vous pouvez définir jusqu’à 4 points de rupture de cache, vous permettant de mettre en cache différentes sections réutilisables séparément. Pour chaque point de rupture, le système vérifiera automatiquement les correspondances de cache aux positions précédentes et utilisera le préfixe correspondant le plus long s’il en trouve un.

​

Limitations du cache

La longueur minimale de prompt pouvant être mise en cache est :

• 1024 tokens pour Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 et Claude Opus 3
• 2048 tokens pour Claude Haiku 3.5 et Claude Haiku 3

Les prompts plus courts ne peuvent pas être mis en cache, même s’ils sont marqués avec cache_control. Toutes les demandes de mise en cache de moins de ce nombre de tokens seront traitées sans mise en cache. Pour voir si un prompt a été mis en cache, consultez les champs d’utilisation de la réponse.

Pour les requêtes simultanées, notez qu’une entrée de cache ne devient disponible qu’après le début de la première réponse. Si vous avez besoin de correspondances de cache pour des requêtes parallèles, attendez la première réponse avant d’envoyer les requêtes suivantes.

Actuellement, “ephemeral” est le seul type de cache pris en charge, qui a par défaut une durée de vie de 5 minutes.

​

Ce qui peut être mis en cache

La plupart des blocs dans la requête peuvent être désignés pour la mise en cache avec cache_control. Cela inclut :

• Outils : Définitions d’outils dans le tableau tools
• Messages système : Blocs de contenu dans le tableau system
• Messages texte : Blocs de contenu dans le tableau messages.content, pour les tours utilisateur et assistant
• Images et documents : Blocs de contenu dans le tableau messages.content, dans les tours utilisateur
• Utilisation d’outils et résultats d’outils : Blocs de contenu dans le tableau messages.content, dans les tours utilisateur et assistant

Chacun de ces éléments peut être marqué avec cache_control pour activer la mise en cache pour cette partie de la requête.

​

Ce qui ne peut pas être mis en cache

Bien que la plupart des blocs de requête puissent être mis en cache, il y a quelques exceptions :

• Les blocs de réflexion ne peuvent pas être mis en cache directement avec cache_control. Cependant, les blocs de réflexion PEUVENT être mis en cache avec d’autres contenus lorsqu’ils apparaissent dans des tours d’assistant précédents. Lorsqu’ils sont mis en cache de cette façon, ils COMPTENT comme des tokens d’entrée lors de la lecture depuis le cache.

• Les blocs de sous-contenu (comme les citations) ne peuvent pas être mis en cache directement. À la place, mettez en cache le bloc de niveau supérieur.

  Dans le cas des citations, les blocs de contenu de document de niveau supérieur qui servent de matériel source pour les citations peuvent être mis en cache. Cela vous permet d’utiliser efficacement la mise en cache des prompts avec des citations en mettant en cache les documents auxquels les citations feront référence.

• Les blocs de texte vides ne peuvent pas être mis en cache.

​

Suivi des performances du cache

Surveillez les performances du cache à l’aide de ces champs de réponse API, dans usage dans la réponse (ou l’événement message_start si streaming) :

• cache_creation_input_tokens : Nombre de tokens écrits dans le cache lors de la création d’une nouvelle entrée.
• cache_read_input_tokens : Nombre de tokens récupérés du cache pour cette requête.
• input_tokens : Nombre de tokens d’entrée qui n’ont pas été lus ou utilisés pour créer un cache.

​

Meilleures pratiques pour une mise en cache efficace

Pour optimiser les performances de mise en cache des prompts :

• Mettez en cache le contenu stable et réutilisable comme les instructions système, les informations de fond, les contextes volumineux ou les définitions d’outils fréquentes.
• Placez le contenu mis en cache au début du prompt pour de meilleures performances.
• Utilisez les points de rupture de cache de manière stratégique pour séparer différentes sections de préfixe pouvant être mises en cache.
• Analysez régulièrement les taux de correspondance du cache et ajustez votre stratégie selon les besoins.

​

Optimisation pour différents cas d’utilisation

Adaptez votre stratégie de mise en cache des prompts à votre scénario :

• Agents conversationnels : Réduisez le coût et la latence pour les conversations prolongées, en particulier celles avec de longues instructions ou des documents téléchargés.
• Assistants de codage : Améliorez l’autocomplétion et les questions-réponses sur la base de code en conservant les sections pertinentes ou une version résumée de la base de code dans le prompt.
• Traitement de documents volumineux : Incorporez du matériel complet de forme longue, y compris des images, dans votre prompt sans augmenter la latence de réponse.
• Ensembles d’instructions détaillés : Partagez des listes complètes d’instructions, de procédures et d’exemples pour affiner les réponses de Claude. Les développeurs incluent souvent un ou deux exemples dans le prompt, mais avec la mise en cache des prompts, vous pouvez obtenir de meilleures performances en incluant plus de 20 exemples diversifiés de réponses de haute qualité.
• Utilisation d’outils agentiques : Améliorez les performances pour les scénarios impliquant plusieurs appels d’outils et des modifications de code itératives, où chaque étape nécessite généralement un nouvel appel API.
• Dialoguer avec des livres, des articles, de la documentation, des transcriptions de podcasts et d’autres contenus de forme longue : Donnez vie à n’importe quelle base de connaissances en intégrant le(s) document(s) entier(s) dans le prompt, et en permettant aux utilisateurs de lui poser des questions.

​

Résolution des problèmes courants

Si vous rencontrez un comportement inattendu :

• Assurez-vous que les sections mises en cache sont identiques et marquées avec cache_control aux mêmes emplacements dans les appels
• Vérifiez que les appels sont effectués dans la durée de vie du cache (5 minutes par défaut)
• Vérifiez que tool_choice et l’utilisation d’images restent cohérentes entre les appels
• Validez que vous mettez en cache au moins le nombre minimum de tokens
• Bien que le système tente d’utiliser le contenu précédemment mis en cache aux positions avant un point de rupture de cache, vous pouvez utiliser un paramètre cache_control supplémentaire pour garantir la recherche dans le cache sur les parties précédentes du prompt, ce qui peut être utile pour les requêtes avec de très longues listes de blocs de contenu

Notez que les modifications de tool_choice ou la présence/absence d’images n’importe où dans le prompt invalideront le cache, nécessitant la création d’une nouvelle entrée de cache.

​

Mise en cache avec des blocs de réflexion

Lorsque vous utilisez la réflexion étendue avec la mise en cache des prompts, les blocs de réflexion ont un comportement spécial :

Mise en cache automatique avec d’autres contenus : Bien que les blocs de réflexion ne puissent pas être explicitement marqués avec cache_control, ils sont mis en cache dans le cadre du contenu de la requête lorsque vous effectuez des appels API ultérieurs avec des résultats d’outils. Cela se produit couramment pendant l’utilisation d’outils lorsque vous renvoyez des blocs de réflexion pour continuer la conversation.

Comptage des tokens d’entrée : Lorsque les blocs de réflexion sont lus depuis le cache, ils comptent comme des tokens d’entrée dans vos métriques d’utilisation. C’est important pour le calcul des coûts et la budgétisation des tokens.

Modèles d’invalidation du cache :

• Le cache reste valide lorsque seuls des résultats d’outils sont fournis comme messages utilisateur
• Le cache est invalidé lorsqu’un contenu utilisateur non lié aux résultats d’outils est ajouté, ce qui entraîne la suppression de tous les blocs de réflexion précédents
• Ce comportement de mise en cache se produit même sans marqueurs cache_control explicites

Exemple avec utilisation d’outil :

Requête 1 : Utilisateur : "Quel temps fait-il à Paris ?"
Réponse : [thinking_block_1] + [tool_use block 1]

Requête 2 : 
Utilisateur : ["Quel temps fait-il à Paris ?"], 
Assistant : [thinking_block_1] + [tool_use block 1], 
Utilisateur : [tool_result_1, cache=True]
Réponse : [thinking_block_2] + [text block 2]
# La requête 2 met en cache son contenu de requête (pas la réponse)
# Le cache inclut : message utilisateur, thinking_block_1, tool_use block 1, et tool_result_1

Requête 3 :
Utilisateur : ["Quel temps fait-il à Paris ?"], 
Assistant : [thinking_block_1] + [tool_use block 1], 
Utilisateur : [tool_result_1, cache=True], 
Assistant : [thinking_block_2] + [text block 2], 
Utilisateur : [Réponse textuelle, cache=True]
# Un bloc utilisateur non lié aux résultats d'outils entraîne l'ignorance de tous les blocs de réflexion
# Cette requête est traitée comme si les blocs de réflexion n'avaient jamais été présents

Lorsqu’un bloc utilisateur non lié aux résultats d’outils est inclus, il désigne une nouvelle boucle d’assistant et tous les blocs de réflexion précédents sont supprimés du contexte.

Pour des informations plus détaillées, consultez la documentation sur la réflexion étendue.

​

Stockage et partage du cache

• Isolation des organisations : Les caches sont isolés entre les organisations. Différentes organisations ne partagent jamais de caches, même si elles utilisent des prompts identiques.

• Correspondance exacte : Les correspondances de cache nécessitent des segments de prompt 100% identiques, y compris tout le texte et les images jusqu’au bloc marqué avec cache control inclus.

• Génération de tokens de sortie : La mise en cache des prompts n’a aucun effet sur la génération de tokens de sortie. La réponse que vous recevez sera identique à celle que vous obtiendriez si la mise en cache des prompts n’était pas utilisée.

​

Durée de cache d’1 heure (bêta)

Si vous trouvez que 5 minutes est trop court, Anthropic propose également une durée de cache d’1 heure.

Pour utiliser le cache étendu, ajoutez extended-cache-ttl-2025-04-11 comme en-tête bêta à votre requête, puis incluez ttl dans la définition cache_control comme ceci :

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

La réponse inclura des informations détaillées sur le cache comme suit :

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

Notez que le champ actuel cache_creation_input_tokens est égal à la somme des valeurs dans l’objet cache_creation.

​

Quand utiliser le cache d’1 heure

Si vous avez des prompts qui sont utilisés à une cadence régulière (c’est-à-dire des prompts système qui sont utilisés plus fréquemment que toutes les 5 minutes), continuez à utiliser le cache de 5 minutes, car celui-ci continuera à être rafraîchi sans frais supplémentaires.

Le cache d’1 heure est préférable dans les scénarios suivants :

• Lorsque vous avez des prompts qui sont probablement utilisés moins fréquemment que toutes les 5 minutes, mais plus fréquemment que toutes les heures. Par exemple, lorsqu’un agent secondaire agentique prendra plus de 5 minutes, ou lors du stockage d’une longue conversation avec un utilisateur et que vous vous attendez généralement à ce que cet utilisateur ne réponde pas dans les 5 prochaines minutes.
• Lorsque la latence est importante et que vos prompts de suivi peuvent être envoyés au-delà de 5 minutes.
• Lorsque vous souhaitez améliorer votre utilisation de la limite de débit, car les correspondances de cache ne sont pas déduites de votre limite de débit.

​

Mélanger différents TTL

Vous pouvez utiliser à la fois des contrôles de cache d’1 heure et de 5 minutes dans la même requête, mais avec une contrainte importante : les entrées de cache avec un TTL plus long doivent apparaître avant les TTL plus courts (c’est-à-dire qu’une entrée de cache d’1 heure doit apparaître avant toute entrée de cache de 5 minutes).

Lorsque vous mélangez des TTL, nous déterminons trois emplacements de facturation dans votre prompt :

1. Position A : Le nombre de tokens à la correspondance de cache la plus élevée (ou 0 s’il n’y a pas de correspondance).
2. Position B : Le nombre de tokens au bloc cache_control d’1 heure le plus élevé après A (ou égal à A s’il n’en existe pas).
3. Position C : Le nombre de tokens au dernier bloc cache_control.

Vous serez facturé pour :

1. Les tokens de lecture de cache pour A.
2. Les tokens d’écriture de cache d’1 heure pour (B - A).
3. Les tokens d’écriture de cache de 5 minutes pour (C - B).

Voici 3 exemples. Ceci représente les tokens d’entrée de 3 requêtes, chacune ayant différentes correspondances et échecs de cache. Chacune a une tarification calculée différente, montrée dans les cases colorées, en conséquence.

​

Exemples de mise en cache des prompts

Pour vous aider à démarrer avec la mise en cache des prompts, nous avons préparé un livre de recettes de mise en cache des prompts avec des exemples détaillés et des meilleures pratiques.

Ci-dessous, nous avons inclus plusieurs extraits de code qui présentent divers modèles de mise en cache des prompts. Ces exemples montrent comment implémenter la mise en cache dans différents scénarios, vous aidant à comprendre les applications pratiques de cette fonctionnalité :

​

FAQ

client.beta.promptCaching.messages.create(...)

client.messages.create(...)