Skip to main content

Fluxo de interação por WebSocket

Este tópico descreve o fluxo de interação multimodal em tempo real entre o servidor e o cliente.

Endpoints de conexão

Modelos compatíveis: qwen3.8-omni-flash-realtime, qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime.
  • China (Pequim)
  • Singapura
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
Substitua {WorkspaceId} pelo ID do workspace da região e model pelo nome do modelo a chamar. Para autenticação e preparação antes da conexão, consulte Acesso por WebSocket.

Fluxo de conexão

Modo VAD

Para ativar o modo VAD, defina o parâmetro session.turn_detection do evento do cliente como "server_vad". Nesse modo, o servidor executa a Detecção de Atividade de Voz (VAD) no áudio recebido e responde ao identificar fala. Esta é a configuração padrão, ideal para cenários em que o cliente envia áudio continuamente ao servidor.
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 servidor gera automaticamente 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

Este fluxo se aplica ao Qwen3.8-Omni-Flash-Realtime nos modos VAD e Manual. Function Calling e MCP podem ser configurados juntos em session.tools. Não podem ser usados com a busca na Web (enable_search). O Model Studio não cobra uma taxa adicional pelas chamadas de ferramentas MCP. A inferência do modelo continua sujeita aos preços do modelo.

Descoberta de ferramentas

Após o cliente configurar servidores MCP com session.update, o serviço Realtime descobre suas ferramentas de forma assíncrona:
Sequência de 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.
  1. Envie session.update com entradas MCP em session.tools.
  2. Trate mcp_list_tools.in_progress, que pode chegar antes de session.updated. session.updated confirma a aceitação da configuração, não a disponibilidade das ferramentas.
  3. O serviço descobre as ferramentas. Ele envia conversation.item.created com um item mcp_list_tools, seguido de mcp_list_tools.completed ou mcp_list_tools.failed com o mesmo item_id. O item contém as ferramentas filtradas finais ou um erro.
A entrada de áudio e response.create podem continuar durante a descoberta, mas apenas Responses criadas após a conclusão da descoberta podem usar as ferramentas correspondentes.

Chamadas MCP e continuação

Quando o modelo seleciona uma ferramenta MCP, o serviço Realtime executa a chamada. Se for necessária aprovação, o cliente deve primeiro responder à solicitação de aprovação:
Sequência de chamada, aprovação e continuação de ferramentas MCP
  1. O servidor cria um item mcp_call por response.output_item.added.
  2. Concatene zero ou mais fragmentos response.mcp_call_arguments.delta. Considere a string JSON completa em response.mcp_call_arguments.done como referência definitiva.
  3. Quando houver necessidade de aprovação, trate conversation.item.created com item.type="mcp_approval_request". Decida se a chamada será permitida e responda com conversation.item.create, item.type="mcp_approval_response", o item.id exato da aprovação e o booleano approve. A aprovação é obrigatória por padrão.
  4. Chamadas aprovadas ou configuradas para dispensar aprovação emitem response.mcp_call.in_progress. O serviço executa a chamada MCP e emite response.mcp_call.completed ou response.mcp_call.failed. A rejeição ou o fim do tempo limite de aprovação emite failed sem executar a chamada.
  5. Processe response.output_item.done para obter o item final da chamada. O response.done da Response que contém a chamada chega após todos os itens MCP dessa Response atingirem um estado terminal. Seu response.output inclui os estados finais: chamadas bem-sucedidas têm completed e output; chamadas que falham têm failed e error.
  6. Para gerar uma resposta do modelo a partir dos resultados MCP, envie um único response.create após o response.done da Response que contém a chamada. Não inclua resultados MCP: eles já estão na conversa. Não use o fluxo manual de retorno function_call_output para essas chamadas MCP executadas pelo servidor.
Consulte Configuração MCP do cliente, Respostas 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 resposta de saída2 MB
Tamanho acumulado dos resultados das ferramentas8 MB
Número acumulado de chamadas de ferramentas256

SDK