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.
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
ImportanteAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
- China (Beijing): from
dashscope.aliyuncs.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.
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
from dashscope.audio.qwen_omni import OmniRealtimeConversation, OmniRealtimeCallback
class MyCallback(OmniRealtimeCallback):
"""Callback for real-time recognition"""
def __init__(self, conversation):
self.conversation = conversation
self.handlers = {
'session.created': self._handle_session_created,
'conversation.item.input_audio_transcription.completed': self._handle_final_text,
'conversation.item.input_audio_transcription.text': self._handle_stash_text,
'input_audio_buffer.speech_started': lambda r: print('======Speech Start======'),
'input_audio_buffer.speech_stopped': lambda r: print('======Speech Stop======')
}
def on_open(self):
print('Connection opened')
def on_close(self, code, msg):
print(f'Connection closed, code: {code}, msg: {msg}')
def on_event(self, response):
try:
handler = self.handlers.get(response['type'])
if handler:
handler(response)
except Exception as e:
print(f'[Error] {e}')
def _handle_session_created(self, response):
print(f"Start session: {response['session']['id']}")
def _handle_final_text(self, response):
print(f"Final recognized text: {response['transcript']}")
def _handle_stash_text(self, response):
print(f"Got stash result: {response['stash']}")
conversation = OmniRealtimeConversation(
model='qwen3-asr-flash-realtime',
# The following URL is for the Chinese mainland. For regions outside
# the Chinese mainland, use
# wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime instead.
url='wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime',
callback=MyCallback(conversation=None) # Temporarily pass None and inject it later.
)
# Inject self into the callback.
conversation.callback.conversation = conversation
| 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
from dashscope.audio.qwen_omni import TranscriptionParams, MultiModality
transcription_params = TranscriptionParams(
language='zh',
sample_rate=16000,
input_audio_format="pcm"
)
conversation.update_session(
output_modalities=[MultiModality.TEXT],
enable_turn_detection=True,
turn_detection_type="server_vad",
turn_detection_threshold=0.0,
turn_detection_silence_duration_ms=400,
enable_input_audio_transcription=True,
transcription_params=transcription_params
)
| 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
transcription_params = TranscriptionParams(
language='zh',
sample_rate=16000,
input_audio_format="pcm"
)
| 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
from dashscope.audio.qwen_omni import 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.
from dashscope.audio.qwen_omni import OmniRealtimeCallback
| 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. |