Alibaba Cloud Model Studio:Client events for Qwen-ASR-Realtime

Esta página documenta os eventos de cliente para servidor da API WebSocket do Qwen-ASR Realtime. Cada seção aborda um tipo de evento, seus parâmetros e as respostas do servidor.

Para obter uma visão geral dos recursos e exemplos completos de código, consulte Reconhecimento de fala em tempo real - Qwen. Para eventos de servidor para cliente, veja Eventos de servidor para Qwen-ASR-Realtime.

Ciclo de vida do evento

Uma sessão típica segue esta sequência:

1. Estabeleça uma conexão WebSocket.
2. Envie session.update para configurar o formato de áudio, o idioma e as definições de VAD.
3. Envie input_audio_buffer.append repetidamente para transmitir dados de áudio.
4. No modo Manual, envie input_audio_buffer.commit para acionar o reconhecimento de uma expressão completa. No modo VAD, o servidor inicia o reconhecimento automaticamente.
5. Envie session.finish para encerrar a sessão e desconecte após receber a resposta session.finished.

session.update

Configure a sessão. Envie este evento imediatamente após estabelecer a conexão WebSocket para definir o formato de áudio, o idioma e os parâmetros de VAD. Se omitido, os valores padrão serão aplicados.

Em caso de sucesso, o servidor responde com um evento session.updated.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
type	string	Sim	Valor fixo: session.update.
event_id	string	Sim	ID de evento exclusivo.
session	object	Sim	Objeto de configuração da sessão. Consulte a tabela de configuração da sessão abaixo.

Configuração da sessão

Parâmetro	Tipo	Obrigatório	Descrição
input_audio_format	string	Não	Formato de codificação de áudio. Valores válidos: pcm, opus. Padrão: pcm.
sample_rate	integer	Não	Taxa de amostragem de áudio em Hz. Valores válidos: 16000, 8000. Padrão: 16000. Defina como 8000 faz com que o servidor realize upsampling para 16.000 Hz (pequeno atraso). Use 8000 apenas para áudio nativo de 8.000 Hz, como telefonia.
input_audio_transcription	object	Não	Definições de reconhecimento de fala.
input_audio_transcription.language	string	Não	Idioma do áudio. Consulte a tabela de idiomas suportados abaixo.
input_audio_transcription.corpus.text	string	Não	Texto de contexto para viés contextual — texto de fundo, vocabulários de entidades ou material de referência que melhora a precisão do reconhecimento. Máximo: 10.000 tokens.
turn_detection	object	Não	Configuração de VAD. Defina como null para o Modo Manual. Se presente, o Modo VAD estará ativado.
turn_detection.type	string	Obrigatório quando turn_detection estiver definido	Valor fixo: server_vad.
turn_detection.threshold	float	Não	Limiar de sensibilidade do VAD. Padrão: 0.2. Intervalo válido: [-1, 1]. Valores menores aumentam a sensibilidade (podem ativar com ruído de fundo). Valores maiores reduzem a sensibilidade e evitam ativações falsas em ambientes ruidosos. Consulte as predefinições recomendadas de VAD abaixo.
turn_detection.silence_duration_ms	integer	Não	Duração do silêncio em milissegundos que marca o fim da expressão. Padrão: 800. Intervalo válido: [200, 6000]. Durações mais curtas (ex.: 300 ms) aceleram as respostas, mas podem dividir pausas naturais. Durações mais longas (ex.: 1.200 ms) lidam melhor com pausas, porém aumentam a latência. Consulte as predefinições recomendadas de VAD abaixo.

Predefinições recomendadas de VAD

Use estas predefinições como pontos de partida. Ajuste conforme seus resultados:

Predefinição	threshold	silence_duration_ms	Mais indicado para
Baixa latência	0.0	400	Interações rápidas, como comandos de voz ou assistência de agente, onde respostas ágeis são mais importantes que lidar com pausas longas
Equilibrado (padrão)	0.2	800	Transcrição de uso geral com equilíbrio entre capacidade de resposta e precisão

Idiomas suportados

Código	Idioma
zh	Chinês (Mandarim, Sichuanês, Minnan e Wu)
yue	Cantonês
en	Inglês
ja	Japonês
de	Alemão
ko	Coreano
ru	Russo
fr	Francês
pt	Português
ar	Árabe
it	Italiano
es	Espanhol
hi	Hindi
id	Indonésio
th	Tailandês
tr	Turco
uk	Ucraniano
vi	Vietnamita
cs	Tcheco
da	Dinamarquês
fil	Filipino
fi	Finlandês
is	Islandês
ms	Malaio
no	Norueguês
pl	Polonês
sv	Sueco

Exemplo

{
    "event_id": "event_123",
    "type": "session.update",
    "session": {
        "input_audio_format": "pcm",
        "sample_rate": 16000,
        "input_audio_transcription": {
            "language": "zh"
        },
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.0,
            "silence_duration_ms": 400
        }
    }
}

input_audio_buffer.append

Transmite um trecho de áudio para o buffer de entrada do servidor — evento principal para envio de dados de áudio.

O comportamento varia conforme o modo de interação:

• Modo VAD: O servidor monitora o buffer em busca de atividade de voz e aciona o reconhecimento automaticamente.
• Modo Manual: O cliente controla os limites das expressões. Envie trechos menores para obter menor latência.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
type	string	Sim	Valor fixo: input_audio_buffer.append.
event_id	string	Sim	ID de evento exclusivo.
audio	string	Sim	Dados de áudio codificados em Base64.

Exemplo

{
    "event_id": "event_2728",
    "type": "input_audio_buffer.append",
    "audio": "<Base64-encoded-audio-data>"
}

input_audio_buffer.commit

Aciona o reconhecimento de todo o áudio no buffer como uma única expressão. Use no modo Manual quando sua aplicação controlar os limites da expressão (por exemplo, push-to-talk).

Este recurso fica desativado no modo VAD.

Em caso de sucesso, o servidor responde com um evento input_audio_buffer.committed.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
type	string	Sim	Valor fixo: input_audio_buffer.commit.
event_id	string	Sim	ID de evento exclusivo.

Exemplo

{
    "event_id": "event_789",
    "type": "input_audio_buffer.commit"
}

session.finish

Encerra a sessão. A resposta do servidor depende da detecção de fala:

• Fala detectada: O servidor conclui o reconhecimento final, envia um evento conversation.item.input_audio_transcription.completed com o resultado e, em seguida, envia um evento session.finished.
• Nenhuma fala detectada: O servidor envia diretamente o evento session.finished.

Após receber o evento session.finished, desconecte a conexão WebSocket.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
type	string	Sim	Valor fixo: session.finish.
event_id	string	Sim	ID de evento exclusivo.

Exemplo

{
    "event_id": "event_341",
    "type": "session.finish"
}