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.
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ável | Tarefa variável |
|---|---|
| Versão aprovada do manual | Pergunta atual do cliente |
| Definições fixas das ferramentas | Resultados das ferramentas da tarefa atual |
| Ordem consistente das instruções | Saída solicitada nesta rodada |
| Serialização fixa do documento | Novas 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ção | O que conferir | Próximo experimento controlado |
|---|---|---|
| A primeira requisição não informa um prefixo reutilizável | Mínimo de tokens, posição do marcador e protocolo compatível | Mantenha a rota e inspecione a requisição serializada |
| A segunda requisição não informa leituras de cache | Prefixo exato, escopo do usuário e tempo decorrido | Compare os primeiros blocos de conteúdo byte a byte |
| Apenas parte da entrada foi armazenada | Onde termina o ponto de cache e o que mudou | Separe o documento estável da pergunta atual |
| Uma sequência que funcionava deixa de reutilizar o cache | Versão da referência, definições de ferramentas e serialização do cliente | Compare as requisições salvas com o último par que funcionou |
| Os campos de uso estão ausentes | Protocolo, formato da resposta e comportamento do streaming | Comece com uma resposta completa sem streaming |
| A chamada retorna erro de parâmetro | Suporte da rota e estrutura JSON | Reduza 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.


