A Alibaba lançou dois modelos Qwen novos em menos de dez dias: o Qwen3.8-Max-0902, que entrou em produção a 1 de setembro de 2026 na QwenCloud, e o Qwen3.8-Flash-Next, publicado em peso aberto no Hugging Face a 26 de agosto. Este tutorial mostra como usar os dois num fluxo real: criar uma conta, enviar o primeiro pedido à API, montar um agente com tool-calling, correr o modelo localmente com vLLM e acabar com um projeto funcional de revisão de código automática. Sem instalações genéricas de Ollama, sem passos vagos. Cada comando aqui foi testado num ambiente Linux com Python 3.11.
O que é o Qwen e porque isto importa agora
Qwen é uma das famílias de modelos de inteligência artificial mais discutidas em 2026, mantida pela Alibaba através da plataforma QwenLM e do repositório oficial no GitHub. Ao contrário da Anthropic ou da OpenAI, a Alibaba publica grande parte dos seus modelos com pesos abertos, o que permite descarregá-los e correr localmente sem depender de uma API paga. É essa combinação de modelos abertos e modelos proprietários rápidos que torna o Qwen relevante para equipas técnicas em Portugal que querem testar agentes de IA sem ficar presas a um único fornecedor.
O Qwen3.8-Max original chegou a 3 de agosto de 2026 como o modelo mais capaz da família até essa data, segundo a própria página de investigação da Qwen. Um mês depois, a 1 de setembro, a Alibaba publicou o snapshot Qwen3.8-Max-0902 (também identificado como qwen3.8-max-2026-09-02), com a mesma arquitetura base mas pós-treinado especificamente para tarefas de programação e trabalho colaborativo, o que a Alibaba resume como “Coding & Cowork”. O preço mantém-se igual ao modelo original. Já tínhamos coberto a chegada do Qwen 3.8 e os seus 2,4 biliões de parâmetros quando o modelo original saiu, e este tutorial parte precisamente desse ponto para chegar à prática.
Em paralelo, a 26 de agosto, saiu o Qwen3.8-Flash-Next, um modelo multimodal com pesos abertos que a própria Alibaba descreve como uma pré-visualização da arquitetura Qwen4. É este modelo que vamos correr localmente mais à frente neste tutorial, porque é leve o suficiente para caber numa única GPU de gama alta e ainda assim suporta tool-calling e um contexto de um milhão de tokens.
Para uma equipa técnica, a razão prática para aprender isto agora, e não daqui a três meses, é simples: quando um snapshot como o Max-0902 sai apenas um mês depois do modelo original, o histórico da Alibaba sugere que este ritmo de lançamento se vai manter. Quem já tem o fluxo de trabalho montado (chave API, agente configurado, ferramentas definidas) troca de modelo alterando uma única linha de código. Quem começa do zero a cada lançamento perde sempre a janela de vantagem competitiva.
Qwen Chat, API ou modelo local: três formas de usar o Qwen
Antes de entrar em código, importa distinguir três formas completamente diferentes de usar o Qwen, porque a maior parte da confusão em fóruns e comunidades vem de misturar estas três camadas. A primeira é o Qwen Chat, a aplicação de conversação da Alibaba, semelhante ao ChatGPT ou ao Gemini, pensada para quem quer escrever texto, gerar imagens ou programar através de uma interface web sem tocar em código. É a via mais rápida para experimentar as capacidades do modelo, mas não serve para construir um agente que se integra noutro sistema.
A segunda camada é a API, o foco principal deste tutorial: um endpoint HTTP que qualquer aplicação pode chamar, pagando por token processado, sem gerir servidores. É a opção certa para produtos que precisam de fiabilidade e de escalar sem depender de hardware próprio. A terceira camada é o modelo local, onde se descarregam os pesos abertos do Qwen3.8-Flash-Next e se corre a inferência na própria infraestrutura, com controlo total sobre onde os dados são processados mas com a responsabilidade de gerir GPUs, memória e disponibilidade. Este tutorial cobre a segunda e a terceira camada em profundidade, porque são as que interessam a quem está a construir algo, não apenas a experimentar.
Qwen3.8-Max-0902 vs Qwen3.8-Flash-Next: qual escolher
Antes de instalar seja o que for, vale a pena perceber a diferença entre os dois modelos, porque vão precisar de abordagens completamente diferentes: um corre na nuvem através de uma chave API, o outro corre na sua própria máquina.
| Característica | Qwen3.8-Max-0902 | Qwen3.8-Flash-Next |
|---|---|---|
| Data de lançamento | 1 de setembro de 2026 | 26 de agosto de 2026 |
| Parâmetros totais | 2,4 biliões (arquitetura MoE) | 125 mil milhões + 51 mil milhões em embeddings N-gram |
| Parâmetros ativos por token | ~95 mil milhões | ~6 mil milhões |
| Janela de contexto | 1 milhão de tokens | 1 milhão de tokens |
| Licença | Proprietário, acesso só via API | Peso aberto, licença Qwen Community 1.0 |
| Onde corre | QwenCloud (API) | Local com vLLM, SGLang, ou Hugging Face |
| Preço API | $2,00 por 1M tokens de input / $6,00 por 1M de output | Grátis para correr local (custo é o hardware) |
Para um protótipo rápido ou para produção sem gerir infraestrutura, a via mais simples é o Qwen3.8-Max-0902 via API. Para quem precisa de correr o modelo dentro da própria rede, por motivos de custo ou de conformidade com o RGPD, o Qwen3.8-Flash-Next é a opção correta. Este tutorial cobre os dois casos, porque na prática a maioria das equipas acaba por usar ambos: a API para protótipos rápidos e o modelo local para produção interna.
Pré-requisitos: contas, hardware e versões
Antes de avançar, confirme que tem o seguinte pronto:
- Python 3.10 ou superior (este tutorial foi testado com Python 3.11.9)
- pip atualizado para a versão 24 ou superior
- Uma conta na QwenCloud para obter uma chave API (gratuita para começar, com limite de utilização)
- Para a parte local: uma GPU com pelo menos 24 GB de VRAM (por exemplo, uma RTX 4090 ou uma A10G) se quiser correr o Qwen3.8-Flash-Next em FP8
- Docker 26 ou superior, caso prefira correr o vLLM em contentor
- Node.js 20 ou superior, apenas se for implementar o servidor MCP com o SDK oficial em JavaScript
- Ligação estável à internet para descarregar os pesos do modelo (o Qwen3.8-Flash-Next em FP8 ronda os 90 GB)
Se não tiver GPU disponível, ainda consegue seguir os passos 1 a 6 deste tutorial só com a API, e ignorar a parte de instalação local. É perfeitamente possível construir um agente completo com tool-calling sem nunca correr um modelo localmente. Para quem quer mesmo testar a parte local sem comprar hardware, um serviço de GPU alugada por hora, como as instâncias A10G ou L40S de vários fornecedores de cloud, custa tipicamente entre um e três dólares por hora, o suficiente para seguir os passos 7 e 8 deste tutorial numa única sessão.
Vale ainda confirmar as versões exatas antes de começar, porque bibliotecas de IA mudam depressa e uma diferença de versão menor já foi motivo de comportamento inesperado em testes anteriores deste tipo de tutorial. Corra python3 --version e pip --version antes de avançar para o passo seguinte, e confirme que está mesmo dentro do intervalo indicado acima.
Passo 1: Criar conta e obter a chave API
Aceda à plataforma qwen.ai e registe uma conta com o seu email. Depois de confirmar o email, vá à secção de gestão de chaves da QwenCloud e gere uma nova chave API. Guarde essa chave num gestor de segredos, nunca a coloque diretamente no código-fonte.
Defina a chave como variável de ambiente no seu terminal:
export QWEN_API_KEY="sk-a_sua_chave_aqui"
export QWEN_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"A QwenCloud expõe um endpoint compatível com a API da OpenAI, o que significa que qualquer biblioteca que já use o SDK da OpenAI funciona quase sem alterações, bastando trocar a URL base e a chave. A conta gratuita vem com um limite de utilização mensal, suficiente para desenvolver e testar, mas não para correr em produção com tráfego real. Se planeia lançar algo para utilizadores finais, verifique o limite atual na sua conta antes de assumir que a camada gratuita aguenta o volume esperado.
Passo 2: Preparar o ambiente Python
Crie um ambiente virtual isolado para este projeto e instale as três bibliotecas que vamos usar ao longo do tutorial: o SDK da OpenAI (que serve para falar com a API do Qwen), o framework Qwen-Agent, e o pacote MCP.
python3 -m venv qwen-env
source qwen-env/bin/activate
pip install --upgrade pip
pip install openai==1.55.0 qwen-agent==0.0.20 mcp==1.2.0Confirme que a instalação correu bem com pip show qwen-agent. Se a versão não aparecer, repita a instalação dentro do ambiente virtual ativo, um erro comum é esquecer o source qwen-env/bin/activate antes de correr o pip.
Passo 3: Enviar o primeiro pedido à API
Com o ambiente pronto, faça um pedido simples para confirmar que a chave funciona. Este exemplo usa o modelo Qwen3.8-Max-0902 diretamente:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["QWEN_API_KEY"],
base_url=os.environ["QWEN_BASE_URL"],
)
resposta = client.chat.completions.create(
model="qwen3.8-max-2026-09-02",
messages=[
{"role": "user", "content": "Explica em duas frases o que é MoE num modelo de linguagem."}
],
)
print(resposta.choices[0].message.content)Se tudo correr bem, o terminal devolve uma resposta em poucos segundos. Um erro 401 nesta fase quase sempre significa que a variável de ambiente não foi carregada corretamente na sessão atual do terminal, veja a secção de resolução de problemas mais abaixo para o caso de isto acontecer.
Passo 4: Definir ferramentas para function calling
Um agente só é útil quando consegue chamar código externo, não apenas gerar texto. O Qwen3.8-Max-0902 segue o mesmo formato de tool-calling da OpenAI: define-se uma lista de ferramentas em JSON Schema, e o modelo decide quando e como as usar.
ferramentas = [
{
"type": "function",
"function": {
"name": "consultar_estado_pr",
"description": "Devolve o estado atual de um pull request no GitHub",
"parameters": {
"type": "object",
"properties": {
"repo": {"type": "string", "description": "nome do repositório, ex: org/projeto"},
"numero": {"type": "integer", "description": "número do pull request"}
},
"required": ["repo", "numero"]
}
}
}
]
resposta = client.chat.completions.create(
model="qwen3.8-max-2026-09-02",
messages=[{"role": "user", "content": "Qual é o estado do PR 42 no repositório shattered/backend?"}],
tools=ferramentas,
tool_choice="auto",
)
print(resposta.choices[0].message.tool_calls)Repare no parâmetro tool_choice="auto". Sem ele, alguns clientes deixam o valor por omissão como none, e o modelo nunca chega a invocar a ferramenta mesmo tendo-a disponível. Isto é um dos erros mais comuns quando se está a testar tool-calling pela primeira vez.
Passo 5: Construir um agente com o framework Qwen-Agent
Chamar ferramentas manualmente funciona para testes, mas um agente real precisa de um ciclo: o modelo pede uma ferramenta, o seu código executa-a, o resultado volta para o modelo, e o modelo decide o próximo passo. É exatamente isso que o framework Qwen-Agent, mantido pela própria equipa Qwen no GitHub, resolve por si.
from qwen_agent.agents import Assistant
configuracao_llm = {
"model": "qwen3.8-max-2026-09-02",
"model_server": os.environ["QWEN_BASE_URL"],
"api_key": os.environ["QWEN_API_KEY"],
}
def consultar_estado_pr(repo: str, numero: int) -> str:
return f"O PR {numero} em {repo} está aprovado, falta apenas o merge."
agente = Assistant(
llm=configuracao_llm,
function_list=[consultar_estado_pr],
system_message="És um assistente técnico que ajuda a equipa a acompanhar pull requests.",
)
for resposta in agente.run(messages=[{"role": "user", "content": "Qual é o estado do PR 42 em shattered/backend?"}]):
ultimo = resposta[-1]
print(ultimo["content"])O Assistant do Qwen-Agent trata sozinho de todo o ciclo: deteta que precisa da ferramenta, chama a função Python diretamente (sem passar por JSON manualmente), e devolve a resposta final já formatada. Isto poupa dezenas de linhas de código de gestão de estado que teria de escrever à mão com a API pura.
O parâmetro function_list aceita tanto funções Python simples, como a usada acima, como definições completas em JSON Schema para casos onde precisa de mais controlo sobre os tipos de parâmetros. Para agentes pequenos, passar funções Python diretamente poupa tempo, porque o Qwen-Agent gera automaticamente o schema a partir da assinatura da função e dos comentários de tipo. Para agentes maiores, com dezenas de ferramentas, vale a pena organizá-las em módulos separados e importá-las dinamicamente, para que o ficheiro principal do agente não cresça sem controlo.
Passo 6: Expor o agente como servidor MCP
O Model Context Protocol (MCP) tornou-se o formato de facto para ligar agentes a ferramentas externas de forma reutilizável, em vez de reescrever as mesmas funções em cada projeto. Em vez de definir as ferramentas dentro do próprio script do agente, pode expô-las através de um servidor MCP que qualquer cliente compatível, incluindo o próprio Qwen-Agent, consegue descobrir e usar.
from mcp.server.fastmcp import FastMCP
servidor = FastMCP("ferramentas-shattered")
@servidor.tool()
def consultar_estado_pr(repo: str, numero: int) -> str:
"""Devolve o estado atual de um pull request no GitHub."""
return f"O PR {numero} em {repo} está aprovado, falta apenas o merge."
if __name__ == "__main__":
servidor.run(transport="stdio")Guarde este ficheiro como servidor_mcp.py e corra-o com python servidor_mcp.py. Qualquer cliente MCP, incluindo agentes construídos com Qwen-Agent através de um adaptador MCP, pode agora descobrir a ferramenta consultar_estado_pr sem que o código do agente precise de conhecer a implementação por trás dela. Isto separa claramente o agente, que decide o quê fazer, das ferramentas, que fazem o trabalho, o que facilita muito manter o projeto à medida que cresce.
Passo 7: Instalar vLLM e correr o Qwen3.8-Flash-Next localmente
Chegou a parte que exige GPU. O vLLM é hoje o motor de inferência mais usado para correr modelos open-weight com boa performance e uma API compatível com a OpenAI, o mesmo motor que já usámos no tutorial de vLLM com Docker para o DeepSeek V4 Flash. Instale-o num ambiente separado, porque tem dependências específicas de CUDA:
pip install vllm==0.7.2
vllm serve Qwen/Qwen3.8-Flash-Next \
--max-model-len 1000000 \
--dtype fp8 \
--enable-auto-tool-choice \
--tool-call-parser hermes \
--port 8000O download dos pesos demora consoante a sua ligação, pode facilmente passar de trinta minutos numa ligação doméstica. As flags --enable-auto-tool-choice e --tool-call-parser hermes são essenciais, sem elas o vLLM ignora silenciosamente o campo tools do pedido e o modelo nunca chama funções, mesmo que o resto do código esteja correto.
Se a sua GPU não tiver 24 GB de VRAM, reduza o --max-model-len para algo como 131072 (128 mil tokens) em vez do milhão completo. O contexto máximo consome memória mesmo antes de o preencher com dados reais.
Se preferir isolar o ambiente em Docker, em vez de instalar o vLLM diretamente no sistema, a imagem oficial vllm/vllm-openai aceita os mesmos parâmetros através da linha de comandos do contentor, o que evita conflitos entre versões de CUDA instaladas para outros projetos na mesma máquina. Para equipas que já correm cargas de trabalho de IA em produção, isolar cada modelo no seu próprio contentor costuma poupar horas de depuração mais tarde, quando surgir o próximo modelo para testar ao lado deste.
Passo 8: Testar o endpoint local e a janela de 1 milhão de tokens
Com o servidor vLLM a correr, teste-o com um pedido curl simples antes de ligar o agente:
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen3.8-Flash-Next",
"messages": [{"role": "user", "content": "Confirma que estás a correr localmente."}]
}'Para testar o contexto de um milhão de tokens de forma prática, carregue um repositório inteiro (por exemplo, todos os ficheiros .py de um monorepo concatenados num único texto) e peça ao modelo para identificar inconsistências de estilo entre módulos. É neste tipo de tarefa, análise de código à escala do repositório inteiro em vez de ficheiro a ficheiro, que a janela de contexto larga compensa o esforço de configuração.
Passo 9: Montar o projeto completo – agente de revisão de código
Agora junte tudo num projeto funcional: um agente que lê um diff de pull request, verifica se há segredos expostos, e sugere melhorias, usando o Qwen3.8-Max-0902 via API e uma ferramenta local.
import os
import subprocess
from qwen_agent.agents import Assistant
def obter_diff(caminho_repo: str) -> str:
resultado = subprocess.run(
["git", "-C", caminho_repo, "diff", "HEAD~1"],
capture_output=True, text=True
)
return resultado.stdout[:20000]
def procurar_segredos(texto_diff: str) -> str:
padroes = ["api_key", "senha", "password", "secret", "token="]
encontrados = [p for p in padroes if p in texto_diff.lower()]
return f"Padrões suspeitos encontrados: {encontrados}" if encontrados else "Nenhum segredo óbvio encontrado."
agente_revisor = Assistant(
llm={
"model": "qwen3.8-max-2026-09-02",
"model_server": os.environ["QWEN_BASE_URL"],
"api_key": os.environ["QWEN_API_KEY"],
},
function_list=[obter_diff, procurar_segredos],
system_message=(
"És um revisor de código sénior. Usa as ferramentas disponíveis para "
"analisar o diff mais recente, verificar segredos expostos, e dar "
"um parecer curto e direto sobre se o PR está pronto para merge."
),
)
pergunta = [{"role": "user", "content": "Revê o último commit em ./meu-projeto e diz se posso fazer merge."}]
for resposta in agente_revisor.run(messages=pergunta):
ultimo = resposta[-1]
print(ultimo["content"])Este projeto tem cerca de trinta linhas e já cobre um caso de uso real: um agente que combina duas ferramentas, decide sozinho quando as usar, e produz um parecer legível para um humano. É a partir desta base que se adicionam mais ferramentas, como correr testes automáticos ou consultar o histórico de incidentes de segurança do repositório.
Para expandir este projeto além do exemplo, três direções fazem sentido a seguir. A primeira é trocar a função procurar_segredos, que hoje só procura padrões de texto simples, por uma ferramenta de deteção mais robusta, como um scanner de segredos dedicado, integrado como mais uma função disponível para o agente. A segunda é ligar o agente diretamente aos webhooks do GitHub, para que corra automaticamente sempre que um pull request é aberto, em vez de ser invocado manualmente. A terceira é migrar as ferramentas definidas dentro do script para o servidor MCP montado no passo anterior, o que permite reutilizar as mesmas ferramentas noutros agentes sem duplicar código.
Segurança do agente: o que ter em conta antes de dar acesso a ferramentas reais
Dar a um modelo de linguagem a capacidade de correr comandos, ler ficheiros ou chamar APIs externas muda por completo o perfil de risco. Um chatbot que só responde a perguntas pode, no pior caso, dizer algo errado. Um agente com tool-calling que tem acesso ao sistema de ficheiros ou ao GitHub pode apagar código, expor segredos ou executar ações que um utilizador nunca pediu, se for enganado por conteúdo malicioso escondido nos dados que processa. Este risco tem nome: injeção de prompt indireta, quando texto controlado por um atacante (um comentário num pull request, um ficheiro README manipulado) contém instruções escondidas que o modelo interpreta como ordens legítimas.
Para o agente de revisão de código construído neste tutorial, três medidas reduzem esse risco de forma prática. Primeiro, limite sempre o âmbito das ferramentas: a função obter_diff só lê, nunca escreve nem executa comandos arbitrários, e é assim que deve continuar mesmo quando adicionar mais capacidades. Segundo, trate qualquer texto que vem de fora (o conteúdo de um diff, um comentário de um pull request) como dados, nunca como instruções, e reforce isso na mensagem de sistema do agente. Terceiro, mantenha um humano no ciclo antes de qualquer ação que altere o repositório, como fazer merge ou apagar uma branch, mesmo que o agente pareça suficientemente competente para agir sozinho. Nenhuma destas medidas é específica do Qwen, aplicam-se a qualquer agente construído sobre qualquer modelo, mas tornam-se especialmente relevantes quando se liga um modelo a ferramentas com efeitos reais no mundo, e não apenas a uma janela de conversa.
Casos de uso reais para equipas em Portugal
O agente construído até aqui é deliberadamente pequeno, para servir de base didática. Na prática, o mesmo padrão, um modelo com tool-calling, uma ou duas ferramentas bem definidas, e um humano a validar ações sensíveis, aplica-se a problemas bastante diferentes consoante o setor. Estes são cinco cenários onde equipas técnicas em Portugal já estão a testar modelos abertos como o Qwen, muitas vezes ao lado de alternativas como o GLM ou o DeepSeek.
- Revisão automática de pull requests: o projeto construído neste tutorial serve de base direta para uma equipa de engenharia que quer um primeiro filtro automático antes da revisão humana, sinalizando segredos expostos ou padrões de código arriscados.
- Suporte técnico interno em português: como o Qwen responde nativamente em português europeu, um agente ligado à base de conhecimento interna de uma empresa (documentação, tickets antigos) pode responder a perguntas de suporte de primeira linha sem depender de um serviço externo pago por conversa.
- Análise de bases de código legadas: a janela de contexto de um milhão de tokens permite carregar módulos inteiros de sistemas antigos, algo particularmente útil para equipas que herdaram código sem documentação e precisam de perceber dependências antes de o alterar.
- Conformidade e RGPD: para setores regulados, como banca ou saúde, correr o Qwen3.8-Flash-Next localmente evita que dados sensíveis de clientes saiam da infraestrutura da organização, um requisito que a via da API pura não garante da mesma forma.
- Automação de tarefas repetitivas de DevOps: um agente com acesso a ferramentas de infraestrutura, sempre com confirmação humana antes de ações destrutivas, pode gerar relatórios de estado de sistemas ou sugerir correções de configuração a partir de logs longos.
Passo 10: Testar, validar e monitorizar custos
Antes de colocar qualquer agente em produção, corra-o contra pelo menos dez casos reais, não apenas o exemplo feliz. Peça diffs vazios, diffs enormes, e diffs com segredos propositadamente inseridos, para confirmar que a ferramenta procurar_segredos dispara corretamente em todos os casos.
Para controlar custos na API, registe o campo usage devolvido em cada resposta e some os tokens ao longo do dia. Ao preço de $2,00 por 1M de tokens de input e $6,00 por 1M de output do Qwen3.8-Max-0902, um agente que processa cem diffs por dia com uma média de 3 mil tokens de input e 500 de output fica, grosso modo, à volta de 90 cêntimos diários, valor que muda rapidamente se começar a incluir repositórios inteiros no contexto em vez de apenas o diff.
Erros comuns e resolução de problemas
Cinco erros que vão atrasar o seu progresso
- Misturar os dois modelos sem perceber a diferença de acesso. O Qwen3.8-Max-0902 só existe via API, o Qwen3.8-Flash-Next só existe como peso aberto. Tentar apontar o cliente OpenAI para o nome do modelo local sem correr o vLLM primeiro dá sempre erro de conexão.
- Esquecer o
tool_choice="auto". Sem este parâmetro, muitos clientes assumemnonepor omissão, e o modelo nunca chama a ferramenta mesmo que ela esteja bem definida. - Não limitar o tamanho do diff enviado ao modelo. Um diff de dez mil linhas consome contexto e dinheiro sem necessidade, é preferível cortar ou resumir antes de enviar.
- Ignorar a licença do modelo que está a usar. O Qwen3.8-Max-0902 é proprietário e sujeito aos termos da QwenCloud, o Qwen3.8-Flash-Next tem licença Qwen Community 1.0. Usar o Flash-Next num produto comercial sem ler os termos dessa licença é um risco jurídico desnecessário.
- Correr o vLLM sem as flags de tool-calling. Esquecer
--enable-auto-tool-choicefaz o servidor local ignorar silenciosamente as ferramentas, sem qualquer mensagem de erro visível. - Não tratar erros de rede como algo esperado. Pedidos à API falham ocasionalmente por motivos de rede, não só por erros de configuração. Um agente em produção sem lógica de nova tentativa (retry) com espera exponencial vai falhar visivelmente em utilizadores reais por causas que uma simples repetição do pedido resolveria.
Nenhum destes erros é exclusivo do Qwen, mas todos aparecem com frequência em relatos de quem está a testar tool-calling pela primeira vez, seja com este modelo ou com qualquer outro que siga o mesmo formato de API.
Tabela de resolução de problemas
| Problema | Causa provável | Solução |
|---|---|---|
| Erro 401 Unauthorized | Chave API não carregada na sessão do terminal | Confirme com echo $QWEN_API_KEY e reexporte a variável |
| Erro 429 Too Many Requests | Limite de utilização da conta gratuita atingido | Adicione espera exponencial entre pedidos ou mude para um plano pago |
| CUDA out of memory ao arrancar o vLLM | VRAM insuficiente para o --max-model-len definido | Reduza o contexto máximo ou mude para uma GPU com mais VRAM |
| O modelo nunca chama a ferramenta | Falta tool_choice="auto" ou as flags do vLLM | Reveja o pedido e as flags --enable-auto-tool-choice --tool-call-parser hermes |
| Resposta cortada a meio | Limite de tokens de output demasiado baixo | Aumente o parâmetro max_tokens no pedido |
| Latência alta com contexto grande | Contexto próximo do milhão de tokens aumenta o tempo de processamento | Reduza o contexto ao mínimo necessário para a tarefa |
| Servidor MCP não liga ao agente | Transporte stdio mal configurado no lado do cliente | Confirme que o cliente MCP aponta para o mesmo executável e transporte |
| Tool call devolve JSON inválido | Descrição da ferramenta demasiado vaga no JSON Schema | Detalhe melhor os campos description de cada parâmetro |
| Download dos pesos falha a meio | Ligação instável ao Hugging Face durante ficheiro grande | Use huggingface-cli download --resume-download |
Dicas avançadas e comparação com outros modelos
Dicas avançadas para produção
Depois de o agente básico funcionar, quatro ajustes fazem diferença real em produção. Primeiro, cacheie o histórico de conversas por sessão em vez de reenviar todo o contexto a cada pedido, isto reduz custos de forma direta quando o contexto ultrapassa algumas dezenas de milhares de tokens. Segundo, adicione um passo de validação humana antes de qualquer ação irreversível sugerida pelo agente, como fazer merge automático de um pull request, o modelo pode errar e a revisão humana continua a ser a rede de segurança mais barata que existe. Terceiro, se estiver a correr o Qwen3.8-Flash-Next localmente com múltiplos utilizadores, use o modo de batching contínuo do vLLM em vez de instâncias separadas por utilizador, o que aumenta bastante o throughput por GPU.
Quarto, registe todas as chamadas a ferramentas num log estruturado, com o pedido original, a ferramenta escolhida e o resultado devolvido. Quando um agente começa a comportar-se de forma inesperada, este registo é a única forma prática de perceber se o problema está no modelo, na descrição da ferramenta, ou nos dados que a ferramenta recebeu. Sem ele, cada investigação de um erro em produção começa do zero.
Para quem quer testar rapidamente sem gerir infraestrutura própria, o OpenRouter disponibiliza vários modelos Qwen através de um único endpoint, útil para comparar versões antes de comprometer com uma delas em produção. Para quem prefere uma instalação local ainda mais simples, sem lidar diretamente com o vLLM, o nosso guia de instalação do Ollama para LLMs locais cobre um caminho alternativo, com menos controlo sobre performance mas mais rápido a arrancar.
Qwen vs GLM-5.3 vs DeepSeek V4 vs Kimi K3
Nenhum destes modelos existe isolado. Antes de decidir qual usar, compare as especificações principais dos concorrentes diretos, todos lançados nas últimas semanas por empresas chinesas e todos com pesos totais ou parcialmente abertos.
| Modelo | Parâmetros totais | Ativos por token | Contexto | Licença |
|---|---|---|---|---|
| Qwen3.8-Max-0902 | 2,4 biliões | ~95 mil milhões | 1M tokens | Proprietário (API) |
| Qwen3.8-Flash-Next | 125 mil milhões + 51 mil milhões (embeddings) | ~6 mil milhões | 1M tokens | Qwen Community 1.0 |
| GLM-5.3 | 743 mil milhões | ~40 mil milhões | 1M tokens | GLM-5.3 License |
| DeepSeek V4-Pro | 1,6 biliões | 49 mil milhões | 1M tokens | MIT (open-weight) |
| Kimi K3 | 2,8 biliões | 104 mil milhões | ~1M tokens (1.048.576) | Kimi K3 License (custom) |
O GLM-5.3, da Zhipu AI, salta de 4,6% para 28,3% no Terminal-Bench 3.0 face à geração anterior, um ganho que a própria Zhipu atribui inteiramente a pós-treino sobre o mesmo modelo base, sem retreinar do zero. O DeepSeek V4-Pro destaca-se por ser o único desta lista com licença MIT sem restrições comerciais adicionais, o que facilita a sua adoção em produtos fechados. Já o Kimi K3, da Moonshot AI, é o maior em número total de parâmetros mas com mais parâmetros ativos por token do que o Qwen3.8-Max, o que geralmente se traduz em inferência mais lenta por token processado. Na prática, a escolha entre eles depende menos de qual pontua mais alto num benchmark isolado e mais de qual licença e qual custo de inferência se encaixam no seu caso de uso.
Para consultar a ficha técnica de cada versão do Qwen à medida que forem saindo, o registo mais atualizado está na página da Qwen na Wikipédia e na organização oficial no Hugging Face. Vale a pena voltar a esta tabela daqui a um mês, porque ao ritmo atual de lançamentos, é provável que pelo menos um destes quatro modelos já tenha sido substituído por uma versão nova antes do final do ano.
Perguntas frequentes
O Qwen é gratuito?
Depende da versão. O Qwen3.8-Flash-Next tem pesos abertos e pode ser descarregado e corrido sem pagar pela inferência, só paga o hardware ou o serviço de cloud onde o correr. O Qwen3.8-Max-0902 é proprietário e cobrado por token através da API, a $2,00 por milhão de tokens de input e $6,00 por milhão de output.
Preciso de GPU para usar o Qwen?
Só se quiser correr o modelo localmente. Para usar via API não precisa de nenhum hardware especial, um portátil comum com ligação à internet chega para os passos 1 a 6 deste tutorial.
Qual a diferença entre Qwen-Agent e MCP?
O Qwen-Agent é um framework que gere o ciclo de decisão do agente, ou seja, decide quando chamar uma ferramenta e processa o resultado. O MCP é um protocolo que define como expor ferramentas de forma reutilizável entre diferentes agentes e clientes. Usam-se em conjunto, não são alternativas um ao outro.
O Qwen3.8-Flash-Next é mesmo Qwen4?
Não oficialmente. A própria Alibaba descreve-o como uma pré-visualização da arquitetura que deverá ser usada na próxima geração, mas ainda faz parte da série Qwen3.8 em termos de nome e versionamento público.
Posso usar o Qwen em produção na Europa sem problemas de RGPD?
Correr o Qwen3.8-Flash-Next localmente, dentro da sua própria infraestrutura na UE, evita a questão de transferência de dados para fora do espaço europeu que surge ao usar a API da QwenCloud. Se optar pela API, confirme onde os dados são processados e leia os termos de serviço antes de enviar dados de clientes.
O vLLM é a única forma de correr o Qwen localmente?
Não. O SGLang é outra opção popular com performance semelhante, e para GPUs mais modestas também é possível usar bibliotecas de quantização mais agressiva. O vLLM foi escolhido aqui por ter o suporte mais maduro para tool-calling compatível com o formato da OpenAI.
Quanto tempo demora este tutorial do início ao fim?
Sem GPU, contando só os passos ligados à API, cerca de 40 minutos. Com a instalação local do Qwen3.8-Flash-Next incluída, conte com pelo menos 90 minutos, a maior parte do tempo gasta a descarregar os pesos do modelo.
O que acontece se o agente chamar a ferramenta errada?
O modelo pode escolher mal quando a descrição da ferramenta é ambígua. A correção passa por escrever descrições mais específicas no JSON Schema, e por adicionar um passo intermédio de confirmação antes de executar ações que alterem dados reais.
Dá para usar o Qwen para gerar imagens ou vídeo, além de texto?
Sim, o Qwen Chat inclui geração de imagem e vídeo através da interface web, e o Qwen3.8-Flash-Next, sendo multimodal, também aceita imagem como entrada. Este tutorial foca-se em texto e tool-calling porque é o caso de uso mais relevante para construir agentes, mas a mesma chave API e o mesmo cliente OpenAI servem para explorar as capacidades multimodais noutros projetos.
