Les requêtes d'inférence adressées aux grands modèles contiennent souvent des entrées qui se chevauchent, comme dans le cas d'une conversation multi-tours ou d'une série de questions portant sur le même ouvrage. La fonctionnalité Context Cache réduit les calculs redondants en mettant en cache le préfixe commun de ces requêtes. Cela améliore la vitesse de réponse et diminue les coûts d'utilisation sans affecter la qualité des réponses.
qwen4-max: Prompt Cache.
Pour s'adapter à différents scénarios, le cache de contexte propose deux modes. Choisissez un mode en fonction de vos besoins en matière de simplicité, de déterminisme et de coût :
- Explicit cache : mode que vous activez manuellement. Vous créez un cache pour un contenu spécifique afin de garantir une correspondance déterministe pendant sa période de validité de 5 minutes. Les jetons utilisés pour créer le cache sont facturés à 125 % du prix standard des jetons d'entrée, tandis que les correspondances de cache ultérieures ne sont facturées qu'à 10 % de ce prix.
- Implicit cache : ce mode automatique ne nécessite aucune configuration supplémentaire et ne peut pas être désactivé ; il est idéal pour les scénarios privilégiant la simplicité. Le système identifie automatiquement et met en cache le préfixe commun des requêtes, mais la probabilité de correspondance n'est pas garantie. La partie de l'entrée servie depuis le cache est facturée à 20 % du prix standard des jetons d'entrée.
Élément | Explicit cache | Implicit cache |
|---|---|---|
Impact sur la qualité de la réponse | Aucun | Aucun |
Facturation des jetons de création de cache | 125 % du prix standard des jetons d'entrée | 100 % du prix standard des jetons d'entrée |
Facturation des jetons d'entrée mis en cache | 10 % du prix standard des jetons d'entrée | 20 % du prix standard des jetons d'entrée |
Nombre minimal de jetons pour la mise en cache | 1024 | 256 |
Période de validité du cache | 5 minutes (réinitialisée lors d'une correspondance) | Indéterminée. Le système efface périodiquement les anciennes données de cache inutilisées. |
Explicit cache
Contrairement au Implicit cache, le Explicit cache nécessite une création explicite et engendre une surcharge, mais il offre un taux de correspondance plus élevé et une latence d'accès plus faible.
Fonctionnement
Ajoutez un marqueur "cache_control": {"type": "ephemeral"} au tableau de messages. Le système recherche ensuite vers l'arrière à partir de chaque marqueur cache_control et examine jusqu'à 20 blocs content précédents pour trouver une correspondance de cache.
Une seule requête prend en charge jusqu'à quatre marqueurs de cache.
-
Absence de correspondance (Cache miss)
En cas d'absence de correspondance, le système crée un nouveau bloc de cache à partir du contenu situé entre le début du tableau de messages et le marqueur
cache_control. Le nouveau bloc de cache a une période de validité de 5 minutes.Le système crée le cache après que le modèle a généré une réponse. Attendez que la demande de création soit terminée avant d'essayer d'utiliser ce cache.
Un bloc de cache contient au moins 1 024 jetons.
- Correspondance de cache (Cache hit) En cas de correspondance, le système sélectionne le préfixe correspondant le plus long et réinitialise la période de validité du bloc de cache correspondant à 5 minutes.
-
Envoyez la première requête : envoyez un message système contenant le texte A (plus de 1 024 jetons) et ajoutez un marqueur de cache :
Le système crée le premier bloc de cache, appelé bloc de cache A.
-
Envoyez la deuxième requête : envoyez une requête avec la structure suivante :
- S'il y a 20 « Other messages » ou moins, la requête correspond au bloc de cache A, ce qui réinitialise sa période de validité à 5 minutes. Le système crée également un nouveau bloc de cache basé sur A, les autres messages et B.
- S'il y a plus de 20 « Other messages », la requête ne correspond pas au bloc de cache A. Le système crée tout de même un nouveau bloc de cache basé sur le contexte complet (A, les autres messages et B).
Modèles pris en charge
- Singapour
- Chine (Pékin)
- Allemagne (Francfort)
- Hong Kong (Chine)
- Japon (Tokyo)
- États-Unis (Virginie)
Les modèles suivants sont disponibles dans le périmètre de déploiement international.Qwen Max : qwen4-max, qwen3.8-max, qwen3.7-max, qwen3.7-max-2026-05-20, qwen3.7-max-2026-06-08Qwen Plus : qwen3.7-plus, qwen3.7-plus-2026-05-26, qwen3.6-plus, qwen3.5-plus, qwen3.5-plus-2026-04-20, qwen-plusQwen Flash : qwen3.7-flash, qwen3.7-flash-2026-07-15, qwen3.6-flash, qwen3.5-flash, qwen-flashQwen Coder : qwen3-coder-flashQwen VL : qwen3-vl-plusMacaron (déployé par MindLab) : mindlab/macaron-v1-tall, mindlab/macaron-v1.1-venti, mindlab/macaron-v1.1-coding-venti
Démarrage rapide
Les exemples suivants illustrent les mécanismes de création de bloc de cache et de correspondance de cache pour les protocoles compatibles avec OpenAI, DashScope et Anthropic.
- Compatible OpenAI
- DashScope
- Compatible Anthropic
cache_control active le Explicit cache pour le contenu simulé du dépôt de code. Pour les requêtes suivantes interrogeant ce contenu, le système réutilise le bloc de cache, éliminant ainsi le recalcul. Cela rend les requêtes qui correspondent au cache plus rapides et moins coûteuses que la requête initiale de création de cache.
Contrôle granulaire avec plusieurs marqueurs de cache
Dans des scénarios complexes, une invite comprend souvent plusieurs parties ayant des fréquences de réutilisation différentes. Vous pouvez utiliser plusieurs marqueurs de cache pour obtenir un contrôle granulaire.
Par exemple, l'invite d'un agent de service client intelligent comprend généralement :
- Persona système : très stable et change rarement.
- Connaissances externes : obtenues à partir de la base de connaissances ou via des requêtes d'outils, et peuvent ne pas changer au cours d'une même conversation.
- Historique des conversations : augmente dynamiquement.
- Question actuelle : différente pour chaque requête.
Facturation
Le Explicit cache affecte uniquement la facturation des jetons d'entrée. Les règles sont les suivantes :
-
Création de cache : le contenu utilisé pour créer un nouveau cache est facturé à 125 % du prix standard des jetons d'entrée. Si le contenu d'un nouveau cache inclut un cache existant comme préfixe, seule la portion incrémentielle est facturée pour la création de cache (c'est-à-dire le nombre de nouveaux jetons de cache moins le nombre de jetons de cache existants).
Par exemple, si vous disposez d'un cache existant de 1 200 jetons (Cache A) et que vous utilisez une nouvelle requête pour mettre en cache 1 500 jetons de contenu (Contenu AB), les 1 200 premiers jetons sont facturés comme une correspondance de cache à 10 % du prix standard. Les 300 nouveaux jetons sont facturés pour la création de cache à 125 % du prix standard.
Le paramètre
cache_creation_input_tokensspécifie le nombre de jetons utilisés pour la création de cache. -
Correspondance de cache : facturé à 10 % du prix standard des jetons d'entrée.
Le paramètre
cached_tokensspécifie le nombre de jetons mis en cache. - Autres jetons : les jetons qui ne correspondent ni à une correspondance de cache ni à une création de cache sont facturés au prix standard des jetons d'entrée.
- qwen4-max : Les prix d’écriture et de lecture du cache explicite ne suivent pas les ratios génériques ci-dessus. Pour les prix exacts, consultez la console Model Studio.
- Exception : le prix de correspondance du Explicit cache pour qwen3.8-max n'est pas de 10 % du prix standard des jetons d'entrée. Pour connaître les tarifs spécifiques, consultez la console Model Studio. (Le prix de création de cache reste à 125 % du prix standard.)
- Macaron (déployé par MindLab) : la création de cache et la correspondance de cache pour mindlab/macaron-v1-tall, mindlab/macaron-v1.1-venti et mindlab/macaron-v1.1-coding-venti sont facturées à des prix unitaires fixes, et non selon les ratios généraux ci-dessus. Pour connaître les tarifs spécifiques, consultez les pages d'informations sur les modèles (mindlab/macaron-v1-tall, mindlab/macaron-v1.1-venti, mindlab/macaron-v1.1-coding-venti) ou la console Model Studio.
Contenu pouvant être mis en cache
Seuls les types de messages suivants dans le tableau messages prennent en charge l'ajout de marqueurs de cache :
-
Message système
Pour l'appel de fonction, si une requête inclut le paramètre
tools, la définition de l'outil est incluse dans le message système pour le calcul du cache. Les définitions d'outils ne peuvent pas être mises en cache indépendamment. Les marqueurs de cache ajoutés aux définitions d'outils sont ignorés, car ils ne peuvent être ajoutés qu'au contenu d'un message. -
Message utilisateur
Lors de la création d'un cache avec le modèle
qwen3-vl-plus, vous pouvez placer le marqueurcache_controlaprès le contenu multimodal ou le texte. Sa position n'affecte pas la manière dont l'intégralité du message utilisateur est mis en cache. - Message assistant
- Message d'outil (résultat de l'exécution de l'outil)
content en un tableau et ajouter le champ cache_control :
messages.
Limitations du cache
- La longueur minimale de l'invite pouvant être mise en cache est de 1 024 jetons.
-
Le cache utilise une stratégie de correspondance de préfixe vers l'arrière. Une absence de correspondance se produit si le contenu correspondant et le message avec le marqueur
cache_controlsont séparés par plus de 20 blocs de contenu. -
Le
typene peut être défini que surephemeral, ce qui crée un cache avec une période de validité de 5 minutes. -
Une seule requête prend en charge jusqu'à quatre marqueurs de cache.
Si plus de quatre marqueurs de cache sont fournis, seuls les quatre derniers prennent effet.
Optimisation du cache pour l'appel de fonction
Une définition d'outil est sérialisée en une chaîne JSON pour la mise en cache. Pour éviter l'invalidation du cache, cette définition doit être identique dans toutes les requêtes. Notez les points suivants :
- Ordre cohérent des outils : l'ordre des outils dans le tableau
toolsdoit être cohérent dans toutes les requêtes. - Ordre cohérent des champs : l'ordre des champs JSON au sein d'un même outil doit être cohérent dans toutes les requêtes.
- Structure cohérente des champs : n'omettez pas et n'ajoutez pas de champs, même s'ils sont vides ou facultatifs.
Optimisation de la structure des messages pour les appels d'outils parallèles
Lorsque vous utilisez des appels d'outils parallèles, le modèle renvoie plusieurs tool_calls dans une seule réponse. Si vous envoyez chaque résultat d'outil sous forme de message tool distinct, le nombre de blocs de contenu dans le tableau messages augmente rapidement. Lorsque plus de 20 blocs de contenu séparent le marqueur cache_control du contenu antérieur, la fenêtre de recherche vers l'arrière ne peut pas atteindre ces blocs antérieurs, ce qui provoque une absence de correspondance.
Pour résoudre ce problème, fusionnez les messages d'outil consécutifs ayant le même rôle en un seul message tool avec plusieurs blocs de contenu avant d'envoyer la requête suivante. Cela réduit le nombre total de blocs de contenu et maintient le contenu que vous souhaitez mettre en cache dans la fenêtre de recherche de 20 blocs.
Avant optimisation (messages d'outil séparés — taux de correspondance plus faible) :
cache_control à des positions stables dans le tableau messages (par exemple, sur le message système ou sur d'autres contenus changeant rarement). Une seule requête prend en charge jusqu'à quatre marqueurs de cache.
Exemples d'utilisation
Interrogation d'un long texte
Interrogation d'un long texte
Pour garantir les performances du modèle, le système ajoute quelques jetons internes. Ces jetons sont facturés au prix standard des entrées. Pour plus d'informations, consultez la FAQ .
Mise en cache des outils pour l'appel de fonction
Mise en cache des outils pour l'appel de fonction
tools est mis en cache dans le cadre du message système. Assurez-vous que la définition de l'outil est identique pour chaque requête (y compris l'ordre des outils, l'ordre des champs et la structure des champs), et ajoutez un indicateur cache_control au dernier content dans messages.Ce qui suit montre le flux complet : la première requête crée le cache, et la deuxième requête correspond au cache.Conversation multi-tours continue
Conversation multi-tours continue
Implicit cache
Modèles pris en charge
- Chine (Pékin)
- Singapour
- États-Unis (Virginie)
- Allemagne (Francfort)
- Chine (Hong Kong)
- Japon (Tokyo)
-
Modèles de génération de texte
- Qwen Max : qwen4-max, qwen3.8-max, qwen3.7-max, qwen3.7-max-2026-05-20, qwen3.7-max-2026-06-08, qwen-max
- Qwen Plus : qwen3.7-plus, qwen3.7-plus-2026-05-26, qwen-plus
- Qwen Flash : qwen3.7-flash, qwen3.7-flash-2026-07-15, qwen-flash
- Qwen Coder : qwen3-coder-flash
- DeepSeek : deepseek-v4-pro, deepseek-v4.1-flash-1017
- Kimi : kimi-k3.1-pro, kimi-k2.7-code, kimi-k2.6, kimi-k2.5
- GLM : glm-5.2, glm-5.2-fast-preview, glm-5.1, glm-5
- MiniMax : MiniMax-M2.5
-
Modèles de compréhension visuelle
- Qwen VL : qwen3-vl-plus
Fonctionnement
La fonctionnalité Implicit cache est activée automatiquement lorsqu'une requête est envoyée à un modèle pris en charge. Le système fonctionne comme suit :
-
Recherche : après réception d'une requête, le système utilise la mise en correspondance de préfixe pour vérifier dans le cache la présence d'un préfixe commun du contenu dans le tableau
messagesde la requête. -
Décision :
- En cas de correspondance, le système utilise le résultat mis en cache pour le reste de l'inférence.
- En cas d'absence de correspondance, le système traite la requête normalement et stocke le préfixe de l'invite dans le cache pour les requêtes futures.
Le système efface périodiquement les données mises en cache qui n'ont pas été utilisées depuis longtemps. La probabilité de correspondance du Context Cache n'est pas de 100 %. Une absence de correspondance peut se produire même si le contexte de la requête est identique. Le système détermine la probabilité de correspondance spécifique.
Augmenter la probabilité de correspondance du cache
Une correspondance du Implicit cache se produit lorsque les préfixes de différentes requêtes comportent du contenu dupliqué. Pour augmenter la probabilité de correspondance, placez le contenu dupliqué au début d'une invite et le contenu unique à la fin.
- Modèle de texte : par exemple, supposons que le système ait mis en cache « ABCD ». Une requête pour « ABE » peut correspondre à la partie « AB », mais une requête pour « BCD » ne correspondra pas.
-
Modèle de compréhension visuelle :
- Pour poser plusieurs questions sur la même image ou vidéo, placez l'image ou la vidéo avant le texte.
- Pour poser la même question sur différentes images ou vidéos, placez le texte avant l'image ou la vidéo.
Facturation
Aucun frais supplémentaire n'est facturé pour l'activation du mode Implicit cache.
Lorsqu'une requête correspond au cache, les jetons d'entrée issus de la correspondance sont facturés en tant que cached_token. Le taux de réduction pour ces jetons varie selon le modèle. Les jetons d'entrée qui ne correspondent pas au cache sont facturés en tant que input_token standard. Les jetons de sortie sont facturés au prix d'origine.
-
Exemple : une requête contient 10 000 jetons d'entrée, et 5 000 d'entre eux entraînent une correspondance de cache. Le coût est calculé comme suit :
-
Pour les modèles autres que deepseek-v4.1-flash, deepseek-v4.1-flash-1017, deepseek-v4-pro, qwen3.8-max, mindlab/macaron-v1-tall, mindlab/macaron-v1.1-venti et mindlab/macaron-v1.1-coding-venti : le prix unitaire du
cached_tokenreprésente 20 % du prix unitaire de l'input_token. -
deepseek-v4-pro : le prix unitaire du
cached_tokenne représente pas 20 % du prix unitaire de l'input_token. Pour connaître les tarifs spécifiques, consultez la console Model Studio. -
deepseek-v4.1-flash et deepseek-v4.1-flash-1017 : le
cached_tokenest facturé à un prix unitaire fixe de 0,003 $ par million de tokens en heures creuses et de 0,006 $ par million de tokens en heures pleines, identique dans toutes les régions. -
qwen3.8-max : le prix unitaire du
cached_tokenne représente pas 20 % du prix unitaire de l'input_token. Pour connaître les tarifs spécifiques, consultez la console Model Studio. - GLM (déployé sur Alibaba Cloud Model Studio) : 25 % pour glm-5.2 et glm-5.2-fast-preview, et 20 % pour tous les autres modèles de la série GLM.
-
Macaron (déployé par MindLab) : le prix unitaire du
cached_tokenne représente pas 20 % du prix unitaire de l'input_token. Pour connaître les tarifs spécifiques, consultez les pages d'informations sur les modèles (mindlab/macaron-v1-tall, mindlab/macaron-v1.1-venti, mindlab/macaron-v1.1-coding-venti) ou la console Model Studio. - Jetons sans correspondance de cache (5 000) : facturés à 100 % du prix unitaire.
- Jetons avec correspondance de cache (5 000) : facturés à 20 % du prix unitaire.
Vous pouvez obtenir le nombre de jetons avec correspondance de cache à partir de l'attribut
cached_tokensdans la réponse.Les appels effectués à l'aide de la méthode OpenAI-compatible - Batch (entrée de fichier) ne sont pas éligibles aux réductions liées au cache.
-
Pour les modèles autres que deepseek-v4.1-flash, deepseek-v4.1-flash-1017, deepseek-v4-pro, qwen3.8-max, mindlab/macaron-v1-tall, mindlab/macaron-v1.1-venti et mindlab/macaron-v1.1-coding-venti : le prix unitaire du
Exemples de correspondance de cache
- Modèles de génération de texte
- Modèles de compréhension visuelle
- Compatible OpenAI
- DashScope
- Compatible Anthropic
usage.prompt_tokens_details.cached_tokens. Cette valeur fait partie de usage.prompt_tokens.Cas d'utilisation
Si vos requêtes partagent un préfixe commun, le cache de contexte peut considérablement améliorer la vitesse d'inférence, réduire le coût d'inférence et diminuer la latence du premier paquet. Cette fonctionnalité est particulièrement utile dans les cas d'utilisation suivants :
-
Réponses aux questions sur des textes longs
Utilisez ce modèle lorsque vous envoyez plusieurs requêtes concernant le même texte long, tel qu'un roman, un manuel scolaire ou un document juridique.
Messages de la première requête
Tableau de messages des requêtes suivantesBien que les questions soient différentes, elles sont toutes basées sur le même article. L'invite système identique et le contenu de l'article constituent une grande quantité d'informations de préfixe répétitives, ce qui présente une forte probabilité de correspondance du cache.
- Saisie semi-automatique de code Dans les scénarios de saisie semi-automatique de code, le modèle utilise le code environnant comme contexte pour générer le code suivant. Au fur et à mesure que vous écrivez, le début du fichier de code reste identique. Le cache de contexte peut stocker ce préfixe pour accélérer les complétions de code.
-
Conversation multi-tours
Pour une conversation multi-tours, vous ajoutez chaque tour au tableau de messages. Cela garantit que chaque nouvelle requête partage un préfixe commun avec les tours précédents, augmentant ainsi la probabilité de correspondance du cache.
Messages du premier tour
Messages du deuxième tourÀ mesure que la conversation s'allonge, les avantages de la mise en cache en termes de vitesse d'inférence et de coût deviennent plus significatifs.
-
Jeux de rôle ou apprentissage par few-shot
Dans les scénarios de jeux de rôle ou d'apprentissage par few-shot, vous incluez souvent des instructions détaillées dans l'invite pour guider le format de sortie du modèle. Cela crée un grand préfixe partagé entre plusieurs requêtes.
Par exemple, lorsque vous demandez au modèle d'agir en tant qu'expert en marketing, l'invite système contient un texte étendu. Voici deux exemples de requêtes :
Avec le cache de contexte, le système peut répondre plus rapidement car l'invite système volumineuse est mise en cache, même lorsque vous modifiez fréquemment le produit dans votre requête (par exemple, d'une montre connectée à un ordinateur portable).
-
Compréhension vidéo
Dans les scénarios de compréhension vidéo, si vous posez plusieurs questions sur la même vidéo, placer
videoavanttextaugmente la probabilité de correspondance du cache. Si vous posez la même question sur différentes vidéos, placertextavantvideoaugmente la probabilité de correspondance du cache. L'exemple suivant montre deux requêtes pour la même vidéo :
FAQ
Q : Quelle est la durée de conservation (période de validité) du cache de contexte ?
R : La période de validité du cache de contexte dépend du type de cache :
- Explicit cache : la période de validité est de 5 minutes, et chaque correspondance la réinitialise à 5 minutes supplémentaires. Si le bloc de cache n'est pas atteint dans les 5 minutes, le système l'efface automatiquement.
- Implicit cache : géré automatiquement par le système sans période de validité fixe. Le système efface périodiquement les données de cache qui n'ont pas été utilisées depuis longtemps.
Q : Comment désactiver le Implicit cache ?
R : Vous ne pouvez pas le désactiver. Le Implicit cache est activé pour toutes les requêtes de modèles applicables, car il n'affecte pas la qualité de la réponse. Lorsqu'une correspondance se produit, il réduit les coûts et améliore la vitesse de réponse.
Q : Pourquoi mon Explicit cache n'a-t-il pas correspondu ?
R : Une absence de correspondance peut se produire pour les raisons suivantes :
- Le système efface le bloc de cache s'il n'est pas atteint dans sa période de validité de 5 minutes.
- Si l'intervalle entre le dernier
contentet un bloc de cache existant est supérieur à 20 blocscontent, aucune correspondance ne se produira. Nous vous recommandons de créer un nouveau bloc de cache.
Q : Une correspondance de cache réinitialise-t-elle sa validité ?
R : Oui. Chaque correspondance réinitialise la période de validité du bloc de cache à 5 minutes.
Q : Le Explicit cache est-il partagé entre les comptes ?
R : Non. Les données du Implicit cache et du Explicit cache sont isolées au niveau du compte.
Q :Le Explicit cache est-il partagé entre les modèles ?
R : Non. Les données de cache sont isolées entre les modèles.
Q : Pourquoiinput_tokensdansusagen'est-il pas égal à la somme decache_creation_input_tokensetcached_tokens?
R : Pour garantir la qualité de la sortie du modèle, le service backend ajoute un petit nombre de jetons (généralement 10 ou moins) à votre invite. Ces jetons sont placés après le marqueur cache_control, de sorte qu'ils ne sont pas comptabilisés pour la création ou la lecture du cache, mais sont inclus dans le total des input_tokens.