Connexion WebSocket à Qwen-Audio-Realtime
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.
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
wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>{WorkspaceId} par l’ID de votre espace de travail lors de l’appel de l’API.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 |
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. |
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 envoieresponse.createpour 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 | 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 | 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 |
| 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 client établit une connexion WebSocket. Le serveur renvoie
session.created. - Le client envoie
session.updatepour configurer la session. Le serveur renvoiesession.updated. - Le client envoie en continu
input_audio_buffer.appendpour ajouter les données audio. - Lorsque le serveur détecte le début de la parole, il renvoie
input_audio_buffer.speech_startedet transmet les incréments de transcription ASR viaconversation.item.input_audio_transcription.delta. - Lorsque le serveur détecte la fin de la parole, il renvoie
input_audio_buffer.speech_stopped,input_audio_buffer.committedetconversation.item.created. - Le serveur génère automatiquement une réponse et transmet les incréments de texte et d’audio (
response.audio_transcript.deltaetresponse.audio.delta), puis renvoieresponse.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
- 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_stoppedrenvoiereason=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.createpour 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 :
-
Le client établit une connexion WebSocket. Le serveur renvoie
session.created. -
Le client envoie son premier
session.update, avec les URL des enregistrements vocaux dansturn_detection.voiceprint_audio_urls. -
Le serveur démarre immédiatement l’enregistrement asynchrone des empreintes vocales. Avant de renvoyer
session.updated, il envoievoiceprint_audio_list.in_progressavec l’identifiant unique de la tâche d’enregistrementitem_id. -
Le serveur renvoie
session.updatedpour confirmer que la configuration de session est appliquée. -
Une fois l’enregistrement des empreintes vocales terminé, le serveur envoie un événement final. Son
item_idcorrespond à la valeur de l’étape 3 :- Enregistrement réussi :
voiceprint_audio_list.completed. - Échec de l’enregistrement :
voiceprint_audio_list.failed, avec un champreasonexpliquant l’échec, par exemple une URL audio impossible à télécharger.
- Enregistrement réussi :
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 client envoie en continu
input_audio_buffer.appendpour ajouter les données audio. - Une fois que l’utilisateur a fini de parler, le client envoie
input_audio_buffer.commitpour soumettre le tampon. - Le client envoie
response.createpour déclencher l’inférence manuellement. - 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 | 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 |
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 ( | 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 ( | La connexion est interrompue | Échec de connexion au LLM ou du stockage |