La mise en cache des invites est une fonctionnalité puissante qui optimise votre utilisation de l'API en vous permettant de reprendre à partir de préfixes spécifiques dans vos invites. Cette approche réduit considérablement le temps de traitement et les coûts pour les tâches répétitives ou les invites avec des éléments cohérents.
Voici un exemple de la façon d'implémenter la mise en cache des invites 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-sonnet-4-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice."
}
]
}'
# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input{"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, l'intégralité du texte de « Pride and Prejudice » est mise en cache à l'aide du paramètre cache_control. Cela permet de réutiliser ce texte volumineux sur plusieurs appels API sans le retraiter à chaque fois. La modification uniquement du message utilisateur vous permet de poser diverses questions sur le livre tout en utilisant le contenu mis en cache, ce qui entraîne des réponses plus rapides et une meilleure efficacité.
Lorsque vous envoyez une demande avec la mise en cache des invites activée :
Ceci est particulièrement utile pour :
Par défaut, le cache a une durée de vie de 5 minutes. Le cache est actualisé sans frais supplémentaires chaque fois que le contenu mis en cache est utilisé.
Si vous trouvez que 5 minutes est trop court, Anthropic propose également une durée de cache d'1 heure à un coût supplémentaire.
Pour plus d'informations, voir Durée de cache d'1 heure.
La mise en cache des invites met en cache le préfixe complet
La mise en cache des invites référence l'invite complète - tools, system et messages (dans cet ordre) jusqu'à et y compris le bloc désigné avec cache_control.
La mise en cache des invites introduit une nouvelle structure tarifaire. Le tableau ci-dessous montre le prix par million de jetons pour chaque modèle pris en charge :
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|---|---|---|---|---|---|
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 | $0.80 / MTok | $1 / MTok | $1.6 / MTok | $0.08 / MTok | $4 / MTok |
| Claude Opus 3 (deprecated) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Haiku 3 | $0.25 / MTok | $0.30 / MTok | $0.50 / MTok | $0.03 / MTok | $1.25 / MTok |
Le tableau ci-dessus reflète les multiplicateurs de tarification suivants pour la mise en cache des invites :
La mise en cache des invites est actuellement prise en charge sur :
Placez le contenu statique (définitions d'outils, instructions système, contexte, exemples) au début de votre invite. 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. Cet ordre forme une hiérarchie où chaque niveau s'appuie sur les précédents.
Vous pouvez utiliser un seul point de rupture de cache à la fin de votre contenu statique, et le système trouvera automatiquement la séquence la plus longue de blocs mis en cache correspondants. Comprendre comment cela fonctionne vous aide à optimiser votre stratégie de mise en cache.
Trois principes fondamentaux :
Les clés de cache sont cumulatives : Lorsque vous mettez explicitement en cache un bloc avec cache_control, la clé de hachage du cache est générée en hachant tous les blocs précédents dans la conversation séquentiellement. Cela signifie que le cache pour chaque bloc dépend de tout le contenu qui l'a précédé.
Vérification séquentielle rétroactive : Le système vérifie les accès au cache en travaillant à rebours à partir de votre point de rupture explicite, en vérifiant chaque bloc précédent dans l'ordre inverse. Cela garantit que vous obtenez le plus long accès au cache possible.
Fenêtre de lookback de 20 blocs : Le système ne vérifie que jusqu'à 20 blocs avant chaque point de rupture cache_control explicite. Après avoir vérifié 20 blocs sans correspondance, il arrête la vérification et passe au point de rupture explicite suivant (le cas échéant).
Exemple : Comprendre la fenêtre de lookback
Considérez une conversation avec 30 blocs de contenu où vous définissez cache_control uniquement sur le bloc 30 :
Si vous envoyez le bloc 31 sans modifications aux blocs précédents : Le système vérifie le bloc 30 (correspondance !). Vous obtenez un accès au cache au bloc 30, et seul le bloc 31 nécessite un traitement.
Si vous modifiez le bloc 25 et envoyez le bloc 31 : Le système vérifie à rebours du bloc 30 → 29 → 28... → 25 (pas de correspondance) → 24 (correspondance !). Puisque le bloc 24 n'a pas changé, vous obtenez un accès au cache au bloc 24, et seuls les blocs 25-30 nécessitent un retraitement.
Si vous modifiez le bloc 5 et envoyez le bloc 31 : Le système vérifie à rebours du bloc 30 → 29 → 28... → 11 (vérification #20). Après 20 vérifications sans trouver de correspondance, il arrête la recherche. Puisque le bloc 5 est au-delà de la fenêtre de 20 blocs, aucun accès au cache ne se produit et tous les blocs nécessitent un retraitement. Cependant, si vous aviez défini un point de rupture cache_control explicite sur le bloc 5, le système continuerait à vérifier à partir de ce point de rupture : bloc 5 (pas de correspondance) → bloc 4 (correspondance !). Cela permet un accès au cache au bloc 4, démontrant pourquoi vous devriez placer des points de rupture avant le contenu modifiable.
Point clé : Définissez toujours un point de rupture de cache explicite à la fin de votre conversation pour maximiser vos chances d'accès au cache. De plus, définissez des points de rupture juste avant les blocs de contenu qui pourraient être modifiables pour assurer que ces sections peuvent être mises en cache indépendamment.
Vous pouvez définir jusqu'à 4 points de rupture de cache si vous souhaitez :
Limitation importante : Si votre invite a plus de 20 blocs de contenu avant votre point de rupture de cache, et que vous modifiez le contenu plus tôt que ces 20 blocs, vous n'obtiendrez pas d'accès au cache à moins d'ajouter des points de rupture explicites supplémentaires plus proches de ce contenu.
La longueur minimale d'invite pouvant être mise en cache est :
Les invites plus courtes ne peuvent pas être mises en cache, même si elles sont marquées avec cache_control. Toute demande de mise en cache de moins que ce nombre de jetons sera traitée sans mise en cache. Pour voir si une invite a été mise en cache, consultez les champs d'utilisation de la réponse.
Pour les demandes 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 d'accès au cache pour les demandes parallèles, attendez la première réponse avant d'envoyer les demandes 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.
Les points de rupture de cache eux-mêmes n'ajoutent aucun coût. Vous êtes facturé uniquement pour :
L'ajout de plus de points de rupture cache_control n'augmente pas vos coûts - vous payez toujours le même montant en fonction du contenu réellement mis en cache et lu. Les points de rupture vous donnent simplement le contrôle sur les sections qui peuvent être mises en cache indépendamment.
La plupart des blocs de la demande peuvent être désignés pour la mise en cache avec cache_control. Ceci inclut :
toolssystemmessages.content, pour les tours utilisateur et assistantmessages.content, dans les tours utilisateurmessages.content, dans les tours utilisateur et assistantChacun de ces éléments peut être marqué avec cache_control pour activer la mise en cache pour cette partie de la demande.
Bien que la plupart des blocs de demande 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 les tours d'assistant précédents. Lorsqu'ils sont mis en cache de cette façon, ils COMPTENT comme jetons d'entrée lorsqu'ils sont lus à partir du cache.
Les blocs de sous-contenu (comme les citations) eux-mêmes 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 la mise en cache des invites avec les citations efficacement en mettant en cache les documents que les citations référenceront.
Les blocs de texte vides ne peuvent pas être mis en cache.
Les modifications du contenu mis en cache peuvent invalider une partie ou la totalité du cache.
Comme décrit dans Structuration de votre invite, le cache suit la hiérarchie : tools → system → messages. Les modifications à 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 modifications. ✘ indique que le cache est invalidé, tandis que ✓ indique que le cache reste valide.
| Ce qui change | Cache des outils | Cache système | Cache des messages | Impact |
|---|---|---|---|---|
| Définitions d'outils | ✘ | ✘ | ✘ | La modification des définitions d'outils (noms, descriptions, paramètres) invalide l'intégralité du cache |
| Basculement de recherche Web | ✓ | ✘ | ✘ | L'activation/désactivation de la recherche Web modifie l'invite système |
| Basculement des citations | ✓ | ✘ | ✘ | L'activation/désactivation des citations modifie l'invite système |
| Choix d'outil | ✓ | ✓ | ✘ | Les modifications du paramètre tool_choice n'affectent que les blocs de messages |
| Images | ✓ | ✓ | ✘ | L'ajout/suppression d'images n'importe où dans l'invite affecte les blocs de messages |
| Paramètres de réflexion | ✓ | ✓ | ✘ | Les modifications des paramètres de réflexion étendue (activation/désactivation, budget) affectent les blocs de messages |
| Résultats non-outils transmis aux demandes de réflexion étendue | ✓ | ✓ | ✘ | Lorsque des résultats non-outils sont transmis dans les demandes tandis que la réflexion étendue est activée, tous les blocs de réflexion précédemment mis en cache sont supprimés du contexte, et tous les messages en contexte qui suivent ces blocs de réflexion sont supprimés du cache. Pour plus de détails, voir Mise en cache avec blocs de réflexion. |
Surveillez les performances du cache à l'aide de 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 jetons écrits dans le cache lors de la création d'une nouvelle entrée.cache_read_input_tokens : Nombre de jetons récupérés du cache pour cette demande.input_tokens : Nombre de jetons d'entrée qui n'ont pas été lus ou utilisés pour créer un cache (c'est-à-dire les jetons après le dernier point de rupture de cache).Comprendre la répartition des jetons
Le champ input_tokens représente uniquement les jetons qui viennent après le dernier point de rupture de cache dans votre demande - pas tous les jetons d'entrée que vous avez envoyés.
Pour calculer le nombre total de jetons d'entrée :
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokensExplication spatiale :
cache_read_input_tokens = jetons avant le point de rupture déjà mis en cache (lectures)cache_creation_input_tokens = jetons avant le point de rupture en cours de mise en cache maintenant (écritures)input_tokens = jetons après votre dernier point de rupture (non éligibles pour le cache)Exemple : Si vous avez une demande avec 100 000 jetons de contenu mis en cache (lus à partir du cache), 0 jetons de nouveau contenu en cours de mise en cache, et 50 jetons dans votre message utilisateur (après le point de rupture de cache) :
cache_read_input_tokens : 100 000cache_creation_input_tokens : 0input_tokens : 50Ceci est important pour comprendre à la fois les coûts et les limites de débit, car input_tokens sera généralement beaucoup plus petit que votre entrée totale lors de l'utilisation efficace de la mise en cache.
Pour optimiser les performances de la mise en cache des invites :
Adaptez votre stratégie de mise en cache des invites à votre scénario :
Si vous rencontrez un comportement inattendu :
tool_choice et l'utilisation des images restent cohérents entre les appelscache_control supplémentaires plus tôt dans l'invite pour assurer que tout le contenu peut être mis en cachetool_use ont un ordre stable car certains langages (par exemple Swift, Go) randomisent l'ordre des clés lors de la conversion JSON, cassant les cachesLes modifications apportées à tool_choice ou la présence/absence d'images n'importe où dans l'invite invalideront le cache, nécessitant la création d'une nouvelle entrée de cache. Pour plus de détails sur l'invalidation du cache, voir Ce qui invalide le cache.
Lors de l'utilisation de la réflexion étendue avec la mise en cache des invites, 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 demande lorsque vous effectuez des appels API ultérieurs avec des résultats d'outils. Cela se produit généralement lors de l'utilisation d'outils lorsque vous transmettez les blocs de réflexion pour continuer la conversation.
Comptage des jetons d'entrée : Lorsque les blocs de réflexion sont lus à partir du cache, ils comptent comme jetons d'entrée dans vos métriques d'utilisation. Ceci est important pour le calcul des coûts et la budgétisation des jetons.
Modèles d'invalidation du cache :
cache_control explicitesPour plus de détails sur l'invalidation du cache, voir Ce qui invalide le cache.
Exemple avec utilisation d'outils :
Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]
Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1
Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never presentLorsqu'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, consultez la documentation sur la réflexion étendue.
Isolation organisationnelle : Les caches sont isolés entre les organisations. Différentes organisations ne partagent jamais les caches, même si elles utilisent des invites identiques.
Correspondance exacte : Les accès au cache nécessitent une correspondance à 100 % des segments d'invite, y compris tout le texte et les images jusqu'à et y compris le bloc marqué avec le contrôle de cache.
Génération de jetons de sortie : La mise en cache des invites n'a aucun effet sur la génération de jetons de sortie. La réponse que vous recevez sera identique à celle que vous obtiendriez si la mise en cache des invites n'était pas utilisée.
Si vous trouvez que 5 minutes est trop court, Anthropic propose également une durée de cache d'1 heure à un coût supplémentaire.
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 de cache détaillées 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 cache_creation_input_tokens actuel est égal à la somme des valeurs dans l'objet cache_creation.
Si vous avez des invites qui sont utilisées à un rythme régulier (c'est-à-dire des invites système qui sont utilisées 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 d'1 heure est mieux utilisé dans les scénarios suivants :
Le cache de 5 minutes et d'1 heure se comportent de la même manière en ce qui concerne la latence. Vous verrez généralement une amélioration du temps jusqu'au premier jeton pour les documents longs.
Vous pouvez utiliser les contrôles de cache d'1 heure et de 5 minutes dans la même demande, 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).
Lors du mélange de TTL, nous déterminons trois emplacements de facturation dans votre invite :
A : Le nombre de jetons au plus haut accès au cache (ou 0 s'il n'y a pas d'accès).B : Le nombre de jetons au plus haut bloc cache_control d'1 heure après A (ou égal à A s'il n'en existe pas).C : Le nombre de jetons au dernier bloc cache_control.Si B et/ou C sont plus grands que A, ils seront nécessairement des accès manqués au cache, car A est l'accès au cache le plus haut.
Vous serez facturé pour :
A.(B - A).(C - B).Voici 3 exemples. Ceci décrit les jetons d'entrée de 3 demandes, chacune ayant différents accès au cache et accès manqués au cache. Chacun a une tarification calculée différente, affichée dans les boîtes colorées, en conséquence.
Pour vous aider à démarrer avec la mise en cache des invites, nous avons préparé un carnet de recettes sur la mise en cache des invites avec des exemples détaillés et les meilleures pratiques.
Ci-dessous, nous avons inclus plusieurs extraits de code qui présentent différents modèles de mise en cache des invites. Ces exemples montrent comment implémenter la mise en cache dans différents scénarios, vous aidant à comprendre les applications pratiques de cette fonctionnalité :