Mise en cache des invites

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    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'."}],
)
print(response.usage.model_dump_json())

# Call the model again with the same inputs up to the cache checkpoint
response = client.messages.create(.....)
print(response.usage.model_dump_json())

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.messages.create({
  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'."
    }
  ]
});
console.log(response.usage);

// Call the model again with the same inputs up to the cache checkpoint
const new_response = await client.messages.create(...)
console.log(new_response.usage);

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;

public class PromptCachingExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_4_20250514)
                .maxTokens(1024)
                .systemOfTextBlockParams(List.of(
                        TextBlockParam.builder()
 .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")
 .build(),
                        TextBlockParam.builder()
 .text("<the entire contents of 'Pride and Prejudice'>")
 .cacheControl(CacheControlEphemeral.builder().build())
 .build()
                ))
                .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
                .build();

        Message message = client.messages().create(params);
        System.out.println(message.usage());
    }
}

{"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 entier de « Pride and Prejudice » est mis en cache à l'aide du paramètre cache_control. Cela permet de réutiliser ce grand texte dans plusieurs appels API sans le retraiter à chaque fois. Modifier uniquement le 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é.

Comment fonctionne la mise en cache des invites

Lorsque vous envoyez une demande avec la mise en cache des invites activée :

1. Le système vérifie si un préfixe d'invite, 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 l'invite complète et met en cache le préfixe une fois que la réponse commence.

Ceci est particulièrement utile pour :

• Les invites avec de nombreux exemples
• De grandes quantités de contexte ou d'informations générales
• 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 frais supplémentaires chaque fois que le contenu mis en cache est utilisé.

Tarification

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 :

Comment implémenter la mise en cache des invites

Modèles pris en charge

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

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Haiku 4.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (obsolète)

Structurer votre invite

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.

Comment fonctionne la vérification automatique des préfixes

Vous pouvez utiliser un seul point de rupture de cache à la fin de votre contenu statique, et le système trouvera automatiquement le préfixe correspondant le plus long. Comprendre comment cela fonctionne vous aide à optimiser votre stratégie de mise en cache.

Trois principes fondamentaux :

1. 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 de manière séquentielle. Cela signifie que le cache pour chaque bloc dépend de tout le contenu qui l'a précédé.

2. 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 l'accès au cache le plus long possible.

3. Fenêtre de recherche rétroactive 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 recherche rétroactive

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.

Quand utiliser plusieurs points de rupture

Vous pouvez définir jusqu'à 4 points de rupture de cache si vous souhaitez :

• Mettre en cache différentes sections qui changent à des fréquences différentes (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 du contenu plus de 20 blocs avant votre point de rupture final
• Placer des points de rupture avant le contenu modifiable pour garantir des accès au cache même lorsque des modifications se produisent au-delà de la fenêtre de 20 blocs

Limitations du cache

La longueur minimale d'invite pouvant être mise en cache est :

• 1024 jetons pour Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (obsolète) et Claude Opus 3 (obsolète)
• 4096 jetons pour Claude Haiku 4.5
• 2048 jetons pour Claude Haiku 3.5 et Claude Haiku 3

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 concurrentes, 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.

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 êtes facturé uniquement pour :

• Écritures de cache : Lorsque du nouveau contenu est écrit dans le cache (25 % de plus que les jetons d'entrée de base pour TTL de 5 minutes)
• Lectures de cache : Lorsque le contenu mis en cache est utilisé (10 % du prix des jetons d'entrée de base)
• Jetons 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 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.

Ce qui peut être mis en cache

La plupart des blocs de la demande 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 demande.

Ce qui ne peut pas être mis en cache

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 aux côtés d'autre contenu lorsqu'ils apparaissent dans les tours assistant précédents. Lorsqu'ils sont mis en cache de cette façon, ils COMPTENT comme des 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.

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 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.

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

Meilleures pratiques pour une mise en cache efficace

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

• Mettez en cache le contenu stable et réutilisable comme les instructions système, les informations générales, les grands contextes ou les définitions d'outils fréquentes.
• Placez le contenu mis en cache au début de l'invite 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.
• Définissez les points de rupture de cache à la fin des conversations et juste avant le contenu modifiable pour maximiser les taux d'accès au cache, en particulier lorsque vous travaillez avec des invites ayant plus de 20 blocs de contenu.
• Analysez régulièrement les taux d'accès au 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 invites à 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 gardant les sections pertinentes ou une version résumée de la base de code dans l'invite.
• Traitement de grands documents : Incorporez du matériel long complet, y compris des images, dans votre invite sans augmenter la latence de réponse.
• Ensembles d'instructions détaillées : 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 ou deux exemples dans l'invite, mais avec la mise en cache des invites, vous pouvez obtenir des performances encore meilleures 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 modifications de code itératives, où chaque étape nécessite généralement un nouvel appel API.
• Parlez à des livres, des articles, de la documentation, des transcriptions de podcasts et d'autres contenus longs : Donnez vie à n'importe quelle base de connaissances en intégrant le ou les documents entiers dans l'invite, et laissez les utilisateurs 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 dans tous 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érents entre les appels
• Validez que vous mettez en cache au moins le nombre minimum de jetons
• Le système vérifie automatiquement les accès au cache aux limites des blocs de contenu précédents (jusqu'à ~20 blocs avant votre point de rupture). Pour les invites avec plus de 20 blocs de contenu, vous devrez peut-être ajouter des paramètres cache_control supplémentaires plus tôt dans l'invite pour assurer que tout le contenu peut être mis en cache
• Vérifiez que les clés de vos blocs de contenu tool_use ont un ordre stable car certains langages (par exemple Swift, Go) randomisent l'ordre des clés lors de la conversion JSON, ce qui casse les caches

Mise en cache avec les blocs de réflexion

Lorsque vous utilisez 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 aux côtés 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 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 des jetons d'entrée dans vos métriques d'utilisation. C'est important pour le calcul des coûts et la budgétisation des jetons.

Modèles d'invalidation du cache :

• Le cache reste valide lorsque seuls les résultats d'outils sont fournis en tant que messages utilisateur
• Le cache est invalidé lorsque du contenu utilisateur non-résultat d'outil 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

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

Exemple avec utilisation d'outils :

Demande 1 : Utilisateur : « Quel est le temps à Paris ? »
Réponse : [thinking_block_1] + [bloc tool_use 1]

Demande 2 :
Utilisateur : [« Quel est le temps à Paris ? »],
Assistant : [thinking_block_1] + [bloc tool_use 1],
Utilisateur : [tool_result_1, cache=True]
Réponse : [thinking_block_2] + [bloc texte 2]
# La demande 2 met en cache son contenu de demande (pas la réponse)
# Le cache inclut : message utilisateur, thinking_block_1, bloc tool_use 1 et tool_result_1

Demande 3 :
Utilisateur : [« Quel est le temps à Paris ? »],
Assistant : [thinking_block_1] + [bloc tool_use 1],
Utilisateur : [tool_result_1, cache=True],
Assistant : [thinking_block_2] + [bloc texte 2],
Utilisateur : [Réponse texte, cache=True]
# Le bloc utilisateur non-résultat d'outil entraîne l'ignorance de tous les blocs de réflexion
# Cette demande est traitée comme si les blocs de réflexion n'avaient jamais été présents

Lorsqu'un bloc utilisateur non-résultat d'outil est inclus, il désigne une nouvelle boucle 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 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 à ce que vous obtiendriez si la mise en cache des invites n'était pas utilisée.

Durée du cache d'1 heure

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.

Quand utiliser le cache d'1 heure

Si vous avez des invites utilisées à un rythme régulier (c'est-à-dire des invites système 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 :

• Lorsque vous avez des invites susceptibles d'être utilisées moins fréquemment que toutes les 5 minutes, mais plus fréquemment que toutes les heures. Par exemple, lorsqu'un agent auxiliaire agentique prendra plus de 5 minutes, ou lorsque 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 prochaines minutes.
• Lorsque la latence est importante et que vos invites de suivi peuvent être envoyées au-delà de 5 minutes.
• Lorsque vous souhaitez améliorer votre utilisation des limites de débit, car les accès au cache ne sont pas déduits de votre limite de débit.

Mélanger différents TTL

Vous pouvez utiliser à la fois 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 des TTL, nous déterminons trois emplacements de facturation dans votre invite :

1. Position A : Le nombre de jetons au plus haut accès au cache (ou 0 s'il n'y a pas d'accès).
2. Position 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).
3. Position C : Le nombre de jetons au dernier bloc cache_control.

Vous serez facturé pour :

1. Jetons de lecture du cache pour A.
2. Jetons d'écriture de cache d'1 heure pour (B - A).
3. Jetons d'écriture de cache de 5 minutes pour (C - B).

Voici 3 exemples. Ceci dépict 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.

Exemples de mise en cache des invites

Pour vous aider à démarrer avec la mise en cache des invites, nous avons préparé un livre de recettes de mise en cache des invites 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 invites. 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