Transmita áudio para o Qwen-ASR-Realtime via WebSocket e receba resultados de transcrição em tempo real pelo DashScope Python SDK.
Para uma visão geral dos modelos compatíveis, recursos e código de exemplo completo, consulte Reconhecimento de fala em tempo real.
Antes de começar, verifique se você tem:
Crie uma instância de
Após conectar, chame
Configure as definições de reconhecimento de fala com o construtor
Crie uma subclasse de
Pré-requisitos
Antes de começar, verifique se você tem:
- DashScope SDK 1.25.6 ou posterior
- Uma chave de API
- Conhecimento do fluxo de interação
Parâmetros da solicitação
Construtor OmniRealtimeConversation
Crie uma instância de OmniRealtimeConversation com os seguintes parâmetros.
Clique para visualizar o código de exemplo
Clique para visualizar o código de exemplo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | Modelo a ser usado. |
callback | OmniRealtimeCallback | Sim | Objeto de callback que gerencia eventos do servidor. |
url | str | Sim | Endpoint WebSocket. China (Pequim): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime. Substitua {WorkspaceId} pelo seu Workspace ID real. |
Configuração da sessão
Após conectar, chame update_session para configurar os parâmetros da sessão.
Clique para visualizar o código de exemplo
Clique para visualizar o código de exemplo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
output_modalities | List[MultiModality] | Sim | Modalidade de saída. Fixo como [MultiModality.TEXT]. |
enable_turn_detection | bool | Não | Ativa a detecção de atividade de voz (VAD) no servidor. Padrão: True. Quando False, chame commit() manualmente para acionar o reconhecimento. |
turn_detection_type | str | Não | Tipo de VAD no servidor. Fixo como server_vad. |
turn_detection_threshold | float | Não | Limiar de sensibilidade do VAD. Padrão: 0.2. Recomendado: 0.0. Intervalo válido: [-1, 1]. Valores menores = maior sensibilidade (pode ser acionado por ruído ambiente). Valores maiores = menos acionamentos falsos em ambientes ruidosos. |
turn_detection_silence_duration_ms | int | Não | Duração do silêncio (ms) que marca o fim de uma fala. Padrão: 800. Recomendado: 400. Intervalo válido: [200, 6000]. Valores menores (ex.: 300 ms) = resposta mais rápida, mas pode dividir pausas naturais. Valores maiores (ex.: 1200 ms) = melhor tratamento de pausas em frases longas, porém com maior latência. |
transcription_params | TranscriptionParams | Não | Configurações de reconhecimento de fala. Consulte TranscriptionParams. |
TranscriptionParams
Configure as definições de reconhecimento de fala com o construtor TranscriptionParams.
Clique para visualizar o código de exemplo
Clique para visualizar o código de exemplo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
language | str | Não | Idioma de origem do áudio. Valores compatíveis: zh (chinês: mandarim, sichuanês, minnan, wu), yue (cantonês), en (inglês), ja (japonês), ko (coreano), de (alemão), fr (francês), es (espanhol), pt (português), it (italiano), ru (russo), ar (árabe), hi (hindi), id (indonésio), th (tailandês), tr (turco), uk (ucraniano), vi (vietnamita), cs (tcheco), da (dinamarquês), fi (finlandês), fil (filipino), is (islandês), ms (malaio), no (norueguês), pl (polonês), sv (sueco) |
sample_rate | int | Não | Taxa de amostragem de áudio em Hz. Padrão: 16000. Compatível: 16000, 8000. Com 8000, o servidor faz upsampling para 16.000 Hz antes do reconhecimento, o que pode adicionar uma pequena latência. Use 8000 apenas para áudio de origem de 8 kHz, como gravações telefônicas. |
input_audio_format | str | Não | Formato de áudio. Padrão: pcm. Compatível: pcm, opus. |
corpus_text | str | Não | Texto de contexto, vocabulários de entidades ou outras informações de referência para viés contextual. Máximo: 10.000 tokens. Para detalhes, consulte Viés contextual. |
Interfaces principais
Classe OmniRealtimeConversation
| Método | Evento de resposta do servidor | Descrição |
|---|---|---|
connect() | session.created, session.updated | Abre uma conexão WebSocket com o servidor. |
update_session(...) | session.updated | Configura a sessão. Chame após connect(). Se omitido, os padrões são aplicados. Consulte Configuração da sessão para os parâmetros. |
append_audio(audio_b64: str) | Nenhum | Envia um bloco de áudio codificado em Base64 para o buffer de entrada do servidor. Com enable_turn_detection=True, o servidor detecta os limites de fala e faz o commit automaticamente. Com enable_turn_detection=False, o cliente controla o momento do commit (máximo de 15 MiB por evento). Blocos menores melhoram a responsividade do VAD. |
commit() | input_audio_buffer.committed | Faz o commit do áudio armazenado no buffer para reconhecimento. Retorna um erro se o buffer estiver vazio. Desativado quando enable_turn_detection=True. |
end_session(timeout: int = 20) | session.finished | Encerra a sessão após o servidor concluir o reconhecimento final. No modo VAD (padrão), chame após enviar todo o áudio. No modo manual, chame após commit(). Variante assíncrona: end_session_async(). |
close() | Nenhum | Encerra a tarefa e fecha a conexão. |
get_session_id() | Nenhum | Retorna o ID da sessão atual. |
get_last_response_id() | Nenhum | Retorna o ID da resposta mais recente. |
Interface OmniRealtimeCallback
Crie uma subclasse de OmniRealtimeCallback e implemente seus métodos para gerenciar eventos do servidor.
| Método | Parâmetros | Descrição |
|---|---|---|
on_open() | Nenhum | Chamado quando a conexão WebSocket é estabelecida. |
on_event(message: dict) | message: um evento do servidor | Chamado quando um evento do servidor é recebido. |
on_close(close_status_code, close_msg) | close_status_code: código de status; close_msg: mensagem de log | Chamado quando a conexão WebSocket é fechada. |