Skip to main content

Qwen-ASR-Realtime Python SDK - API reference

Diffusez des flux audio vers Qwen-ASR-Realtime via WebSocket et obtenez des résultats de transcription en temps réel grâce au SDK Python DashScope.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :
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) : passez de dashscope.aliyuncs.com à {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : passez de dashscope-intl.aliyuncs.com à {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Remplacez {WorkspaceId} par votre véritable ID d'espace de travail. Les domaines existants restent pleinement opérationnels.

Démarrage rapide

Le code d'exemple lit le fichier your_audio_file.pcm (PCM16, 16 kHz, mono). Si vous disposez uniquement d'un fichier MP3, WAV ou d'un format similaire, convertissez-le avec ffmpeg :
ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm
Python
import logging
import os
import signal
import sys
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor

# Les API Key des régions Singapour et Pékin sont différentes. Obtenez votre API Key : https://www.alibabacloud.com/help/model-studio/get-api-key
# Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # Voici la configuration de la région de Singapour (ap-southeast-1). Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def setup_logging():
    """Configure log output"""
    logger = logging.getLogger('dashscope')
    logger.setLevel(logging.DEBUG)
    handler = logging.StreamHandler(sys.stdout)
    handler.setLevel(logging.DEBUG)
    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    logger.propagate = False
    return logger

def handle_event(event):
    """Handle a server-side event"""
    kind = event.get('type')
    if kind == 'session.created':
        print(f"Start session: {event['session']['id']}")
    elif kind == 'conversation.item.input_audio_transcription.completed':
        print(f"Final recognized text: {event['transcript']}")
    elif kind == 'conversation.item.input_audio_transcription.text':
        print(f"Got transcription result: {event['text'] + event['stash']}")
    elif kind == 'input_audio_buffer.speech_started':
        print('======Speech Start======')
    elif kind == 'input_audio_buffer.speech_stopped':
        print('======Speech Stop======')

def receive_events(session):
    """Receive and process server-side events"""
    for event in session.events():
        handle_event(event)

def read_audio_chunks(file_path, chunk_size=3200):
    """Read the audio file in chunks"""
    with open(file_path, 'rb') as f:
        while chunk := f.read(chunk_size):
            yield chunk

def send_audio(session, file_path, delay=0.1):
    """Send audio data"""
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"Audio file {file_path} does not exist.")

    print("Processing audio file... Press 'Ctrl+C' to stop.")
    for chunk in read_audio_chunks(file_path):
        session.append_audio(chunk)  # les bytes sont automatiquement encodés en Base64 avant l'envoi
        time.sleep(delay)

def main():
    setup_logging()

    audio_file_path = "./your_audio_file.pcm"

    # L'entrée dans le contexte with établit automatiquement la connexion
    with client.audio.realtime.connect(
        model='qwen3-asr-flash-realtime',
    ) as session:
        def handle_exit(sig, frame):
            print('Ctrl+C pressed, exiting...')
            session.close()
            sys.exit(0)

        signal.signal(signal.SIGINT, handle_exit)

        # Mettre à jour la configuration de la session : sortie texte uniquement, avec transcription de l'audio d'entrée activée
        session.update_session(
            output_modalities=['text'],
            enable_input_audio_transcription=True,
            transcription_params={
                'language': 'zh',
                'sample_rate': 16000,
                'input_audio_format': 'pcm',
            },
        )
        # Lire jusqu'à session.updated pour confirmer que la configuration a pris effet
        for event in session.events():
            if event.get('type') == 'session.updated':
                break

        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            try:
                send_audio(session, audio_file_path)
                # envoyer session.finish et attendre finished puis la fermeture
                session.end_session()
                receiver.result()
            finally:
                # close doit être exécuté dans le contexte du pool pour débloquer le récepteur
                session.close()
        print("Audio processing completed.")

if __name__ == '__main__':
    main()

Paramètres de requête

client.audio.realtime.connect

Les paramètres suivants se configurent avec client.audio.realtime.connect.
# Les API Key des régions Singapour et Pékin sont différentes. Obtenez votre API Key : https://www.alibabacloud.com/help/model-studio/get-api-key
# Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # Voici la configuration de la région de Singapour (ap-southeast-1). Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Créez une session de reconnaissance en temps réel : l'entrée dans le contexte with établit automatiquement la connexion
session = client.audio.realtime.connect(
    model='qwen3-asr-flash-realtime',
)
ParamètreTypeObligatoireDescription
modelstrOuiModèle à utiliser.
ws_urlstrNonEndpoint WebSocket complet. S'il n'est pas spécifié, l'endpoint est déterminé automatiquement d'après le workspace et la region du Client :
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.

Configuration de session

Après la connexion, appelez update_session pour définir les paramètres de session.
session.update_session(
    output_modalities=['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={
        'language': 'zh',
        'sample_rate': 16000,
        'input_audio_format': 'pcm',
    },
)
ParamètreTypeObligatoireDescription
output_modalitiesList[str]OuiModalité de sortie. Valeur fixe : ["text"].
enable_turn_detectionboolNonActive la détection d'activité vocale (VAD) côté serveur. Valeur par défaut : True. Si défini sur False, appelez manuellement commit() pour déclencher la reconnaissance.
turn_detection_typestrNonType de VAD côté serveur. Valeur fixe : server_vad.
turn_detection_thresholdfloatNonSeuil de sensibilité du VAD. Valeur par défaut : 0.2. Recommandé : 0.0. Plage valide : [-1, 1].
Des valeurs plus basses = sensibilité accrue (risque de déclenchement sur le bruit ambiant). Des valeurs plus élevées = moins de faux positifs dans les environnements bruyants.
turn_detection_silence_duration_msintNonDurée de silence (ms) marquant la fin d'une phrase. Valeur par défaut : 800. Recommandé : 400. Plage valide : [200, 6000].
Une valeur faible (ex. : 300 ms) = réponse plus rapide mais peut scinder les pauses naturelles. Une valeur élevée (ex. : 1200 ms) = mieux adaptée aux pauses dans les phrases longues mais latence accrue.
transcription_paramsdictNonParamètres de reconnaissance vocale. Consultez transcription_params.

transcription_params

Définissez les paramètres de reconnaissance vocale via le dictionnaire transcription_params de update_session.
session.update_session(
    output_modalities=['text'],
    enable_input_audio_transcription=True,
    transcription_params={
        'language': 'zh',
        'sample_rate': 16000,
        'input_audio_format': 'pcm',
    },
)
ParamètreTypeObligatoireDescription
languagestrNonLangue source de l'audio. Valeurs prises en charge :
zh (chinois : mandarin, sichuanais, minnan, wu), yue (cantonais), en (anglais), ja (japonais), ko (coréen), de (allemand), fr (français), es (espagnol), pt (portugais), it (italien), ru (russe), ar (arabe), hi (hindi), id (indonésien), th (thaï), tr (turc), uk (ukrainien), vi (vietnamien), cs (tchèque), da (danois), fi (finnois), fil (filipino), is (islandais), ms (malais), no (norvégien), pl (polonais), sv (suédois)
sample_rateintNonTaux d'échantillonnage audio en Hz. Valeur par défaut : 16000. Valeurs prises en charge : 16000, 8000. Avec 8000, le serveur rééchantillonne à 16 000 Hz avant la reconnaissance, ce qui peut ajouter une légère latence. N'utilisez 8000 que pour un audio source à 8 kHz, comme les enregistrements téléphoniques.
input_audio_formatstrNonFormat audio. Valeur par défaut : pcm. Formats pris en charge : pcm, opus.
corpus_textstrNonTexte contextuel, vocabulaire d'entités ou autres informations de référence pour le biaisage contextuel. Maximum : 10 000 tokens. Pour plus de détails, consultez Biaisage contextuel.

Référence de l’API

Classe RealtimeSession

Une session de reconnaissance en temps réel se crée avec client.audio.realtime.connect(model=...) : la connexion est établie à l'entrée dans le contexte with (ou lors de l'appel de la méthode connect() de la session).
MéthodeÉvénement de réponse serveur (délivré via events())Description
connect()session.created, session.updatedOuvre une connexion WebSocket avec le serveur. Appelée automatiquement à l'entrée dans le contexte with ; n'appelez pas connect() puis entrez dans le contexte with de la même session.
update_session(...)session.updatedConfigure la session. À appeler après connect(). Si omis, les valeurs par défaut s'appliquent. Consultez la section Configuration de session pour les paramètres.
append_audio(audio: Union[str, bytes])NoneAjoute un fragment audio au tampon d'entrée du serveur. Une valeur str est considérée comme déjà encodée en Base64 ; les bytes sont automatiquement encodés en Base64. Avec enable_turn_detection=True, le serveur détecte les limites de parole et valide automatiquement. Avec enable_turn_detection=False, le client contrôle le moment de la validation (max. 15 Mio par événement). Des fragments plus petits améliorent la réactivité du VAD.
commit()input_audio_buffer.committedValide l'audio mis en tampon pour la reconnaissance. Renvoie une erreur si le tampon est vide. Désactivé lorsque enable_turn_detection=True.
end_session()session.finishedTermine la session une fois la reconnaissance finale effectuée par le serveur. En mode VAD (par défaut), appelez cette méthode après l'envoi de tout l'audio. En mode manuel, appelez-la après commit().
close()NoneArrête la tâche et ferme la connexion (idempotent, n'envoie pas session.finish).
events()Événements du serveur (le type d'événement est dans event["type"])Lit en continu les événements du serveur. L'itération se termine après le renvoi de session.finished ; consommez les événements depuis un unique thread récepteur et ne créez pas plusieurs lecteurs concurrents.
session.session_id, session.last_response_idNoneL'ID de session de la tâche en cours et l'ID de réponse le plus récent (attributs).

Itération d'événements (events())

Le serveur renvoie les réponses et les données au client sous forme d'événements. Itérez sur les events() de la session dans un thread récepteur et répartissez selon event["type"] (liste complète des événements : consultez Événements du serveur).
def receive_events(session):
    for event in session.events():
        kind = event.get('type')
        if kind == 'session.created':
            print(f"Start session: {event['session']['id']}")
        elif kind == 'conversation.item.input_audio_transcription.completed':
            print(f"Final recognized text: {event['transcript']}")
        elif kind == 'conversation.item.input_audio_transcription.text':
            print(f"Got transcription result: {event['text'] + event['stash']}")
MéthodeParamètresDescription
events()event : un événement serveurLit et renvoie en continu les événements du serveur (dict). L'itération se termine à la fermeture de la connexion ou à la réception de session.finished.
recv_event()NoneLecture bloquante d'un événement serveur unique sans itération ; renvoie None en l'absence d'événement (connexion fermée).