Skip to main content

SDK Python Qwen-LiveTranslate-Realtime

Ce document explique comment utiliser le SDK Python DashScope pour appeler le modèle de traduction audio et vidéo en temps réel Qwen-LiveTranslate-Realtime.

Consultez la documentation Qwen-LiveTranslate-Realtime Python SDK actuelle. Pour la connexion et l’authentification, consultez Connexion WebSocket. Pour les champs des événements et les exemples JSON, consultez Événements client et Événements serveur.

Prérequis

  1. Installez le SDK. Vérifiez que votre version du SDK DashScope est 1.25.6 ou ultérieure.
  2. Obtenez une clé API.
Alibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions Chine (Pékin) et Singapour. Ces nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • Chine (Pékin) : de wss://dashscope.aliyuncs.com à wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : de wss://dashscope-intl.aliyuncs.com à wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} correspond à l'ID de votre espace de travail, disponible sur la page Workspace Details dans la console Alibaba Cloud Model Studio. Le domaine existant reste pleinement fonctionnel.

Paramètres de requête

  • Définissez les paramètres suivants dans le constructeur de la classe OmniRealtimeConversation.
    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 = conversation
    
    ParamètreTypeObligatoireDescription
    modelstrOuiNom du modèle à utiliser. Définissez cette valeur sur qwen3.5-livetranslate-flash-realtime (recommandé).
    callbackOmniRealtimeCallbackOuiInstance de rappel pour gérer les événements côté serveur.
    urlstrOuiEndpoint du service pour la traduction en temps réel :
    • Chine (Pékin) : wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime
    • Singapour : wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime
    Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
  • Configurez les paramètres ci-dessous via la méthode update_session de la classe OmniRealtimeConversation.
    # 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,
    )
    
    ParamètreTypeObligatoireDescription
    output_modalitiesList[MultiModality]NonFormat de sortie des résultats de traduction.Valeur par défaut : [MultiModality.TEXT, MultiModality.AUDIO].Valeurs valides :
    • [MultiModality.TEXT] : Sortie texte uniquement
    • [MultiModality.TEXT, MultiModality.AUDIO] : Sortie texte et audio
    voicestrNonVoix utilisée pour la sortie audio.Valeur par défaut :
    • Qwen3.5-LiveTranslate-Flash-Realtime : Tina
    Valeurs valides : Voix prises en charge.
    input_audio_transcription_modelstrNonDéfinissez ce paramètre sur qwen3-asr-flash-realtime pour recevoir les résultats de reconnaissance vocale dans la langue source.
    translation_paramsTranslationParamsNonParamètres de traduction (langue cible et mots-clés).
    enable_turn_detectionboolNonActive ou désactive la détection d'activité vocale (VAD).Valeur par défaut : True, ce qui active le mode VAD où le serveur détecte automatiquement le début et la fin de la parole pour déclencher la traduction.Définissez cette valeur sur False pour passer en mode manuel, où le client soumet explicitement l'audio via la méthode commit. Pour une description détaillée des paramètres, consultez la section turn_detection dans le document Événements client.
  • Spécifiez les paramètres suivants dans le constructeur de la classe TranslationParams.
    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'
            }
        )
    )
    

    Paramètre

    Type

    Obligatoire

    Description

    language

    str

    Non

    Langue cible de la traduction.

    Valeur par défaut : en.

    Valeurs valides : Langues prises en charge.

    corpus

    TranslationParams.Corpus

    Non

    Tableau de mots-clés permettant d'améliorer la précision de traduction pour des termes spécifiques.

    corpus.phrases

    dict

    Non

    Dictionnaire de correspondance des mots-clés, où les clés sont les termes sources et les valeurs leurs traductions cibles.

    Exemple : {'Inteligencia Artificial': 'Artificial Intelligence'}

Interfaces principales

Classe OmniRealtimeConversation

Importation : from dashscope.audio.qwen_omni import OmniRealtimeConversation
Signature de la méthodeÉvénement de réponse serveur (envoyé via rappel)Description
def connect(self) -> None:
Événement serveur
Session créée
Événement serveur
Configuration de session mise à jour
Établit la connexion au serveur.
def update_session(self,
    output_modalities: List[MultiModality],
    voice: str = None,
    translation_params: TranslationParams = None,
    **kwargs) -> None:
Session mise à jour
Session mise à jour
Met à jour la configuration de la session. Appelez cette méthode immédiatement après la connexion. En son absence, les configurations par défaut s'appliquent.
def end_session(self, timeout: int = 20) -> None:
session.finished
Le serveur termine la traduction vocale et clôture la session
Termine la session. Le serveur effectue le dernier traitement de traduction.
def append_audio(self, audio_b64: str) -> None:
AucunEnvoie des fragments audio encodés en Base64 au serveur. La détection de la parole et la traduction s'effectuent automatiquement.
def commit(self) -> None:
Événement serveur
Tampon audio d'entrée validé
En mode manuel, valide l'audio précédemment ajouté au tampon serveur via la méthode append_audio. Dès réception, le serveur commence automatiquement à générer les réponses de traduction. En mode VAD, cet appel est inutile car le serveur valide les données automatiquement.
def clear_appended_audio(self) -> None:
Événement serveur
Tampon audio d'entrée effacé
Efface les données audio non validées présentes dans le tampon serveur actuel.
def close(self) -> None:
AucunArrête la tâche et ferme la connexion.
def get_session_id(self) -> str:
AucunRécupère l'ID de session.
def get_last_response_id(self) -> str:
AucunRécupère l'ID de la dernière réponse.

Interface de rappel (OmniRealtimeCallback)

Recevez les événements et les données du serveur par le biais de rappels. Héritez de cette classe et implémentez ses méthodes pour traiter les événements provenant du serveur. Importation : from dashscope.audio.qwen_omni import OmniRealtimeCallback
Signature de la méthodeParamètresDescription
def on_open(self) -> None:
AucunAppelé lors de l'ouverture de la connexion WebSocket.
def on_event(self, message: dict) -> None:
message : Événement serveurAppelé lorsque le serveur envoie un événement.
def on_close(self, close_status_code, close_msg) -> None:
close_status_code : Code d'état.close_msg : Message de journal lors de la fermeture de la connexion WebSocket.Appelé lors de la fermeture de la connexion WebSocket.

dashscope.Client() : réception des événements après une erreur

Avec dashscope.Client() du SDK DashScope 2.x, recevez les événements avec les méthodes events() ou recv_event() de la session. Consultez Itération des événements du SDK Python 2.x pour leur utilisation complète. Lorsque vous interceptez DashScopeError, l'itérateur events() en cours est déjà terminé. Intercepter l'exception dans un try/except externe ne relance pas la réception des événements. Si la connexion WebSocket reste utilisable, corrigez la requête et appelez à nouveau events(), ou utilisez recv_event() pour recevoir les événements un par un. Si la connexion est fermée, commencez par vous reconnecter et configurer une nouvelle session, puis reprenez la réception des événements. Pour rechercher la cause de l'erreur, consultez l'événement d'erreur d'origine du serveur dans le champ body de l'exception.

Exemple complet

Cet exemple capture l'audio du microphone et le traduit en temps réel.
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()