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.
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:
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.
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.
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.
O Qwen4 adiciona os dois recursos a seguir ao uso básico. Você pode combiná-los:
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.
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ê.
A saída é semelhante à seguinte. O número real de tokens depende do comprimento do documento:
A entrada da segunda solicitação é idêntica à da primeira, então a segunda lê o cache criado pela primeira.
O tempo de vida do cache (TTL) pode ser
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:
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.
O
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.
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.
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.
O TTL se aplica apenas ao cache explícito. Se você definir apenas
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.
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_controlda API Chat Completions compatível com OpenAI continua compatível e é usado da mesma forma queprompt_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.
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 O marcador de bloco de conteúdo existente Na segunda solicitação,
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:"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.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
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 Os valores de
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:prompt_cache_options.mode e seus comportamentos são os seguintes:| Configuração | Ponto de interrupção automático | Comportamento do cache |
|---|---|---|
mode é implicit | Colocado | Tanto 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 manuais | Não colocado | Cria ou lê o cache nos pontos de interrupção manuais |
mode é explicit sem pontos de interrupção manuais | Não colocado | Usa o cache implícito |
prompt_cache_options é omitido, é null ou {}, ou apenas ttl é definido | Não colocado | Armazena 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.- Compatível com OpenAI Chat Completions
- Compatível com OpenAI Responses
- Compatível com Anthropic
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 Se
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: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.
| Solicitação | TTL desta solicitação | Expiração antes da solicitação | Expiração após a solicitação (aproximada) | Cobrança e nível |
|---|---|---|---|---|
| Enviada às 12:20 | 5m | 13:00 | 13:00 | Leitura 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:58 | 5m | 13:00 | 13:03 | Leitura 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:01 | 1h | 13:03 | 14:01 | Leitura de cache. O cache já está no nível 1h, então não há criação devido à atualização. |
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
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,
usage quando o cache é criado pela primeira vez (somente entrada de texto, modo sem thinking):| Campo | Descrição |
|---|---|
prompt_tokens | Nú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_tokens | Soma de prompt_tokens e completion_tokens |
prompt_tokens_details.cached_tokens | Número de tokens lidos do cache |
prompt_tokens_details.cache_write_tokens | Número de tokens gravados no cache |
prompt_tokens_details.cache_creation_input_tokens | Número de tokens gravados no cache. Igual a cache_write_tokens. Não some os dois. |
prompt_tokens_details.cache_type | Tipo de cache explícito. Sempre ephemeral. |
prompt_tokens_details.cache_creation | Nú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. |
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
5mse o conteúdo for reutilizado em 5 minutos, pois cada acerto renova o cache. Use1hse 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 entrada | Cobrança |
|---|---|
| Gravação de cache, TTL de 5m | Aproximadamente 125% do preço do token de entrada |
| Gravação de cache, TTL de 1h | Aproximadamente 200% do preço do token de entrada |
| Leitura de cache | Qwen4-Max |
| Não lido do cache e não gravado no cache | Preço do token de entrada |
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
5mou1h.
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.