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 cohérents.

Voici un exemple de comment implémenter la mise en cache des prompts avec l’API Messages en utilisant un bloc cache_control :

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Vous êtes un assistant IA chargé d'analyser des œuvres littéraires. Votre objectif est de fournir des commentaires perspicaces sur les thèmes, les personnages et le style d'écriture.\n"
      },
      {
        "type": "text",
        "text": "<tout le contenu d'Orgueil et Préjugés>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analysez les thèmes principaux dans Orgueil et Préjugés."
      }
    ]
  }'

# Appelez le modèle à nouveau avec les mêmes entrées jusqu'au point de contrôle du cache
curl https://api.anthropic.com/v1/messages # reste de l'entrée

{"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, tout le texte d‘“Orgueil et Préjugés” est mis en cache en utilisant le paramètre cache_control. Cela permet la réutilisation de ce texte volumineux à travers plusieurs appels API sans le retraiter à chaque fois. Changer seulement le message utilisateur vous permet de poser diverses questions sur le livre tout en utilisant le contenu mis en cache, conduisant à des réponses plus rapides et une efficacité améliorée.

​

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. S’il est 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.

Ceci est particulièrement utile pour :

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

Par défaut, le cache a une durée de vie de 5 minutes. Le cache est actualisé 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 de tarification. Le tableau ci-dessous montre le prix par million de tokens pour chaque modèle supporté :

​

Comment implémenter la mise en cache des prompts

​

Modèles supportés

La mise en cache des prompts est actuellement supportée sur :

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5 (déprécié)
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (déprécié)

​

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 en utilisant le paramètre cache_control.

Les préfixes de cache sont créés dans l’ordre suivant : tools, system, puis messages. Cet ordre forme une hiérarchie où chaque niveau s’appuie sur les précédents.

​

Comment fonctionne la vérification automatique des préfixes

Vous pouvez utiliser juste un point de rupture de cache à la fin de votre contenu statique, et le système trouvera automatiquement le préfixe correspondant le plus long. Voici comment cela fonctionne :

• Lorsque vous ajoutez un point de rupture cache_control, le système vérifie automatiquement les correspondances de cache à toutes les limites de blocs de contenu précédentes (jusqu’à environ 20 blocs avant votre point de rupture explicite)
• Si l’une de ces positions précédentes correspond au contenu mis en cache de requêtes antérieures, le système utilise le préfixe correspondant le plus long
• Cela signifie que vous n’avez pas besoin de plusieurs points de rupture juste pour activer la mise en cache - un à la fin est suffisant

​

Quand utiliser plusieurs points de rupture

Vous pouvez définir jusqu’à 4 points de rupture de cache si vous voulez :

• Mettre en cache différentes sections qui changent à différentes fréquences (par exemple, les outils changent rarement, mais le contexte se met à jour quotidiennement)
• Avoir plus de contrôle sur exactement ce qui est mis en cache
• Assurer la mise en cache pour le contenu plus de 20 blocs avant votre point de rupture final

​

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 (déprécié) et Claude Opus 3 (déprécié)
• 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. Toute requête pour mettre en cache moins que ce nombre de tokens sera traitée sans mise en cache. Pour voir si un prompt a été mis en cache, voir les champs d’utilisation de la réponse.

Pour les requêtes concurrentes, notez qu’une entrée de cache ne devient disponible qu’après que la première réponse commence. 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 supporté, qui a par défaut une durée de vie de 5 minutes.

​

Comprendre les coûts des points de rupture de cache

Les points de rupture de cache eux-mêmes n’ajoutent aucun coût. Vous n’êtes facturé que pour :

• Écritures de cache : Quand du nouveau contenu est écrit dans le cache (25% de plus que les tokens d’entrée de base pour TTL de 5 minutes)
• Lectures de cache : Quand le contenu mis en cache est utilisé (10% du prix des tokens d’entrée de base)
• Tokens d’entrée réguliers : Pour tout contenu non mis en cache

Ajouter plus de points de rupture cache_control n’augmente pas vos coûts - vous payez toujours le même montant basé sur le contenu qui est réellement mis en cache et lu. Les points de rupture vous donnent simplement le contrôle sur quelles sections peuvent être mises en cache indépendamment.

​

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 portion 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’autre contenu quand ils apparaissent dans des tours d’assistant précédents. Quand ils sont mis en cache de cette façon, ils COMPTENT comme tokens d’entrée quand ils sont lus depuis le cache.

• Les sous-blocs de contenu (comme les citations) eux-mêmes ne peuvent pas être mis en cache directement. Au lieu de cela, 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 les citations en mettant en cache les documents que les citations référenceront.

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

​

Ce qui invalide le cache

Les modifications du contenu mis en cache peuvent invalider une partie ou la totalité du cache.

Comme décrit dans Structurer votre prompt, le cache suit la hiérarchie : tools → system → messages. Les changements à chaque niveau invalident ce niveau et tous les niveaux suivants.

Le tableau suivant montre quelles parties du cache sont invalidées par différents types de changements. ✘ indique que le cache est invalidé, tandis que ✓ indique que le cache reste valide.

​

Suivi des performances du cache

Surveillez les performances du cache en utilisant ces champs de réponse API, dans usage dans la réponse (ou é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 depuis ou utilisés pour créer un cache.

​

Meilleures pratiques pour une mise en cache efficace

Pour optimiser les performances de la mise en cache des prompts :

• Mettez en cache le contenu stable et réutilisable comme les instructions système, les informations de base, les grands contextes, 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 stratégiquement pour séparer différentes sections de préfixes pouvant être mises en cache.
• Analysez régulièrement les taux de correspondance de cache et ajustez votre stratégie selon les besoins.

​

Optimisation pour différents cas d’usage

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

• Agents conversationnels : Réduisez les coûts et la latence pour les conversations étendues, en particulier celles avec de longues instructions ou des documents téléchargés.
• Assistants de codage : Améliorez l’autocomplétion et les Q&R de base de code en gardant des sections pertinentes ou une version résumée de la base de code dans le prompt.
• Traitement de grands documents : Incorporez du matériel complet de forme longue incluant des images dans votre prompt sans augmenter la latence de réponse.
• Ensembles d’instructions détaillés : Partagez des listes étendues d’instructions, de procédures et d’exemples pour affiner les réponses de Claude. Les développeurs incluent souvent un exemple ou deux dans le prompt, mais avec la mise en cache des prompts vous pouvez obtenir de meilleures performances en incluant 20+ exemples divers 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 changements de code itératifs, où chaque étape nécessite typiquement un nouvel appel API.
• Parler à des livres, papiers, documentation, transcriptions de podcasts, et autre contenu de forme longue : Donnez vie à toute base de connaissances en intégrant le(s) document(s) entier(s) dans le prompt, et laissez les utilisateurs lui poser des questions.

​

Dépannage 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 à travers les appels
• Vérifiez que les appels sont faits 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érents entre les appels
• Validez que vous mettez en cache au moins le nombre minimum de tokens
• Le système vérifie automatiquement les correspondances de cache aux limites de blocs de contenu précédentes (jusqu’à ~20 blocs avant votre point de rupture). Pour les prompts avec plus de 20 blocs de contenu, vous pourriez avoir besoin de paramètres cache_control supplémentaires plus tôt dans le prompt pour assurer que tout le contenu peut être mis en cache

​

Mise en cache avec les blocs de réflexion

Lors de l’utilisation de 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’autre contenu : 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 quand vous faites des appels API suivants avec des résultats d’outils. Cela arrive couramment pendant l’utilisation d’outils quand vous repassez les blocs de réflexion pour continuer la conversation.

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

Modèles d’invalidation du cache :

• Le cache reste valide quand seuls les résultats d’outils sont fournis comme messages utilisateur
• Le cache est invalidé quand du contenu utilisateur non-résultat-d’outil est ajouté, causant 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

Pour plus de détails sur l’invalidation du cache, voir Ce qui invalide le cache.

Exemple avec utilisation d’outils :

Requête 1 : Utilisateur : "Quel est le temps à Paris ?"
Réponse : [bloc_de_réflexion_1] + [bloc d'utilisation d'outil 1]

Requête 2 : 
Utilisateur : ["Quel est le temps à Paris ?"], 
Assistant : [bloc_de_réflexion_1] + [bloc d'utilisation d'outil 1], 
Utilisateur : [résultat_outil_1, cache=True]
Réponse : [bloc_de_réflexion_2] + [bloc de texte 2]
# La Requête 2 met en cache son contenu de requête (pas la réponse)
# Le cache inclut : message utilisateur, bloc_de_réflexion_1, bloc d'utilisation d'outil 1, et résultat_outil_1

Requête 3 :
Utilisateur : ["Quel est le temps à Paris ?"], 
Assistant : [bloc_de_réflexion_1] + [bloc d'utilisation d'outil 1], 
Utilisateur : [résultat_outil_1, cache=True], 
Assistant : [bloc_de_réflexion_2] + [bloc de texte 2], 
Utilisateur : [Réponse texte, cache=True]
# Le bloc utilisateur non-résultat-d'outil cause 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

Quand un bloc utilisateur non-résultat-d’outil 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, voir la documentation de 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 les caches, même si elles utilisent des prompts identiques.

• Correspondance exacte : Les correspondances de cache nécessitent des segments de prompt 100% identiques, incluant tout le texte et les images jusqu’au bloc marqué avec contrôle de cache 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 à ce que vous obtiendriez si la mise en cache des prompts n’était pas utilisée.

​

Durée de cache de 1 heure

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

Pour utiliser le cache étendu, 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 de 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 égale la somme des valeurs dans l’objet cache_creation.

​

Quand utiliser le cache de 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 actualisé sans frais supplémentaires.

Le cache de 1 heure est mieux utilisé dans les scénarios suivants :

• Quand vous avez des prompts qui sont probablement utilisés moins fréquemment que 5 minutes, mais plus fréquemment que toutes les heures. Par exemple, quand un agent agentique latéral prendra plus de 5 minutes, ou quand vous stockez une longue conversation de chat avec un utilisateur et vous vous attendez généralement à ce que cet utilisateur ne réponde pas dans les 5 minutes suivantes.
• Quand la latence est importante et vos prompts de suivi peuvent être envoyés au-delà de 5 minutes.
• Quand vous voulez améliorer votre utilisation de limite de taux, car les correspondances de cache ne sont pas déduites de votre limite de taux.

​

Mélanger différents TTL

Vous pouvez utiliser à la fois des contrôles de cache de 1 heure et 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, une entrée de cache de 1 heure doit apparaître avant toute entrée de cache de 5 minutes).

Lors du mélange de 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 correspondances).
2. Position B : Le nombre de tokens au bloc cache_control de 1 heure le plus élevé après A (ou égale A si aucun n’existe).
3. Position C : Le nombre de tokens au dernier bloc cache_control.

Vous serez facturé pour :

1. Tokens de lecture de cache pour A.
2. Tokens d’écriture de cache de 1 heure pour (B - A).
3. 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 boîtes colorées, en conséquence.

​

Exemples de mise en cache des prompts

Pour vous aider à commencer 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 démontrent comment implémenter la mise en cache dans différents scénarios, vous aidant à comprendre les applications pratiques de cette fonctionnalité :

​

FAQ