Skip to main content

Cache explícito (Qwen4)

Cache explícito exclusivo dos modelos da série Qwen4. Use o cache automático ou os pontos de interrupção de cache para especificar o prefixo de entrada a ser reutilizado e defina um tempo de vida de 5 minutos ou 1 hora para reduzir o cálculo repetido, a latência e os custos de entrada.

Em cenários como conversas de vários turnos, perguntas e respostas sobre documentos longos e agentes, as solicitações consecutivas geralmente compartilham muito conteúdo inicial, como o prompt de sistema, as descrições de ferramentas ou os documentos de referência. Com o cache explícito (Qwen4), as solicitações posteriores dentro do período de validade podem ler esse conteúdo diretamente do cache em vez de recalculá-lo, o que reduz a latência das respostas e os custos de entrada. O cache explícito usa pontos de interrupção de cache para especificar o prefixo de conteúdo a ser reutilizado, e os acertos de cache são determinísticos: desde que o prefixo seja idêntico e ainda esteja dentro do período de validade, as solicitações posteriores podem ler o cache. O cache implícito, que identifica prefixos comuns automaticamente, não garante acertos de cache. O Qwen4 adiciona o cache automático e o TTL do cache ao uso básico. Para obter mais informações, consulte Uso avançado.
Esta página descreve a versão do Qwen4 do cache explícito existente: o uso de pontos de interrupção em blocos de conteúdo permanece o mesmo, com a adição do cache automático e do TTL do cache. A relação com os dois modos de cache do Context Cache:
  • Cache explícito: use pontos de interrupção de cache para especificar o prefixo de entrada, com acertos de cache determinísticos. É o tema desta página.
  • Cache implícito: quando nenhum parâmetro de cache é definido, os prefixos comuns são identificados automaticamente e os acertos de cache não são garantidos. Para obter mais informações, consulte Cache implícito.
  • O marcador de bloco de conteúdo cache_control da API Chat Completions compatível com OpenAI continua compatível e é usado da mesma forma que prompt_cache_breakpoint. Para obter mais informações, consulte Uso básico.

Como funciona

O cache é criado e lido por ponto de interrupção. No cache automático, o sistema coloca um ponto de interrupção no final da entrada. Nos pontos de interrupção de cache, você os marca nos blocos de conteúdo. O prefixo de cache de cada ponto de interrupção é toda a entrada desde o início da solicitação até o final do bloco de conteúdo que contém esse ponto de interrupção. Quando uma solicitação é recebida, o sistema usa cada ponto de interrupção como ponto final, pesquisa retroativamente até 20 blocos de conteúdo e seleciona o prefixo idêntico mais longo que já está em cache:
  • Acerto de cache: o prefixo em cache é lido e estendido de acordo com o TTL da solicitação atual.
  • Falha de cache: o conteúdo desde o início da solicitação até o ponto de interrupção é criado como um novo cache. Se parte do prefixo já gerou um acerto de cache, apenas a parte nova é armazenada em cache.
Um acerto de cache exige um prefixo totalmente idêntico, e o cache só é reutilizado entre solicitações do mesmo usuário. Para melhorar a taxa de acertos, coloque o conteúdo que não muda no início e o conteúdo que muda em cada solicitação após o ponto de interrupção. Se nenhum parâmetro de cache for definido, o sistema usa o cache implícito para identificar prefixos comuns automaticamente, mas os acertos de cache não são garantidos. Para reutilizar conteúdo específico de forma confiável, habilite o cache automático ou defina pontos de interrupção de cache.

Uso básico

Defina um ponto de interrupção de cache no bloco de conteúdo que deseja reutilizar. O sistema usa o final desse bloco de conteúdo como ponto de interrupção e trata toda a entrada desde o início da solicitação até esse ponto como o prefixo de cache: a primeira solicitação cria o cache, e as solicitações posteriores com o mesmo prefixo dentro do período de validade o lerão. O prefixo de cache deve conter pelo menos 1.024 tokens.
  • Compatível com OpenAI Chat Completions
  • Compatível com OpenAI Responses
  • Compatível com Anthropic
Adicione prompt_cache_breakpoint com o valor {"mode": "explicit"} ao bloco de conteúdo que será armazenado em cache em messages. O content da mensagem que contém o ponto de interrupção deve ser um array:
messages=[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": long_text,
        "prompt_cache_breakpoint": {"mode": "explicit"},  # <-- Ponto de interrupção de cache
      },
      {"type": "text", "text": "Resuma este documento."},  # O conteúdo após o ponto de interrupção não faz parte deste cache
    ],
  }
],
O marcador de bloco de conteúdo existente "cache_control": {"type": "ephemeral"} continua compatível e é usado da mesma forma que prompt_cache_breakpoint. Para o mesmo usuário, o cache com o mesmo prefixo pode ser reutilizado entre os dois marcadores. Para novas integrações, recomendamos prompt_cache_breakpoint.
Use apenas um dos marcadores prompt_cache_breakpoint e cache_control em uma mesma solicitação.
O exemplo a seguir envia duas solicitações: a primeira cria o cache e a segunda mantém o mesmo prefixo e altera apenas a pergunta para ler o cache.
Python
import os
from openai import OpenAI

client = OpenAI(
  # Se a variável de ambiente não estiver configurada, substitua a linha a seguir por: api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # Este é o URL da região de China (Pequim). Ao chamar, substitua WorkspaceId pelo ID real do espaço de trabalho. O URL varia conforme a região.
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Documento longo que será reutilizado. O prefixo de cache deve conter pelo menos 1024 tokens.
long_text = "<Documento longo fixo>" * 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"}},  # <-- Ponto de interrupção de cache
          {"type": "text", "text": question},  # O conteúdo após o ponto de interrupção pode mudar a cada solicitação
        ],
      }
    ],
    extra_body={
      "enable_thinking": False,
    },
  )
  return completion.usage.prompt_tokens_details

ask("Resuma este documento.")  # Primeira solicitação: cria o cache
details = ask("Liste os três pontos principais deste documento.")  # Segunda solicitação: lê o cache
print(f"Cache lido: {details.cached_tokens} tokens, cache criado: {details.cache_write_tokens} tokens")
Na segunda solicitação, cached_tokens é o número de tokens lidos do cache e cache_write_tokens é o número de tokens criados por esta solicitação. Se o prefixo não mudar, cache_write_tokens será 0. Os números são apenas ilustrativos e os valores reais dependem do comprimento do documento.

Usar vários pontos de interrupção

Se o prompt for composto por várias partes que mudam com frequências diferentes, você pode definir um ponto de interrupção para cada parte. Por exemplo, um prompt de atendimento ao cliente geralmente inclui a persona do sistema (que muda pouco), os resultados de recuperação da base de conhecimento (que mudam conforme o tópico da pergunta) e o histórico da conversa (que cresce continuamente). Ao definir um ponto de interrupção no final de cada parte, a persona do sistema ainda pode gerar acertos de cache mesmo quando o conteúdo da base de conhecimento mudar. Cada solicitação mantém no máximo os últimos 4 pontos de interrupção válidos. Pontos de interrupção adicionais não têm efeito. Quando o cache automático está habilitado, o ponto de interrupção automático ocupa um desses 4 espaços.

Renovação quando o ponto de interrupção se move

O sistema só cria ou renova pontos de interrupção na solicitação atual. Depois que o ponto de interrupção se move, o período de validade do ponto de interrupção anterior não é estendido, mesmo que seu cache seja lido. Por exemplo, com o mesmo TTL, o ponto de interrupção da solicitação anterior está no token 2048 e a solicitação atual o move para o token 3072 sem manter o ponto de interrupção anterior. Se o ponto de interrupção anterior estiver dentro do escopo de pesquisa e ainda não tiver expirado, a solicitação atual lê os primeiros 2048 tokens do cache e armazena os 1024 tokens seguintes em cache. O sistema só cria ou renova o ponto de interrupção no token 3072. O cache no token 2048 não é renovado.

Uso avançado

O Qwen4 adiciona os dois recursos a seguir ao uso básico. Você pode combiná-los:
  • Cache automático: o sistema coloca automaticamente um ponto de interrupção no final da entrada, adequado para conversas de vários turnos.
  • TTL do cache: escolha 5 minutos ou 1 hora.

Cache automático

Com o cache automático, o sistema coloca automaticamente um ponto de interrupção no final da entrada de cada solicitação, então você não precisa mover o ponto de interrupção à medida que a conversa cresce. O ponto de interrupção automático não inclui o sufixo de modelo usado para iniciar a geração da resposta. O cache automático pode ser usado junto com os pontos de interrupção de cache descritos em Uso básico. Se já houver um ponto de interrupção manual no final da entrada, o ponto de interrupção não será colocado duas vezes.
  • Compatível com OpenAI Chat Completions
  • Compatível com OpenAI Responses
  • Compatível com Anthropic
Defina prompt_cache_options no nível superior da solicitação e configure mode como implicit. Com o SDK Python da OpenAI, passe-o por extra_body:
completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "Resuma este documento: " + long_text}],
  extra_body={
    "enable_thinking": False,
    "prompt_cache_options": {"mode": "implicit"},  # <-- Habilita o cache automático
  },
)
Os valores de prompt_cache_options.mode e seus comportamentos são os seguintes:
ConfiguraçãoPonto de interrupção automáticoComportamento do cache
mode é implicitColocadoTanto o ponto de interrupção automático no final da entrada quanto os pontos de interrupção manuais têm efeito
mode é explicit com pontos de interrupção manuaisNão colocadoCria ou lê o cache nos pontos de interrupção manuais
mode é explicit sem pontos de interrupção manuaisNão colocadoUsa o cache implícito
prompt_cache_options é omitido, é null ou {}, ou apenas ttl é definidoNão colocadoArmazena em cache nos pontos de interrupção manuais, se existirem; caso contrário, usa o cache implícito
Quando mode é implicit, o cache do ponto de interrupção automático é usado e segue as regras de TTL e cobrança desta página. Isso é diferente do cache implícito usado quando nenhum parâmetro de cache é definido. Definir mode como explicit significa apenas que nenhum ponto de interrupção automático é colocado. Isso não desativa o cache implícito. mode se aplica apenas à solicitação atual.
O exemplo completo a seguir habilita o cache automático e envia duas vezes a mesma solicitação de documento longo: a primeira cria o cache e a segunda o lê.
  • Compatível com OpenAI Chat Completions
  • Compatível com OpenAI Responses
  • Compatível com Anthropic
import os
from openai import OpenAI

client = OpenAI(
  # Se a variável de ambiente não estiver configurada, substitua a linha a seguir por: api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # Este é o URL da região de China (Pequim). Ao chamar, substitua WorkspaceId pelo ID real do espaço de trabalho. O URL varia conforme a região.
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Documento longo que será reutilizado. O prefixo de cache deve conter pelo menos 1024 tokens.
long_text = "<Documento longo fixo>" * 400

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

for i in range(1, 3):
  details = ask()
  print(f"Solicitação {i}: cache lido {details.cached_tokens} tokens, cache criado {details.cache_write_tokens} tokens")
A saída é semelhante à seguinte. O número real de tokens depende do comprimento do documento:
Solicitação 1: cache lido 0 tokens, cache criado 2048 tokens
Solicitação 2: cache lido 2048 tokens, cache criado 0 tokens
A entrada da segunda solicitação é idêntica à da primeira, então a segunda lê o cache criado pela primeira.

Definir o TTL do cache

O tempo de vida do cache (TTL) pode ser 5m (5 minutos) ou 1h (1 hora). O valor padrão é 5m. Quando o cache gera um acerto dentro do período de validade, ele é renovado automaticamente. Para obter mais informações, consulte Regras de renovação.
  • Compatível com OpenAI Chat Completions
  • Compatível com OpenAI Responses
  • Compatível com Anthropic
Defina em prompt_cache_options.ttl no nível superior da solicitação. O valor se aplica a todos os pontos de interrupção da solicitação:
extra_body={
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "1h",  # <-- O TTL do cache é de 1 hora
  },
},
Se prompt_cache_options.ttl não for definido, o ttl do último marcador cache_control da solicitação será usado. Se esse marcador não tiver ttl, ou se a solicitação não tiver nenhum marcador cache_control, o TTL será 5m.O TTL se aplica apenas ao cache explícito. Ao definir ttl, defina também pontos de interrupção de cache ou habilite o cache automático.

Regras de renovação

Para a primeira solicitação, ou depois que o cache expirar, o cache é criado com o TTL da solicitação atual. Quando uma solicitação gera um acerto em um cache válido, a renovação e a cobrança seguem as regras abaixo:
  • A data de expiração mais tardia é mantida, junto com o nível mais alto. A nova data de expiração é aproximadamente a mais tardia entre a expiração original e o horário de início do processamento do cache da solicitação atual mais o TTL atual. Por exemplo, uma solicitação às 12:03 que gera um acerto em um cache de 5m que expira às 12:05 estende a expiração para aproximadamente 12:08. Como outro exemplo, quando uma solicitação de 5m gera um acerto em um cache de 1h válido, a renovação é calculada com base em 5m, mas o cache mantém o nível 1h, e as solicitações de 1h posteriores dentro do período de validade continuam sendo cobradas como leituras de cache.
  • Ao atualizar de 5m para 1h, a parte atualizada é cobrada como criação de cache de 1h. Quando uma solicitação de 1h gera um acerto em um cache de 5m válido, a parte que gerou o acerto é recriada com TTL de 1h e não é mais cobrada como leitura. Se parte do prefixo já tiver um cache de 1h válido, essa parte continua sendo cobrada como leitura, e apenas a parte restante e o novo prefixo são cobrados como criação. Em todos os outros casos (uma solicitação de 5m gera um acerto em um cache de 5m, uma solicitação de 5m gera um acerto em um cache de 1h, ou uma solicitação de 1h gera um acerto em um cache de 1h), a parte que gerou o acerto é cobrada como leitura.
O período de validade começa quando o processamento do cache da solicitação atual é iniciado. Ele não é somado à expiração original nem é reiniciado quando a resposta termina. O tempo de geração da resposta é contado dentro do período de validade, e a data de expiração real fornece um pouco de tempo de processamento adicional. O exemplo a seguir mostra solicitações sequenciais para o mesmo cache, criado com TTL de 1h às 12:00 e que expira originalmente às 13:00:
SolicitaçãoTTL desta solicitaçãoExpiração antes da solicitaçãoExpiração após a solicitação (aproximada)Cobrança e nível
Enviada às 12:205m13:0013:00Leitura de cache. 12:25 é anterior à expiração original, então a expiração permanece a mesma. Não é encurtada nem estendida até 13:20.
Enviada às 12:585m13:0013:03Leitura de cache. A expiração é estendida para 5 minutos após o início desta solicitação, e o cache mantém o nível 1h.
Enviada às 13:011h13:0314:01Leitura de cache. O cache já está no nível 1h, então não há criação devido à atualização.
O exemplo acima pressupõe solicitações sequenciais com o mesmo prefixo. Quando várias solicitações gravam no mesmo cache ao mesmo tempo, elas podem se sobrescrever e não há garantia de que a última data de expiração seja mantida.

Ver o uso do cache

O usage da resposta retorna o número de tokens lidos do cache e gravados no cache. Para saída em streaming com a API Chat Completions compatível com OpenAI, defina stream_options como {"include_usage": true} e leia o uso no último fragmento que contém usage.
  • Compatível com OpenAI Chat Completions
  • Compatível com OpenAI Responses
  • Compatível com Anthropic
A seguir está o usage quando o cache é criado pela primeira vez (somente entrada de texto, modo sem 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": {}
  }
}
CampoDescrição
prompt_tokensNúmero total de tokens de entrada, incluindo leitura de cache, gravação de cache e entrada que não usa cache. Não é reduzido pelos acertos de cache.
total_tokensSoma de prompt_tokens e completion_tokens
prompt_tokens_details.cached_tokensNúmero de tokens lidos do cache
prompt_tokens_details.cache_write_tokensNúmero de tokens gravados no cache
prompt_tokens_details.cache_creation_input_tokensNúmero de tokens gravados no cache. Igual a cache_write_tokens. Não some os dois.
prompt_tokens_details.cache_typeTipo de cache explícito. Sempre ephemeral.
prompt_tokens_details.cache_creationNúmero de tokens gravados no cache por TTL. A soma de ephemeral_5m_input_tokens e ephemeral_1h_input_tokens é igual ao número de tokens gravados no cache.
No exemplo acima, a entrada que não usa cache é 2304 − 0 − 2048 = 256 tokens. Todos os campos de cache são números brutos de tokens e não incluem multiplicadores de cobrança. Ao enviar novamente uma solicitação com o mesmo prefixo dentro do período de validade, cached_tokens será 2048, cache_write_tokens, cache_creation_input_tokens e os dois itens de cache_creation serão 0, e prompt_tokens permanecerá 2304.Os detalhes de entrada de imagem, áudio e vídeo são retornados conforme a entrada real. Os detalhes de saída, como thinking, são retornados conforme o modelo e a configuração. Os campos não aplicáveis são omitidos em vez de retornados como 0.

Práticas recomendadas

  • Use o cache automático para conversas de vários turnos. O ponto de interrupção automático avança à medida que a conversa cresce, então você não precisa ajustar pontos de interrupção a cada turno.
  • Coloque o conteúdo fixo no início. Coloque o conteúdo que não muda, como o prompt de sistema, as definições de ferramentas e os documentos de referência, no início da entrada. Coloque o conteúdo que muda a cada solicitação, como carimbos de data e hora e perguntas do usuário, no final.
  • Coloque o ponto de interrupção no último bloco de conteúdo idêntico em todas as solicitações. Não coloque o ponto de interrupção em um bloco de conteúdo que muda a cada solicitação. Caso contrário, cada solicitação criará um novo cache e nunca o lerá.
  • Adicione ao histórico, não o reescreva. Modificar, excluir ou reordenar mensagens anteriores ou definições de ferramentas impede que os caches posteriores gerem acertos.
  • Use vários pontos de interrupção para conteúdo que muda com frequências diferentes. Por exemplo, se as definições de ferramentas mudam pouco, mas os documentos de referência são atualizados diariamente, defina um ponto de interrupção no final de cada um.
  • Adicione um ponto de interrupção quando um turno adicionar muitos blocos de conteúdo. Cada ponto de interrupção pesquisa retroativamente até 20 blocos de conteúdo. Se um turno adicionar conteúdo além desse escopo, adicione um ponto de interrupção no meio.
  • Escolha o TTL de acordo com o intervalo de reutilização. Use 5m se o conteúdo for reutilizado em 5 minutos, pois cada acerto renova o cache. Use 1h se o intervalo de reutilização estiver entre 5 minutos e 1 hora.
  • Monitore os acertos de cache com os campos de uso. A taxa de acertos é o número de tokens lidos do cache dividido pelo total de tokens de entrada. Se a taxa de acertos for baixa, verifique se a posição do prefixo e os pontos de interrupção estão estáveis.

Cobrança

Os pontos de interrupção de cache afetam apenas a forma como os tokens de entrada são cobrados. Os tokens de saída são cobrados pelo preço padrão.
Tipo de token de entradaCobrança
Gravação de cache, TTL de 5mAproximadamente 125% do preço do token de entrada
Gravação de cache, TTL de 1hAproximadamente 200% do preço do token de entrada
Leitura de cacheQwen4-Max
Não lido do cache e não gravado no cachePreço do token de entrada
Se o prefixo de cache da solicitação atual contiver um cache válido existente, a parte existente será cobrada como leitura de cache, e apenas a parte nova será cobrada como gravação de cache. Para cobrança quando o TTL for atualizado de 5m para 1h, consulte Regras de renovação.

Limitações

  • Apenas os modelos da série Qwen4 são compatíveis.
  • O prefixo deve conter pelo menos 1.024 tokens. Prefixos menores não criam cache; a solicitação é concluída e os detalhes de gravação por TTL são omitidos.
  • Cada solicitação mantém no máximo os últimos 4 pontos de interrupção válidos. Quando o cache automático está habilitado, o ponto de interrupção automático ocupa um deles.
  • Com cada ponto de interrupção como ponto final, o sistema pesquisa retroativamente até 20 blocos de conteúdo. Se o cache a ser acessado estiver a mais de 20 blocos de conteúdo do ponto de interrupção, ele não poderá ser acessado.
  • O TTL só pode ser 5m ou 1h.

Perguntas frequentes

P: Uma solicitação pode gerar um acerto de cache sem nenhum parâmetro de cache?

Sim. Sem parâmetros de cache, o cache implícito é usado. O sistema identifica prefixos comuns automaticamente, mas os acertos de cache não são garantidos. Para gerar acertos de cache de forma confiável, defina pontos de interrupção de cache ou habilite o cache automático.

P: Por que o período de validade do cache não muda quando defino apenas o TTL?

O TTL se aplica apenas ao cache explícito. Se você definir apenas prompt_cache_options.ttl na API Chat Completions compatível com OpenAI, a solicitação usará o cache implícito. Adicione também pontos de interrupção manuais ou defina prompt_cache_options.mode como implicit.

P: Uma solicitação de 5m que gera um acerto em um cache de 1h encurta o período de validade do cache?

Não. A nova data de expiração é a mais tardia entre a expiração original e a renovação da solicitação atual, e o cache mantém o nível 1h. Para obter mais informações, consulte Regras de renovação.