Qwen3 GGUF: corrigir tokenizer e chat template

#Os três sintomas a reconhecer

Três sinais indicam um problema no tokenizer ou no template de chat, em vez de um problema no modelo: uma tag de reflexão (geralmente “think”) que se abre sem nunca se fechar na resposta, uma geração que continua indefinidamente sem parar no final lógico da resposta, ou um modelo que responde fora do assunto como se não tivesse entendido que lhe foi feita uma pergunta. Nos três casos, o problema não está no próprio modelo: a estrutura do texto que ele recebe como entrada está malformada.

#A causa raiz: o chat template

Um modelo de linguagem nunca recebe diretamente suas mensagens: um template de chat as formata (marcadores de turnos de fala, prompt de sistema, marcadores de início/fim) antes de transformá-las em tokens. Se esse template estiver ausente, mal escolhido ou mal interpretado pelo motor de inferência, o modelo recebe um texto que não se parece com os textos usados em seu treinamento e produz saídas de qualidade inferior, mesmo que os próprios pesos do modelo e o tokenizer estejam corretos.

#A opção --jinja: a primeira coisa a verificar

A documentação oficial da Qwen recomenda explicitamente adicionar --jinja ao iniciar um GGUF Qwen3 com llama.cpp: essa opção instrui o programa a usar o template de chat incorporado ao arquivo GGUF. Esse uso é apresentado como o método preferível a um template genérico escolhido por padrão pelo mecanismo.

./llama-cli -hf Qwen/Qwen3-8B-GGUF:Q8_0 --jinja --color -ngl 99 -fa -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 -c 40960 -n 32768 --no-context-shift

Se o seu comando de inicialização não contém --jinja, essa é a primeira correção a tentar antes de qualquer outra hipótese. Muitos scripts e interfaces criados antes da adoção generalizada dessa opção ainda a omitem, o que explica boa parte dos relatos de “respostas quebradas” com arquivos GGUF Qwen3, embora esses arquivos sejam válidos.

#Um bug de parsing conhecido e corrigido

Um erro específico afetou o llama.cpp no template de chat do Qwen3: o mecanismo de templates não conseguia analisar uma sintaxe Jinja de fatiamento de lista (messages[::-1]), usada para percorrer o histórico da conversa em ordem inversa na lógica de chamada de ferramentas. O erro relatado era uma falha de análise que apontava precisamente para essa linha do template.

1. 01
   Identificar a versão do llama.cpp utilizada

   Uma versão antiga pode não incluir a correção de parsing para a sintaxe de slicing usada pelo template Qwen3.
2. 02
   Atualizar para uma versão recente

   Recompilar ou baixar novamente um binário atualizado do llama.cpp resolve esse caso específico, sem precisar modificar o GGUF em si.
3. 03
   Se a atualização não for possível

   Fornecer um template personalizado simplificado via --chat-template-file, evitando a construção Jinja problemática.

#llama-server e llama-cli não se comportam da mesma forma

Um comportamento relatado no repositório llama.cpp: ativar --jinja com llama-server pode fazer desaparecer o bloco de reflexão (o conteúdo entre as tags de pensamento) da resposta, enquanto esse mesmo bloco permanece visível ao usar llama-cli com a mesma opção e o mesmo modelo. Se sua integração depende da presença do conteúdo de reflexão na saída (para observabilidade ou depuração), não se trata de um problema de tokenizer, mas de uma diferença no tratamento entre os dois binários — verificar qual dos dois você está usando antes de investigar mais.

Essa distinção tem uma consequência prática para quem cria uma integração baseada no llama.cpp em vez de uma simples sessão interativa: um pipeline de testes que valida o formato de saída no llama-cli e depois é implantado em produção usando o llama-server pode apresentar uma regressão silenciosa nesse ponto específico sem que nenhum parâmetro da aplicação tenha mudado. Documentar explicitamente qual binário atende ao ambiente de produção e testar nesse binário específico, em vez daquele usado no desenvolvimento local, evita essa armadilha.

#Forçar a desativação do modo de reflexão

O Qwen3 oferece um mecanismo de alternância entre o modo de reflexão e o modo direto no nível do template de chat. A documentação oficial do Qwen indica, no entanto, que esse mecanismo de desativação forçada (hard switch) não está exposto nativamente no llama.cpp: definir enable_thinking como false via opções de linha de comando pode ser ignorado dependendo da versão, como mostram diversos relatos recentes sobre variantes do Qwen3.5.

A solução alternativa documentada pela Qwen consiste em fornecer um template personalizado via --chat-template-file, no qual enable_thinking é definido explicitamente como false no próprio template, em vez de ser passado como parâmetro no momento da requisição. Isso é mais confiável do que um parâmetro de execução que depende do suporte exato da sua versão do llama.cpp.

Ponto a esclarecer para evitar generalizações indevidas: o relato #20182 (« enable_thinking param cannot turn off thinking ») refere-se especificamente ao Qwen3.5-9B na build 8215, continua com a etiqueta « bug-unconfirmed » no repositório llama.cpp e foi fechado sem resolução (« not planned »). Nada prova que o mesmo comportamento afete um GGUF do Qwen3 original (em oposição ao Qwen3.5): se você encontrar esse sintoma em um Qwen3 clássico, trate-o como um caso a ser isolado e relatado separadamente, em vez de considerá-lo uma confirmação automática desse ticket.

#Verificar a origem de um GGUF de terceiros

Parte dos problemas com o tokenizer nos arquivos GGUF Qwen3 não vem do llama.cpp, mas do próprio arquivo GGUF: uma conversão feita com uma versão antiga das ferramentas de conversão, ou um arquivo em que o tokenizer foi mal exportado, produz sintomas semelhantes (ausência de fim de geração, tokens especiais mal reconhecidos). Antes de procurar um bug no mecanismo de inferência, comparar o tamanho e a data de publicação do seu arquivo GGUF com os de um repositório reconhecido (Qwen oficial ou requantizações documentadas) permite descartar essa hipótese.

Uma referência simples para distinguir rapidamente entre um problema de arquivo e um problema de configuração: se o mesmo GGUF funcionar corretamente em outra máquina ou com outra versão do llama.cpp, o próprio arquivo provavelmente não é o problema. Por outro lado, se baixar novamente os arquivos do mesmo repositório várias vezes na mesma máquina reproduzir sistematicamente o sintoma, a hipótese mais provável passa a ser a configuração local (versão do binário, opções de inicialização), em vez do arquivo.

#Quantização baixa demais: chamadas de ferramentas malformadas

Um último sintoma, distinto dos três primeiros, afeta especificamente o uso do Qwen3 como agente com chamadas de ferramentas: em vez de um problema de formatação de texto, a própria chamada de ferramenta chega truncada, com argumentos vazios ou mal estruturados (JSON inválido). Um guia comunitário de solução de problemas dedicado ao llama.cpp documenta que a estrutura das chamadas de ferramentas é sensível ao nível de quantização: quantizações abaixo de 4 bits (Q3, Q2, IQ) geram chamadas de ferramentas malformadas mesmo quando o template do chat é corretamente aplicado com --jinja.

Esse ponto pode passar despercebido porque parece, à primeira vista, um problema clássico de tokenizer: uma resposta truncada faz pensar imediatamente em um template de chat mal fechado. A diferença prática está no contexto em que o sintoma aparece: um problema de template afeta todas as respostas, incluindo o texto simples sem chamada de ferramenta, enquanto um problema de quantização nas chamadas de ferramentas geralmente deixa as respostas em texto livre intactas e só se manifesta na estrutura JSON estrita esperada pelo protocolo de chamada de ferramentas.

#Tabela rápida de solução de problemas

• Entender os formatos GGUF e safetensors
• Ficha técnica do Qwen3-32B
• llama.cpp: o que é e vale a pena abandonar o Ollama?
• Escolher sua quantização (Q4, Q5, Q8, FP16)
• Fonte: documentação oficial Qwen para llama.cpp
• Fonte: bug de parsing do template de chat do Qwen3 (llama.cpp)
• Fonte: diferença de comportamento server/cli no bloco de reflexão
• Fonte: guia de solução de problemas do llama.cpp (quantização e chamadas de ferramentas)