Cache de prompts do Qwen4: reutilize o contexto do agente e investigue falhas

Configure um ponto de cache no Qwen4, compare duas requisições e interprete o uso. Inclui gerador local e diagnóstico de falhas de reutilização.

Um bloco de impressão reutilizável produz impressões iguais enquanto um pequeno detalhe laranja muda.

Se um agente consulta repetidamente o mesmo material de referência, coloque o contexto estável antes de um ponto de cache e a pergunta variável depois dele. Em seguida, confira as leituras de cache informadas. Enviar prompts semelhantes e receber uma resposta mais rápida não basta para comprovar que o cache funcionou.

Este guia aborda a API direta do Qwen4 no QwenCloud, verificada em 16 de novembro de 2026, e complementa nosso guia de acesso e migração do Qwen4-Max. O gerador de requisições abaixo funciona localmente, sem chave. Não executamos requisições pagas de cache para este artigo: os exemplos descrevem um experimento reproduzível, sem apresentar economia ou latência medidas.

Defina o que deve permanecer idêntico

Considere um agente de análise de atendimento que recebe o mesmo manual de produto e responde a uma pergunta diferente do cliente a cada rodada. O manual é um bom candidato à reutilização. Um horário, identificador aleatório ou pergunta variável inserido antes dele pode alterar o início da requisição.

Divida a entrada explicitamente em duas partes:

Contexto estávelTarefa variável
Versão aprovada do manualPergunta atual do cliente
Definições fixas das ferramentasResultados das ferramentas da tarefa atual
Ordem consistente das instruçõesSaída solicitada nesta rodada
Serialização fixa do documentoNovas evidências que alteram a análise

Não mantenha informações incorretas apenas para aumentar a taxa de acertos. Quando o manual muda, um novo prefixo é adequado. Registre a versão e o hash do documento para distinguir uma falha de cache causada por uma atualização intencional de uma mudança acidental de formatação.

O guia oficial de cache do Qwen4 documenta um prefixo mínimo de 1.024 tokens, correspondência exata do prefixo no escopo do mesmo usuário e suporte a Chat Completions, Responses e Anthropic Messages. O recurso de cache explícito do Qwen4 não é compatível com DashScope. Contar palavras ou caracteres não equivale a contar tokens com exatidão.

Gere duas requisições localmente

Use um documento sintético ou sem informações sensíveis que você tenha autorização para enviar ao provedor escolhido. Salve-o como reference.txt. Mantenha seu conteúdo inalterado entre a primeira e a segunda requisição.

Salve o código abaixo como build_cache_requests.py:

import hashlib
import json
from pathlib import Path

reference = Path("reference.txt").read_text(encoding="utf-8")
if not reference.strip():
    raise SystemExit("reference.txt is empty")

questions = [
    "List the three main responsibilities described in the reference.",
    "Which responsibilities in the reference require an explicit approval?"
]
for number, question in enumerate(questions, 1):
    payload = {
        "model": "qwen4-max",
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": reference,
                    "prompt_cache_breakpoint": {"mode": "explicit"}
                },
                {"type": "text", "text": question}
            ]
        }],
        "enable_thinking": False,
        "max_completion_tokens": 1024
    }
    Path(f"request-{number}.json").write_text(
        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
    )
print("Reference SHA256:", hashlib.sha256(reference.encode()).hexdigest())
print("Created two request files; no network requests were sent.")

Execute python3 build_cache_requests.py. Inspecione o JSON gerado: o primeiro bloco de conteúdo e seu ponto de cache devem ser exatamente iguais; apenas a pergunta do segundo bloco deve mudar. Esse script não conta os tokens da referência. Use os recursos de contagem do provedor ou um tokenizador já validado para o modelo e confira o mínimo antes de enviar uma requisição cobrada.

O ponto de cache pertence a um bloco de conteúdo, por isso content é um array. Este exemplo usa um único marcador; não o combine com uma segunda sintaxe de marcação de cache na mesma requisição. A primeira chamada pretende criar um contexto reutilizável, e a segunda pretende reutilizá-lo. Os dados de uso efetivamente retornados determinam se isso ocorreu.

Envie as requisições em sequência para a rota correta

Configure uma chave de pagamento por uso do QwenCloud para a região escolhida, seguindo o guia oficial de chaves. O comando abaixo usa o endpoint Chat Completions de Singapura. Uma chave do Ofox ou do Token Plan não pode substituí-la indistintamente.

curl --silent --show-error --fail-with-body --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request-1.json -o response-1.json

Confira o resultado HTTP, o corpo da resposta e os dados de uso antes de continuar. Depois que a primeira requisição terminar com sucesso, repita o comando com request-2.json e response-2.json. Execute dentro do prazo de validade documentado do cache. Não envie as duas simultaneamente neste experimento: a sequência facilita distinguir criação de reutilização.

Um timeout não comprova que o provedor deixou de processar a tarefa. Confira os registros da requisição antes de tentar novamente e estabeleça um orçamento explícito para o experimento. Este guia não executa nenhum dos comandos em seu nome.

O prazo padrão do cache é de cinco minutos; o guia oficial também documenta uma opção de uma hora. No primeiro experimento, mantenha o padrão. Alterar prazo e prefixo juntos dificulta o diagnóstico de uma falha. O tempo de geração também consome parte do prazo disponível.

Leia os dados de uso do protocolo utilizado

Para o experimento com Chat Completions acima, inspecione usage.prompt_tokens_details. Diferencie leituras de cache, gravações de cache e entrada comum. A simples presença de um campo de cache não comprova que todo o documento foi reutilizado.

import json
from pathlib import Path

for name in ["response-1.json", "response-2.json"]:
    response = json.loads(Path(name).read_text(encoding="utf-8"))
    usage = response.get("usage") or {}
    details = usage.get("prompt_tokens_details") or {}
    print(name, {
        "input_tokens": usage.get("prompt_tokens"),
        "cache_read_tokens": details.get("cached_tokens"),
        "cache_write_tokens": details.get("cache_write_tokens"),
        "output_tokens": usage.get("completion_tokens")
    })

Valores ausentes permanecem como None; o script não converte silenciosamente a falta de informação em zero. Guarde as duas respostas brutas de forma privada. Se o provedor retornar a estrutura de uso de outro protocolo, consulte a documentação desse protocolo em vez de renomear campos até o script parecer funcionar.

Por exemplo, o QwenCloud documenta os detalhes de cache de Responses em input_tokens_details, enquanto o formato compatível com Anthropic tem campos próprios de leitura e criação. Alguns campos são aliases: somar um alias à contagem correspondente superestimaria o uso. Consulte as tabelas de cada protocolo na referência de uso do cache.

Investigue a falha sem alterar tudo ao mesmo tempo

ObservaçãoO que conferirPróximo experimento controlado
A primeira requisição não informa um prefixo reutilizávelMínimo de tokens, posição do marcador e protocolo compatívelMantenha a rota e inspecione a requisição serializada
A segunda requisição não informa leituras de cachePrefixo exato, escopo do usuário e tempo decorridoCompare os primeiros blocos de conteúdo byte a byte
Apenas parte da entrada foi armazenadaOnde termina o ponto de cache e o que mudouSepare o documento estável da pergunta atual
Uma sequência que funcionava deixa de reutilizar o cacheVersão da referência, definições de ferramentas e serialização do clienteCompare as requisições salvas com o último par que funcionou
Os campos de uso estão ausentesProtocolo, formato da resposta e comportamento do streamingComece com uma resposta completa sem streaming
A chamada retorna erro de parâmetroSuporte da rota e estrutura JSONReduza ao exemplo documentado com um único marcador

Conversas longas de agentes têm um limite adicional: o guia oficial documenta uma busca retroativa de até 20 blocos de conteúdo por ponto de cache e a retenção apenas dos últimos quatro pontos efetivos, incluindo um ponto automático quando utilizado. Se o crescimento do histórico levar o prefixo útil para fora dessa janela, revise a organização dos blocos e coloque um ponto explícito no limite do contexto estável. Não apague resultados de ferramentas ou histórico de raciocínio necessários apenas para forçar um acerto. Guarde as requisições antes e depois da mudança e verifique os dados de uso resultantes.

Não interprete toda falha de cache como regressão do modelo. O harness pode reordenar ferramentas, acrescentar texto de sistema dinâmico no início ou mudar a formatação do documento. Registre uma representação sem dados sensíveis do prefixo estável e seu hash antes de atribuir a falha ao provedor.

Para erros de identificador ou endpoint, consulte nosso guia de diagnóstico de modelo não encontrado (em inglês). Se o cache funciona, mas um agente de várias rodadas perde resultados de ferramentas, trata-se de outro problema, relacionado ao histórico; veja como preservar chamadas de ferramentas entre rodadas (em inglês).

Calcule a economia de tarefas completas e aprovadas

Uma gravação de cache pode ter um custo diferente de uma leitura ou da entrada comum. Compare a sequência completa, incluindo a gravação inicial e todas as respostas geradas, com a mesma sequência sem cache. Use as tarifas atuais da região em preços do QwenCloud, sem copiar valores de outra região ou de uma promoção de prévia.

Registre por chamada: versão do documento, tokens de entrada, tokens lidos do cache, tokens gravados no cache, entrada comum, tokens de saída, duração e resultado da validação. Não conte aliases duas vezes. Um desconto na entrada em cache não representa o mesmo percentual de desconto na tarefa inteira do agente: saídas e ferramentas externas podem responder por boa parte do total.

Confira a resposta, além da cobrança. No exemplo com duas perguntas, verifique de forma independente se as responsabilidades e exigências de aprovação citadas estão na referência. Uma resposta mais barata, mas sem fundamento no documento, não é um resultado aprovado.

Este fluxo usa diretamente o QwenCloud. Nossa consulta ao catálogo do Ofox em 16 de novembro não listou o Qwen4. Para rotas já existentes no Ofox, confira o modelo exato no catálogo, use a autenticação do Ofox e siga o tratamento de erros do Ofox. Esses documentos não comprovam que os novos parâmetros de cache do QwenCloud estejam disponíveis no Ofox.

Perguntas frequentes

Repetir um prompt comprova que o Qwen4 usou o cache?
Não. Verifique os campos de leitura de cache retornados pelo provedor. Uma resposta mais rápida ou um texto repetido, por si só, não comprova um acerto de cache.
Posso usar esses parâmetros de cache no Ofox?
Este artigo descreve a API direta do Qwen4 no QwenCloud. A consulta ao catálogo do Ofox em 16 de novembro não listou o Qwen4; não presuma que o mesmo modelo ou contrato de cache esteja disponível pelo Ofox.