Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Qwen-Omni-Realtime Acesso por WebSocket

Última atualização: Nov 20, 2026

Qwen-Omni-Realtime Acesso por WebSocket

Escopo de aplicação

Este documento se aplica ao Qwen-Omni-Realtime. O exemplo usa qwen3.8-omni-flash-realtime; as configurações de qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime estão na referência de eventos. Para os parâmetros do modelo legado qwen3-omni-flash-realtime-2025-09-15, consulte SDK para Python.

  • Use a chave de API e o ID do workspace correspondentes à região e ao workspace selecionados.
  • domínio de Singapura: {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com.
  • Armazene as chaves de API permanentes no servidor. Não as inclua em navegadores nem em aplicações móveis.

Endereços e autenticação

WebSocketwss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtime

qwen3.8-omni-flash-realtime exige o domínio específico do workspace. Os modelos anteriores podem continuar usando os domínios originais: wss://dashscope.aliyuncs.com em Pequim e wss://dashscope-intl.aliyuncs.com em Singapura. Para mais detalhes, consulte SDK para Python.

Defina Authorization: Bearer <API_KEY> no cabeçalho da solicitação de handshake do WebSocket. Substitua o ID do workspace e o nome real do modelo. Não inclua chaves de API permanentes em navegadores nem em aplicações móveis.

O cabeçalho opcional user-agent identifica o cliente. A documentação geral de integração WebSocket também lista X-DashScope-WorkSpace (ID do workspace) e X-DashScope-DataInspection (configuração de inspeção de conformidade dos dados). Use esses cabeçalhos conforme os requisitos do modelo.

Para gerar chaves de API temporárias e consultar suas permissões, consulte Gerar uma chave de API temporária.

Os URLs de workspace a seguir usam qwen3.5-omni-plus-realtime como modelo de exemplo.

  • China (Pequim) wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
  • Singapura wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime

Substitua {WorkspaceId} pelo ID do workspace da região selecionada.

Configuração da sessão

Depois de estabelecer a conexão e receber session.created, envie session.update. Envie a entrada somente após receber a confirmação session.updated; trate os erros pelos eventos error.

Os exemplos a seguir se aplicam a qwen3.8-omni-flash-realtime. Outras versões devem usar as configurações das respectivas referências de eventos, sem misturar os níveis dos campos.

{
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Tina",
    "turn_detection": {
      "type": "server_vad"
    }
  }
}

Entrada, resultados e encerramento

O áudio é enviado por input_audio_buffer.append. Os formatos de entrada, as condições de envio e os limites de entrada de imagem estão em Eventos do cliente. Processe os resultados, os estados e os erros em Eventos do servidor. O estabelecimento da conexão não significa que a solicitação da aplicação foi concluída.

A sequência dos turnos automáticos, do modo Manual, do Function Calling e do MCP está em Fluxo de interação. Após receber os resultados necessários, feche a conexão WebSocket.

Fluxo de interação

Modo VAD

Para ativar o modo VAD, defina session.turn_detection.type do evento de eventos do cliente como "server_vad". No modo VAD, o servidor executa a detecção de atividade de voz no áudio recebido e responde quando detecta fala. Esse modo é adequado para quando o cliente envia áudio continuamente ao servidor e é o modo padrão atual.

server_vad

  • O servidor envia o evento input_audio_buffer.speech_started ao detectar o início da fala.
  • O cliente pode adicionar áudio ao buffer a qualquer momento enviando um evento input_audio_buffer.append.
  • O servidor envia o evento input_audio_buffer.speech_stopped ao detectar o fim da fala.
  • O servidor confirma o buffer de áudio de entrada enviando um evento input_audio_buffer.committed.
  • O servidor envia um evento conversation.item.created contendo o item de mensagem do usuário criado a partir do buffer de áudio.

Fluxo de chamada de ferramenta

No modo VAD, quando uma resposta gerada pelo servidor exige uma chamada de ferramenta, ocorre o seguinte fluxo de interação:

image.svg

  • Após detectar o fim da fala e gerar uma resposta, o servidor determina que uma chamada de ferramenta é necessária.
  • O servidor envia um evento response.function_call_arguments.delta com dados incrementais dos argumentos da chamada de ferramenta.
  • O servidor envia um evento response.function_call_arguments.done para indicar que todos os argumentos da chamada de ferramenta foram enviados.
  • O cliente executa a chamada de ferramenta e obtém o resultado.
  • O cliente envia um evento conversation.item.create contendo o resultado da chamada de ferramenta.
  • O cliente envia um evento response.create para acionar o servidor a gerar uma resposta com base no resultado da chamada de ferramenta.

Modo Manual

Para ativar o modo Manual, defina o parâmetro session.turn_detection do evento do cliente como null. Nessa configuração, o cliente solicita uma resposta do servidor enviando explicitamente os eventos input_audio_buffer.commit e response.create. Esse modo é adequado para cenários de "pressionar para falar", como o envio de mensagens de voz em aplicativos de chat.

manual

  • O cliente pode adicionar áudio ao buffer enviando um evento input_audio_buffer.append.
  • O cliente confirma o buffer de áudio de entrada enviando um evento input_audio_buffer.commit. Essa confirmação cria um novo item de mensagem do usuário na conversa.
  • O servidor responde enviando um evento input_audio_buffer.committed.
  • O cliente envia um evento response.create para acionar o modelo e gerar a resposta final.
  • O servidor responde enviando um evento conversation.item.created.

Fluxo de chamada de ferramenta

image.svg

No modo Manual, quando uma resposta gerada pelo servidor exige uma chamada de ferramenta, ocorre o seguinte fluxo de interação:

  • Após o cliente enviar um evento response.create, o servidor gera uma resposta e detecta a necessidade de uma chamada de ferramenta.
  • O servidor envia um evento response.function_call_arguments.delta contendo dados incrementais dos argumentos da chamada de ferramenta.
  • O servidor envia um evento response.function_call_arguments.done para sinalizar que a transferência dos argumentos da chamada de ferramenta foi concluída.
  • O cliente executa a chamada de ferramenta e obtém o resultado.
  • O cliente envia o resultado da chamada de ferramenta utilizando um evento conversation.item.create.
  • O cliente envia um evento response.create para acionar o modelo e gerar a resposta final.
  • O servidor gera uma resposta baseada no resultado da chamada de ferramenta e a envia ao cliente por meio de eventos response.audio.delta ou response.text.delta.

Chamadas de ferramentas MCP

O fluxo a seguir se aplica ao Qwen3.8-Omni-Flash-Realtime e pode ser usado em conjunto com o modo VAD ou Manual descrito acima.

Function Calling e MCP podem ser configurados em session.tools na mesma sessão e não podem ser ativados junto com a busca na Web (enable_search). O Model Studio não cobra taxas adicionais pelas chamadas de ferramentas MCP; a inferência do modelo continua sendo cobrada pelo preço do modelo.

Com o MCP, as ferramentas são executadas pelo servidor, enquanto no fluxo de Function Calling descrito acima as ferramentas são executadas pelo cliente; os dois diferem na forma de devolver os resultados.

Descoberta de ferramentas

Depois que o cliente configura os serviços MCP via session.update, o serviço Realtime descobre as ferramentas de forma assíncrona. O fluxo de interação é o seguinte:

Diagrama de sequência da descoberta de ferramentas MCP

Nos diagramas de sequência desta seção, opt indica execução quando uma condição é atendida; alt indica ramificações alternativas escolhidas por condição; par indica processamento paralelo.

  • session.updated indica apenas que a configuração MCP foi aceita, não que as ferramentas já estão disponíveis.
  • mcp_list_tools.in_progress pode chegar antes de session.updated.
  • O cliente pode continuar enviando áudio ou response.create antes do término da descoberta de ferramentas; no entanto, apenas Responses criadas após a conclusão da descoberta podem usar as ferramentas MCP correspondentes.
  • Quando a descoberta de ferramentas é bem-sucedida, o servidor envia primeiro conversation.item.created contendo a lista final de ferramentas e, em seguida, envia mcp_list_tools.completed.
  • Quando a descoberta de ferramentas falha, o servidor envia primeiro conversation.item.created contendo um erro e, em seguida, envia mcp_list_tools.failed.

Chamadas MCP e continuação

Depois que o modelo seleciona uma ferramenta MCP, o serviço Realtime executa a chamada da ferramenta; quando a aprovação é necessária, o cliente responde primeiro com o resultado da aprovação. O fluxo de interação é o seguinte:

Diagrama de sequência de chamada, aprovação e continuação de resposta das ferramentas MCP

Uma aprovação rejeitada ou expirada aciona diretamente response.mcp_call.failed, sem executar a ferramenta e sem passar por response.mcp_call.in_progress. Quando a aprovação não é necessária ou é concedida, a sequência típica de eventos é a seguinte:

response.output_item.added(mcp_call)
→ response.mcp_call_arguments.delta
→ response.mcp_call_arguments.done
→ 可选:conversation.item.created(mcp_approval_request)
→ 可选:conversation.item.create(mcp_approval_response)
→ response.mcp_call.in_progress
→ response.mcp_call.completed 或 response.mcp_call.failed
→ response.output_item.done(最终 mcp_call)
→ response.done(父 Response)

O servidor envia response.done depois que todos os itens MCP da mesma Response pai atingem um estado terminal. O response.output já contém o snapshot final do mcp_call: itens bem-sucedidos ficam como completed e contêm output; itens com falha ficam como failed e contêm error.

Se for necessário que o modelo continue gerando uma resposta com base no resultado do MCP, o cliente deve enviar um único response.create, sem anexar o resultado do MCP, após receber o response.done pai.

Consulte Configuração de ferramentas MCP do cliente, Resposta de aprovação, Eventos MCP do servidor e Itens de conversa MCP.

Limites de uso

As seguintes restrições MCP padrão se aplicam a cada sessão:

ItemValor padrão
Servidores MCP8
Ferramentas MCP128
Tempo limite de descoberta de ferramentas30 segundos
Tempo limite de aprovação60 segundos
Tempo limite de execução de ferramentas30 segundos
Tamanho de uma única resposta upstream2 MB
Tamanho acumulado dos resultados das ferramentas8 MB
Número acumulado de chamadas de ferramentas256

Tratamento de erros

Se o handshake falhar, verifique o domínio, a região, o workspace, a chave de API, o nome do modelo, seu estado de ativação e as permissões. Depois de estabelecer a conexão, localize o problema pelo evento error e consulte Códigos de erro. Guarde o ID do evento para facilitar a investigação. A ausência de resposta não basta para concluir que o protocolo não é compatível.

SDKs e referências