cache_control
:
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.
tools
, system
, et messages
(dans cet ordre) jusqu’au bloc désigné avec cache_control
inclus.Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
---|---|---|---|---|---|
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 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.5 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / 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 |
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.
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 d’arrêt explicite)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 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.
cache_control
n’augmente pas vos coûts - vous payez toujours le même montant basé sur quel contenu est réellement mis en cache et lu. Les points d’arrêt vous donnent simplement le contrôle sur quelles sections peuvent être mises en cache indépendamment.
cache_control
. Cela inclut :
tools
system
messages.content
, pour les tours utilisateur et assistantmessages.content
, dans les tours utilisateurmessages.content
, dans les tours utilisateur et assistantcache_control
pour activer la mise en cache pour cette portion de la requête.
cache_control
. Cependant, les blocs de réflexion PEUVENT être mis en cache avec d’autre contenu lorsqu’ils apparaissent dans les tours d’assistant précédents. Lorsqu’ils sont mis en cache de cette façon, ils COMPTENT comme tokens d’entrée lorsqu’ils sont lus depuis le cache.
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.
Ce qui change | Cache des outils | Cache système | Cache des messages | Impact |
---|---|---|---|---|
Définitions d’outils | ✘ | ✘ | ✘ | Modifier les définitions d’outils (noms, descriptions, paramètres) invalide tout le cache |
Basculement de recherche web | ✓ | ✘ | ✘ | Activer/désactiver la recherche web modifie le prompt système |
Basculement des citations | ✓ | ✘ | ✘ | Activer/désactiver les citations modifie le prompt système |
Choix d’outil | ✓ | ✓ | ✘ | Les changements au paramètre tool_choice n’affectent que les blocs de messages |
Images | ✓ | ✓ | ✘ | Ajouter/supprimer des images n’importe où dans le prompt affecte les blocs de messages |
Paramètres de réflexion | ✓ | ✓ | ✘ | Les changements aux paramètres de réflexion étendue (activer/désactiver, budget) affectent les blocs de messages |
Résultats non-outils passés aux requêtes de réflexion étendue | ✓ | ✓ | ✘ | Lorsque des résultats non-outils sont passés dans les requêtes pendant 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 dans le contexte qui suivent ces blocs de réflexion sont supprimés du cache. Pour plus de détails, voir Mise en cache avec les blocs de réflexion. |
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.tool_choice
et l’utilisation d’images restent cohérents entre les appelscache_control
supplémentaires plus tôt dans le prompt pour assurer que tout le contenu peut être mis en cachetool_choice
ou la présence/absence d’images n’importe où dans le prompt invalideront le cache, nécessitant qu’une nouvelle entrée de cache soit créée. Pour plus de détails sur l’invalidation du cache, voir Ce qui invalide le cache.cache_control
, ils sont mis en cache dans le cadre du contenu de la requête lorsque vous faites des appels API suivants avec des résultats d’outils. Cela arrive couramment pendant l’utilisation d’outils lorsque vous renvoyez les 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 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 :
cache_control
explicitesttl
dans la définition cache_control
comme ceci :
cache_creation_input_tokens
égale la somme des valeurs dans l’objet cache_creation
.
A
: Le nombre de tokens à la correspondance de cache la plus élevée (ou 0 s’il n’y a pas de correspondances).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).C
: Le nombre de tokens au dernier bloc cache_control
.B
et/ou C
sont plus grands que A
, ils seront nécessairement des échecs de cache, car A
est la correspondance de cache la plus élevée.A
.(B - A)
.(C - B)
.Exemple de mise en cache de contexte volumineux
input_tokens
: Nombre de tokens dans le message utilisateur seulementcache_creation_input_tokens
: Nombre de tokens dans tout le message système, incluant le document juridiquecache_read_input_tokens
: 0 (pas de correspondance de cache sur la première requête)input_tokens
: Nombre de tokens dans le message utilisateur seulementcache_creation_input_tokens
: 0 (pas de nouvelle création de cache)cache_read_input_tokens
: Nombre de tokens dans tout le message système mis en cacheMise en cache des définitions d'outils
cache_control
est placé sur l’outil final (get_time
) pour désigner tous les outils comme faisant partie du préfixe statique.Cela signifie que toutes les définitions d’outils, incluant get_weather
et tout autre outil défini avant get_time
, seront mises en cache comme un seul préfixe.Cette approche est utile lorsque vous avez un ensemble cohérent d’outils que vous voulez réutiliser à travers plusieurs requêtes sans les retraiter à chaque fois.Pour la première requête :input_tokens
: Nombre de tokens dans le message utilisateurcache_creation_input_tokens
: Nombre de tokens dans toutes les définitions d’outils et le prompt systèmecache_read_input_tokens
: 0 (pas de correspondance de cache sur la première requête)input_tokens
: Nombre de tokens dans le message utilisateurcache_creation_input_tokens
: 0 (pas de nouvelle création de cache)cache_read_input_tokens
: Nombre de tokens dans toutes les définitions d’outils mises en cache et le prompt systèmeContinuer une conversation multi-tours
cache_control
pour que la conversation puisse être mise en cache de manière incrémentale. Le système recherchera automatiquement et utilisera le préfixe mis en cache le plus long précédemment pour les messages de suivi. C’est-à-dire, les blocs qui étaient précédemment marqués avec un bloc cache_control
ne sont plus marqués avec ceci plus tard, mais ils seront toujours considérés comme une correspondance de cache (et aussi un rafraîchissement de cache !) s’ils sont touchés dans les 5 minutes.De plus, notez que le paramètre cache_control
est placé sur le message système. Ceci est pour s’assurer que si cela est évincé du cache (après ne pas avoir été utilisé pendant plus de 5 minutes), il sera rajouté au cache lors de la prochaine requête.Cette approche est utile pour maintenir le contexte dans les conversations en cours sans traiter de manière répétée les mêmes informations.Lorsque ceci est configuré correctement, vous devriez voir ce qui suit dans la réponse d’utilisation de chaque requête :input_tokens
: Nombre de tokens dans le nouveau message utilisateur (sera minimal)cache_creation_input_tokens
: Nombre de tokens dans les nouveaux tours assistant et utilisateurcache_read_input_tokens
: Nombre de tokens dans la conversation jusqu’au tour précédentTout assembler : Multiples points d'arrêt de cache
cache_control
sur la dernière définition d’outil met en cache toutes les définitions d’outils.
cache_control
pour permettre la mise en cache incrémentale de la conversation au fur et à mesure qu’elle progresse.
input_tokens
: Tokens dans le message utilisateur finalcache_creation_input_tokens
: Tokens dans tous les segments mis en cache (outils + instructions + documents RAG + historique de conversation)cache_read_input_tokens
: 0 (pas de correspondances de cache)input_tokens
: Tokens dans le nouveau message utilisateur seulementcache_creation_input_tokens
: Tous nouveaux tokens ajoutés à l’historique de conversationcache_read_input_tokens
: Tous les tokens précédemment mis en cache (outils + instructions + documents RAG + conversation précédente)Ai-je besoin de plusieurs points d'arrêt de cache ou un seul à la fin est-il suffisant ?
Les points d'arrêt de cache ajoutent-ils des coûts supplémentaires ?
Quelle est la durée de vie du cache ?
Combien de points d'arrêt de cache puis-je utiliser ?
cache_control
) dans votre prompt.La mise en cache des prompts est-elle disponible pour tous les modèles ?
Comment la mise en cache des prompts fonctionne-t-elle avec la réflexion étendue ?
Comment activer la mise en cache des prompts ?
cache_control
dans votre requête API.Puis-je utiliser la mise en cache des prompts avec d'autres fonctionnalités de l'API ?
Comment la mise en cache des prompts affecte-t-elle la tarification ?
Puis-je effacer manuellement le cache ?
Comment puis-je suivre l'efficacité de ma stratégie de mise en cache ?
cache_creation_input_tokens
et cache_read_input_tokens
dans la réponse API.Qu'est-ce qui peut casser le cache ?
Comment la mise en cache des prompts gère-t-elle la confidentialité et la séparation des données ?
cache_control
n’importe où dans vos prompts. Pour l’efficacité des coûts, il est mieux d’exclure les parties très variables (par exemple, l’entrée arbitraire de l’utilisateur) de la mise en cache.
Puis-je utiliser la mise en cache des prompts avec l'API Batches ?
Pourquoi est-ce que je vois l'erreur `AttributeError: 'Beta' object has no attribute 'prompt_caching'` en Python ?
Pourquoi est-ce que je vois 'TypeError: Cannot read properties of undefined (reading 'messages')' ?