A Qwen API é oferecida pelo Alibaba Cloud Model Studio (Bailian), e o DashScope é seu sistema de interface nativo. O Model Studio oferece tanto a interface compatível com OpenAI quanto a interface nativa DashScope. Para a maioria das equipes, começar pela interface compatível com OpenAI é o caminho mais simples: SDKs, frameworks de agentes e ferramentas existentes normalmente exigem apenas três mudanças — API Key, URL base e nome do modelo.

As armadilhas reais não estão em "conseguir chamar", mas na região da URL base, na validade do nome do modelo, em como interpretar streaming e em quais parâmetros não podem ser copiados da OpenAI. Este artigo faz a ponte funcionar com uma requisição mínima e depois cobre chamadas de ferramenta, diagnóstico de erros e checklist de migração.

Nota: Qwen, Tongyi Qianwen, Alibaba Cloud, Model Studio (Bailian) e DashScope são marcas ou nomes de produto do Alibaba Group e empresas associadas. Este artigo é apenas uma explicação técnica e não tem vínculo de afiliação, representação ou endosso com o Alibaba Group. URL base, nomes de modelo, tamanho de contexto e critérios de cobrança podem mudar; valem a documentação oficial do Alibaba Cloud Model Studio e a página de preços do site.

1. Preparação antes de integrar

Confirme três itens antes de começar:

  • Uma API Key válida e compatível com a região de destino.
  • A URL base correta; China continental, site internacional e endereço do gateway não podem ser misturados.
  • Um nome de modelo realmente disponível no momento; não copie exemplos de artigos antigos.

Recomenda-se validar autenticação e rede com curl antes de conectar o SDK. Assim, em caso de erro, fica mais fácil distinguir chave, endereço e código.

2. URL base: primeiro a região, depois o domínio

O caminho da interface compatível com OpenAI é fixo em /compatible-mode/v1, e o endpoint de chat acrescenta /chat/completions. O domínio varia por região; as formas comuns são:

Cenário URL base compatível com OpenAI Observação
China continental (Pequim, domínio compartilhado antigo) https://dashscope.aliyuncs.com/compatible-mode/v1 Compatível com código antigo; ainda disponível
Singapura (site internacional) https://dashscope-intl.aliyuncs.com/compatible-mode/v1 Conta e chave do site internacional
Virgínia, EUA https://dashscope-us.aliyuncs.com/compatible-mode/v1 Apenas IPv4; recursos conforme documentação
Hong Kong https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 Região e chave independentes
Workspace dedicado https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 Recomendado para produção; melhor throughput e isolamento
ZSQH AI Gateway https://ai.zhongshangqihang.com/v1 Entrada unificada para vários modelos

Alguns pontos-chave. Primeiro, a API Key é vinculada à região; chamadas entre regiões normalmente retornam 401 e invalid_api_key, o que indica incompatibilidade entre chave e endereço, não necessariamente chave inválida. Segundo, contas da China continental e do site internacional são sistemas distintos: chaves, faturas e listas de modelos não são compartilhadas. Terceiro, o domínio dedicado ao workspace só aceita a chave daquele workspace, mas oferece melhor throughput e isolamento de tráfego, sendo adequado à produção; o domínio compartilhado antigo facilita testes rápidos e uso entre workspaces.

Se a equipe usa vários modelos e não quer manter regiões, cotas e múltiplos conjuntos de chaves, pode criar uma chave unificada no ZSQH AI Gateway e trocar a URL base pelo endereço da última linha da tabela.

3. Como escolher o nome do modelo

A lista de modelos do Model Studio é atualizada com frequência. Tomando como exemplo a página oficial atual, a seção de geração de texto lista modelos Qwen como qwen3.8-max, qwen3.7-plus e qwen3.8-flash. Pela nomenclatura, entende-se de forma aproximada: max prioriza o teto de capacidade, plus prioriza equilíbrio e flash prioriza baixa latência e custo; posicionamento e tamanho de contexto seguem a documentação oficial, e preços mudam, valendo a página de preços.

Não escolha apenas "o mais forte". Atendimento, classificação em lote e moderação de conteúdo costumam ser mais econômicos em faixas de baixa latência; análise de documentos longos e agentes complexos pedem configuração superior. Transforme o nome do modelo em item de configuração, não em valor fixo no código, para facilitar trocas futuras.

Há duas armadilhas comuns. Nomes de tutoriais antigos como qwen-max e qwen-plus podem ter sido ajustados; confirme na lista de modelos do console antes de integrar. Para capacidade vetorial, use a série de embeddings (por exemplo, qwen3.7-text-embedding), cujo corpo de requisição é diferente do chat. O Qwen-Audio não suporta o protocolo compatível com OpenAI e exige a interface nativa DashScope.

4. Primeira chamada com curl

Prepare primeiro a variável de ambiente, para evitar que a chave apareça no histórico de comandos:

export DASHSCOPE_API_KEY="your_key_here"

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {"role": "system", "content": "Você é um assistente técnico conciso."},
      {"role": "user", "content": "Explique em três frases o que é um gateway de API."}
    ],
    "temperature": 0.7
  }'

Em uma resposta normal, observe três campos: choices[0].message.content é a resposta, usage é o consumo e finish_reason indica o motivo do encerramento. Se retornar 401, verifique chave e região; se retornar 404 e ModelNotFound, verifique o nome do modelo e se ele está ativado naquela região.

5. Chamada com o SDK Python e streaming

O SDK da OpenAI precisa ser 1.0 ou superior. Apontando a URL base para o Model Studio, a chamada é basicamente igual à da OpenAI:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

stream = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "Escreva uma apresentação de produto com no máximo cem palavras."}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

No streaming, atenção: o primeiro chunk pode conter apenas informações de papel, com content vazio; não presuma que todo chunk tem texto. Com stream_options={"include_usage": True}, o consumo aparece no último chunk. Em HTTP direto, a resposta é SSE e termina com data: [DONE]. Quando o usuário fecha a página, o servidor deve cancelar a requisição upstream o quanto antes para evitar geração e cobrança desnecessárias.

6. Chamadas de ferramenta e diferenças de parâmetros

As chamadas de ferramenta seguem o formato tools e tool_choice da OpenAI. Quando o modelo retorna message.tool_calls, é preciso interpretar function.arguments de cada chamada como JSON, executar a função local e devolver o resultado como mensagem com role: "tool". Em fluxos de vários turnos, cada rodada precisa reenviar tools. Em produção, valide parâmetros e permissões e controle timeout; não confie diretamente nos parâmetros gerados pelo modelo.

A documentação oficial de compatibilidade atualmente impõe duas restrições às ferramentas: apenas alguns modelos são listados como suportados, e tools não pode ser usado junto com stream=True por enquanto. Lista de modelos e capacidades são atualizadas continuamente; teste com o modelo de destino antes do lançamento. Se o negócio precisa chamar ferramentas durante o streaming, considere a interface nativa DashScope ou transformar a chamada de ferramenta em uma etapa sem streaming.

Ao migrar da OpenAI, observe também estas diferenças de parâmetros:

  • messages: apenas messages[0] pode ter papel system; user e assistant normalmente se alternam, e a última mensagem deve ser user.
  • temperature: faixa de [0, 2); a documentação não recomenda 0.
  • top_p: faixa de (0, 1.0).
  • seed: inteiro sem sinal de 64 bits.
  • stop: os elementos do array não podem misturar token ID e string.
  • system_fingerprint: atualmente retorna string vazia.
  • Parâmetros estendidos como enable_search: normalmente enviados via extra_body, e não são suportados por todos os modelos.
  • Campos como response_format e frequency_penalty: não têm compatibilidade assegurada na documentação; não presuma comportamento igual ao da OpenAI.

7. Tabela de erros comuns

Sintoma Código comum Causa possível Tratamento
401 InvalidApiKey / invalid_api_key Chave errada, região incompatível, chave de plano misturada Verificar região e tipo de chave e da URL base
404 ModelNotFound / model_not_found Nome do modelo errado, modelo inexistente na região, não ativado Consultar a lista de modelos no console
404 model_not_supported Modelo não suporta o modo compatível com OpenAI Usar a interface nativa DashScope
403 AccessDenied / Workspace.AccessDenied Permissão insuficiente de workspace ou modelo Verificar permissão do workspace
403 AllocationQuota.FreeTierOnly Cota gratuita esgotada Recarregar ou ajustar o plano
429 Série Throttling Limite de requisições, tokens ou concorrência Reduzir concorrência, backoff, solicitar cota
400 Arrearage Conta inadimplente Recarregar e tentar novamente
400 Range of input length... Entrada acima do limite de contexto Comprimir o prompt ou dividir em partes
400 DataInspectionFailed Entrada ou saída bloqueada pela segurança de conteúdo Ajustar o conteúdo e tentar novamente

Retry só funciona para 429, 5xx e timeout de rede. Erros 401, 403, 404 e de parâmetro não melhoram com nova tentativa e apenas consomem tempo e cota. Ao diagnosticar, registre o Request ID da resposta e consulte os logs do console; isso é muito mais rápido do que adivinhar.

8. Checklist de migração da OpenAI

  1. Faça backup dos prompts, parâmetros de modelo e conjunto de avaliação atuais.
  2. Crie uma chave Qwen compatível com a região de destino; não reutilize chave de outro fornecedor.
  3. Transforme URL base e nome de modelo em itens de configuração.
  4. Verifique a regra de papéis de messages: primeiro system, último user.
  5. Verifique o parsing de streaming e a forma de contabilizar usage.
  6. Faça uma rodada de regressão de chamadas de ferramenta com ferramentas reais.
  7. Compare qualidade, latência e consumo com o mesmo lote de amostras.
  8. Ajuste retry, timeout e concorrência e observe por uma semana antes de mudar tudo.
  9. Registre o Request ID nos logs e mantenha um interruptor de rollback.

9. Perguntas frequentes (FAQ)

1. A Qwen API é compatível com a OpenAI?

As interfaces de chat mais usadas são compatíveis, mas ainda existem diferenças de vínculo regional, ordem de papéis, faixa de parâmetros e restrições de chamada de ferramenta. Valide item a item conforme a documentação oficial e não presuma comportamento idêntico.

2. China continental e site internacional podem compartilhar uma chave?

Não. Conta, chave, domínio de acesso e fatura são independentes entre os dois sites. Chamadas entre regiões ou sites normalmente retornam 401 e invalid_api_key.

3. Devo usar o domínio antigo ou o domínio dedicado ao workspace?

Para testes rápidos, o domínio compartilhado antigo serve; para produção, recomenda-se o domínio dedicado ao workspace, com melhor throughput e isolamento de tráfego. O essencial é que a chave corresponda à região e ao workspace do domínio.

4. Por que recebo model_not_found com o nome do modelo correto?

As causas comuns são: o modelo não existe naquela região, não está ativado, o nome tem diferença de maiúsculas e minúsculas ou a versão foi descontinuada. Vale a lista atual de modelos do console.

5. tools pode ser usado com stream?

A documentação oficial de compatibilidade atualmente indica que os dois não podem ser usados juntos e que a chamada de ferramenta só é listada para alguns modelos. Capacidades e restrições mudam com os modelos; teste com o modelo de destino antes do lançamento ou use a interface nativa DashScope.

Leituras relacionadas