Connexion WebRTC à Qwen-Audio-Realtime
WebRTC utilise des pistes de médias pour transmettre l’audio et DataChannel pour transmettre les événements du modèle et le texte. Le client web peut utiliser l’API native du navigateur, tandis que les autres clients peuvent utiliser des bibliothèques prenant en charge WebRTC standard. Model Studio ne fournit pas de SDK WebRTC dédié.
Ce document décrit la procédure d’intégration WebRTC de ce modèle et fournit un exemple complet côté navigateur.
Ce document concerne Qwen-Audio-Realtime. Les instructions d’intégration existantes couvrent 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. Le modèle de l’exemple est
Le navigateur envoie une Offer SDP à l’AppServer métier. AppServer transmet la requête suivante avec l’API Key et renvoie l’Answer SDP sans modification au navigateur ; les API Keys à longue durée de validité ne parviennent pas au frontend.
Voici un exemple complet côté navigateur. Implémentez d’abord l’interface
AppServer configure l’échange SDP selon le modèle cible, la région et l’espace de travail. Les paramètres suivants concernent les connexions Realtime standard. Pour les paramètres propres à une application, suivez la bonne pratique correspondante.
Pour les régions, les adresses et l’authentification, consultez Authentification et échange SDP. L’interface de l’AppServer métier est implémentée par l’entreprise et ne fait pas partie de l’API SDK de Model Studio.
Côté web, créez une
Les directions sont relatives au client. Les émetteurs-récepteurs WebRTC négocient l’envoi et la réception :
Par exemple, une conversation vocale utilise généralement un flux audio bidirectionnel. L’Offer SDP doit inclure la section de média audio
Ce tableau décrit les directions des médias nécessaires à l’application ; il ne garantit pas que toutes les combinaisons puissent être négociées indépendamment. La configuration dépend du modèle cible et des capacités de négociation du serveur.
Négociez les directions requises avant de créer l’Offer. Si le modèle nécessite une confirmation d’initialisation, réservez les capacités d’envoi sans attacher les pistes capturées. Lorsque le modèle est prêt, utilisez
L’exemple suivant présente une conversation vocale bidirectionnelle. Deux options dans
Créez un DataChannel avant de créer une Offer pour que la SDP inclue la négociation du canal de données. Consultez Envoi et réception d’événements sur le canal Data pour savoir comment le client et le serveur créent les canaux.
DataChannel envoie les événements d’initialisation du modèle, les événements textuels et de contrôle, et reçoit les résultats, les états et les erreurs du modèle. La piste de médias transmet l’audio.
L’exemple complet crée un canal d’événements client et enregistre le callback du canal serveur avant de créer une Offer.
Effectuez la connexion dans l’ordre suivant :
Écoutez
Lorsque la connexion et le canal d’événements sont disponibles, initialisez le modèle cible selon son protocole. Conservez les événements d’initialisation serveur et combinez-les avec l’état du canal pour avancer ; ne supposez pas un ordre fixe d’arrivée des rappels.
Par exemple, lorsque vous configurez un modèle avec
L’exemple suivant présente le déroulement
Une fois le modèle prêt, associez la piste audio en amont nécessaire. Traitez la sortie du modèle dans le callback de piste distante et analysez en continu les événements renvoyés par DataChannel.
Lorsque la connexion n’est plus nécessaire, arrêtez les pistes de capture locales de votre application, fermez les DataChannels et le
Vérifiez que le canal est
Utilisez la même fonction de liaison pour les canaux créés par le client et le serveur. Elle gère le transport et l’analyse JSON ;
Respectez également les règles suivantes :
Périmètre d’application
Ce document concerne Qwen-Audio-Realtime. Les instructions d’intégration existantes couvrent 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. Le modèle de l’exemple est qwen-audio-3.1-realtime-plus.
- Utilisez l’API Key et l’ID de l’espace de travail correspondant à la région et à l’espace de travail sélectionnés.
- Domaine de Pékin :
{WorkspaceId}.cn-beijing.maas.aliyuncs.com; domaine de Singapour :{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. - Les API Keys à longue durée de validité sont stockées côté serveur et ne doivent pas être incluses dans les applications mobiles ou de navigateur. Pour leur génération et leurs autorisations, consultez Générer une API Key temporaire.
Authentification et échange SDP
Le navigateur envoie une Offer SDP à l’AppServer métier. AppServer transmet la requête suivante avec l’API Key et renvoie l’Answer SDP sans modification au navigateur ; les API Keys à longue durée de validité ne parviennent pas au frontend.
- Méthode :
POST
POST
https://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plusPOST
https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus- En-têtes de requête :
Authorization: Bearer <API_KEY>,Content-Type: application/sdp - Corps de la requête : chaîne Offer SDP.
- Réponse réussie : HTTP 200, avec l’Answer SDP dans le corps ; un échec renvoie un code 4xx.
/api/realtime/sdp désigne une interface personnalisée de l’AppServer métier, qui doit implémenter le transfert décrit ci-dessus ; ce n’est pas une URL fournie par Model Studio.
Déroulement

- Préparez la clé API et les paramètres du modèle cible sur AppServer.
- Créez l’objet de connexion client et enregistrez les rappels.
- Configurez les directions des médias et les DataChannels sans attacher les pistes média montantes.
- Échangez les SDP via AppServer et attendez que la connexion et le canal d’événements soient prêts.
- Configurez le modèle selon son protocole. Attachez les pistes média montantes nécessaires après confirmation.
- Arrêtez la capture, fermez la connexion et libérez les ressources à la fin de l’interaction.
- L’audio est transmis sur les pistes de médias WebRTC ; l’application doit obtenir la piste audio locale, associer le lecteur distant, puis envoyer et recevoir les messages DataChannel selon les définitions d’événements du modèle cible.
- L’authentification WebRTC s’effectue lors de l’échange SDP ; aucun jeton AOQ n’est nécessaire. Relayez l’authentification et les SDP via AppServer pour ne pas exposer la clé API à long terme dans le code frontend.
-
Une connexion réussie indique que le canal de transmission est établi, mais ne signifie pas que l’initialisation du modèle est terminée. Avec
qwen-audio-3.1-realtime-plusutilisé sur cette page, n’activez les médias en amont nécessaires qu’après avoir envoyésession.updateet reçusession.updated.
Exemple complet
Voici un exemple complet côté navigateur. Implémentez d’abord l’interface /api/realtime/sdp de l’AppServer métier comme décrit dans Authentification et échange SDP, puis ouvrez cette page HTML depuis la même origine que l’AppServer, avec le même protocole, hôte et port. Par exemple, la page et /api/realtime/sdp sont toutes deux servies par http://localhost:3000. Le serveur stocke l’API Key et transfère les données SDP ; n’incluez pas d’API Keys à longue durée de validité dans la page. Cliquez sur “Start” pour établir la connexion, puis sur “End” pour libérer les ressources à la fin de l’interaction. Cet exemple établit une connexion à la fois ; rechargez la page pour démarrer une autre session.
1. Préparer l’authentification et les paramètres de connexion
AppServer configure l’échange SDP selon le modèle cible, la région et l’espace de travail. Les paramètres suivants concernent les connexions Realtime standard. Pour les paramètres propres à une application, suivez la bonne pratique correspondante.
| Setting | Value |
|---|---|
| Méthode | POST |
| URL | https://{endpoint}/api/v1/webrtc/realtime?model={model_name} |
Content-Type | application/sdp |
Authorization | Bearer <API_KEY> |
| Corps de la requête | Offer SDP |
| Réponse réussie | Answer SDP |
2. Initialiser l’objet de connexion et enregistrer les callbacks
Côté web, créez une RTCPeerConnection ; sur les autres plateformes, initialisez la bibliothèque correspondante. Avant d’établir la connexion, enregistrez les gestionnaires suivants :
- Changements d’état de la connexion : déterminez si la connexion a réussi, a échoué ou a été interrompue.
- Création, ouverture, messages et fermeture de DataChannel : transporte les événements du modèle.
- Piste de médias distante : reçoit et lit l’audio, ou traite les autres médias pris en charge par l’application cible.
txt ; vous devez donc traiter le callback datachannel.
3. Configurer les directions des médias et les DataChannels
Sélectionner la direction audio
Les directions sont relatives au client. Les émetteurs-récepteurs WebRTC négocient l’envoi et la réception : sendrecv est bidirectionnel, sendonly envoie uniquement et recvonly reçoit uniquement. Les capacités disponibles dépendent aussi de la réponse SDP du serveur et de la prise en charge du modèle.
| Direction | Configuration |
|---|---|
| Envoyer l’audio | Négociez l’envoi audio et préparez le microphone ou une piste audio externe. Ajoutez la piste une fois le modèle prêt. |
| Recevoir l’audio | Négociez la réception audio et configurez la lecture dans le callback de réception d’une piste distante. |
m=audio ; ne la supprimez pas simplement parce que l’application n’a pas besoin de lire l’audio.
Directions des médias pour ce modèle
| Modèle ou application | Envoyer de l’audio | Recevoir de l’audio | Envoyer de la vidéo | Recevoir de la vidéo |
|---|---|---|---|---|
| Qwen-Audio-Realtime | À activer pour les conversations vocales | À activer lorsqu’une réponse vocale est nécessaire | Ne peut pas être activé | Ne peut pas être activé |
Préparer les médias sans les envoyer
Négociez les directions requises avant de créer l’Offer. Si le modèle nécessite une confirmation d’initialisation, réservez les capacités d’envoi sans attacher les pistes capturées. Lorsque le modèle est prêt, utilisez replaceTrack sur l’émetteur correspondant pour démarrer la transmission. Enregistrez à l’avance les gestionnaires de réception.
Configurez séparément l’envoi et la réception audio selon les besoins ; ne regroupez pas l’activation du microphone, la lecture audio et l’initialisation du modèle dans une seule opération.
Exemple de configuration des médias
L’exemple suivant présente une conversation vocale bidirectionnelle. Deux options dans media contrôlent respectivement l’envoi et la réception audio ; addTransceiver négocie la direction à l’avance, et la piste capturée reste d’abord stockée localement jusqu’à ce que le modèle soit prêt, puis elle est associée à l’émetteur.
Consultez le code dans l’exemple complet.
Créer les canaux d’événements
Créez un DataChannel avant de créer une Offer pour que la SDP inclue la négociation du canal de données. Consultez Envoi et réception d’événements sur le canal Data pour savoir comment le client et le serveur créent les canaux.
DataChannel envoie les événements d’initialisation du modèle, les événements textuels et de contrôle, et reçoit les résultats, les états et les erreurs du modèle. La piste de médias transmet l’audio.
L’exemple complet crée un canal d’événements client et enregistre le callback du canal serveur avant de créer une Offer.
4. Établir la connexion
Effectuez la connexion dans l’ordre suivant :
- Appelez
createOfferetsetLocalDescription. - Collectez les informations sur les candidats selon les méthodes ICE prises en charge par le serveur ; dans cet exemple, la SDP locale est envoyée une fois la collecte ICE terminée.
- Envoyez la SDP locale à l’AppServer métier, qui utilise l’API Key pour appeler l’interface d’échange SDP de Model Studio.
- Vérifiez l’état HTTP et, en cas de succès, appelez
setRemoteDescriptionavec l’Answer SDP renvoyée. - Attendez que l’état de la connexion indique un succès et confirmez que le DataChannel utilisé pour envoyer les événements du modèle est ouvert.
setRemoteDescription indique uniquement que l’étape de négociation correspondante est terminée ; elle ne prouve pas que la connexion des médias a réussi. Les événements du modèle ne peuvent pas non plus être envoyés si DataChannel n’est pas à l’état open.
Code de connexion et callbacks d’état
Écoutez connectionstatechange pour déterminer l’état de la connexion et icegatheringstatechange pour attendre la SDP locale complète. L’initialisation du modèle nécessite également l’état open de DataChannel et l’événement de disponibilité du modèle ; elle ne doit pas dépendre uniquement de la fin de l’échange SDP.
L’exemple complet effectue l’échange SDP avec startSession() et traite le résultat de la connexion dans le callback d’état de la connexion.
L’AppServer métier doit transférer l’Offer selon l’adresse et les en-têtes de requête de la section 1 ; l’API d’exemple doit renvoyer du texte SDP brut. Ne transmettez pas directement à setRemoteDescription du contenu incluant des en-têtes de réponse HTTP, des journaux ou des enveloppes JSON.
5. Échanger les événements du modèle et les médias
Initialiser le modèle
Lorsque la connexion et le canal d’événements sont disponibles, initialisez le modèle cible selon son protocole. Conservez les événements d’initialisation serveur et combinez-les avec l’état du canal pour avancer ; ne supposez pas un ordre fixe d’arrivée des rappels.
Par exemple, lorsque vous configurez un modèle avec session.update, construisez l’événement selon son protocole et attendez la confirmation de configuration avant d’envoyer les entrées. Les paramètres de voix, de modalités de sortie, de VAD et de fréquence d’échantillonnage doivent tous provenir de la documentation du modèle actuel.
session.created indique la création de la session ; il ne signifie pas systématiquement que la configuration est appliquée. Pour les modèles exigeant une confirmation de la configuration de session, attendez session.updated.
Les définitions des événements du modèle figurent dans Événements client et Événements serveur. Gérez la transmission des médias et les modes disponibles comme décrit sur cette page.
Exemples d’événements du modèle
L’audio est transmis sur la piste de médias et n’utilise pas l’événement WebSocket d’envoi des médias.
session.created → session.update → session.updated pour qwen-audio-3.1-realtime-plus. Configurez les champs selon la référence des événements du modèle. N’associez la piste audio en amont qu’après avoir reçu session.updated, qui confirme la fin de la configuration.
Consultez le code dans l’exemple complet.
Pour le modèle d’exemple qwen-audio-3.1-realtime-plus, l’activation de la sortie audio permet de suivre l’état de génération audio avec response.audio.done ; cet événement ne signifie pas que la lecture audio du client est terminée.
Démarrer la transmission et la réception des médias
Une fois le modèle prêt, associez la piste audio en amont nécessaire. Traitez la sortie du modèle dans le callback de piste distante et analysez en continu les événements renvoyés par DataChannel.
-
L’audio transite par les pistes média RTP ; aucun événement
input_audio_buffer.appendn’est nécessaire. - Les DataChannels transportent le texte et les événements d’état, de contrôle et d’erreur.
startSendingMedia() associe la piste en amont et ontrack traite les médias reçus.
6. Terminer l’interaction et libérer les ressources
Lorsque la connexion n’est plus nécessaire, arrêtez les pistes de capture locales de votre application, fermez les DataChannels et le RTCPeerConnection, libérez les lecteurs et effacez l’état de l’application.
Effacez l’état de disponibilité du modèle après un échec ou une déconnexion inattendue. Initialisez à nouveau le modèle sur une nouvelle connexion au lieu de réutiliser l’état de session précédent.
Dans l’exemple complet, endSession() libère la connexion et les ressources de médias.
Appelez endSession() lorsque l’utilisateur clique sur le bouton de fin ou ferme la page.
Envoyer et recevoir des événements sur le canal Data
Vérifiez que le canal est open avant d’appeler send avec un événement sérialisé. Analysez les messages entrants dans son rappel message, y compris sur les canaux créés par le serveur.
Les noms, champs, paramètres et moments d’envoi des événements suivent les définitions des événements client du modèle cible ; l’analyse, les changements d’état, les résultats et la gestion des erreurs après réception suivent les définitions des événements serveur du modèle. Les événements d’initialisation sont envoyés selon les exigences du modèle, puis les événements textuels et de contrôle selon les besoins métier.
Exemple DataChannel
Utilisez la même fonction de liaison pour les canaux créés par le client et le serveur. Elle gère le transport et l’analyse JSON ; handleModelEvent de la section 5 traite la sémantique du modèle. Utilisez sendModelEvent pour l’initialisation, le texte ou le contrôle uniquement lorsque le protocole du modèle le permet.
Dans l’exemple complet, sendModelEvent() et bindDataChannel() envoient et reçoivent les événements.
Dans l’exemple complet, le bouton de démarrage appelle startSession() et le bouton de fin appelle endSession(). Ce sont des fonctions définies dans cet exemple, et non des API WebRTC intégrées.
Définitions des événements Qwen-Audio-Realtime
| Modèle ou application | Événements client (envoi) | Événements serveur (réception) |
|---|---|---|
| Qwen-Audio-Realtime | Événements client | Événements serveur |
-
Utilisez le champ
typedes événements pour identifier les événements du modèle et traitez les identifiants associés selon la référence des événements de ce modèle. - Les opérations requises par le modèle, telles que la confirmation de l’initialisation, la soumission des entrées, l’annulation des réponses et la fin des tâches, sont toutes traitées sur le canal Data selon le protocole correspondant ; elles définissent les interactions du modèle et sont distinctes de la déconnexion du transport.
- Les données audio sont transmises sur les pistes de médias. Lorsque vous utilisez la référence des événements du modèle, suivez cette page pour l’encapsulation des médias et les modes d’interaction disponibles. N’appliquez pas directement la méthode WebSocket d’envoi des médias.