Alibaba Cloud Model Studio:Caché de contexto

Las solicitudes de inferencia para modelos grandes a menudo contienen entradas superpuestas, como en una conversación de varios turnos o una serie de preguntas sobre el mismo libro. La Caché de Contexto reduce la computación redundante almacenando en caché el prefijo común de estas solicitudes. Esto mejora la velocidad de respuesta y reduce los costos de uso sin afectar la calidad de la respuesta.

Para admitir diferentes escenarios, la caché de contexto ofrece dos modos. Elija un modo según sus requisitos de conveniencia, determinismo y costo:

• Caché explícita: Un modo que usted habilita manualmente. Crea una caché para contenido específico para asegurar un acierto determinista dentro de su periodo de validez de 5 minutos. Los tokens utilizados para crear la caché generalmente se facturan al 125% del precio estándar de tokens de entrada, mientras que los aciertos de caché posteriores generalmente se facturan solo al 10% de ese precio. Para precios específicos, consulte Facturación.
• Caché implícita: Este modo automático no requiere configuración adicional y no se puede desactivar, siendo ideal para escenarios que priorizan la comodidad. El sistema identifica automáticamente y almacena en caché el prefijo común de las solicitudes, pero la probabilidad de acierto no está garantizada. La parte de la entrada servida desde la caché generalmente se factura al 20% del precio estándar de tokens de entrada. Para precios específicos, consulte Facturación.

Aunque el recuento mínimo de tokens es el mismo para ambos modos, el significado difiere: la caché explícita es creada y gestionada activamente por el usuario; la caché implícita es creada y gestionada automáticamente por el sistema. Alcanzar 1,024 tokens solo significa que la solicitud cumple las condiciones técnicas para un acierto de caché, pero no garantiza un acierto real.

Caché explícita

A diferencia de una caché implícita, una caché explícita requiere una creación explícita e implica sobrecarga, pero ofrece una mayor tasa de aciertos de caché y una menor latencia de acceso.

Funcionamiento

Agregue un marcador "cache_control": {"type": "ephemeral"} a la matriz de mensajes. Luego, el sistema busca hacia atrás desde cada marcador cache_control y examina hasta 20 bloques content precedentes para encontrar un acierto de caché.

Una sola solicitud admite hasta cuatro marcadores de caché.

• Fallo de caché

  Si ocurre un fallo de caché, el sistema crea un nuevo bloque de caché a partir del contenido entre el inicio de la matriz de mensajes y el marcador cache_control. El nuevo bloque de caché tiene un período de validez de 5 minutos.

  El sistema crea la caché después de que el modelo genera una respuesta. Espere a que se complete la solicitud de creación antes de intentar encontrar esa caché.

  Un bloque de caché contiene al menos 1,024 tokens.

• Acierto de caché

  Si ocurre un acierto de caché, el sistema selecciona el prefijo coincidente más largo y restablece el período de validez del bloque de caché correspondiente a 5 minutos.

El siguiente ejemplo demuestra cómo funciona esto:

1. Enviar la primera solicitud: Envíe un mensaje del sistema que contenga el texto A (más de 1,024 tokens) y agregue un marcador de caché:

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

El sistema crea el primer bloque de caché, llamándolo bloque de caché A. 2. Enviar la segunda solicitud: Envíe una solicitud con la siguiente estructura:

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

• Si hay 20 o menos "Otros mensajes", la solicitud encuentra el bloque de caché A, restableciendo su período de validez a 5 minutos. El sistema también crea un nuevo bloque de caché basado en A, los otros mensajes y B.
• Si hay más de 20 "Otros mensajes", la solicitud falla el bloque de caché A. El sistema aún crea un nuevo bloque de caché basado en el contexto completo (A, los otros mensajes y B).

Modelos admitidos

Inicio rápido

Los siguientes ejemplos demuestran los mecanismos de creación de bloques de caché y aciertos de caché para protocolos compatibles con OpenAI, DashScope y 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-flash";
    // 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}")

Agregar el marcador cache_control habilita la caché explícita para el contenido del repositorio de código simulado. Para solicitudes posteriores que consulten este contenido, el sistema reutiliza el bloque de caché, eliminando el recálculo. Esto hace que las solicitudes que aciertan en la caché sean más rápidas y económicas que la solicitud inicial de creación de caché.

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

Control detallado con múltiples marcadores de caché

En escenarios complejos, un prompt a menudo consta de múltiples partes con diferentes frecuencias de reutilización. Puede usar múltiples marcadores de caché para lograr un control detallado.

Por ejemplo, el prompt para un agente inteligente de servicio al cliente generalmente incluye:

• Persona del sistema: Altamente estable y rara vez cambia.
• Conocimiento externo: Se obtiene de la base de conocimientos o mediante consultas de herramientas y puede no cambiar durante una sola conversación.
• Historial de conversación: Crece dinámicamente.
• Pregunta actual: Diferente para cada solicitud.

Si almacena en caché todo el prompt como una sola unidad, cualquier cambio menor, como una actualización del conocimiento externo, puede provocar un fallo de caché.

Puede agregar hasta cuatro marcadores de caché en una solicitud para crear bloques de caché separados para diferentes partes del prompt. Esto mejora la tasa de aciertos de caché y permite un control detallado.

Facturación

La caché explícita solo afecta cómo se facturan los tokens de entrada. Las reglas son las siguientes:

• Creación de caché: El contenido utilizado para crear una nueva caché se factura al 125% del precio estándar de tokens de entrada. Si el contenido para una nueva caché incluye una caché existente como prefijo, solo la parte incremental se factura por creación de caché (es decir, el número de nuevos tokens de caché menos el número de tokens de caché existentes).

  Por ejemplo, si tiene una caché existente de 1,200 tokens (Caché A) y utiliza una nueva solicitud para almacenar en caché 1,500 tokens de contenido (Contenido AB), los primeros 1,200 tokens se facturan como un acierto de caché al 10% del precio estándar. Los nuevos 300 tokens se facturan por creación de caché al 125% del precio estándar.

  El parámetro cache_creation_input_tokens especifica el número de tokens utilizados para la creación de la caché.

• Acierto de caché: Se factura al 10% del precio estándar de tokens de entrada.

  El parámetro cached_tokens especifica el número de tokens almacenados en caché.

• Otros tokens: Los tokens que ni son un acierto de caché ni se utilizan para la creación de caché se facturan al precio estándar de tokens de entrada.

• Excepción: El precio de acierto de caché explícita para qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash y qwen3.8-2.4t-a95b no es 10% del precio estándar de tokens de entrada. Para precios específicos, consulte la consola de Model Studio.

Contenido almacenable en caché

Solo los siguientes tipos de mensajes en la matriz messages admiten la adición de marcadores de caché:

• Mensaje del sistema

  NotaPara la llamada de funciones, si una solicitud incluye el parámetro tools, la definición de la herramienta se incluye en el mensaje del sistema para el cálculo de la caché. Las definiciones de herramientas no se pueden almacenar en caché de forma independiente. Los marcadores de caché agregados a las definiciones de herramientas se ignoran, ya que solo se pueden agregar al contenido de un mensaje.

• Mensaje de usuario

  Al crear una caché con el modelo qwen3-vl-plus, puede colocar el marcador cache_control después del contenido multimodal o del texto. Su posición no afecta cómo se almacena en caché todo el mensaje del usuario.

• Mensaje del asistente

• Mensaje de herramienta (el resultado de la ejecución de la herramienta)

Por ejemplo, para un mensaje del sistema, debe cambiar el campo content a una matriz y agregar el campo cache_control:

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

Esta estructura también se aplica a otros tipos de mensajes en la matriz messages.

Limitaciones de la caché

• La longitud mínima del prompt almacenable en caché es de 1,024 tokens.

• La caché utiliza una estrategia de coincidencia de prefijos hacia atrás. Ocurre un fallo de caché si el contenido coincidente y el mensaje con el marcador cache_control están separados por más de 20 bloques de contenido.

• El type solo se puede establecer en ephemeral, lo que crea una caché con un período de validez de 5 minutos.

• Una sola solicitud admite hasta cuatro marcadores de caché.

  Si se proporcionan más de cuatro marcadores de caché, solo los últimos cuatro surten efecto.

Optimización de caché de Function Calling

Una definición de herramienta se serializa en una cadena JSON para su almacenamiento en caché. Para evitar la invalidación de la caché, esta definición debe ser idéntica en todas las solicitudes. Tenga en cuenta lo siguiente:

• Orden consistente de herramientas: El orden de las herramientas en la matriz tools debe ser consistente en todas las solicitudes.
• Orden consistente de campos: El orden de los campos JSON dentro de la misma herramienta debe ser consistente en todas las solicitudes.
• Estructura de campos consistente: No omita ni agregue campos, incluso si están vacíos o son opcionales.

Optimización de la estructura de mensajes para llamadas de herramientas paralelas

Cuando utiliza llamadas de herramientas en paralelo, el modelo devuelve múltiples tool_calls en una sola respuesta. Si envía cada resultado de herramienta como un mensaje tool separado, el número de bloques de contenido en la matriz messages crece rápidamente. Cuando más de 20 bloques de contenido separan el marcador cache_control del contenido anterior, la ventana de retrospección hacia atrás no puede alcanzar esos bloques anteriores, causando un fallo de caché.

Para resolver esto, fusione mensajes de herramienta consecutivos del mismo rol en un único mensaje tool con múltiples bloques de contenido antes de enviar la siguiente solicitud. Esto reduce el recuento total de bloques de contenido y mantiene el contenido que usted want almacenar en caché dentro de la ventana de retrospección de 20 bloques.

Antes de la optimización (mensajes de herramienta separados — menor tasa de aciertos de caché):

# 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"})

Después de la optimización (mensaje de herramienta combinado — mayor tasa de aciertos de caché):

# 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"},
    ],
})

Para mejorar aún más la tasa de aciertos de caché, coloque marcadores cache_control en posiciones estables dentro de la matriz messages (por ejemplo, en el mensaje del sistema o en otro contenido que cambie con poca frecuencia). Una sola solicitud admite hasta cuatro marcadores de caché.

Ejemplos de uso

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}")

Caché implícita

Modelos admitidos

Funcionamiento

La función de caché implícita se habilita automáticamente cuando se envía una solicitud a un modelo compatible. El sistema funciona de la siguiente manera:

1. Búsqueda: Después de recibir una solicitud, el sistema utiliza coincidencia de prefijos para verificar en la caché si existe un prefijo común del contenido en la matriz messages de la solicitud.

2. Decisión:

   • Si ocurre un acierto de caché, el sistema utiliza el resultado almacenado en caché para el resto de la inferencia.
   • Si ocurre un fallo de caché, el sistema procesa la solicitud normalmente y almacena el prefijo del prompt en la caché para futuras solicitudes.

El sistema borra periódicamente los datos almacenados en caché que no se han utilizado durante mucho tiempo. La probabilidad de acierto de la Caché de Contexto no es 100%. Puede ocurrir un fallo de caché incluso si el contexto de la solicitud es idéntico. El sistema determina la probabilidad de acierto específica.

Alcanzar el recuento mínimo de tokens no garantiza un acierto de caché. La ocurrencia de un acierto también depende de factores como el estado de generación de la caché, el periodo de validez de la caché y la programación del sistema. Consulte el recuento de tokens de acierto de caché en la respuesta de la API para conocer los resultados reales.

Aumentar la probabilidad de acierto de caché

Un acierto de caché implícita ocurre cuando los prefijos de diferentes solicitudes tienen contenido duplicado. Para aumentar la probabilidad de aciertos, coloque el contenido duplicado al principio de un prompt y el contenido único al final.

• Modelo de texto: Por ejemplo, suponga que el sistema ha almacenado en caché "ABCD". Una solicitud de "ABE" podría encontrar la parte "AB", pero una solicitud de "BCD" no lo hará.

• Modelo de comprensión visual:
  • Para hacer varias preguntas sobre la misma imagen o video, coloque la imagen o el video antes del texto.
  • Para hacer la misma pregunta sobre diferentes imágenes o videos, coloque el texto antes de la imagen o el video.

Facturación

No se cobran tarifas adicionales por habilitar el modo de caché implícita.

Cuando una solicitud acierta en la caché, los tokens de entrada provenientes del acierto de caché se facturan como cached_token. La tasa de descuento para estos tokens varía según el modelo. Los tokens de entrada que no aciertan en la caché se facturan como input_token estándar. Los tokens de salida se facturan al precio original.

• Para modelos distintos de deepseek-v4.1-flash, deepseek-v4.1-flash-1017, deepseek-v4-pro, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b y qwen3.8-omni-flash: El precio unitario de cached_token es 20% del precio unitario de input_token.

• qwen3.8-omni-flash: Los tokens de entrada con acierto de caché se facturan a un precio unitario fijo. Para precios regionales, consulte Precios de modelos.

• deepseek-v4-pro: El precio unitario de cached_token no es 20% del precio unitario de input_token. Para precios específicos, consulte la consola de Model Studio.

• deepseek-v4.1-flash y deepseek-v4.1-flash-1017: El precio unitario de cached_token es 10% del precio unitario de input_token. Para deepseek-v4.1-flash-1017, esta regla se aplica en las seis regiones indicadas anteriormente, tanto en los periodos de alta demanda como en los de baja demanda, según el precio unitario de entrada de la misma región y periodo.

• qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash y qwen3.8-2.4t-a95b: El precio unitario de cached_token no es 20% del precio unitario de input_token. Para precios específicos, consulte la consola de Model Studio.

• GLM (implementado en Alibaba Cloud Model Studio): glm-5.3, 25% para glm-5.2 y glm-5.2-fast-preview, y 20% para todos los demás modelos de la serie GLM.

Ejemplo: Una solicitud contiene 10,000 tokens de entrada, y 5,000 de ellos resultan en un acierto de caché. El costo se calcula de la siguiente manera:

• Tokens sin acierto de caché (5,000): Se facturan al 100% del precio unitario.
• Tokens con acierto de caché (5,000): Se facturan al 20% del precio unitario.

El costo total de entrada es 60% del costo en un modo sin caché: (50% × 100%) + (50% × 20%) = 60%.

Puede obtener el número de tokens con acierto de caché desde el atributo cached_tokens en la respuesta.

Las llamadas realizadas mediante el método Compatible con OpenAI - Lote (entrada de archivo) no son elegibles para descuentos por caché.

Ejemplos de aciertos de caché

{
    "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": "qwen3-vl-plus",
  "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": "qwen3-vl-plus",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 369,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 896,
    "output_tokens": 28
  }
}

Casos de uso

Si sus solicitudes comparten un prefijo común, la caché de contexto puede mejorar significativamente la velocidad de inferencia, reducir el costo de inferencia y disminuir la latencia del primer paquete. Esta función es particularmente útil en los siguientes casos de uso:

1. Preguntas y respuestas sobre textos largos

   Utilice este patrón cuando envíe múltiples solicitudes sobre el mismo texto largo, como una novela, un libro de texto o un documento legal.

   Mensajes de la primera solicitud

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

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."}]

Aunque las preguntas son diferentes, todas se basan en el mismo artículo. El mismo mensaje del sistema y el contenido del artículo constituyen una gran cantidad de información de prefijo repetitiva, lo que tiene una alta probabilidad de acierto de caché. 2. Autocompletado de código

En escenarios de autocompletado de código, el modelo utiliza el código circundante como contexto para generar código posterior. A medida que escribe, el inicio del archivo de código permanece igual. La caché de contexto puede almacenar este prefijo para acelerar los completados de código. 3. Conversación de varios turnos

Para una conversación de varios turnos, usted agrega cada turno a la matriz de mensajes. Esto asegura que cada nueva solicitud comparta un prefijo común con los turnos anteriores, aumentando la probabilidad de un acierto de caché.

messages=[{"role": "system","content": "You are a helpful assistant."},
          {"role": "user","content": "Who are you?"}]

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?"}]

A medida que crece la conversación, los beneficios del almacenamiento en caché para la velocidad de inferencia y el costo se vuelven más significativos. 4. Juego de roles o aprendizaje few-shot

En escenarios de juego de roles o aprendizaje few-shot, a menudo incluye instrucciones extensas en el prompt para guiar el formato de salida del modelo. Esto crea un prefijo compartido grande en múltiples solicitudes.

Por ejemplo, al instruir al modelo para que actúe como un experto en marketing, el prompt del sistema contiene texto extenso. A continuación se muestran dos ejemplos de solicitudes:

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."}
]

Con la caché de contexto, el sistema puede responder más rápido porque el prompt del sistema extenso se almacena en caché, incluso cuando cambia frecuentemente el producto en su solicitud (por ejemplo, de un reloj inteligente a una computadora portátil). 5. Comprensión de video

En escenarios de comprensión de video, si hace múltiples preguntas sobre el mismo video, colocar video antes de text aumenta la probabilidad de un acierto de caché. Si hace la misma pregunta sobre diferentes videos, colocar text antes de video aumenta la probabilidad de un acierto de caché. El siguiente ejemplo muestra dos solicitudes para el mismo video:

# 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

P: ¿Cuánto tiempo se retiene la caché de contexto (período de validez)?

R: El período de validez de la caché de contexto depende del tipo de caché:

• Caché explícita: El período de validez es de 5 minutos, y cada acierto de caché lo restablece a otros 5 minutos. Si el bloque de caché no se encuentra dentro de 5 minutos, el sistema lo borra automáticamente.
• Caché implícita: Gestionada automáticamente por el sistema sin un período de validez fijo. El sistema borra periódicamente los datos de caché que no se han utilizado durante mucho tiempo.

P: ¿Cómo deshabilito la caché implícita?

R: No puede desactivarla. La caché implícita está habilitada para todas las solicitudes de modelos aplicables porque no afecta la calidad de la respuesta. Cuando ocurre un acierto de caché, reduce los costos y mejora la velocidad de respuesta.

P: ¿Por qué falló mi caché explícita?

R: Un fallo de caché puede ocurrir por las siguientes razones:

• El sistema elimina el bloque de caché si no se accede a él dentro de su período de validez de 5 minutos.
• Si el intervalo entre el último content y un bloque de caché existente es mayor que 20 bloques content, no ocurrirá un acierto de caché. Le recomendamos que cree un nuevo bloque de caché.

P: ¿Un acierto de caché restablece su validez?

R: Sí. Cada acierto restablece el período de validez del bloque de caché a 5 minutos.

P: ¿Se comparte la caché explícita entre cuentas?

R: No. Tanto los datos de la caché implícita como los de la caché explícita están aislados a nivel de cuenta.

P: ¿Se comparte la caché explícita entre modelos?

R: No. Los datos de caché están aislados entre modelos.

P: ¿Por qué input_tokens en usage no es igual a la suma de cache_creation_input_tokens y cached_tokens?

R: Para garantizar la calidad de la salida del modelo, el servicio backend agrega una pequeña cantidad de tokens (generalmente 10 o menos) a su prompt. Estos tokens se colocan después del marcador cache_control, por lo que no se cuentan para la creación o lectura de caché, pero sí se incluyen en el total de input_tokens.