Qwen-Audio-Realtime Acesso por WebSocket
Guia do usuário: Conversa por voz em tempo real (Qwen-Audio-Realtime). Para as definições detalhadas dos eventos, consulte Eventos do cliente e Eventos do servidor.
Modelos compatíveis: qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.
ImportanteO Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
- China (Beijing): de
dashscope.aliyuncs.compara{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: de
dashscope-intl.aliyuncs.compara{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Substitua {WorkspaceId} pelo ID do workspace. Os domínios existentes continuam disponíveis.
Endpoint da API
A URL do WebSocket é fixa, conforme mostrado a seguir. Especifique o modelo a ser chamado por meio do parâmetro de consulta model (substitua <model_name> pelo modelo real):
China (Pequim)
wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>Ao chamar a API, substitua {WorkspaceId} pelo ID do workspace.
Singapura
wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>Ao chamar a API, substitua {WorkspaceId} pelo ID do workspace.
ImportanteA URL deve usar wss://. Defina Authorization nos cabeçalhos da solicitação e informe o modelo pelo parâmetro de consulta model.
Cabeçalhos da solicitação
Inclua as seguintes informações nos cabeçalhos da solicitação:
AuthorizationstringObrigatório: SimToken de autenticação no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API real.
user-agentstringObrigatório: NãoIdentificador do cliente que ajuda o servidor a rastrear a origem da solicitação.
X-DashScope-WorkSpacestringObrigatório: NãoID do workspace do Alibaba Cloud Model Studio.
ImportanteAuthorization é validado durante o handshake do WebSocket. Se a chave de API estiver ausente ou for inválida, o handshake falhará com HTTP 401/403. Armazene chaves permanentes no servidor, e não em navegadores ou aplicações móveis. Para gerar chaves temporárias e consultar suas permissões, consulte Gerar uma chave de API temporária.
A documentação geral de integração do WebSocket também lista o cabeçalho de solicitação de inspeção de conformidade de dados X-DashScope-DataInspection, usado conforme os requisitos do modelo. O exemplo de qwen-audio-3.1-realtime-plus usa x-dashscope-dataInspection: disable.
Conceitos fundamentais
- Sessão: Uma conexão WebSocket corresponde a uma sessão, que mantém a configuração e o contexto da conversa.
- Item da conversa: Cada mensagem da conversa, organizada como uma lista encadeada.
- Resposta: Saída de uma inferência do modelo. Uma resposta contém um ou mais itens de saída, que podem ser mensagens do assistente ou chamadas de função.
- Chamada de função: Uma solicitação do modelo para o cliente executar uma ferramenta. Após executar a função, o cliente envia o resultado como
function_call_output, depois enviaresponse.createpara acionar a próxima inferência. - Detecção de turnos: Controla quando a inferência é acionada.
Modos de interação
A Realtime API do Qwen-Audio oferece três modos de interação, configurados por session.turn_detection no evento session.update. Para detecção automática, defina type dentro do objeto. Para push-to-talk, defina todo o campo turn_detection como null:
Modo | Valor de session.turn_detection | Descrição | Casos de uso |
|---|---|---|---|
server_vad | Objeto. Defina | O servidor usa VAD para detectar o início e o fim da fala e acionar a inferência automaticamente. | Conversa sem usar as mãos e assistentes de voz |
Detecção semântica inteligente de turnos | Objeto. Defina | Combina percepção acústica e compreensão semântica para detectar os limites dos turnos, em vez de depender apenas de sinais de voz. Sons sem significado semântico, como "uh" e "ah", não acionam um turno nem interrompem a reprodução do modelo. | Conversa natural com baixa latência e tratamento preciso de interrupções |
push-to-talk |
| O cliente confirma o áudio e aciona a inferência manualmente. | Push-to-talk e controle preciso |
Fluxo de interação
Para as definições detalhadas dos eventos, consulte Eventos do cliente e Eventos do servidor.
Modo server_vad
O servidor detecta a atividade de voz no áudio recebido e aciona a inferência automaticamente ao detectar o fim da fala.
Como ativar: Defina turn_detection.type do evento session.update como server_vad.
Um turno completo de conversa
O diagrama a seguir mostra uma sequência típica de interação no modo server_vad:
O cliente e o servidor interagem na seguinte ordem:
- O cliente estabelece uma conexão WebSocket. O servidor retorna
session.created. - O cliente envia
session.updatepara configurar a sessão. O servidor retornasession.updated. - O cliente envia continuamente
input_audio_buffer.appendpara adicionar dados de áudio. - Ao detectar o início da fala, o servidor retorna
input_audio_buffer.speech_startede transmite as transcrições ASR incrementais emconversation.item.input_audio_transcription.delta. - Ao detectar o fim da fala, o servidor retorna
input_audio_buffer.speech_stopped,input_audio_buffer.committedeconversation.item.created. - O servidor gera uma resposta automaticamente, transmite incrementos de texto e áudio (
response.audio_transcript.deltaeresponse.audio.delta) e retornaresponse.done.
Interrupção pelo usuário
Se o VAD detectar que o usuário começou a falar durante a reprodução do modelo, o servidor cancelará a resposta atual e retornará response.done com status cancelled. Em seguida, iniciará um novo turno de entrada de fala e resposta. O diagrama a seguir mostra essa sequência de interrupção:
Modo smart_turn / smart_turn_v2
Este modo combina percepção acústica e compreensão semântica para detectar o fim da fala. Ele pode filtrar sons sem significado, como confirmações breves e áudio de fundo. Sons sem significado semântico são repassados por meio do evento conversation.item.ambient_audio_transcription.delta e não acionam um turno de conversa.
Como ativar: Defina turn_detection.type do evento session.update como smart_turn ou smart_turn_v2.
smart_turn_v2 (recomendado): amplia o smart_turn com maior compreensão do contexto da conversa para identificar melhor a intenção de interação em cenários com várias pessoas. Reduz respostas e interrupções indesejadas causadas por outras pessoas ou comentários não relacionados.
Um turno completo de conversa
O diagrama a seguir mostra uma sequência típica de interação no modo smart_turn / smart_turn_v2:
As principais diferenças em relação ao modo server_vad são:
- Sons sem significado semântico, como "uh" e "ah", não acionam a inferência. Eles são retornados pelo evento
ambient_audio_transcription. - Uma fala identificada anteriormente como válida pode ser invalidada:
input_audio_buffer.speech_stoppedretornareason=turn_invalid. Nesse caso, a inferência não é acionada. - Enquanto aguarda a próxima entrada do usuário, o cliente pode enviar explicitamente
response.createpara acionar a inferência.
Interrupção pelo usuário
O tratamento de interrupções é essencialmente igual ao do modo server_vad. O diagrama a seguir mostra essa sequência:
Turno inválido
Uma fala identificada anteriormente como válida pode ser invalidada: input_audio_buffer.speech_stopped retorna reason=turn_invalid. Nesse caso, a inferência não é acionada. O cliente deve continuar enviando áudio e aguardar a próxima entrada de fala válida. O diagrama a seguir mostra essa sequência de turno inválido:
Fluxo de configuração do aprimoramento de falante
No modo smart_turn / smart_turn_v2, se o primeiro session.update incluir voiceprint_audio_urls, o servidor registrará as impressões vocais de forma assíncrona, carregando as características de áudio dos falantes de destino. Os eventos informam o progresso do registro. Uma falha no registro não impede a conversa normal.
O registro das impressões vocais segue esta ordem:
-
O cliente estabelece uma conexão WebSocket. O servidor retorna
session.created. -
O cliente envia seu primeiro
session.update, informando as URLs dos áudios de impressão vocal emturn_detection.voiceprint_audio_urls. -
O servidor inicia imediatamente o registro assíncrono das impressões vocais. Antes de retornar
session.updated, enviavoiceprint_audio_list.in_progresscom o identificador exclusivo da tarefa de registroitem_id. -
O servidor retorna
session.updatedpara confirmar que a configuração da sessão entrou em vigor. -
Ao terminar o registro das impressões vocais, o servidor envia um evento de estado final. Seu
item_idcorresponde ao valor da etapa 3:- Registro bem-sucedido:
voiceprint_audio_list.completed. - Falha no registro:
voiceprint_audio_list.failed, com um camporeasonque explica a falha, como uma URL de áudio que não pode ser baixada.
- Registro bem-sucedido:
Observaçãovoiceprint_audio_urls só entra em vigor no primeiro session.update. O campo é ignorado nas atualizações seguintes.
Modo push-to-talk
O cliente controla manualmente quando confirmar o áudio e acionar a inferência. Este modo é adequado para interações push-to-talk.
Como ativar: Defina turn_detection do evento session.update como null.
Um turno completo de conversa
O diagrama a seguir mostra uma sequência típica de interação no modo push-to-talk:
O cliente e o servidor interagem na seguinte ordem:
- O cliente envia continuamente
input_audio_buffer.appendpara adicionar dados de áudio. - Depois que o usuário termina de falar, o cliente envia
input_audio_buffer.commitpara confirmar o buffer. - O cliente envia
response.createpara acionar a inferência manualmente. - O servidor gera uma resposta e transmite texto e áudio em streaming.
Interrupção pelo usuário
O cliente envia response.cancel para cancelar a resposta atual. O servidor retorna response.done com status cancelled e motivo client_cancelled. O diagrama a seguir mostra essa sequência de interrupção:
Restrições de operação por modo
Operação | push-to-talk | server_vad | smart_turn / smart_turn_v2 |
|---|---|---|---|
session.update | Todos os campos podem ser alterados em IDLE; alguns têm restrições nos demais estados | Todos os campos podem ser alterados em IDLE; alguns têm restrições nos demais estados | Todos os campos podem ser alterados em IDLE; alguns têm restrições nos demais estados |
input_audio_buffer.append | Permitido | Permitido | Permitido |
input_audio_buffer.commit | Permitido | Ignorado | Ignorado |
input_audio_buffer.clear | Permitido | Ignorado | Ignorado |
response.create | Permitido após confirmar o áudio armazenado no buffer com | Permitido quando nenhuma resposta está sendo gerada; não acione outra resposta durante a geração | Permitido enquanto aguarda a próxima entrada do usuário; não acione outra resposta dentro de um turno ativo, de |
response.cancel | Permitido durante a inferência | Permitido durante a inferência | Permitido durante a inferência |
conversation.item.create/delete/retrieve | Permitido | Permitido | Permitido |
Observaçãoturn_detection e input_audio_format só podem ser alterados antes do primeiro envio de áudio, enquanto a sessão estiver em IDLE.
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. Para descrições completas dos erros, consulte Códigos de erro.
Tipo | Comportamento | Exemplo |
|---|---|---|
Erro do cliente ( | A conexão permanece aberta; o erro é informado | Parâmetros inválidos, operações não permitidas no estado atual ou item_id duplicado |
Erro do servidor ( | A conexão é encerrada | Falha na conexão com o LLM ou no armazenamento |