Qwen-Audio-Realtime API WebSocket

Qwen-Audio-Realtime Protocolo de conexão WebSocket, cabeçalhos de solicitação, conceitos básicos e fluxos de interação

O Qwen-Audio A API em tempo real fornece conversação por voz em tempo real via WebSocket. O cliente interage com o servidor enviando e recebendo eventos JSON, suportando entrada de voz, entrada de texto, detecção de atividade de voz (VAD) e streaming de voz e saída de texto.

Guia do usuário: Conversa por voz em tempo real (Qwen-Audio-Realtime). Para obter detalhes sobre eventos de cliente e servidor, consulte Eventos de cliente e Eventos do servidor.

Terminal de serviço

Use o seguinte URL do WebSocket. O model parâmetro de consulta especifica o modelo a ser chamado (substitua <model_name> com o nome real do modelo):

wss://maas.qwencloudapi.com/api-ws/v1/realtime?model=<model_name>

A URL deve usar o wss:// esquema. Defina autorização nos cabeçalhos da solicitação; especifique o modelo através do model parâmetro de consulta.

Solicitar cabeçalhos

Inclua os seguintes campos nos cabeçalhos da solicitação:

A autorização é verificada durante o handshake do WebSocket. Se a chave de API for inválida ou estiver ausente, o handshake falhará com um erro HTTP 401 ou 403.

Conceitos básicos

• Sessão: Cada conexão WebSocket corresponde a uma sessão, que mantém a configuração e o contexto da conversa.
• Item de conversa: cada mensagem na conversa, organizada como uma lista vinculada em ordem.
• Resposta: A saída produzida por uma rodada de inferência de modelo, contendo um ou mais itens de saída. Um item de saída pode ser uma mensagem do assistente ou uma chamada de função.
• Chamada de função: um item de saída produzido quando o modelo solicita ao cliente que execute uma função de ferramenta. Após a execução, o cliente escreve de volta o resultado via function_call_output e desencadeia a próxima rodada de inferência com response.create.
• Detecção de curva: controla quando a inferência é acionada.

Modos de interação

O Qwen-Audio A API Realtime oferece suporte a três modos de interação, configurados por meio do turn_detection.type parâmetro no session.update evento:

Fluxos de interação

Para obter detalhes sobre eventos de cliente e servidor, consulte Eventos de cliente e Eventos do servidor.

modo servidor_vad

O servidor realiza detecção de atividade de voz no áudio recebido e aciona automaticamente a inferência assim que detecta o fim da fala.

Para ativar: Definir turn_detection.type para server_vad no session.update evento.

Uma conversa completa

Em ordem cronológica, o cliente e o servidor interagem da seguinte forma:

1. O cliente estabelece uma conexão WebSocket; o servidor retorna um session.created evento.
2. O cliente envia session.update configurar parâmetros de sessão; o servidor retorna session.updated.
3. O cliente envia continuamente input_audio_buffer.append eventos para anexar dados de áudio.
4. O servidor detecta o início da fala e retorna input_audio_buffer.speech_started, enquanto transmite transcrição ASR incremental via conversation.item.input_audio_transcription.delta.
5. O servidor detecta o fim da fala e retorna input_audio_buffer.speech_stopped, input_audio_buffer.committede conversation.item.created.
6. O servidor gera automaticamente uma resposta, streaming de texto e deltas de áudio (response.audio_transcript.delta, response.audio.delta) e finalmente retorna response.done.

Sequência completa do evento:

Interrupção do usuário

Se o VAD detectar que o usuário está começando a falar enquanto o modelo está reproduzindo uma resposta, o servidor cancela a resposta atual (retornando response.done com status cancelled) e, em seguida, inicia uma nova rodada de entrada e resposta de voz.

Sequência de eventos de interrupção:

1. O servidor está transmitindo response.audio.delta (laço).
2. O cliente envia input_audio_buffer.append (o usuário começa a falar).
3. O servidor retorna response.done (status=cancelled), cancelando a resposta atual.
4. O servidor retorna input_audio_buffer.speech_started.
5. O cliente continua enviando input_audio_buffer.append; os fluxos do servidor conversation.item.input_audio_transcription.delta.
6. O servidor detecta o fim da fala e retorna input_audio_buffer.speech_stopped e conversation.item.input_audio_transcription.completed.
7. O servidor confirma o buffer de áudio internamente, retornando input_audio_buffer.committed e conversation.item.created.
8. O servidor inicia automaticamente uma nova rodada de inferência e retorna response.created.

modo inteligente_turn

Combina percepção acústica com compreensão semântica para detectar o final da fala, filtrando backchannels, ruído de fundo e outros sons sem significado. Sons não semânticos são transmitidos através do conversation.item.ambient_audio_transcription.delta evento e não aciona um turno de conversa.

Para ativar: Definir turn_detection.type para smart_turn no session.update evento.

Uma conversa completa

Principais diferenças do modo server_vad:

• Sons não semânticos (como “um” ou “uh”) não desencadeiam inferência; em vez disso, eles são devolvidos através do ambient_audio_transcription eventos.
• Discurso inicialmente julgado válido poderá posteriormente ser retratado (input_audio_buffer.speech_stopped retorna com reason=turn_invalid), caso em que a inferência não é acionada.
• Enquanto aguarda a próxima entrada do usuário, o cliente pode enviar explicitamente response.create para desencadear inferência.

Sequência completa do evento:

Interrupção do usuário

O tratamento de interrupções é basicamente o mesmo que no modo server_vad:

1. O servidor está transmitindo response.audio.delta (laço).
2. O cliente envia input_audio_buffer.append (o usuário começa a falar).
3. O servidor retorna response.done (status=cancelled), cancelando a resposta atual.
4. O servidor retorna input_audio_buffer.speech_started.
5. O cliente continua enviando input_audio_buffer.append; os fluxos do servidor conversation.item.input_audio_transcription.delta.
6. O servidor retorna conversation.item.input_audio_transcription.completed e input_audio_buffer.speech_stopped.
7. O servidor confirma o buffer de áudio internamente, retornando input_audio_buffer.committed e conversation.item.created.
8. O servidor inicia automaticamente uma nova rodada de inferência e retorna response.created.

Turnos inválidos

Discurso inicialmente julgado válido poderá posteriormente ser retratado (input_audio_buffer.speech_stopped retorna com reason=turn_invalid), caso em que a inferência não é acionada. O cliente deverá continuar enviando áudio e aguardar o próximo turno de fala válido.

Sequência de eventos de turno inválida:

1. O cliente envia continuamente input_audio_buffer.append.
2. O servidor retorna input_audio_buffer.speech_started.
3. O cliente continua enviando input_audio_buffer.append; os fluxos do servidor conversation.item.input_audio_transcription.delta.
4. O servidor retorna input_audio_buffer.speech_stopped (motivo=turn_inválido).
5. O cliente continua enviando áudio, aguardando o próximo turno de fala válido.

Fluxo de registro de impressão de voz

No modo smart_turn, quando voiceprint_audio_urls está incluído no primeiro session.update, o servidor executa o registro de impressão de voz de forma assíncrona (carregando os recursos de áudio do locutor alvo) e notifica o progresso do registro por meio de eventos. Uma falha no registro de impressão de voz não bloqueia o fluxo normal da conversa.

Em ordem cronológica, o fluxo de interação de registro de impressão de voz é o seguinte:

1. O cliente envia session.update, incluindo o URL do áudio de impressão de voz em turn_detection.voiceprint_audio_urls; o servidor retorna session.updated.
2. O servidor inicia imediatamente o registro de impressão de voz de forma assíncrona, pressionando um voiceprint_audio_list.in_progress evento antes de retornar session.updated, carregando um único item_id para esta tarefa de inscrição.
3. O servidor retorna session.updated, confirmando que a configuração da sessão entrou em vigor.
4. Após a conclusão do registro de impressão de voz, o servidor envia um evento de terminal (com o mesmo item_id como na etapa 2):
   • Em caso de sucesso: voiceprint_audio_list.completed.
   • Em caso de falha: voiceprint_audio_list.failed, com um reason campo explicando a falha (por exemplo, não foi possível fazer download do URL do áudio).

voiceprint_audio_urls só entra em vigor no primeiro session.update. As ocorrências subsequentes deste campo são ignoradas.

modo apertar para falar

O cliente controla manualmente o envio de áudio e o disparo de inferência. Adequado para cenários push-to-talk.

Para ativar: Definir turn_detection para null no session.update evento.

Uma conversa completa

Em ordem cronológica, o cliente e o servidor interagem da seguinte forma:

1. O cliente envia continuamente input_audio_buffer.append eventos para anexar dados de áudio.
2. Após o usuário terminar de falar, o cliente envia input_audio_buffer.commit para confirmar o buffer.
3. O cliente envia response.create para acionar manualmente a inferência.
4. O servidor gera uma resposta, transmitindo texto e áudio.

Sequência completa do evento:

Interrupção do usuário

O cliente envia response.cancel para cancelar a resposta atual; o servidor retorna response.done (estado cancelled, razão client_cancelled).

Sequência de eventos de interrupção:

1. O servidor está transmitindo response.audio_transcript.delta e response.audio.delta (laço).
2. O cliente envia response.cancel.
3. O servidor retorna response.done (status=cancelado, motivo=cliente_cancelado).
4. O cliente continua enviando input_audio_buffer.append; os fluxos do servidor conversation.item.input_audio_transcription.delta.
5. O cliente envia input_audio_buffer.commit para confirmar o buffer.
6. O servidor retorna conversation.item.input_audio_transcription.completed, input_audio_buffer.committede conversation.item.created.
7. O cliente envia response.create para acionar manualmente uma nova rodada de inferência.
8. O servidor retorna response.created, iniciando uma nova rodada de resposta.

Restrições de operação por modo

turn_detection e input_audio_format só pode ser alterado antes do primeiro áudio ser enviado (estado IDLE).

Tratamento de erros