Skip to main content

Connexion WebSocket à Qwen-Audio-Realtime

Connexion WebSocket à Qwen-Audio-Realtime

Guide d’utilisation : Conversation vocale en temps réel (Qwen-Audio-Realtime). Pour les définitions détaillées des événements, consultez Événements client et Événements serveur. Modèles pris en charge : qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus et qwen-audio-3.0-realtime-flash.
Alibaba Cloud Model Studio propose des domaines propres à chaque espace de travail dans les régions Chine (Pékin) et Singapour. Ces nouveaux domaines dédiés améliorent les performances et la stabilité des requêtes d’inférence. Nous vous recommandons de migrer vers ces domaines :
  • China (Beijing) : passez de dashscope.aliyuncs.com à {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore : passez de dashscope-intl.aliyuncs.com à {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Remplacez {WorkspaceId} par l’ID de votre espace de travail. Les domaines existants restent disponibles.

Point de terminaison

Utilisez l'URL WebSocket suivante. Le paramètre de requête model spécifie le modèle. Remplacez <model_name> par le nom du modèle :
  • Chine (Pékin)
  • Singapour
WebSocketwss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Remplacez {WorkspaceId} par l’ID de votre espace de travail lors de l’appel de l’API.

L’URL doit utiliser wss://. Définissez Authorization dans les en-têtes de requête et indiquez le modèle avec le paramètre de requête model.

En-têtes de requête

Incluez les informations suivantes dans les en-têtes de requête :

Paramètre

Type

Obligatoire

Description

Authorization

string

Oui

Jeton d’authentification au format Bearer <your_api_key>. Remplacez <your_api_key> par votre API Key.

user-agent

string

Non

Identifiant du client utilisé pour tracer la source de la requête.

X-DashScope-WorkSpace

string

Non

ID de l’espace de travail Alibaba Cloud Model Studio.

L’authentification est vérifiée pendant la négociation WebSocket. Si l’API Key est absente ou non valide, la négociation échoue avec un code HTTP 401/403. Stockez les API Keys à longue durée de validité sur le serveur, sans les inclure dans une application mobile ou de navigateur. Pour les API Keys temporaires et leurs autorisations, consultez Générer une API Key temporaire.
La référence générale WebSocket présente également l’en-tête X-DashScope-DataInspection pour l’inspection des données. Utilisez-le selon les exigences du modèle. L’exemple pour qwen-audio-3.1-realtime-plus utilise x-dashscope-dataInspection: disable.

Concepts clés

  • Session: Une connexion WebSocket correspond à une session, qui conserve la configuration et le contexte de conversation.
  • Élément de conversation: Chaque message de la conversation, organisé en liste chaînée.
  • Réponse: La sortie d’une inférence du modèle. Une réponse contient un ou plusieurs éléments de sortie, qui peuvent être des messages de l’assistant ou des appels de fonction.
  • Appel de fonction: Une requête du modèle demandant au client d’exécuter une fonction d’outil. Après l’exécution, le client soumet le résultat sous la forme function_call_output, puis envoie response.create pour déclencher l’inférence suivante.
  • Détection des tours: Contrôle le déclenchement de l’inférence.

Modes d’interaction

Qwen-Audio Realtime API prend en charge trois modes d’interaction, configurés via session.turn_detection dans l’événement session.update. Pour la détection automatique, définissez type dans l’objet. Pour le mode push-to-talk, définissez le champ turn_detection entier sur null :

Mode

Valeur de session.turn_detection

Description

Cas d’utilisation

server_vad

Objet. Définissez type à server_vad.

Le serveur utilise la VAD pour détecter le début et la fin de la parole et déclencher automatiquement l’inférence.

Conversation mains libres et assistants vocaux

Détection sémantique intelligente des tours

Objet. Définissez type à smart_turn ou smart_turn_v2 (recommandé).

Combine la perception acoustique et la compréhension sémantique pour détecter les limites des tours, au lieu de se fier uniquement aux signaux vocaux. Les sons sans signification sémantique, tels que "uh" et "ah", ne déclenchent pas de tour et n’interrompent pas la lecture du modèle.

Conversation naturelle à faible latence et gestion précise des interruptions

push-to-talk

null

Le client soumet manuellement l’audio et déclenche l’inférence.

Push-to-talk et contrôle précis

Déroulement des interactions

Pour les définitions détaillées des événements, consultez Événements client et Événements serveur.

Mode server_vad

Le serveur effectue une détection d’activité vocale sur l’audio entrant et déclenche automatiquement l’inférence lorsqu’il détecte la fin de la parole. Activer ce mode : Définissez turn_detection.type à server_vad dans le champ session.update événement.
  • Un tour de conversation complet
  • Interruption par l’utilisateur
Le diagramme suivant montre une séquence d’interaction courante en mode server_vad :
111
Le client et le serveur interagissent dans l’ordre suivant :
  1. Le client établit une connexion WebSocket. Le serveur renvoie session.created.
  2. Le client envoie session.update pour configurer la session. Le serveur renvoie session.updated.
  3. Le client envoie en continu input_audio_buffer.append pour ajouter les données audio.
  4. Lorsque le serveur détecte le début de la parole, il renvoie input_audio_buffer.speech_started et transmet les incréments de transcription ASR via conversation.item.input_audio_transcription.delta.
  5. Lorsque le serveur détecte la fin de la parole, il renvoie input_audio_buffer.speech_stopped, input_audio_buffer.committed et conversation.item.created.
  6. Le serveur génère automatiquement une réponse et transmet les incréments de texte et d’audio (response.audio_transcript.delta et response.audio.delta), puis renvoie response.done.

Mode smart_turn / smart_turn_v2

Ce mode combine perception acoustique et compréhension sémantique pour détecter la fin de la parole. Il peut filtrer les sons sans signification, tels que les acquiescements et l’audio en arrière-plan. Ces sons sont transmis via les événements conversation.item.ambient_audio_transcription.delta et ne déclenchent pas de tour de conversation. Activer ce mode : Définissez turn_detection.type à smart_turn ou smart_turn_v2 dans le champ session.update événement. smart_turn_v2 (recommandé) : étend smart_turn avec une meilleure compréhension du contexte de conversation pour identifier les intentions d’interaction dans les scénarios à plusieurs interlocuteurs. Il réduit les réponses et interruptions indésirables dues à d’autres locuteurs ou à des propos sans rapport.
  • Un tour de conversation complet
  • Interruption par l’utilisateur
  • Tour non valide
Le diagramme suivant montre une séquence d’interaction courante en mode smart_turn / smart_turn_v2 :
111
Les principales différences avec le mode server_vad sont les suivantes :
  • Les sons sans signification sémantique, tels que "uh" et "ah", ne déclenchent pas d’inférence. Ils sont renvoyés via les événements ambient_audio_transcription.
  • Une séquence vocale précédemment reconnue comme valide peut être invalidée : input_audio_buffer.speech_stopped renvoie reason=turn_invalid. Dans ce cas, aucune inférence n’est déclenchée.
  • Pendant l’attente de l’entrée utilisateur suivante, le client peut envoyer explicitement response.create pour déclencher l’inférence.

Procédure de configuration du renforcement du locuteur

En mode smart_turn / smart_turn_v2, si le premier session.update contient voiceprint_audio_urls, le serveur enregistre les empreintes vocales de façon asynchrone en chargeant les caractéristiques audio des locuteurs cibles. Des événements indiquent la progression de l’enregistrement. Un échec de cet enregistrement ne bloque pas la conversation normale. L’enregistrement des empreintes vocales se déroule dans l’ordre suivant :
  1. Le client établit une connexion WebSocket. Le serveur renvoie session.created.
  2. Le client envoie son premier session.update, avec les URL des enregistrements vocaux dans turn_detection.voiceprint_audio_urls.
  3. Le serveur démarre immédiatement l’enregistrement asynchrone des empreintes vocales. Avant de renvoyer session.updated, il envoie voiceprint_audio_list.in_progress avec l’identifiant unique de la tâche d’enregistrement item_id.
  4. Le serveur renvoie session.updated pour confirmer que la configuration de session est appliquée.
  5. Une fois l’enregistrement des empreintes vocales terminé, le serveur envoie un événement final. Son item_id correspond à la valeur de l’étape 3 :
    • Enregistrement réussi : voiceprint_audio_list.completed.
    • Échec de l’enregistrement : voiceprint_audio_list.failed, avec un champ reason expliquant l’échec, par exemple une URL audio impossible à télécharger.
voiceprint_audio_urls prend effet uniquement dans le premier session.update. Ce champ est ignoré dans les mises à jour suivantes.

Mode push-to-talk

Le client contrôle manuellement la soumission de l’audio et le déclenchement de l’inférence. Ce mode convient aux interactions push-to-talk. Activer ce mode : Définissez turn_detection à null dans le champ session.update événement.
  • Un tour de conversation complet
  • Interruption par l’utilisateur
Le diagramme suivant montre une séquence d’interaction courante en mode push-to-talk :
111
Le client et le serveur interagissent dans l’ordre suivant :
  1. Le client envoie en continu input_audio_buffer.append pour ajouter les données audio.
  2. Une fois que l’utilisateur a fini de parler, le client envoie input_audio_buffer.commit pour soumettre le tampon.
  3. Le client envoie response.create pour déclencher l’inférence manuellement.
  4. Le serveur génère une réponse et transmet le texte et l’audio en streaming.

Contraintes des opérations par mode

Opération

push-to-talk

server_vad

smart_turn / smart_turn_v2

session.update

Tous les champs peuvent être modifiés à l’état IDLE ; certains sont restreints dans les autres états

Tous les champs peuvent être modifiés à l’état IDLE ; certains sont restreints dans les autres états

Tous les champs peuvent être modifiés à l’état IDLE ; certains sont restreints dans les autres états

input_audio_buffer.append

Autorisé

Autorisé

Autorisé

input_audio_buffer.commit

Autorisé

Ignoré

Ignoré

input_audio_buffer.clear

Autorisé

Ignoré

Ignoré

response.create

Autorisé après la soumission de l’audio en mémoire tampon avec input_audio_buffer.commit; ne déclenchez pas une autre réponse pendant la génération

Autorisé lorsqu’aucune réponse n’est en cours de génération ; ne déclenchez pas une autre réponse pendant la génération

Autorisé pendant l’attente de l’entrée utilisateur suivante ; ne déclenchez pas une autre réponse dans un tour actif, de input_audio_buffer.speech_started à response.done

response.cancel

Autorisé pendant l’inférence

Autorisé pendant l’inférence

Autorisé pendant l’inférence

conversation.item.create/delete/retrieve

Autorisé

Autorisé

Autorisé

turn_detection et input_audio_format ne peuvent être modifiés qu’avant le premier envoi audio, pendant que la session est à l’état IDLE.

Gestion des erreurs

Si la négociation échoue, vérifiez le domaine, la région, l’espace de travail, l’API Key, le nom du modèle, son activation et les autorisations. Pour les descriptions complètes, consultez Codes d’erreur.

Type

Comportement

Exemple

Erreur client (invalid_request_error)

La connexion reste ouverte ; l’erreur est signalée

Paramètres non valides, opérations interdites dans l’état actuel ou item_id dupliqué

Erreur serveur (server_error)

La connexion est interrompue

Échec de connexion au LLM ou du stockage

SDK et références

SDK disponibles