Cache explicite réservé aux modèles de la série Qwen4. Utilisez le cache automatique ou les points de rupture de cache pour désigner le préfixe d'entrée à réutiliser, et définissez une durée de vie de 5 minutes ou 1 heure afin de réduire les calculs répétés, la latence et les coûts d'entrée.
Dans des scénarios tels que les conversations à plusieurs tours, les questions-réponses sur des documents volumineux et les agents, les requêtes successives partagent souvent une grande quantité de contenu initial, comme le prompt système, les descriptions d'outils ou les documents de référence. Avec le cache explicite (Qwen4), les requêtes suivantes pendant la période de validité peuvent lire ce contenu directement depuis le cache au lieu de le recalculer, ce qui réduit la latence des réponses et les coûts d'entrée.
Le cache explicite utilise des points de rupture de cache pour désigner le préfixe de contenu à réutiliser, et les succès de cache sont déterministes : tant que le préfixe est identique et reste dans la période de validité, les requêtes suivantes peuvent lire le cache. Le cache implicite, qui identifie automatiquement les préfixes communs, ne garantit pas les succès de cache.
Qwen4 ajoute le cache automatique et le TTL du cache à l'utilisation de base. Pour plus d'informations, consultez Utilisation avancée.
Le cache est créé et lu par point de rupture. Avec le cache automatique, le système place un point de rupture à la fin de l'entrée. Avec les points de rupture de cache, vous les marquez sur les blocs de contenu. Le préfixe de cache de chaque point de rupture correspond à toute l'entrée depuis le début de la requête jusqu'à la fin du bloc de contenu qui contient ce point de rupture.
Lorsqu'une requête est reçue, le système utilise chaque point de rupture comme point de fin, remonte jusqu'à 20 blocs de contenu et sélectionne le plus long préfixe identique déjà en cache :
Définissez un point de rupture de cache sur le bloc de contenu à réutiliser. Le système utilise la fin de ce bloc de contenu comme point de rupture et traite toute l'entrée depuis le début de la requête jusqu'à ce point comme préfixe de cache : la première requête crée le cache, et les requêtes suivantes avec le même préfixe pendant la période de validité le liront. Le préfixe de cache doit contenir au moins 1 024 jetons.
Si le prompt se compose de plusieurs parties qui changent à des fréquences différentes, vous pouvez définir un point de rupture pour chaque partie. Par exemple, un prompt de service client comprend généralement le persona système (qui change rarement), les résultats de récupération de la base de connaissances (qui changent selon le sujet de la question) et l'historique de la conversation (qui ne cesse de s'allonger). En définissant un point de rupture à la fin de chaque partie, le persona système peut toujours produire des succès de cache même lorsque le contenu de la base de connaissances change.
Chaque requête conserve au maximum les 4 derniers points de rupture valides. Les points de rupture supplémentaires n'ont aucun effet. Lorsque le cache automatique est activé, le point de rupture automatique occupe l'un de ces 4 emplacements.
Le système ne crée ou ne renouvelle les points de rupture que dans la requête actuelle. Une fois le point de rupture déplacé, la période de validité du point de rupture précédent n'est pas prolongée, même si son cache est lu.
Par exemple, avec le même TTL, le point de rupture de la requête précédente se trouve au jeton 2 048 et la requête actuelle le déplace au jeton 3 072 sans conserver le point de rupture précédent. Si le point de rupture précédent se trouve dans la portée de recherche et n'a pas encore expiré, la requête actuelle lit les 2 048 premiers jetons depuis le cache et met en cache les 1 024 jetons suivants. Le système ne crée ou ne renouvelle que le point de rupture au jeton 3 072. Le cache au jeton 2 048 n'est pas renouvelé.
Qwen4 ajoute les deux fonctionnalités suivantes à l'utilisation de base. Vous pouvez les combiner :
Avec le cache automatique, le système place automatiquement un point de rupture à la fin de l'entrée de chaque requête, de sorte que vous n'avez pas besoin de déplacer le point de rupture à mesure que la conversation s'allonge. Le point de rupture automatique n'inclut pas le suffixe de modèle utilisé pour démarrer la génération de la réponse. Le cache automatique peut être utilisé avec les points de rupture de cache décrits dans Utilisation de base. Si un point de rupture manuel se trouve déjà à la fin de l'entrée, le point de rupture n'est pas placé deux fois.
L'exemple complet suivant active le cache automatique et envoie deux fois la même requête sur le document volumineux : la première requête crée le cache et la seconde le lit.
La sortie est similaire à la suivante. Le nombre réel de jetons dépend de la longueur du document :
L'entrée de la deuxième requête est identique à celle de la première, la deuxième requête lit donc le cache créé par la première.
La durée de vie du cache (TTL) peut être
Pour la première requête, ou après l'expiration du cache, le cache est créé avec le TTL de la requête actuelle. Lorsqu'une requête produit un succès sur un cache valide, le renouvellement et la facturation suivent les règles ci-dessous :
L'exemple ci-dessus suppose des requêtes séquentielles avec le même préfixe. Lorsque plusieurs requêtes écrivent dans le même cache en même temps, elles peuvent s'écraser mutuellement, et la conservation de la dernière date d'expiration n'est pas garantie.
Le champ
Les points de rupture de cache n'affectent que la facturation des jetons d'entrée. Les jetons de sortie sont facturés au tarif standard.
Si le préfixe de cache de la requête actuelle contient un cache valide existant, la partie existante est facturée comme une lecture de cache et seule la nouvelle partie est facturée comme une écriture de cache. Pour la facturation lors du passage du TTL de 5m à 1h, consultez Règles de renouvellement.
Oui. Sans paramètre de cache, le cache implicite est utilisé. Le système identifie automatiquement les préfixes communs, mais les succès de cache ne sont pas garantis. Pour produire des succès de cache de manière fiable, définissez des points de rupture de cache ou activez le cache automatique.
Le TTL ne s'applique qu'au cache explicite. Si vous ne définissez que
Non. La nouvelle date d'expiration est la plus tardive entre l'expiration d'origine et le renouvellement de la requête actuelle, et le cache conserve le niveau 1h. Pour plus d'informations, consultez Règles de renouvellement.
Cette page décrit la version Qwen4 du cache explicite existant : l'utilisation des points de rupture sur les blocs de contenu reste inchangée, avec l'ajout du cache automatique et du TTL du cache. Sa relation avec les deux modes de cache de Context Cache :
- Cache explicite : utilisez des points de rupture de cache pour désigner le préfixe d'entrée, avec des succès de cache déterministes. C'est l'objet de cette page.
- Cache implicite : lorsqu'aucun paramètre de cache n'est défini, les préfixes communs sont identifiés automatiquement et les succès de cache ne sont pas garantis. Pour plus d'informations, consultez Cache implicite.
- Le marqueur de bloc de contenu
cache_controlde l'API Chat Completions compatible OpenAI reste pris en charge et s'utilise commeprompt_cache_breakpoint. Pour plus d'informations, consultez Utilisation de base.
Fonctionnement
Le cache est créé et lu par point de rupture. Avec le cache automatique, le système place un point de rupture à la fin de l'entrée. Avec les points de rupture de cache, vous les marquez sur les blocs de contenu. Le préfixe de cache de chaque point de rupture correspond à toute l'entrée depuis le début de la requête jusqu'à la fin du bloc de contenu qui contient ce point de rupture.
Lorsqu'une requête est reçue, le système utilise chaque point de rupture comme point de fin, remonte jusqu'à 20 blocs de contenu et sélectionne le plus long préfixe identique déjà en cache :
- Succès de cache : le préfixe en cache est lu et sa durée est prolongée selon le TTL de la requête actuelle.
- Échec de cache : le contenu depuis le début de la requête jusqu'au point de rupture est créé comme nouveau cache. Si une partie du préfixe a déjà produit un succès de cache, seule la nouvelle partie est mise en cache.
Utilisation de base
Définissez un point de rupture de cache sur le bloc de contenu à réutiliser. Le système utilise la fin de ce bloc de contenu comme point de rupture et traite toute l'entrée depuis le début de la requête jusqu'à ce point comme préfixe de cache : la première requête crée le cache, et les requêtes suivantes avec le même préfixe pendant la période de validité le liront. Le préfixe de cache doit contenir au moins 1 024 jetons.
- Compatible OpenAI Chat Completions
- Compatible OpenAI Responses
- Compatible Anthropic
Ajoutez Le marqueur de bloc de contenu existant Dans la deuxième requête,
prompt_cache_breakpoint avec la valeur {"mode": "explicit"} au bloc de contenu à mettre en cache dans messages. Le content du message contenant le point de rupture doit être un tableau :"cache_control": {"type": "ephemeral"} reste pris en charge et s'utilise comme prompt_cache_breakpoint. Pour un même utilisateur, le cache ayant le même préfixe peut être réutilisé entre ces deux marqueurs. Pour les nouvelles intégrations, nous recommandons prompt_cache_breakpoint.L'exemple suivant envoie deux requêtes : la première crée le cache et la seconde conserve le même préfixe et ne modifie que la question pour lire le cache.Python
cached_tokens correspond au nombre de jetons lus depuis le cache et cache_write_tokens au nombre de jetons créés par cette requête. Si le préfixe ne change pas, cache_write_tokens vaut 0. Ces valeurs sont indicatives et les valeurs réelles dépendent de la longueur du document.Utiliser plusieurs points de rupture
Si le prompt se compose de plusieurs parties qui changent à des fréquences différentes, vous pouvez définir un point de rupture pour chaque partie. Par exemple, un prompt de service client comprend généralement le persona système (qui change rarement), les résultats de récupération de la base de connaissances (qui changent selon le sujet de la question) et l'historique de la conversation (qui ne cesse de s'allonger). En définissant un point de rupture à la fin de chaque partie, le persona système peut toujours produire des succès de cache même lorsque le contenu de la base de connaissances change.
Chaque requête conserve au maximum les 4 derniers points de rupture valides. Les points de rupture supplémentaires n'ont aucun effet. Lorsque le cache automatique est activé, le point de rupture automatique occupe l'un de ces 4 emplacements.
Renouvellement lors du déplacement du point de rupture
Le système ne crée ou ne renouvelle les points de rupture que dans la requête actuelle. Une fois le point de rupture déplacé, la période de validité du point de rupture précédent n'est pas prolongée, même si son cache est lu.
Par exemple, avec le même TTL, le point de rupture de la requête précédente se trouve au jeton 2 048 et la requête actuelle le déplace au jeton 3 072 sans conserver le point de rupture précédent. Si le point de rupture précédent se trouve dans la portée de recherche et n'a pas encore expiré, la requête actuelle lit les 2 048 premiers jetons depuis le cache et met en cache les 1 024 jetons suivants. Le système ne crée ou ne renouvelle que le point de rupture au jeton 3 072. Le cache au jeton 2 048 n'est pas renouvelé.
Utilisation avancée
Qwen4 ajoute les deux fonctionnalités suivantes à l'utilisation de base. Vous pouvez les combiner :
- Cache automatique : le système place automatiquement un point de rupture à la fin de l'entrée, adapté aux conversations à plusieurs tours.
- TTL du cache : choisissez 5 minutes ou 1 heure.
Cache automatique
Avec le cache automatique, le système place automatiquement un point de rupture à la fin de l'entrée de chaque requête, de sorte que vous n'avez pas besoin de déplacer le point de rupture à mesure que la conversation s'allonge. Le point de rupture automatique n'inclut pas le suffixe de modèle utilisé pour démarrer la génération de la réponse. Le cache automatique peut être utilisé avec les points de rupture de cache décrits dans Utilisation de base. Si un point de rupture manuel se trouve déjà à la fin de l'entrée, le point de rupture n'est pas placé deux fois.
- Compatible OpenAI Chat Completions
- Compatible OpenAI Responses
- Compatible Anthropic
Définissez Les valeurs de
prompt_cache_options au niveau supérieur de la requête et réglez mode sur implicit. Avec le SDK Python OpenAI, transmettez-le via extra_body :prompt_cache_options.mode et leur comportement sont les suivants :| Paramètre | Point de rupture automatique | Comportement du cache |
|---|---|---|
mode vaut implicit | Placé | Le point de rupture automatique en fin d'entrée et les points de rupture manuels prennent tous deux effet |
mode vaut explicit avec des points de rupture manuels | Non placé | Crée ou lit le cache aux points de rupture manuels |
mode vaut explicit sans point de rupture manuel | Non placé | Utilise le cache implicite |
prompt_cache_options est omis, vaut null ou {}, ou seul ttl est défini | Non placé | Met en cache aux points de rupture manuels s'ils existent ; sinon, utilise le cache implicite |
Lorsque
mode vaut implicit, le cache du point de rupture automatique est utilisé et suit les règles de TTL et de facturation de cette page. Cela diffère du cache implicite utilisé lorsqu'aucun paramètre de cache n'est défini. Définir mode sur explicit signifie uniquement qu'aucun point de rupture automatique n'est placé. Cela ne désactive pas le cache implicite. mode ne s'applique qu'à la requête actuelle.- Compatible OpenAI Chat Completions
- Compatible OpenAI Responses
- Compatible Anthropic
Définir le TTL du cache
La durée de vie du cache (TTL) peut être 5m (5 minutes) ou 1h (1 heure). La valeur par défaut est 5m. Lorsque le cache produit un succès pendant la période de validité, il est automatiquement renouvelé. Pour plus d'informations, consultez Règles de renouvellement.
- Compatible OpenAI Chat Completions
- Compatible OpenAI Responses
- Compatible Anthropic
Définissez-la dans Si
prompt_cache_options.ttl au niveau supérieur de la requête. La valeur s'applique à tous les points de rupture de la requête :prompt_cache_options.ttl n'est pas défini, le ttl du dernier marqueur cache_control de la requête est utilisé. Si ce marqueur n'a pas de ttl, ou si la requête ne contient aucun marqueur cache_control, le TTL est 5m.Le TTL ne s'applique qu'au cache explicite. Lorsque vous définissez ttl, définissez également des points de rupture de cache ou activez le cache automatique.Règles de renouvellement
Pour la première requête, ou après l'expiration du cache, le cache est créé avec le TTL de la requête actuelle. Lorsqu'une requête produit un succès sur un cache valide, le renouvellement et la facturation suivent les règles ci-dessous :
- La date d'expiration la plus tardive est conservée, ainsi que le niveau le plus élevé. La nouvelle date d'expiration correspond approximativement à la plus tardive entre la date d'expiration d'origine et l'heure de début du traitement du cache de la requête actuelle plus le TTL actuel. Par exemple, une requête à 12:03 qui produit un succès sur un cache de 5m expirant à 12:05 repousse l'expiration à environ 12:08. Autre exemple : lorsqu'une requête de 5m produit un succès sur un cache de 1h valide, le renouvellement est calculé sur la base de 5m, mais le cache conserve le niveau 1h, et les requêtes de 1h suivantes pendant la période de validité sont toujours facturées comme des lectures de cache.
- Lors du passage de 5m à 1h, la partie mise à niveau est facturée comme une création de cache de 1h. Lorsqu'une requête de 1h produit un succès sur un cache de 5m valide, la partie ayant produit le succès est recréée avec un TTL de 1h et n'est plus facturée comme une lecture. Si une partie du préfixe dispose déjà d'un cache de 1h valide, cette partie reste facturée comme une lecture, et seules la partie restante et le nouveau préfixe sont facturés comme une création. Dans tous les autres cas (une requête de 5m produit un succès sur un cache de 5m, une requête de 5m produit un succès sur un cache de 1h, ou une requête de 1h produit un succès sur un cache de 1h), la partie ayant produit le succès est facturée comme une lecture.
| Requête | TTL de cette requête | Expiration avant la requête | Expiration après la requête (approximative) | Facturation et niveau |
|---|---|---|---|---|
| Envoyée à 12:20 | 5m | 13:00 | 13:00 | Lecture de cache. 12:25 est antérieur à l'expiration d'origine, l'expiration reste donc inchangée. Elle n'est ni raccourcie ni repoussée à 13:20. |
| Envoyée à 12:58 | 5m | 13:00 | 13:03 | Lecture de cache. L'expiration est repoussée à 5 minutes après le début de cette requête, et le cache conserve le niveau 1h. |
| Envoyée à 13:01 | 1h | 13:03 | 14:01 | Lecture de cache. Le cache est déjà au niveau 1h, il n'y a donc pas de création due à la mise à niveau. |
Consulter l'utilisation du cache
Le champ usage de la réponse indique le nombre de jetons lus depuis le cache et écrits dans le cache. Pour une sortie en streaming avec l'API Chat Completions compatible OpenAI, définissez stream_options sur {"include_usage": true} et lisez l'utilisation dans le dernier fragment contenant usage.
- Compatible OpenAI Chat Completions
- Compatible OpenAI Responses
- Compatible Anthropic
Voici le champ
Dans l'exemple ci-dessus, l'entrée qui n'utilise pas le cache est de 2 304 − 0 − 2 048 = 256 jetons. Tous les champs de cache sont des nombres bruts de jetons et n'incluent pas les multiplicateurs de facturation. Si vous envoyez à nouveau une requête avec le même préfixe pendant la période de validité,
usage lors de la première création du cache (entrée texte uniquement, mode sans thinking) :| Champ | Description |
|---|---|
prompt_tokens | Nombre total de jetons d'entrée, y compris la lecture du cache, l'écriture dans le cache et l'entrée qui n'utilise pas le cache. Non réduit par les succès de cache. |
total_tokens | Somme de prompt_tokens et completion_tokens |
prompt_tokens_details.cached_tokens | Nombre de jetons lus depuis le cache |
prompt_tokens_details.cache_write_tokens | Nombre de jetons écrits dans le cache |
prompt_tokens_details.cache_creation_input_tokens | Nombre de jetons écrits dans le cache. Égal à cache_write_tokens. Ne les additionnez pas. |
prompt_tokens_details.cache_type | Type de cache explicite. Toujours ephemeral. |
prompt_tokens_details.cache_creation | Nombre de jetons écrits dans le cache par TTL. La somme de ephemeral_5m_input_tokens et ephemeral_1h_input_tokens est égale au nombre de jetons écrits dans le cache. |
cached_tokens vaut 2 048, cache_write_tokens, cache_creation_input_tokens et les deux éléments de cache_creation valent 0, et prompt_tokens reste à 2 304.Les détails d'entrée pour les images, l'audio et la vidéo sont renvoyés selon l'entrée réelle. Les détails de sortie, comme le thinking, sont renvoyés selon le modèle et la configuration. Les champs non applicables sont omis plutôt que renvoyés avec la valeur 0.Bonnes pratiques
- Utilisez le cache automatique pour les conversations à plusieurs tours. Le point de rupture automatique avance à mesure que la conversation s'allonge, vous n'avez donc pas à ajuster les points de rupture à chaque tour.
- Placez le contenu fixe au début. Placez le contenu qui ne change pas, comme le prompt système, les définitions d'outils et les documents de référence, au début de l'entrée. Placez le contenu qui change à chaque requête, comme les horodatages et les questions de l'utilisateur, à la fin.
- Placez le point de rupture sur le dernier bloc de contenu identique dans toutes les requêtes. Ne placez pas le point de rupture sur un bloc de contenu qui change à chaque requête. Sinon, chaque requête créera un nouveau cache sans jamais le lire.
- Ajoutez à l'historique, ne le réécrivez pas. La modification, la suppression ou la réorganisation de messages précédents ou de définitions d'outils empêche les caches suivants de produire des succès.
- Utilisez plusieurs points de rupture pour les contenus qui changent à des fréquences différentes. Par exemple, si les définitions d'outils changent rarement mais que les documents de référence sont mis à jour quotidiennement, définissez un point de rupture à la fin de chacun.
- Ajoutez un point de rupture lorsqu'un tour ajoute de nombreux blocs de contenu. Chaque point de rupture remonte jusqu'à 20 blocs de contenu. Si un tour ajoute du contenu au-delà de cette portée, ajoutez un point de rupture au milieu.
- Choisissez le TTL selon l'intervalle de réutilisation. Utilisez
5msi le contenu est réutilisé dans les 5 minutes, car chaque succès renouvelle le cache. Utilisez1hsi l'intervalle de réutilisation se situe entre 5 minutes et 1 heure. - Surveillez les succès de cache à l'aide des champs d'utilisation. Le taux de succès est le nombre de jetons lus depuis le cache divisé par le nombre total de jetons d'entrée. Si le taux de succès est faible, vérifiez la stabilité de la position du préfixe et des points de rupture.
Facturation
Les points de rupture de cache n'affectent que la facturation des jetons d'entrée. Les jetons de sortie sont facturés au tarif standard.
| Type de jeton d'entrée | Facturation |
|---|---|
| Écriture de cache, TTL de 5m | Environ 125 % du prix du jeton d'entrée |
| Écriture de cache, TTL de 1h | Environ 200 % du prix du jeton d'entrée |
| Lecture de cache | Qwen4-Max |
| Non lu depuis le cache et non écrit dans le cache | Prix du jeton d'entrée |
Limites
- Seuls les modèles de la série Qwen4 sont pris en charge.
- Le préfixe doit contenir au moins 1 024 tokens. Un préfixe plus court ne crée aucun cache ; la requête réussit et les détails de création par TTL sont omis.
- Chaque requête conserve au maximum les 4 derniers points de rupture valides. Lorsque le cache automatique est activé, le point de rupture automatique occupe l'un d'eux.
- En utilisant chaque point de rupture comme point de fin, le système remonte jusqu'à 20 blocs de contenu. Si le cache à atteindre se trouve à plus de 20 blocs de contenu du point de rupture, il ne peut pas être atteint.
- Le TTL ne peut être que
5mou1h.
FAQ
Q : Une requête peut-elle produire un succès de cache sans aucun paramètre de cache ?
Oui. Sans paramètre de cache, le cache implicite est utilisé. Le système identifie automatiquement les préfixes communs, mais les succès de cache ne sont pas garantis. Pour produire des succès de cache de manière fiable, définissez des points de rupture de cache ou activez le cache automatique.
Q : Pourquoi la période de validité du cache ne change-t-elle pas lorsque je ne définis que le TTL ?
Le TTL ne s'applique qu'au cache explicite. Si vous ne définissez que prompt_cache_options.ttl dans l'API Chat Completions compatible OpenAI, la requête utilise le cache implicite. Ajoutez également des points de rupture manuels ou définissez prompt_cache_options.mode sur implicit.