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 :
- SDK DashScope version 2.0.1 ou ultérieure
- Une clé API
- Une bonne compréhension du flux d'interaction
ImportantAlibaba 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
RemarqueLe 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
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.
Cliquez pour afficher l'exemple de code
# 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ètre | Type | Obligatoire | Description |
|---|---|---|---|
model | str | Oui | Modèle à utiliser. |
ws_url | str | Non | Endpoint 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.
Cliquez pour afficher l'exemple de code
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ètre | Type | Obligatoire | Description |
|---|---|---|---|
output_modalities | List[str] | Oui | Modalité de sortie. Valeur fixe : ["text"]. |
enable_turn_detection | bool | Non | Active 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_type | str | Non | Type de VAD côté serveur. Valeur fixe : server_vad. |
turn_detection_threshold | float | Non | Seuil 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_ms | int | Non | Duré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_params | dict | Non | Paramè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.
Cliquez pour afficher l'exemple de code
session.update_session(
output_modalities=['text'],
enable_input_audio_transcription=True,
transcription_params={
'language': 'zh',
'sample_rate': 16000,
'input_audio_format': 'pcm',
},
)
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
language | str | Non | Langue 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_rate | int | Non | Taux 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_format | str | Non | Format audio. Valeur par défaut : pcm. Formats pris en charge : pcm, opus. |
corpus_text | str | Non | Texte 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.updated | Ouvre 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.updated | Configure 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]) | None | Ajoute 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.committed | Valide 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.finished | Termine 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() | None | Arrê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_id | None | L'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éthode | Paramètres | Description |
|---|---|---|
events() | event : un événement serveur | Lit 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() | None | Lecture bloquante d'un événement serveur unique sans itération ; renvoie None en l'absence d'événement (connexion fermée). |