Cette rubrique explique comment utiliser le cache explicite et présente les bonnes pratiques associées. L'ajout de marqueurs de cache à vos requêtes garantit des correspondances déterministes pour un contenu d'entrée identique, ce qui réduit considérablement les coûts et la latence.
Quand utiliser le cache explicite
- Garantie de correspondance : Le cache explicite assure un taux de réussite de 100 %, indépendamment de l'ordonnancement des ressources backend. Privilégiez cette option si votre application nécessite une réutilisation stable du contenu.
- Réutilisation fréquente du même prompt : La soumission répétée de prompts identiques ou très similaires permet de réaliser des économies substantielles. La création du cache n'entraîne qu'un supplément de 25 % par rapport au prix standard d'entrée, tandis que chaque correspondance ultérieure génère une économie de 90 %. Une seule correspondance suffit à rentabiliser l'opération.
- Gestion de contextes longs pour les Agents en production : Dans les applications Agent, des mécanismes courants comme la compression, le résumé ou les rappels système modifient continuellement le contexte. Le cache explicite permet d'ancrer et de réutiliser des segments clés du contexte afin qu'ils restent en cache, même lorsque le contexte environnant évolue.
Outils Agent et de codage
Les outils Agent et de codage suivants se connectent à Alibaba Cloud Model Studio via le protocole Anthropic et prennent en charge nativement le cache explicite. Configurez-les selon leur documentation respective pour qu'ils exploitent automatiquement le cache explicite et optimisent la gestion du contexte.
Les exemples ci-dessous utilisent l'endpoint de Singapour. Pour d'autres régions, remplacez l'URL de base par l'endpoint régional correspondant.
- Claude Code
- Open Code
- OpenClaw
- Hermes
À partir de la version v2.x, Claude Code inclut automatiquement des marqueurs cache_control dans les requêtes (système, environnement et dernier message utilisateur). Aucune configuration supplémentaire n'est requise après la connexion à l'endpoint compatible Anthropic d'Alibaba Cloud Model Studio.ConfigurationCréez ou modifiez le fichier ~/.claude/settings.json (Windows : C:\Users<username>.claude\settings.json) avec les paramètres de plan appropriés. Vous pouvez également établir la connexion via des variables d'environnement :Définissez l'endpoint du protocole Anthropic :
- Token Plan (Team) : https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic
- Coding Plan : https://coding-intl.dashscope.aliyuncs.com/apps/anthropic
-
Paiement à l'utilisation : https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic
Remplacez
WorkspaceIdpar votre véritable ID d'espace de travail.
Intégration API
Points clés
- Ajoutez
"cache_control": {"type": "ephemeral"}au contenu du message que vous souhaitez mettre en cache. Tout le contenu, depuis le début du tableau messages jusqu'à ce marqueur, sera mis en cache sous forme de bloc. - Le contenu mis en cache doit comporter au moins 1024 tokens.
- Une requête unique prend en charge jusqu'à 4 marqueurs de cache.
- La durée de vie (TTL) du cache est de 5 minutes, renouvelée automatiquement à chaque correspondance.
- Les définitions d'outils font partie du prompt système pour la mise en cache. Toute modification des outils entraîne une invalidation du cache.
Démarrage rapide
L'exemple suivant illustre le flux de travail de base : la première requête crée un cache, tandis que la seconde l'utilise.
Vérifier l'état du cache
Examinez le champ usage dans la réponse pour confirmer le comportement du cache :
cache_creation_input_tokens: Nombre de tokens pour lesquels un nouveau cache a été créé. Une valeur supérieure à 0 indique la création d'un nouveau bloc de cache.cached_tokens(compatible OpenAI) oucache_read_input_tokens(compatible Anthropic) : Nombre de tokens ayant trouvé une correspondance dans le cache. Une valeur supérieure à 0 confirme que le cache a été utilisé avec succès.
Bonnes pratiques par scénario
Conversations multi-tours
Caractéristiques :
- Les utilisateurs interagissent avec le modèle sur plusieurs tours, chaque requête transportant l'historique complet de la conversation.
- Cas d'usage typiques : service client, questions-réponses sur une base de connaissances, assistants de codage.
cache_control au dernier message de chaque requête. Chaque tour utilise ainsi le cache créé lors du tour précédent (l'historique de la conversation), tout en créant un nouveau cache incluant le tour actuel pour la prochaine itération.
Exemple :
Agent en production (plusieurs marqueurs de cache)
Caractéristiques :
- Conversations longues et multi-tours comprenant : prompt système + définitions de compétences/outils + contexte projet + messages utilisateur / appels d'outils.
- Fréquences de modification variables selon les sections.
- Cas d'usage typiques : assistants de codage IA (Claude Code, OpenClaw), systèmes de questions-réponses basés sur le RAG.
- Prompt système — un marqueur (change rarement).
- Définitions de compétences/outils — un marqueur (peut changer par combinaison).
- Contexte projet — un marqueur (peut être remplacé ou compressé).
- Messages utilisateur / appels d'outils — un marqueur (s'allonge à chaque tour).
- L'utilisateur continue de poser des questions sur le même produit : Le persona, les outils et la base de connaissances restent inchangés, ce qui déclenche une correspondance au niveau du marqueur 2 (correspondance de préfixe la plus longue) pour des économies maximales.
- Augmentation du nombre de tours de conversation : Le contenu antérieur (persona + outils + base de connaissances + historique) correspond au cache du tour précédent ; seul le nouveau contenu nécessite la création d'un nouveau cache.
Organisez le contenu du plus stable au moins stable : placez le contenu qui change le moins au début (par exemple, le persona système) et celui qui change le plus à la fin (par exemple, la conversation en cours) afin de maximiser les taux de réussite du cache.
Traitement par lots (exécution de tâches)
Caractéristiques :
- Requêtes à tour unique, sans nécessité de mémorisation du contexte.
- Prompt système long et fixe (instructions de tâche) + entrée utilisateur variable (données à traiter).
- Cas d'usage typiques : classification de texte, reconnaissance d'intention, extraction de données, modération de contenu.
cache_control uniquement sur le prompt système. Toutes les requêtes suivantes utiliseront le cache tant que le prompt système reste inchangé.
Exemple :
Function Calling avec définitions d'outils mises en cache
Caractéristiques :
- Utilisation de Function Calling avec une longue liste de définitions d'outils.
- Les définitions d'outils restent inchangées d'une requête à l'autre.
tools fait partie du prompt système pour la mise en cache. Assurez-vous que les définitions d'outils sont strictement identiques d'une requête à l'autre (même ordre, même ordre des champs, même structure) et ajoutez un marqueur cache_control au contenu du message.
Remarques importantes
- Exigence de format de contenu : Lors de l'ajout de
cache_control, le champ content doit être au format tableau. Le contenu sous forme de chaîne ne prend pas en charge les marqueurs de cache. - Granularité des marqueurs de cache : Les modèles Qwen3.5 et ultérieurs ne prennent en charge que les points d'arrêt de cache au niveau du message. Placer plusieurs marqueurs
cache_controldans le tableau de contenu d'un seul message ne crée pas de points d'arrêt distincts ; le système stocke uniquement le cache à la position du dernier marqueur dans ce message et ne peut pas effectuer de correspondance par troncature sur des blocs de contenu intermédiaires. De plus, plusieurs messages système sont fusionnés en interne en un seul segment et ne peuvent pas servir de points d'arrêt distincts. Pour créer plusieurs points d'arrêt indépendants, répartissez les marqueurscache_controlsur des messages ayant des rôles différents (par exemple, un sur system, un sur user). Les modèles antérieurs à Qwen3.5 prennent en charge les points d'arrêt au niveau du contenu (intra-message). - Exclusivité mutuelle avec le cache implicite : Une requête ne peut utiliser qu'un seul mode de mise en cache. Si la requête contient un marqueur
cache_control, le cache explicite est utilisé ; sinon, le système utilise automatiquement le cache implicite.