Todos los productos
Search
Centro de documentos

Alibaba Cloud Model Studio:Caché explícita (Qwen4)

Última actualización: Nov 16, 2026

Caché explícita exclusiva de los modelos de la serie Qwen4. Use la caché automática o los puntos de interrupción de caché para especificar el prefijo de entrada que se reutilizará y establezca un tiempo de vida de 5 minutos o 1 hora para reducir el cálculo repetido, la latencia y los costos de entrada.

En escenarios como conversaciones de varios turnos, preguntas y respuestas sobre documentos extensos y agentes, las solicitudes consecutivas suelen compartir una gran cantidad de contenido inicial, como el prompt del sistema, las descripciones de herramientas o los documentos de referencia. Con la caché explícita (Qwen4), las solicitudes posteriores dentro del período de validez pueden leer ese contenido directamente de la caché en lugar de volver a calcularlo, lo que reduce la latencia de respuesta y los costos de entrada.

La caché explícita usa puntos de interrupción de caché para especificar el prefijo de contenido que se reutilizará, y los aciertos de caché son deterministas: siempre que el prefijo sea idéntico y siga dentro del período de validez, las solicitudes posteriores pueden leer la caché. La caché implícita, que identifica prefijos comunes de forma automática, no garantiza aciertos de caché.

Qwen4 agrega la caché automática y el TTL de caché al uso básico. Para obtener más información, consulte Uso avanzado.

NotaEsta página describe la versión de Qwen4 de la caché explícita existente: el uso de puntos de interrupción en bloques de contenido no cambia y se agregan la caché automática y el TTL de caché. Su relación con los dos modos de caché de Context Cache:

  • Caché explícita: use puntos de interrupción de caché para especificar el prefijo de entrada, con aciertos de caché deterministas. Es el tema de esta página.
  • Caché implícita: cuando no se establece ningún parámetro de caché, se identifican prefijos comunes de forma automática y los aciertos de caché no están garantizados. Para obtener más información, consulte Caché implícita.
  • El marcador de bloque de contenido cache_control de la API Chat Completions compatible con OpenAI sigue siendo compatible y se usa igual que prompt_cache_breakpoint. Para obtener más información, consulte Uso básico.

Cómo funciona

La caché se crea y se lee por punto de interrupción. En la caché automática, el sistema coloca un punto de interrupción al final de la entrada. En los puntos de interrupción de caché, usted los marca en los bloques de contenido. El prefijo de caché de cada punto de interrupción es toda la entrada desde el inicio de la solicitud hasta el final del bloque de contenido que contiene ese punto de interrupción.

Cuando se recibe una solicitud, el sistema usa cada punto de interrupción como punto final, busca hacia atrás hasta 20 bloques de contenido y selecciona el prefijo idéntico más largo que ya esté en caché:

  • Acierto de caché: se lee el prefijo en caché y se extiende según el TTL de la solicitud actual.
  • Fallo de caché: el contenido desde el inicio de la solicitud hasta el punto de interrupción se crea como una nueva caché. Si parte del prefijo ya produjo un acierto de caché, solo la parte nueva se guarda en caché.

Un acierto de caché requiere un prefijo totalmente idéntico, y la caché solo se reutiliza entre solicitudes del mismo usuario. Para mejorar la tasa de aciertos, coloque el contenido que no cambia al principio y el contenido que cambia en cada solicitud después del punto de interrupción.

Si no se establece ningún parámetro de caché, el sistema usa la caché implícita para identificar prefijos comunes de forma automática, pero los aciertos de caché no están garantizados. Para reutilizar contenido específico de forma confiable, habilite la caché automática o establezca puntos de interrupción de caché.

Uso básico

Establezca un punto de interrupción de caché en el bloque de contenido que desea reutilizar. El sistema usa el final de ese bloque de contenido como punto de interrupción y trata toda la entrada desde el inicio de la solicitud hasta ese punto como el prefijo de caché: la primera solicitud crea la caché y las solicitudes posteriores con el mismo prefijo dentro del período de validez la leerán. El prefijo de caché debe contener al menos 1024 tokens.

Compatible con OpenAI Chat Completions

Agregue prompt_cache_breakpoint con el valor {"mode": "explicit"} al bloque de contenido que se va a almacenar en caché en messages. El content del mensaje que contiene el punto de interrupción debe ser un arreglo:

messages=[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": long_text,
        "prompt_cache_breakpoint": {"mode": "explicit"},  # <-- Punto de interrupción de caché
      },
      {"type": "text", "text": "Resume este documento."},  # El contenido posterior al punto de interrupción no forma parte de esta caché
    ],
  }
],

El marcador de bloque de contenido existente "cache_control": {"type": "ephemeral"} sigue siendo compatible y se usa igual que prompt_cache_breakpoint. Para el mismo usuario, la caché con el mismo prefijo se puede reutilizar entre ambos marcadores. Para nuevas integraciones, se recomienda prompt_cache_breakpoint.

AdvertenciaUse solo uno de prompt_cache_breakpoint y cache_control en una misma solicitud.

El siguiente ejemplo envía dos solicitudes: la primera crea la caché y la segunda mantiene el mismo prefijo y solo cambia la pregunta para leer la caché.

import os
from openai import OpenAI

client = OpenAI(
  # Si la variable de entorno no está configurada, reemplace la línea siguiente por: api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # Esta es la URL de la región de Singapore. Al llamar, reemplace WorkspaceId por el ID de espacio de trabajo real. La URL varía según la región.
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Documento extenso que se reutilizará. El prefijo de caché debe contener al menos 1024 tokens.
long_text = "<Documento extenso fijo>" * 400

def ask(question):
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
      {
        "role": "user",
        "content": [
          {"type": "text", "text": long_text, "prompt_cache_breakpoint": {"mode": "explicit"}},  # <-- Punto de interrupción de caché
          {"type": "text", "text": question},  # El contenido posterior al punto de interrupción puede cambiar en cada solicitud
        ],
      }
    ],
    extra_body={
      "enable_thinking": False,
    },
  )
  return completion.usage.prompt_tokens_details

ask("Resume este documento.")  # Primera solicitud: crea la caché
details = ask("Enumera los tres puntos principales de este documento.")  # Segunda solicitud: lee la caché
print(f"Caché leída: {details.cached_tokens} tokens, caché creada: {details.cache_write_tokens} tokens")

En la segunda solicitud, cached_tokens es la cantidad de tokens leídos de la caché y cache_write_tokens es la cantidad de tokens creados por esta solicitud. Si el prefijo no cambia, cache_write_tokens es 0. Las cifras son solo ilustrativas y los valores reales dependen de la longitud del documento.

Compatible con OpenAI Responses

Utilice el endpoint compatible con OpenAI /compatible-mode/v1/responses. Configure prompt_cache_options en la raíz de la solicitud y prompt_cache_breakpoint en los bloques de contenido de mensajes en input.

CampoTipoDescripción
prompt_cache_optionsobjectObjeto opcional para configurar el modo de caché y el TTL.
prompt_cache_options.modestringOpcional. Admite implicit y explicit; el valor predeterminado es implicit. implicit activa el caché explícito y configura un punto automático al final del último mensaje de entrada; los puntos manuales y automáticos se aplican juntos. explicit requiere un punto manual para crear el caché y no tiene efecto sin él.
prompt_cache_options.ttlstringOpcional. Admite 5m y 1h; el valor predeterminado es 5m.
input[].content[].prompt_cache_breakpointobjectObjeto opcional en un bloque de contenido, con prioridad sobre el modo de caché de la raíz. Se admite en bloques de tipo input_text, input_image e input_file.
prompt_cache_breakpoint.modestringObligatorio al configurar un punto de interrupción. Solo admite explicit. Envíe {"mode": "explicit"} de forma explícita.

El ejemplo envía dos solicitudes consecutivas. El documento largo anterior al punto de interrupción permanece idéntico; solo cambia la pregunta posterior. La primera solicitud crea el caché y la segunda lo lee dentro del TTL. Se usa qwen4-max. Instale openai y configure DASHSCOPE_API_KEY y DASHSCOPE_BASE_URL. La Base URL de Singapore es https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1; sustituya {WorkspaceId} por el ID de su espacio de trabajo.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url=os.environ["DASHSCOPE_BASE_URL"],
)
long_text = "Cache reference: Paris is the capital of France. " * 400

for question in ["Summarize this document.", "What is the capital of France?"]:
    response = client.responses.create(
        model="qwen4-max",
        input=[{
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": long_text,
                    "prompt_cache_breakpoint": {"mode": "explicit"},
                },
                {"type": "input_text", "text": question},
            ],
        }],
        reasoning={"effort": "none"},
        max_output_tokens=128,
        extra_body={"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}},
    )
    print(response.output_text)
    print(response.usage.model_dump())

Para curl, configure DASHSCOPE_RESPONSES_URL con la Base URL anterior seguida de /responses. Sustituya el documento de ejemplo por uno real de al menos 1,024 tokens.

curl "$DASHSCOPE_RESPONSES_URL" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen4-max",
    "input": [{
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "<DOCUMENT_WITH_AT_LEAST_1024_TOKENS>",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        },
        {"type": "input_text", "text": "Summarize this document."}
      ]
    }],
    "reasoning": {"effort": "none"},
    "max_output_tokens": 128,
    "prompt_cache_options": {"mode": "explicit", "ttl": "5m"}
  }'

Compatible con Anthropic

Agregue cache_control con el valor {"type": "ephemeral"} al bloque de contenido que se va a almacenar en caché en system o messages:

system=[
  {
    "type": "text",
    "text": long_text,
    "cache_control": {"type": "ephemeral"},  # <-- Punto de interrupción de caché
  }
],

Usar varios puntos de interrupción

Si el prompt consta de varias partes que cambian con distinta frecuencia, puede establecer un punto de interrupción para cada parte. Por ejemplo, un prompt de atención al cliente suele incluir la persona del sistema (que cambia poco), los resultados de recuperación de la base de conocimiento (que cambian según el tema de la pregunta) y el historial de la conversación (que crece continuamente). Si establece un punto de interrupción al final de cada parte, la persona del sistema puede seguir produciendo aciertos de caché aunque cambie el contenido de la base de conocimiento.

Cada solicitud conserva como máximo los últimos 4 puntos de interrupción válidos. Los puntos de interrupción adicionales no tienen efecto. Cuando se habilita la caché automática, el punto de interrupción automático ocupa uno de esos 4 espacios.

Renovación cuando se mueve el punto de interrupción

El sistema solo crea o renueva puntos de interrupción en la solicitud actual. Después de que se mueve un punto de interrupción, el período de validez del punto de interrupción anterior no se extiende, aunque se lea su caché.

Por ejemplo, con el mismo TTL, el punto de interrupción de la solicitud anterior está en el token 2048 y la solicitud actual lo mueve al token 3072 sin mantener el punto de interrupción anterior. Si el punto de interrupción anterior está dentro del alcance de búsqueda y aún no ha caducado, la solicitud actual lee los primeros 2048 tokens de la caché y almacena los siguientes 1024 tokens en caché. El sistema solo crea o renueva el punto de interrupción en el token 3072. La caché en el token 2048 no se renueva.

Uso avanzado

Qwen4 agrega las siguientes dos capacidades al uso básico. Puede combinarlas:

  • Caché automática: el sistema coloca automáticamente un punto de interrupción al final de la entrada, adecuado para conversaciones de varios turnos.
  • TTL de caché: elija 5 minutos o 1 hora.

Caché automática

Con la caché automática, el sistema coloca automáticamente un punto de interrupción al final de la entrada de cada solicitud, por lo que no necesita mover el punto de interrupción a medida que crece la conversación. El punto de interrupción automático no incluye el sufijo de plantilla que se usa para iniciar la generación de la respuesta. La caché automática se puede usar junto con los puntos de interrupción de caché descritos en Uso básico. Si ya existe un punto de interrupción manual al final de la entrada, el punto de interrupción no se coloca dos veces.

Compatible con OpenAI Chat Completions

Establezca prompt_cache_options en el nivel superior de la solicitud y configure mode como implicit. Con el SDK de Python de OpenAI, páselo mediante extra_body:

completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "Resume este documento: " + long_text}],
  extra_body={
    "enable_thinking": False,
    "prompt_cache_options": {"mode": "implicit"},  # <-- Habilita la caché automática
  },
)

Los valores de prompt_cache_options.mode y su comportamiento son los siguientes:

ConfiguraciónPunto de interrupción automáticoComportamiento de la caché
mode es implicitSe colocaTanto el punto de interrupción automático al final de la entrada como los puntos de interrupción manuales tienen efecto
mode es explicit con puntos de interrupción manualesNo se colocaCrea o lee la caché en los puntos de interrupción manuales
mode es explicit sin puntos de interrupción manualesNo se colocaUsa la caché implícita
Se omite prompt_cache_options, es null o {}, o solo se establece ttlNo se colocaAlmacena en caché en los puntos de interrupción manuales si existen; de lo contrario, usa la caché implícita

NotaCuando mode es implicit, se usa la caché del punto de interrupción automático y se aplican las reglas de TTL y facturación de esta página. Esto es distinto de la caché implícita que se usa cuando no se establece ningún parámetro de caché. Establecer mode como explicit solo significa que no se coloca ningún punto de interrupción automático. No desactiva la caché implícita. mode solo se aplica a la solicitud actual.

Compatible con OpenAI Responses

Configure prompt_cache_options para activar el caché explícito. mode es implicit de forma predeterminada: se configura un punto al final del último mensaje de entrada y también se aplican los puntos manuales.

response = client.responses.create(
    model="qwen4-max",
    input=[{"role": "user", "content": [{"type": "input_text", "text": long_text}]}],
    reasoning={"effort": "none"},
    max_output_tokens=128,
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
print(response.usage.model_dump())

Compatible con Anthropic

Establezca cache_control con el valor {"type": "ephemeral"} en el nivel superior de la solicitud. El cache_control de nivel superior habilita la caché automática y se puede usar junto con cache_control en bloques de contenido. Con el SDK de Python de Anthropic, páselo mediante extra_body:

message = client.messages.create(
  model="qwen4-max",
  max_tokens=1024,
  messages=[{"role": "user", "content": "Resume este documento: " + long_text}],
  extra_body={"cache_control": {"type": "ephemeral"}},  # <-- Habilita la caché automática en el nivel superior de la solicitud
)

El siguiente ejemplo completo habilita la caché automática y envía la misma solicitud de documento extenso dos veces: la primera solicitud crea la caché y la segunda la lee.

Compatible con OpenAI Chat Completions

import os
from openai import OpenAI

client = OpenAI(
  # Si la variable de entorno no está configurada, reemplace la línea siguiente por: api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # Esta es la URL de la región de Singapore. Al llamar, reemplace WorkspaceId por el ID de espacio de trabajo real. La URL varía según la región.
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Documento extenso que se reutilizará. El prefijo de caché debe contener al menos 1024 tokens.
long_text = "<Documento extenso fijo>" * 400

def ask():
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "Resume este documento: " + long_text}],
    extra_body={
      "enable_thinking": False,
      "prompt_cache_options": {"mode": "implicit"},  # <-- Habilita la caché automática
    },
  )
  return completion.usage.prompt_tokens_details

for i in range(1, 3):
  details = ask()
  print(f"Solicitud {i}: caché leída {details.cached_tokens} tokens, caché creada {details.cache_write_tokens} tokens")
import OpenAI from "openai";

const client = new OpenAI({
  // Si la variable de entorno no está configurada, reemplace la línea siguiente por: apiKey: "sk-xxx"
  apiKey: process.env.DASHSCOPE_API_KEY,
  // Esta es la URL de la región de Singapore. Al llamar, reemplace WorkspaceId por el ID de espacio de trabajo real. La URL varía según la región.
  baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});

// Documento extenso que se reutilizará. El prefijo de caché debe contener al menos 1024 tokens.
const longText = "<Documento extenso fijo>".repeat(400);

async function ask() {
  const completion = await client.chat.completions.create({
    model: "qwen4-max",
    messages: [{ role: "user", content: "Resume este documento: " + longText }],
    enable_thinking: false,
    prompt_cache_options: { mode: "implicit" }, // <-- Habilita la caché automática
  });
  return completion.usage.prompt_tokens_details;
}

async function main() {
  for (let i = 1; i <= 2; i++) {
    const details = await ask();
    console.log(`Solicitud ${i}: caché leída ${details.cached_tokens} tokens, caché creada ${details.cache_write_tokens} tokens`);
  }
}

main().catch(console.error);
# Esta es la URL de la región de Singapore. Al llamar, reemplace WorkspaceId por el ID de espacio de trabajo real. La URL varía según la región.
# Reemplace <Documento extenso fijo> por un documento extenso de al menos 1024 tokens y envíelo dos veces dentro del período de validez.
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen4-max",
    "messages": [
      {"role": "user", "content": "Resume este documento: <Documento extenso fijo>"}
    ],
    "enable_thinking": false,
    "prompt_cache_options": {"mode": "implicit"}
  }'

Compatible con OpenAI Responses

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url=os.environ["DASHSCOPE_BASE_URL"],
)
long_text = "Cache reference: Paris is the capital of France. " * 400

for question in ["Summarize this document.", "Summarize this document."]:
    response = client.responses.create(
        model="qwen4-max",
        input=[{
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": long_text,
                },
                {"type": "input_text", "text": question},
            ],
        }],
        reasoning={"effort": "none"},
        max_output_tokens=128,
        extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "5m"}},
    )
    print(response.output_text)
    print(response.usage.model_dump())

Compatible con Anthropic

import os
import anthropic

client = anthropic.Anthropic(
  # Si la variable de entorno no está configurada, reemplace la línea siguiente por: api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # Esta es la URL de la región de Singapore. Al llamar, reemplace WorkspaceId por el ID de espacio de trabajo real. La URL varía según la región.
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
)

# Documento extenso que se reutilizará. El prefijo de caché debe contener al menos 1024 tokens.
long_text = "<Documento extenso fijo>" * 400

def ask():
  message = client.messages.create(
    model="qwen4-max",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Resume este documento: " + long_text}],
    extra_body={"cache_control": {"type": "ephemeral"}},  # <-- Habilita la caché automática en el nivel superior de la solicitud
  )
  return message.usage

for i in range(1, 3):
  usage = ask()
  print(f"Solicitud {i}: caché leída {usage.cache_read_input_tokens} tokens, caché creada {usage.cache_creation_input_tokens} tokens")
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  // Si la variable de entorno no está configurada, reemplace la línea siguiente por: apiKey: "sk-xxx"
  apiKey: process.env.DASHSCOPE_API_KEY,
  // Esta es la URL de la región de Singapore. Al llamar, reemplace WorkspaceId por el ID de espacio de trabajo real. La URL varía según la región.
  baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
});

// Documento extenso que se reutilizará. El prefijo de caché debe contener al menos 1024 tokens.
const longText = "<Documento extenso fijo>".repeat(400);

async function ask() {
  const message = await client.messages.create({
    model: "qwen4-max",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Resume este documento: " + longText }],
    cache_control: { type: "ephemeral" }, // <-- Habilita la caché automática en el nivel superior de la solicitud
  });
  return message.usage;
}

async function main() {
  for (let i = 1; i <= 2; i++) {
    const usage = await ask();
    console.log(`Solicitud ${i}: caché leída ${usage.cache_read_input_tokens} tokens, caché creada ${usage.cache_creation_input_tokens} tokens`);
  }
}

main().catch(console.error);
# Esta es la URL de la región de Singapore. Al llamar, reemplace WorkspaceId por el ID de espacio de trabajo real. La URL varía según la región.
# Reemplace <Documento extenso fijo> por un documento extenso de al menos 1024 tokens y envíelo dos veces dentro del período de validez.
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $DASHSCOPE_API_KEY" \
  -d '{
    "model": "qwen4-max",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "messages": [
      {"role": "user", "content": "Resume este documento: <Documento extenso fijo>"}
    ]
  }'

La salida es similar a la siguiente. El número real de tokens depende de la longitud del documento:

Solicitud 1: caché leída 0 tokens, caché creada 2048 tokens
Solicitud 2: caché leída 2048 tokens, caché creada 0 tokens

La entrada de la segunda solicitud es idéntica a la de la primera, por lo que la segunda lee la caché creada por la primera.

Establecer el TTL de caché

El período de validez de la caché (TTL) puede ser 5m (5 minutos) o 1h (1 hora). El valor predeterminado es 5m. Cuando la caché produce un acierto dentro del período de validez, se renueva automáticamente. Para obtener más información, consulte Reglas de renovación.

Compatible con OpenAI Chat Completions

Establézcalo en prompt_cache_options.ttl en el nivel superior de la solicitud. El valor se aplica a todos los puntos de interrupción de la solicitud:

extra_body={
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "1h",  # <-- El TTL de la caché es de 1 hora
  },
},

Si no se establece prompt_cache_options.ttl, se usa el ttl del último marcador cache_control de la solicitud. Si ese marcador no tiene ttl, o la solicitud no tiene ningún marcador cache_control, el TTL es 5m.

El TTL solo se aplica a la caché explícita. Al establecer ttl, establezca también puntos de interrupción de caché o habilite la caché automática.

Compatible con OpenAI Responses

Configure el TTL en prompt_cache_options.ttl en la raíz. Admite 5m y 1h; el valor predeterminado es 5m.

extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}}

Compatible con Anthropic

Cuando la caché automática está habilitada, establezca ttl en el cache_control de nivel superior. El valor predeterminado es 5m:

extra_body={"cache_control": {"type": "ephemeral", "ttl": "1h"}},  # <-- El TTL de la caché es de 1 hora

Cuando use puntos de interrupción de caché, establezca ttl en el cache_control del bloque de contenido:

system=[
  {
    "type": "text",
    "text": long_text,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},  # <-- El TTL de la caché es de 1 hora
  }
],

Reglas de renovación

Para la primera solicitud, o después de que caduque la caché, esta se crea con el TTL de la solicitud actual. Cuando una solicitud produce un acierto en una caché válida, la renovación y la facturación siguen estas reglas:

  • Se conserva la fecha de caducidad más tardía, junto con el nivel más alto. La nueva fecha de caducidad es aproximadamente la más tardía entre la caducidad original y la hora de inicio del procesamiento de la caché de la solicitud actual más el TTL actual. Por ejemplo, una solicitud a las 12:03 que produce un acierto en una caché de 5m que caduca a las 12:05 extiende la caducidad a aproximadamente las 12:08. Como otro ejemplo, cuando una solicitud de 5m produce un acierto en una caché de 1h válida, la renovación se calcula según 5m, pero la caché mantiene el nivel de 1h y las solicitudes de 1h posteriores dentro del período de validez se siguen facturando como lecturas de caché.
  • Al actualizar de 5m a 1h, la parte actualizada se factura como creación de caché de 1h. Cuando una solicitud de 1h produce un acierto en una caché de 5m válida, la parte que produjo el acierto se vuelve a crear con un TTL de 1h y ya no se factura como lectura. Si parte del prefijo ya tiene una caché de 1h válida, esa parte se sigue facturando como lectura, y solo la parte restante y el prefijo nuevo se facturan como creación. En todos los demás casos (una solicitud de 5m produce un acierto en una caché de 5m, una solicitud de 5m produce un acierto en una caché de 1h, o una solicitud de 1h produce un acierto en una caché de 1h), la parte que produjo el acierto se factura como lectura.

El período de validez comienza cuando se inicia el procesamiento de la caché de la solicitud actual. No se suma a la fecha de caducidad original ni se reinicia cuando termina la respuesta. El tiempo de generación de la respuesta cuenta dentro del período de validez, y la fecha de caducidad real proporciona un poco de tiempo de procesamiento adicional.

El siguiente ejemplo muestra solicitudes consecutivas para la misma caché, creada con un TTL de 1h a las 12:00 y que originalmente caduca a las 13:00:

SolicitudTTL de esta solicitudCaducidad antes de la solicitudCaducidad después de la solicitud (aproximada)Facturación y nivel
Enviada a las 12:205m13:0013:00Lectura de caché. Las 12:25 son anteriores a la caducidad original, por lo que la caducidad no cambia. No se acorta ni se extiende hasta las 13:20.
Enviada a las 12:585m13:0013:03Lectura de caché. La caducidad se extiende a 5 minutos después del inicio de esta solicitud, y la caché mantiene el nivel de 1h.
Enviada a las 13:011h13:0314:01Lectura de caché. La caché ya está en el nivel de 1h, por lo que no hay creación por la actualización.

El ejemplo anterior supone solicitudes seriales con el mismo prefijo. Cuando varias solicitudes escriben en la misma caché al mismo tiempo, pueden sobrescribirse entre sí y no se garantiza que se conserve la última fecha de caducidad.

Ver el uso de la caché

El usage de la respuesta devuelve la cantidad de tokens leídos de la caché y escritos en la caché. Para la salida en streaming con la API Chat Completions compatible con OpenAI, establezca stream_options como {"include_usage": true} y lea el uso del último fragmento que contiene usage.

Compatible con OpenAI Chat Completions

A continuación se muestra el usage cuando la caché se crea por primera vez (solo entrada de texto, modo sin thinking):

{
  "usage": {
    "prompt_tokens": 2304,
    "completion_tokens": 128,
    "total_tokens": 2432,
    "prompt_tokens_details": {
      "text_tokens": 2304,
      "cached_tokens": 0,
      "cache_write_tokens": 2048,
      "cache_creation_input_tokens": 2048,
      "cache_type": "ephemeral",
      "cache_creation": {
        "ephemeral_5m_input_tokens": 2048,
        "ephemeral_1h_input_tokens": 0
      }
    },
    "completion_tokens_details": {}
  }
}
CampoDescripción
prompt_tokensTotal de tokens de entrada, incluidos la lectura de caché, la escritura de caché y la entrada que no usa caché. No se reduce por los aciertos de caché.
total_tokensSuma de prompt_tokens y completion_tokens
prompt_tokens_details.cached_tokensCantidad de tokens leídos de la caché
prompt_tokens_details.cache_write_tokensCantidad de tokens escritos en la caché
prompt_tokens_details.cache_creation_input_tokensCantidad de tokens escritos en la caché. Es igual a cache_write_tokens. No sume ambos.
prompt_tokens_details.cache_typeTipo de caché explícita. Siempre es ephemeral.
prompt_tokens_details.cache_creationCantidad de tokens escritos en la caché por TTL. La suma de ephemeral_5m_input_tokens y ephemeral_1h_input_tokens es igual a la cantidad de tokens escritos en la caché.

En el ejemplo anterior, la entrada que no usa caché es 2304 − 0 − 2048 = 256 tokens. Todos los campos de caché son cantidades de tokens sin procesar y no incluyen multiplicadores de facturación. Cuando envíe de nuevo una solicitud con el mismo prefijo dentro del período de validez, cached_tokens será 2048, cache_write_tokens, cache_creation_input_tokens y ambos elementos de cache_creation serán 0, y prompt_tokens seguirá siendo 2304.

Los detalles de entrada de imagen, audio y video se devuelven según la entrada real. Los detalles de salida, como thinking, se devuelven según el modelo y la configuración. Los campos que no se aplican se omiten en lugar de devolverse como 0.

Compatible con OpenAI Responses

prompt_cache_options en la raíz de la respuesta devuelve mode (implicit o explicit) y ttl (5m o 1h). El uso se encuentra en usage.input_tokens_details. En streaming, lea response.usage del evento response.completed; no utilice la opción de Chat Completions stream_options.include_usage.

CampoDescripción
input_tokensTodos los tokens de entrada, incluidas lecturas y escrituras de caché y entrada sin caché.
input_tokens_details.cached_tokensTokens leídos del caché.
input_tokens_details.cache_write_tokensTokens escritos en el caché.
input_tokens_details.cache_write_tokens_details.ttl_5m_tokens / ttl_1h_tokensTokens de escritura por TTL. La suma de ambos valores es igual a cache_write_tokens.

Estos campos se devolvieron en el endpoint de prueba de Beijing al crear un caché 5m por primera vez. En la segunda solicitud con el mismo prefijo, cached_tokens es 4488, mientras que cache_write_tokens y ambos campos de escritura por TTL son 0.

{
  "prompt_cache_options": {
    "mode": "explicit",
    "ttl": "5m"
  },
  "usage": {
    "input_tokens": 4498,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 4488,
      "cache_write_tokens_details": {
        "ttl_5m_tokens": 4488,
        "ttl_1h_tokens": 0
      }
    },
    "output_tokens": 32,
    "output_tokens_details": {
      "reasoning_tokens": 32
    },
    "total_tokens": 4530
  }
}

No confunda los campos input_tokens_details de Responses con prompt_tokens_details de Chat Completions o cache_creation de Anthropic.

Compatible con Anthropic

A continuación se muestra el usage cuando la caché se crea por primera vez con la caché automática habilitada y el TTL establecido en 1h:

{
  "usage": {
    "input_tokens": 8,
    "output_tokens": 128,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 2048,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 0,
      "ephemeral_1h_input_tokens": 2048
    },
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}
CampoDescripción
input_tokensCantidad de tokens de entrada que no se leyeron de la caché ni se escribieron en la caché
cache_read_input_tokensCantidad de tokens leídos de la caché
cache_creation_input_tokensCantidad de tokens escritos en la caché
cache_creationCantidad de tokens escritos en la caché por TTL
prompt_tokens_details.cached_tokensCantidad de tokens leídos de la caché. Es igual a cache_read_input_tokens. No sume ambos valores.

El total de tokens de entrada es la suma de input_tokens, cache_read_input_tokens y cache_creation_input_tokens, es decir, 8 + 0 + 2048 = 2056 en el ejemplo anterior.

Prácticas recomendadas

  • Use la caché automática para conversaciones de varios turnos. El punto de interrupción automático avanza a medida que crece la conversación, por lo que no necesita ajustar puntos de interrupción en cada turno.
  • Coloque el contenido fijo al principio. Coloque el contenido que no cambia, como el prompt del sistema, las definiciones de herramientas y los documentos de referencia, al principio de la entrada. Coloque el contenido que cambia en cada solicitud, como marcas de tiempo y preguntas del usuario, al final.
  • Coloque el punto de interrupción en el último bloque de contenido idéntico en todas las solicitudes. No coloque el punto de interrupción en un bloque de contenido que cambia en cada solicitud. De lo contrario, cada solicitud creará una caché nueva y nunca la leerá.
  • Agregue al historial, no lo reescriba. Modificar, eliminar o reordenar mensajes anteriores o definiciones de herramientas impide que las cachés posteriores produzcan aciertos.
  • Use varios puntos de interrupción para contenido que cambia con distinta frecuencia. Por ejemplo, si las definiciones de herramientas cambian poco pero los documentos de referencia se actualizan a diario, establezca un punto de interrupción al final de cada uno.
  • Agregue un punto de interrupción cuando un turno agregue muchos bloques de contenido. Cada punto de interrupción busca hacia atrás hasta 20 bloques de contenido. Si un turno agrega contenido más allá de ese alcance, agregue un punto de interrupción en el medio.
  • Elija el TTL según el intervalo de reutilización. Use 5m si el contenido se reutiliza en 5 minutos, ya que cada acierto renueva la caché. Use 1h si el intervalo de reutilización está entre 5 minutos y 1 hora.
  • Supervise los aciertos de caché con los campos de uso. La tasa de aciertos es la cantidad de tokens leídos de la caché dividida por el total de tokens de entrada. Si la tasa de aciertos es baja, compruebe si la posición del prefijo y los puntos de interrupción son estables.

Facturación

Los puntos de interrupción de caché solo afectan la forma en que se facturan los tokens de entrada. Los tokens de salida se facturan a la tarifa estándar.

Tipo de token de entradaFacturación
Escritura de caché, TTL de 5mAproximadamente 125% del precio del token de entrada
Escritura de caché, TTL de 1hAproximadamente 200% del precio del token de entrada
Lectura de cachéQwen4-Max
No leído de la caché ni escrito en la cachéPrecio del token de entrada

Si el prefijo de caché de la solicitud actual contiene una caché válida existente, la parte existente se factura como lectura de caché y solo la parte nueva se factura como escritura de caché. Para la facturación cuando el TTL se actualiza de 5m a 1h, consulte Reglas de renovación.

Limitaciones

  • Solo se admiten los modelos de la serie Qwen4.
  • El prefijo debe contener al menos 1024 tokens. Los prefijos más cortos no crean un caché; la solicitud se completa y se omiten los detalles de escritura por TTL.
  • Cada solicitud conserva como máximo los últimos 4 puntos de interrupción válidos. Cuando la caché automática está habilitada, el punto de interrupción automático ocupa uno de ellos.
  • Con cada punto de interrupción como punto final, el sistema busca hacia atrás hasta 20 bloques de contenido. Si la caché que se va a acertar está a más de 20 bloques de contenido del punto de interrupción, no se puede acertar.
  • El TTL solo puede ser 5m o 1h.

Preguntas frecuentes

P: ¿Puede una solicitud producir un acierto de caché sin ningún parámetro de caché?

Sí. Sin parámetros de caché, se usa la caché implícita. El sistema identifica prefijos comunes de forma automática, pero los aciertos de caché no están garantizados. Para producir aciertos de caché de forma confiable, establezca puntos de interrupción de caché o habilite la caché automática.

P: ¿Por qué el período de validez de la caché no cambia cuando solo establezco el TTL?

El TTL solo se aplica a la caché explícita. Si solo establece prompt_cache_options.ttl en la API Chat Completions compatible con OpenAI, la solicitud usa la caché implícita. Agregue también puntos de interrupción manuales o establezca prompt_cache_options.mode como implicit.

P: ¿Una solicitud de 5m que produce un acierto en una caché de 1h acorta el período de validez de la caché?

No. La nueva fecha de caducidad es la más tardía entre la caducidad original y la renovación de la solicitud actual, y la caché mantiene el nivel de 1h. Para obtener más información, consulte Reglas de renovación.