Este documento descreve como usar o SDK Python do DashScope para chamar o modelo de tradução de áudio e vídeo em tempo real Qwen-LiveTranslate-Realtime.
Para a conexão e a autenticação, consulte Acesso por WebSocket. Para os campos de eventos e exemplos JSON, consulte Eventos do cliente e Eventos do servidor.
Pré-requisitos
- Instale o SDK. Verifique se a versão do seu DashScope SDK é 1.25.6 ou superior.
- Obtenha uma chave de API.
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 a migração para os novos domínios:
- China (Beijing): de
wss://dashscope.aliyuncs.comparawss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: de
wss://dashscope-intl.aliyuncs.comparawss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} é o ID do seu workspace, que pode ser encontrado na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.
Início rápido
Este exemplo captura áudio do microfone e o traduz em tempo real.
Código de exemplo para tradução em tempo real a partir do microfone
import os
import sys
import base64
import signal
import pyaudio
from dashscope.audio.qwen_omni import (
OmniRealtimeConversation,
OmniRealtimeCallback,
MultiModality,
)
from dashscope.audio.qwen_omni.omni_realtime import TranslationParams
class Callback(OmniRealtimeCallback):
"""Callback handler class for real-time translation"""
def __init__(self, speaker):
self.speaker = speaker
def on_open(self):
print("[Connection established]")
def on_close(self, code, msg):
print(f"[Connection closed] code: {code}, msg: {msg}")
def on_event(self, response):
event_type = response.get("type", "")
if event_type == "input_audio_buffer.speech_started":
print("====== Speech input detected ======")
elif event_type == "input_audio_buffer.speech_stopped":
print("====== Speech input ended ======")
elif event_type == "conversation.item.input_audio_transcription.completed":
print(f"[Original text] {response.get('transcript', '')}")
elif event_type == "response.audio_transcript.done":
print(f"[Translation result] {response.get('transcript', '')}")
elif event_type == "response.audio.delta":
audio_b64 = response.get("delta", "")
if audio_b64:
self.speaker.write(base64.b64decode(audio_b64))
elif event_type == "error":
print(f"[Error] {response.get('error', {}).get('message', '')}")
def main():
# Check for the API key.
if not os.environ.get("DASHSCOPE_API_KEY"):
print("Set the DASHSCOPE_API_KEY environment variable.")
sys.exit(1)
# Initialize PyAudio.
pya = pyaudio.PyAudio()
# Initialize the speaker for playing back the translated audio.
speaker = pya.open(
format=pyaudio.paInt16,
channels=1,
rate=24000,
output=True,
frames_per_buffer=2400
)
# Initialize the microphone for capturing speech input.
mic = pya.open(
format=pyaudio.paInt16,
channels=1,
rate=16000,
input=True,
frames_per_buffer=1600
)
# Create a callback instance.
callback = Callback(speaker=speaker)
# Create a real-time session.
conversation = OmniRealtimeConversation(
model="qwen3.5-livetranslate-flash-realtime",
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
url="wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime",
callback=callback
)
# Connect to the server.
conversation.connect()
# Configure translation parameters.
translation_params = TranslationParams(
language="en", # Target language for translation: English
corpus=TranslationParams.Corpus(
phrases={
"Source Term 1": "Target Translation 1",
"Source Term 2": "Target Translation 2"
}
)
)
# Update the session configuration.
conversation.update_session(
output_modalities=[MultiModality.TEXT, MultiModality.AUDIO],
input_audio_transcription_model="qwen3-asr-flash-realtime",
voice="Tina",
translation_params=translation_params,
)
# Register the exit signal handler.
def on_exit(sig, frame):
print("\n[Exiting...]")
mic.stop_stream()
mic.close()
speaker.stop_stream()
speaker.close()
pya.terminate()
conversation.end_session()
conversation.close()
sys.exit(0)
signal.signal(signal.SIGINT, on_exit)
print("[Starting real-time translation] Speak into the microphone. Press Ctrl+C to exit.")
# Continuously capture and send microphone audio.
while True:
audio_data = mic.read(1600, exception_on_overflow=False)
conversation.append_audio(base64.b64encode(audio_data).decode("ascii"))
if __name__ == "__main__":
main()
Parâmetros da solicitação
-
Defina os seguintes parâmetros no construtor da classe
OmniRealtimeConversation.Clique em visualizar o código de exemplo
from dashscope.audio.qwen_omni import ( OmniRealtimeConversation, OmniRealtimeCallback, MultiModality, ) from dashscope.audio.qwen_omni.omni_realtime import TranslationParams class MyCallback(OmniRealtimeCallback): """Callback handler for real-time translation""" def __init__(self, conversation=None): self.conversation = conversation self.handlers = { 'session.created': self._handle_session_created, 'response.audio_transcript.done': self._handle_translation_done, 'response.audio.delta': self._handle_audio_delta, 'response.done': lambda r: print('======Response Done======'), '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"Session created: {response['session']['id']}") def _handle_translation_done(self, response): print(f"Translation result: {response['transcript']}") def _handle_audio_delta(self, response): # Process incremental audio data. audio_b64 = response.get('delta', '') # Decode the audio data for playback or to save it. conversation = OmniRealtimeConversation( model='qwen3.5-livetranslate-flash-realtime', # China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region. url='wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime', callback=MyCallback(conversation=None) # Temporarily pass None. It will be injected later. ) # Inject self into the callback. conversation.callback.conversation = conversationParâmetro Tipo Obrigatório Descrição modelstrSim
Nome do modelo a ser utilizado. Defina como
qwen3.5-livetranslate-flash-realtime(recomendado).callbackOmniRealtimeCallbackSim
Instância de callback para tratar eventos do lado do servidor.
urlstrSim
Endpoint do service para tradução em tempo real:
- China (Beijing):
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime - Singapore:
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime
Substitua
{WorkspaceId}pelo seu workspace ID real. - China (Beijing):
-
Configure os parâmetros abaixo por meio do método
update_sessionda classeOmniRealtimeConversation.Clique em visualizar o código de exemplo
# Set translation parameters translation_params = TranslationParams( language='en', # Target language corpus=TranslationParams.Corpus( phrases={ 'Inteligencia Artificial': 'Artificial Intelligence', 'Aprendizaje Automático': 'Machine Learning' } ) ) # Update session configuration conversation.update_session( output_modalities=[MultiModality.TEXT, MultiModality.AUDIO], voice='Tina', translation_params=translation_params, )Parâmetro
Tipo
Obrigatório
Descrição
output_modalitiesList[MultiModality]Não
Formato de saída dos resultados da tradução.
Padrão:
[MultiModality.TEXT, MultiModality.AUDIO].Valores válidos:
[MultiModality.TEXT]: Gera apenas texto[MultiModality.TEXT, MultiModality.AUDIO]: Gera texto e áudio
voicestrNão
Voz utilizada na saída de áudio.
Padrão:
Qwen3.5-LiveTranslate-Flash-Realtime:
Tina
Valores válidos: Supported voices.
input_audio_transcription_modelstrNão
Defina este parâmetro como
qwen3-asr-flash-realtimepara receber resultados de reconhecimento de fala no idioma de origem.translation_paramsTranslationParamsNão
Configurações de tradução (idioma alvo e palavras-chave).
enable_turn_detectionboolNão
Indica se o VAD (Detecção de Atividade de Voz) deve ser ativado.
Valor padrão:
True, que habilita o modo VAD, onde o servidor detecta automaticamente o início e o fim da fala e aciona a tradução.Defina como
Falsepara alternar para o modo Manual, no qual o cliente envia o áudio manualmente através do métodocommit. Para descrições detalhadas dos parâmetros, consulte a descrição deturn_detectionno documento Client events. -
Especifique os seguintes parâmetros no construtor da classe
TranslationParams.Clique em visualizar o código de exemplo
translation_params = TranslationParams( language='en', # Target language code corpus=TranslationParams.Corpus( phrases={ 'Inteligencia Artificial': 'Artificial Intelligence', # Source phrase: Target translation 'Aprendizaje Automático': 'Machine Learning' } ) )Parâmetro
Tipo
Obrigatório
Descrição
languagestrNão
Idioma alvo da tradução.
Padrão:
en.Valores válidos: Supported languages.
corpusTranslationParams.CorpusNão
Mapeamento de palavras-chave para melhorar a precisão da tradução de termos específicos.
corpus.phrasesdictNão
Tabela de mapeamento de palavras-chave, onde as chaves são os termos de origem e os valores são as traduções alvo.
Exemplo:
{'Inteligencia Artificial': 'Artificial Intelligence'}
Referência da API
Classe OmniRealtimeConversation
Importação: from dashscope.audio.qwen_omni import OmniRealtimeConversation
| Assinatura do método | Evento de resposta do servidor (enviado via callback) | Descrição |
|---|---|---|
|
| Conecta ao servidor. |
| Sessão atualizada
| Atualiza a configuração da sessão. Chame imediatamente após a conexão. Caso este método não seja chamado, as configurações padrão serão aplicadas. |
|
| Encerra a sessão. O servidor finaliza o processamento da última tradução. |
| Nenhum | Envia fragmentos de áudio codificados em Base64 para o servidor. A detecção de fala e a tradução ocorrem automaticamente. |
|
| No modo Manual, envia o áudio previamente adicionado ao buffer do servidor através do método |
|
| Limpa os dados de áudio não confirmados no buffer atual do servidor. |
| Nenhum | Interrompe a tarefa e fecha a conexão. |
| Nenhum | Obtém o ID da sessão. |
| Nenhum | Obtém o ID da última resposta. |
Interface de callback (OmniRealtimeCallback)
Receba eventos e dados do servidor por meio de callbacks.
Herde esta classe e implemente seus métodos para tratar os eventos provenientes do servidor.
Importação: from dashscope.audio.qwen_omni import OmniRealtimeCallback
| Assinatura do método | Parâmetros | Descrição |
|---|---|---|
| Nenhum | Chamado quando a conexão WebSocket é aberta. |
| message: Server-side event | Chamado quando o servidor envia um evento. |
| close_status_code: O código de status. close_msg: A mensagem de log quando a conexão WebSocket é fechada. | Chamado quando a conexão WebSocket é fechada. |
dashscope.Client(): recebimento de eventos após um erro
Ao usar dashscope.Client() no DashScope SDK 2.x, receba eventos pelos métodos events() ou recv_event() da sessão. Consulte Iteração de eventos do Python SDK 2.x para o uso completo.
Quando você captura DashScopeError, o iterador events() em uso já terminou. Capturar a exceção em um try/except externo não reinicia o recebimento de eventos.
Se a conexão WebSocket ainda puder ser usada, corrija a solicitação e chame events() novamente ou use recv_event() para receber um evento por vez. Se a conexão estiver fechada, primeiro reconecte e configure uma nova sessão e depois retome o recebimento de eventos.
Para investigar a causa do erro, leia o evento de erro original do servidor em body na exceção.