Alibaba Cloud Model Studio:Context Cache

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.

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.

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.

L'exemple suivant illustre ce fonctionnement :

1. 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 :

   [{"role": "system", "content": [{"type": "text", "text": A, "cache_control": {"type": "ephemeral"}}]}]
   

   Le système crée le premier bloc de cache, appelé bloc de cache A.

2. Envoyez la deuxième requête : envoyez une requête avec la structure suivante :

   [
       {"role": "system", "content": A},
       <Other messages>
       {"role": "user","content": [{"type": "text", "text": B, "cache_control": {"type": "ephemeral"}}]}
   ]
   

   • 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

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.

from openai import OpenAI
import os

client = OpenAI(
    # If the environment variable is not set, replace the following line with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # If you use a model in China (Beijing), replace the base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Mock code repository content. The minimum cacheable prompt length is 1,024 tokens.
long_text_content = "<Your Code Here>" * 400

# Function to make a request
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Place the cache_control marker here. This creates a cache block containing all content from the start of the messages array up to this point.
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # The user's question is different for each request.
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # Select a model that supports explicit cache.
        model="qwen3.8-max",
        messages=messages,
    )
    return completion

# First request
first_completion = get_completion("What is the content of this code?")
print(f"First request cache creation tokens: {first_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"First request cached tokens: {first_completion.usage.prompt_tokens_details.cached_tokens}")
print("=" * 20)
# Second request. The code content is the same, but the question is different.
second_completion = get_completion("How can this code be optimized?")
print(f"Second request cache creation tokens: {second_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Second request cached tokens: {second_completion.usage.prompt_tokens_details.cached_tokens}")

import os
from dashscope import MultiModalConversation
# The following URL is for Singapore. Replace {WorkspaceId} with your workspace ID. The URL varies by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

# Mock code repository content. The minimum cacheable prompt length is 1,024 tokens.
long_text_content = "<Your Code Here>" * 400

# Function to make a request
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Place the cache_control marker here. This creates a cache block containing all content from the start of the messages array up to this point.
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # The user's question is different for each request.
        {
            "role": "user",
            "content": [{"text": user_input}],
        },
    ]
    response = MultiModalConversation.call(
        # If the environment variable is not set, use your Model Studio API key directly: api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        model="qwen3.8-max",
        messages=messages,
    )
    return response

# First request
first_completion = get_completion("What is the content of this code?")
print(f"First request cache creation tokens: {first_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"First request cached tokens: {first_completion.usage.prompt_tokens_details['cached_tokens']}")
print("=" * 20)
# Second request. The code content is the same, but the question is different.
second_completion = get_completion("How can this code be optimized?")
print(f"Second request cache creation tokens: {second_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"Second request cached tokens: {second_completion.usage.prompt_tokens_details['cached_tokens']}")

// Minimum Java SDK version: 2.21.6
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.MessageContentText;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;

import java.util.Arrays;
import java.util.Collections;

public class Main {
    private static final String MODEL = "qwen3-coder-plus";
    // Mock code repository content (repeated 400 times to ensure it exceeds 1,024 tokens).
    private static final String LONG_TEXT_CONTENT = generateLongText(400);
    private static String generateLongText(int repeatCount) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < repeatCount; i++) {
            sb.append("<Your Code Here>");
        }
        return sb.toString();
    }
    private static GenerationResult getCompletion(String userQuestion)
            throws NoApiKeyException, ApiException, InputRequiredException {
        // The following URL is for Singapore. Replace {WorkspaceId} with your workspace ID. The URL varies by region.
        Generation gen = new Generation("http", "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1");

        // Build the system message with cache control.
        MessageContentText systemContent = MessageContentText.builder()
                .type("text")
                .text(LONG_TEXT_CONTENT)
                .cacheControl(MessageContentText.CacheControl.builder()
                        .type("ephemeral") // Set the cache type.
                        .build())
                .build();

        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .contents(Collections.singletonList(systemContent))
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content(userQuestion)
                .build();

        // Build the request parameters.
        GenerationParam param = GenerationParam.builder()
                .model(MODEL)
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();
        return gen.call(param);
    }

    private static void printCacheInfo(GenerationResult result, String requestLabel) {
        System.out.printf("%s cache creation tokens: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCacheCreationInputTokens());
        System.out.printf("%s cached tokens: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCachedTokens());
    }

    public static void main(String[] args) {
        try {
            // First request
            GenerationResult firstResult = getCompletion("What is the content of this code?");
            printCacheInfo(firstResult, "First request");
            System.out.println(new String(new char[20]).replace('\0', '='));            // Second request
            GenerationResult secondResult = getCompletion("How can this code be optimized?");
            printCacheInfo(secondResult, "Second request");
        } catch (NoApiKeyException | ApiException | InputRequiredException e) {
            System.err.println("API call failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

import anthropic
import os

api_key = os.getenv("DASHSCOPE_API_KEY")
client = anthropic.Anthropic(
    # If the environment variable is not set, replace the following line with: api_key="sk-xxx"
    api_key=api_key,
    # If you use a model in China (Beijing), replace the base_url with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
    default_headers={"Authorization": f"Bearer {api_key}"},
)

# Mock code repository content. The minimum cacheable prompt length is 1,024 tokens.
long_text_content = "<Your Code Here>" * 400

# Function to make a request
def get_completion(user_input):
    response = client.messages.create(
        # Select a model that supports explicit cache.
        model="qwen3.8-max",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": long_text_content,
                # Place the cache_control marker here to create a cache block from the system text content. This marker can also be placed in `messages`.
                "cache_control": {"type": "ephemeral"},
            }
        ],
        messages=[
            # The user's question is different for each request.
            {"role": "user", "content": user_input},
        ],
    )
    return response

# First request
first_completion = get_completion("What is the content of this code?")
print(f"First request cache creation tokens: {first_completion.usage.cache_creation_input_tokens}")
print(f"First request cached tokens: {first_completion.usage.cache_read_input_tokens}")
print("=" * 20)
# Second request. The code content is the same, but the question is different.
second_completion = get_completion("How can this code be optimized?")
print(f"Second request cache creation tokens: {second_completion.usage.cache_creation_input_tokens}")
print(f"Second request cached tokens: {second_completion.usage.cache_read_input_tokens}")

L'ajout du marqueur 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.

First request cache creation tokens: 1605
First request cached tokens: 0
====================
Second request cache creation tokens: 0
Second request cached tokens: 1605

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.

Si vous mettez en cache l'intégralité de l'invite en tant qu'unité unique, toute modification mineure, telle qu'une mise à jour des connaissances externes, peut entraîner une absence de correspondance.

Vous pouvez ajouter jusqu'à quatre marqueurs de cache dans une requête pour créer des blocs de cache distincts pour différentes parties de l'invite. Cela améliore le taux de correspondance du cache et permet un contrôle granulaire.

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_tokens spé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_tokens spé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.

• 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.)

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

  RemarquePour 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 marqueur cache_control aprè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)

Par exemple, pour un message système, vous devez modifier le champ content en un tableau et ajouter le champ cache_control :

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "<your specified prompt>",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

Cette structure s'applique également aux autres types de messages dans le tableau 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_control sont séparés par plus de 20 blocs de contenu.

• Le type ne peut être défini que sur ephemeral, 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 tools doit ê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) :

# After the model returns parallel tool_calls, send each result as a separate message
messages.append(assistant_message)  # assistant message containing parallel tool_calls
# Each tool result is its own message — increases content block count by N
messages.append({"role": "tool", "tool_call_id": "call_1", "content": "result_1"})
messages.append({"role": "tool", "tool_call_id": "call_2", "content": "result_2"})

Après optimisation (message d'outil fusionné — taux de correspondance plus élevé) :

# After the model returns parallel tool_calls, merge all results into one message
messages.append(assistant_message)  # assistant message containing parallel tool_calls
# Merge all tool results into a single message with multiple content blocks
messages.append({
    "role": "tool",
    "tool_call_id": "call_1",
    "content": [
        {"type": "text", "text": "result_1"},
        {"type": "text", "text": "result_2", "tool_call_id": "call_2"},
    ],
})

Pour améliorer encore le taux de correspondance, placez les marqueurs 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

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # This is the base_url for the Singapore region. When making a call, replace {WorkspaceId} with your actual WorkspaceId. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Mock code repository content
long_text_content = "<Your Code Here>" * 400

# Function to send a request
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Place the cache_control marker here to create a cache from the start of the prompt to the end of this content object (the mock code repository content).
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # Select a model that supports explicit cache
        model="qwen3.8-max",
        messages=messages,
    )
    return completion

# First request
first_completion = get_completion("What is the content of this code?")
created_cache_tokens = first_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"First request - Cache creation tokens: {created_cache_tokens}")
hit_cached_tokens = first_completion.usage.prompt_tokens_details.cached_tokens
print(f"First request - Cache hit tokens: {hit_cached_tokens}")
print(f"First request - Uncached tokens: {first_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")
print("=" * 20)
# Second request with the same code content but a different question
second_completion = get_completion("What are some possible optimizations for this code?")
created_cache_tokens = second_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"Second request - Cache creation tokens: {created_cache_tokens}")
hit_cached_tokens = second_completion.usage.prompt_tokens_details.cached_tokens
print(f"Second request - Cache hit tokens: {hit_cached_tokens}")
print(f"Second request - Uncached tokens: {second_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")

First request - Cache creation tokens: 1605
First request - Cache hit tokens: 0
First request - Uncached tokens: 13
====================
Second request - Cache creation tokens: 0
Second request - Cache hit tokens: 1605
Second request - Uncached tokens: 15

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Mock code repository content, ensuring it exceeds the minimum 1,024-token threshold for explicit cache.
long_text_content = "<Your Code Here>" * 400

# Tool definition: Ensure it is identical for every request (tool order, field order, and field structure).
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather information for a specified city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "The city name, e.g., Beijing, Shanghai, or New York."
                    },
                    "unit": {
                        "type": "string",
                        "description": "The temperature unit, 'celsius' or 'fahrenheit'. Defaults to 'celsius'.",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["city"],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "Get the current date and time for a specified time zone.",
            "parameters": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "IANA time zone name, e.g., 'Asia/Shanghai' or 'America/New_York'. Defaults to 'Asia/Shanghai'."
                    }
                },
                "required": [],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "Convert currency amounts based on real-time exchange rates.",
            "parameters": {
                "type": "object",
                "properties": {
                    "from_currency": {
                        "type": "string",
                        "description": "The ISO 4217 code of the source currency, e.g., CNY, USD, or EUR."
                    },
                    "to_currency": {
                        "type": "string",
                        "description": "The ISO 4217 code of the target currency."
                    },
                    "amount": {
                        "type": "number",
                        "description": "The amount to be converted."
                    }
                },
                "required": ["from_currency", "to_currency", "amount"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
]

def get_completion(user_input, messages=None):
    if messages is None:
        messages = [
            {
                "role": "system",
                "content": [
                    {
                        "type": "text",
                        "text": long_text_content,
                        # Place the cache_control marker here. This creates a cache block with all content from the start of the messages array to the current content object.
                        # The cache_control marker must be on the 'content' of a message, not on 'tools'.
                        "cache_control": {"type": "ephemeral"},
                    }
                ],
            }
        ]

    messages.append({"role": "user", "content": user_input})

    completion = client.chat.completions.create(
        # Select a model that supports explicit cache
        model="qwen3.7-plus",
        messages=messages,
        tools=tools,
        # Disable thinking mode
        extra_body={"enable_thinking": False},
    )
    return completion

# First request: Create cache
print("=== First request (Create cache) ===")
first_completion = get_completion("What's the weather like in Beijing now?")
usage = first_completion.usage
print(f"Prompt Tokens: {usage.prompt_tokens}")
print(f"Cache creation tokens: {usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Cache hit tokens: {usage.prompt_tokens_details.cached_tokens}")
print(f"Model selected tool(s): {[t.function.name for t in first_completion.choices[0].message.tool_calls or []]}")
print()

# Second request: Hits the cache with the same system message but a different question
print("=== Second request (Cache hit) ===")
messages = [
    {
        "role": "system",
        "content": [
            {
                "type": "text",
                "text": long_text_content,
                "cache_control": {"type": "ephemeral"},
            }
        ],
    }
]
second_completion = get_completion("What's the weather like in Shanghai now?", messages=messages)
usage = second_completion.usage
print(f"Prompt Tokens: {usage.prompt_tokens}")
print(f"Cache creation tokens: {usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Cache hit tokens: {usage.prompt_tokens_details.cached_tokens}")
print(f"Model selected tool(s): {[t.function.name for t in second_completion.choices[0].message.tool_calls or []]}")

=== First request (Create cache) ===
 Prompt Tokens: 2174
 Cache creation tokens: 2156
 Cache hit tokens: 0
 Model selected tool(s): ['get_weather']

 === Second request (Cache hit) ===
 Prompt Tokens: 2174
 Cache creation tokens: 0
 Cache hit tokens: 2156
 Model selected tool(s): ['get_weather']

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # This is the base_url for the Singapore region. When making a call, replace {WorkspaceId} with your actual WorkspaceId. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

system_prompt = "You are a witty person." * 400
messages = [{"role": "system", "content": system_prompt}]

def get_completion(messages):
    completion = client.chat.completions.create(
        model="qwen3.8-max",
        messages=messages,
    )
    return completion

while True:
    user_input = input("User: ")
    messages.append({"role": "user", "content": [{"type": "text", "text": user_input, "cache_control": {"type": "ephemeral"}}]})
    completion = get_completion(messages)
    print(f"[AI Response] {completion.choices[0].message.content}")
    messages.append(completion.choices[0].message)
    created_cache_tokens = completion.usage.prompt_tokens_details.cache_creation_input_tokens
    hit_cached_tokens = completion.usage.prompt_tokens_details.cached_tokens
    uncached_tokens = completion.usage.prompt_tokens - created_cache_tokens - hit_cached_tokens
    print(f"[Cache Info] Cache creation tokens: {created_cache_tokens}")
    print(f"[Cache Info] Cache hit tokens: {hit_cached_tokens}")
    print(f"[Cache Info] Uncached tokens: {uncached_tokens}")

Implicit cache

Modèles pris en charge

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 :

1. 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 messages de la requête.

2. 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-pro et qwen3.8-max : le prix unitaire du cached_token représente 20 % du prix unitaire de l'input_token.

  • deepseek-v4-pro : le prix unitaire du cached_token ne représente pas 20 % du prix unitaire de l'input_token. Pour connaître les tarifs spécifiques, consultez la console Model Studio.

  • qwen3.8-max : le prix unitaire du cached_token ne 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.

  • 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.

  Le coût total des entrées représente 60 % du coût en mode sans cache : (50 % × 100 %) + (50 % × 20 %) = 60 %.

  

  Vous pouvez obtenir le nombre de jetons avec correspondance de cache à partir de l'attribut cached_tokens dans 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.

Exemples de correspondance de cache

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "I am a large-scale language model developed by Alibaba Cloud. My name is Qwen."
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 3019,
        "completion_tokens": 104,
        "total_tokens": 3123,
        "prompt_tokens_details": {
            "cached_tokens": 2048
        }
    },
    "created": 1735120033,
    "system_fingerprint": null,
    "model": "qwen-plus",
    "id": "chatcmpl-6ada9ed2-7f33-9de2-8bb0-78bd4035025a"
}

{
    "status_code": 200,
    "request_id": "f3acaa33-e248-97bb-96d5-cbeed34699e1",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "I am a large language model from Alibaba Cloud. My name is Qwen. I can generate various types of text, such as articles, stories, and poems, and can adapt them based on different scenarios and requirements. Additionally, I can answer various questions and provide help and solutions. If you have any questions or need assistance, feel free to ask, and I will do my best to provide support. Please note that repeating the same content may not yield a more detailed response. We recommend providing more specific information or varying your questions so I can better understand your needs."
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 3019,
        "output_tokens": 101,
        "prompt_tokens_details": {
            "cached_tokens": 2048
        },
        "total_tokens": 3120
    }
}

{
    "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
    "type": "message",
    "role": "assistant",
    "content": [
        {
            "type": "text",
            "text": "This content is repeated placeholder text."
        }
    ],
    "model": "qwen3.7-max",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 82,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 1536,
        "output_tokens": 14
    }
}

{
  "id": "chatcmpl-3f3bf7d0-b168-9637-a245-dd0f946c700f",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "This image shows a heartwarming scene of a woman and a dog interacting on a beach. The woman, wearing a plaid shirt, is sitting on the sand and smiling as she interacts with the dog. The dog is a large, light-colored breed wearing a colorful collar, with its front paw raised as if to shake hands or give a high-five to the woman. The background is a vast ocean and sky, with sunlight shining from the right side of the frame, adding a warm and serene atmosphere to the entire scene.",
        "refusal": null,
        "role": "assistant",
        "audio": null,
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1744956927,
  "model": "qwen-vl-max",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 93,
    "prompt_tokens": 1316,
    "total_tokens": 1409,
    "completion_tokens_details": null,
    "prompt_tokens_details": {
      "audio_tokens": null,
      "cached_tokens": 1152
    }
  }
}

{
  "status_code": 200,
  "request_id": "06a8f3bb-d871-9db4-857d-2c6eeac819bc",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "text": "This image shows a heartwarming scene of a woman and a dog interacting on a beach. The woman, wearing a plaid shirt, is sitting on the sand and smiling as she interacts with the dog. The dog is a large breed wearing a colorful collar, with its front paw raised as if to shake hands or give a high-five to the woman. The background is a vast ocean and sky, with sunlight shining from the right side of the frame, adding a warm and serene atmosphere to the entire scene."
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 1292,
    "output_tokens": 87,
    "input_tokens_details": {
      "text_tokens": 43,
      "image_tokens": 1249
    },
    "total_tokens": 1379,
    "output_tokens_details": {
      "text_tokens": 87
    },
    "image_tokens": 1249,
    "cached_tokens": 1152
  }
}

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows a heartwarming scene of a woman and a dog interacting on a beach."
    }
  ],
  "model": "qwen-vl-max",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 369,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 896,
    "output_tokens": 28
  }
}

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 :

1. 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

   messages = [{"role": "system","content": "You are a language teacher who can help students with reading comprehension."},
             {"role": "user","content": "
   

   Tableau de messages des requêtes suivantes

   messages = [{"role": "system","content": "You are a language arts teacher. You can help students with reading comprehension."},
             {"role": "user","content": "<Article content> Please analyze the third paragraph of this text."}]
   

   Bien 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.

2. 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.

3. 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=[{"role": "system","content": "You are a helpful assistant."},
             {"role": "user","content": "Who are you?"}]
   

   Messages du deuxième tour

   messages=[{"role": "system","content": "You are a helpful assistant."},
             {"role": "user","content": "Who are you?"},
             {"role": "assistant","content": "I am Qwen, developed by Alibaba Cloud."},
             {"role": "user","content": "What can you do?"}]
   

   À 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.

4. 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 :

   system_prompt = """You are an experienced marketing expert. Provide detailed marketing suggestions for different products in the following format:
   
   1. Target audience: xxx
   
   2. Main selling points: xxx
   
   3. Marketing channels: xxx
   ...
   12. Long-term development strategy: xxx
   
   Ensure your suggestions are specific, actionable, and highly relevant to the product features."""
   
   # The user message for the first request asks about a smartwatch.
   messages_1=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "Provide marketing suggestions for a newly launched smartwatch."}
   ]
   
   # The user message for the second request asks about a laptop. Because the system_prompt is the same, a cache hit is highly likely.
   messages_2=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "Provide marketing suggestions for a newly launched laptop."}
   ]
   

   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).

5. 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 video avant text augmente la probabilité de correspondance du cache. Si vous posez la même question sur différentes vidéos, placer text avant video augmente la probabilité de correspondance du cache. L'exemple suivant montre deux requêtes pour la même vidéo :

   # The user message for the first request asks about the content of this video.
   messages1 = [
       {"role":"system","content":[{"text": "You are a helpful assistant."}]},
       {"role": "user",
           "content": [
               {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
               {"text": "What is the content of this video?"}
           ]
       }
   ]
   
   # For the second request about the same video, placing the video before the text increases the likelihood of a cache hit.
   messages2 = [
       {"role":"system","content":[{"text": "You are a helpful assistant."}]},
       {"role": "user",
           "content": [
               {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
               {"text": "Describe the series of events in the video. Output the start time (start_time), end time (end_time), and event (event) in JSON format. Do not include the ```json``` code block."}
           ]
       }
   ]
   

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 content et un bloc de cache existant est supérieur à 20 blocs content, 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.