Skip to main content

Cache explicite (Qwen4)

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.
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_control de l'API Chat Completions compatible OpenAI reste pris en charge et s'utilise comme prompt_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.
Un succès de cache exige un préfixe entièrement identique, et le cache n'est réutilisé qu'entre les requêtes d'un même utilisateur. Pour améliorer le taux de succès, placez le contenu qui ne change pas au début et le contenu qui change à chaque requête après le point de rupture. Si aucun paramètre de cache n'est défini, le système utilise le cache implicite pour identifier automatiquement les préfixes communs, mais les succès de cache ne sont pas garantis. Pour réutiliser un contenu précis de manière fiable, activez le cache automatique ou définissez des points de rupture de 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 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 :
messages=[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": long_text,
        "prompt_cache_breakpoint": {"mode": "explicit"},  # <-- Point de rupture de cache
      },
      {"type": "text", "text": "Résumez ce document."},  # Le contenu après le point de rupture ne fait pas partie de ce cache
    ],
  }
],
Le marqueur de bloc de contenu existant "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.
N'utilisez qu'un seul des deux marqueurs prompt_cache_breakpoint et cache_control dans une même requête.
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
import os
from openai import OpenAI

client = OpenAI(
  # Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par : api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # Il s'agit de l'URL de la région de Chine (Pékin). Lors de l'appel, remplacez WorkspaceId par l'ID d'espace de travail réel. L'URL varie selon la région.
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Document volumineux à réutiliser. Le préfixe de cache doit contenir au moins 1 024 jetons.
long_text = "<Document volumineux fixe>" * 400

def ask(question):
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
      {
        "role": "user",
        "content": [
          {"type": "text", "text": long_text, "prompt_cache_breakpoint": {"mode": "explicit"}},  # <-- Point de rupture de cache
          {"type": "text", "text": question},  # Le contenu après le point de rupture peut changer à chaque requête
        ],
      }
    ],
    extra_body={
      "enable_thinking": False,
    },
  )
  return completion.usage.prompt_tokens_details

ask("Résumez ce document.")  # Première requête : crée le cache
details = ask("Citez les trois points principaux de ce document.")  # Deuxième requête : lit le cache
print(f"Cache lu : {details.cached_tokens} jetons, cache créé : {details.cache_write_tokens} jetons")
Dans la deuxième requête, 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 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 :
completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "Résumez ce document : " + long_text}],
  extra_body={
    "enable_thinking": False,
    "prompt_cache_options": {"mode": "implicit"},  # <-- Active le cache automatique
  },
)
Les valeurs de prompt_cache_options.mode et leur comportement sont les suivants :
ParamètrePoint de rupture automatiqueComportement du cache
mode vaut implicitPlacé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 manuelsNon placéCrée ou lit le cache aux points de rupture manuels
mode vaut explicit sans point de rupture manuelNon placéUtilise le cache implicite
prompt_cache_options est omis, vaut null ou {}, ou seul ttl est définiNon 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.
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.
  • Compatible OpenAI Chat Completions
  • Compatible OpenAI Responses
  • Compatible Anthropic
import os
from openai import OpenAI

client = OpenAI(
  # Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par : api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # Il s'agit de l'URL de la région de Chine (Pékin). Lors de l'appel, remplacez WorkspaceId par l'ID d'espace de travail réel. L'URL varie selon la région.
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Document volumineux à réutiliser. Le préfixe de cache doit contenir au moins 1 024 jetons.
long_text = "<Document volumineux fixe>" * 400

def ask():
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "Résumez ce document : " + long_text}],
    extra_body={
      "enable_thinking": False,
      "prompt_cache_options": {"mode": "implicit"},  # <-- Active le cache automatique
    },
  )
  return completion.usage.prompt_tokens_details

for i in range(1, 3):
  details = ask()
  print(f"Requête {i} : cache lu {details.cached_tokens} jetons, cache créé {details.cache_write_tokens} jetons")
La sortie est similaire à la suivante. Le nombre réel de jetons dépend de la longueur du document :
Requête 1 : cache lu 0 jeton, cache créé 2 048 jetons
Requête 2 : cache lu 2 048 jetons, cache créé 0 jeton
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.

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 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 :
extra_body={
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "1h",  # <-- Le TTL du cache est de 1 heure
  },
},
Si 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.
La période de validité commence au début du traitement du cache de la requête actuelle. Elle ne s'ajoute pas à la date d'expiration d'origine et n'est pas réinitialisée à la fin de la réponse. Le temps de génération de la réponse est pris en compte dans la période de validité, et la date d'expiration réelle laisse un peu de temps de traitement supplémentaire. L'exemple suivant montre des requêtes successives sur le même cache, créé avec un TTL de 1h à 12:00 et expirant initialement à 13:00 :
RequêteTTL de cette requêteExpiration avant la requêteExpiration après la requête (approximative)Facturation et niveau
Envoyée à 12:205m13:0013:00Lecture 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:585m13:0013:03Lecture 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:011h13:0314:01Lecture de cache. Le cache est déjà au niveau 1h, il n'y a donc pas de création due à la mise à niveau.
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.

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 usage lors de la première création du cache (entrée texte uniquement, mode sans thinking) :
{
  "usage": {
    "prompt_tokens": 2304,
    "completion_tokens": 128,
    "total_tokens": 2432,
    "prompt_tokens_details": {
      "text_tokens": 2304,
      "cached_tokens": 0,
      "cache_write_tokens": 2048,
      "cache_creation_input_tokens": 2048,
      "cache_type": "ephemeral",
      "cache_creation": {
        "ephemeral_5m_input_tokens": 2048,
        "ephemeral_1h_input_tokens": 0
      }
    },
    "completion_tokens_details": {}
  }
}
ChampDescription
prompt_tokensNombre 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_tokensSomme de prompt_tokens et completion_tokens
prompt_tokens_details.cached_tokensNombre de jetons lus depuis le cache
prompt_tokens_details.cache_write_tokensNombre de jetons écrits dans le cache
prompt_tokens_details.cache_creation_input_tokensNombre de jetons écrits dans le cache. Égal à cache_write_tokens. Ne les additionnez pas.
prompt_tokens_details.cache_typeType de cache explicite. Toujours ephemeral.
prompt_tokens_details.cache_creationNombre 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.
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é, 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 5m si le contenu est réutilisé dans les 5 minutes, car chaque succès renouvelle le cache. Utilisez 1h si 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éeFacturation
Écriture de cache, TTL de 5mEnviron 125 % du prix du jeton d'entrée
Écriture de cache, TTL de 1hEnviron 200 % du prix du jeton d'entrée
Lecture de cacheQwen4-Max
Non lu depuis le cache et non écrit dans le cachePrix du jeton d'entrée
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.

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 5m ou 1h.

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.

Q : Une requête de 5m qui produit un succès sur un cache de 1h raccourcit-elle la période de validité du cache ?

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.