Criar Conclusão de Chat (qwen-mt-turbo)

Dado um prompt, o modelo retornará uma ou mais previsões de conclusão (Completion) e também pode retornar as probabilidades de tokens alternativos (Tokens) em cada posição. Esta interface é usada principalmente para dialogar com o modelo e processar tarefas de linguagem natural, como tradução automática.

Documentação Oficial de Referência: Alibaba Cloud Model Studio - Modelo de Tradução Automática

Informações da API

Protocolo de Requisição: HTTP/HTTPS
Método de Requisição: POST
Caminho da Requisição (Endpoint): https://api.codingplanx.ai/v1/chat/completions

Cabeçalhos da Requisição (Headers)

Nome do Parâmetro	Obrigatório	Tipo	Exemplo de Valor	Descrição
Content-Type	Sim	string	`application/json`	Formato dos dados
Accept	Sim	string	`application/json`	Formato de retorno esperado
Authorization	Não	string	`Bearer {{YOUR_API_KEY}}`	Credencial de autenticação da API

Parâmetros da Requisição (Request Body)

O formato do corpo da requisição é application/json.

Nome do Parâmetro	Obrigatório	Tipo	Descrição
model	Sim	string	O ID do modelo a ser usado. Exemplo: `qwen-mt-turbo`.
messages	Sim	array	Lista de mensagens incluídas na conversa até o momento. Contém os campos `role` e `content`.
? role	Não	string	O papel do remetente da mensagem, como `user`, `assistant` ou `system`.
? content	Não	string	O conteúdo da mensagem.
tools	Sim	array	Uma lista de ferramentas que o modelo pode chamar. Atualmente, suporta apenas funções como ferramentas. Usado para fornecer uma lista de funções para as quais o modelo pode gerar entradas JSON.
tool_choice	Sim	object	Controla qual função o modelo chama (se houver). `none` significa que não chamará nenhuma, `auto` significa que o modelo escolhe por conta própria. Também pode forçar a chamada de uma função específica usando `{"type": "function", "function": {"name": "minha_funcao"}}`.
temperature	Não	integer	Temperatura de amostragem, entre 0 e 2. Valores mais altos (como 0.8) tornam a saída mais aleatória, enquanto valores mais baixos (como 0.2) tornam a saída mais focada e determinística. Recomenda-se alterar este valor ou `top_p`, mas não ambos simultaneamente.
top_p	Não	integer	Parâmetro de amostragem de núcleo (Nucleus sampling). 0.1 significa que apenas os tokens que compõem os 10% de maior massa de probabilidade serão considerados. Recomenda-se alterar este valor ou `temperature`, mas não ambos.
n	Não	integer	Quantas opções de conclusão de chat gerar para cada mensagem de entrada. O padrão é 1.
stream	Não	boolean	Se deve ativar a saída em fluxo (streaming). Se `true`, enviará incrementos parciais da mensagem na forma de Server-Sent Events (SSE) e, ao concluir, enviará `data: [DONE]`. O padrão é `false`.
stop	Não	string	Sequências (máximo de 4) onde a API parará de gerar novos tokens.
max_tokens	Não	integer	O número máximo de tokens a serem gerados na conclusão do chat. O comprimento total dos tokens de entrada e gerados é limitado pelo comprimento de contexto do modelo.
presence_penalty	Não	number	Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens com base em sua presença atual no texto, aumentando a probabilidade de o modelo falar sobre novos tópicos.
frequency_penalty	Não	number	Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens com base em sua frequência atual no texto, reduzindo a probabilidade de o modelo repetir as mesmas frases.
logit_bias	Não	object/null	Modifica a probabilidade de tokens específicos aparecerem na conclusão. Aceita um objeto JSON que mapeia IDs de tokens para valores de viés (de -100 a 100).
user	Não	string	Identificador único que representa seu usuário final, pode ajudar a monitorar e detectar abusos.
response_format	Não	object	Objeto que especifica o formato no qual o modelo deve formatar a saída. Usar `{"type": "json_object"}` ativa o Modo JSON. Nota: Ao usá-lo, você deve instruir o modelo a gerar JSON na própria mensagem (prompt).
seen	Não	integer	Recurso em fase de testes. Usado como semente (seed) para amostragem determinística. Repetir requisições com a mesma semente e parâmetros deve retornar o mesmo resultado.

Exemplo de Requisição (Cenário de Tradução Automática)

{
  "model": "qwen-mt-turbo",
  "messages": [
    {
      "role": "user",
      "content": "看完这个视频我没有笑"
    }
  ],
  "translation_options": {
    "source_lang": "auto",
    "target_lang": "English"
  }
}

(Nota: translation_options é um parâmetro de extensão exclusivo do modelo de tradução qwen-mt-turbo)

Parâmetros de Resposta (Response Body)

O formato de retorno é application/json.

Nome do Parâmetro	Tipo	Descrição
id	string	Identificador único da conclusão de chat.
object	string	Tipo de objeto, geralmente `chat.completion`.
created	integer	Timestamp de criação (segundos Unix).
choices	array	Lista das opções de conclusão geradas.
? index	integer	O índice desta opção na lista.
? message	object	Objeto da mensagem gerada pelo modelo. Contém `role` e `content`.
? finish_reason	string	O motivo pelo qual o modelo parou de gerar (ex: `stop` indica conclusão normal, `length` indica que o limite máximo de tokens foi atingido).
usage	object	Estatísticas de consumo de Tokens desta requisição.
? prompt_tokens	integer	Quantidade de tokens consumidos pelo prompt (entrada).
? completion_tokens	integer	Quantidade de tokens consumidos pelo conteúdo gerado (saída).
? total_tokens	integer	Quantidade total de tokens consumidos.

Exemplo de Resposta (200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

Perguntas Frequentes (FAQs)

1. Para quais cenários o modelo `qwen-mt-turbo` é usado principalmente?

O qwen-mt-turbo é um modelo profundamente otimizado para Tradução Automática (Machine Translation). Embora utilize a interface padrão de Chat Completions, ao enviar o texto a ser traduzido e configurar os idiomas de origem e destino, ele é capaz de fornecer resultados de tradução de altíssima qualidade.

2. Como implementar o efeito de "máquina de escrever" (saída em stream/fluxo)?

No corpo da requisição, defina o parâmetro stream como true. Neste caso, a API não retornará a resposta JSON completa de uma só vez, mas continuará enviando blocos de dados (data chunks) através do protocolo Server-Sent Events (SSE). Quando a geração de conteúdo for concluída, o marcador de fim de fluxo data: [DONE] será retornado.

3. Por que recebi o erro `401 Unauthorized`?

Verifique o campo Authorization nos cabeçalhos (Headers) da requisição. Certifique-se de que o formato seja Bearer <SUA_API_KEY> (observe que há um espaço entre "Bearer" e a API Key) e que a API Key esteja ativa e tenha permissão para chamar este modelo.

4. Como devo configurar `temperature` e `top_p`?

Ambos os parâmetros são usados para controlar a aleatoriedade da saída do modelo. A recomendação oficial é modificar apenas um deles, mantendo o outro em seu valor padrão. Se você deseja que os resultados de tradução ou de perguntas e respostas sejam mais rigorosos e precisos, é recomendável diminuir a temperature (ex: 0.1 - 0.2); se desejar gerar conteúdo mais criativo, pode aumentá-la (ex: 0.8).

5. O parâmetro `translation_options` no exemplo de requisição é obrigatório?

Trata-se de uma configuração de extensão suportada por modelos especializados em tradução como o qwen-mt-turbo, usada para especificar claramente o idioma de origem (source_lang) e o idioma de destino (target_lang). Embora você possa usar linguagem natural no content do array messages para instruir o modelo a traduzir, usar translation_options torna a instrução de tradução mais explícita e o resultado mais estável. Se a API for utilizada para diálogos básicos que não envolvam tradução, você pode omitir este parâmetro.