Connexion AOQ à Qwen-Audio-Realtime
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. - Stockez l’API Key uniquement sur le serveur. Ne l’intégrez pas à une application mobile ou à un navigateur.
- Lors de la capture audio avec un microphone, demandez l’autorisation d’accès au microphone conformément aux exigences de la plateforme.
- Téléchargez le SDK de votre plateforme depuis Téléchargement du SDK.
Authentification et informations de connexion
clientIp est facultatif. S’il est omis, la passerelle utilise l’adresse IP depuis laquelle elle reçoit la requête.
https://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plushttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus-d '{}' dans le corps de la requête par -d '{"clientIp":"<CLIENT_PUBLIC_IP>"}'.
Champs de la requête
Configuration | Valeur | Description |
|---|---|---|
endpoint | Sélectionner le domaine du point de terminaison pour votre cas d’utilisation | Indiquez le domaine du point de terminaison. Pour plus d’informations, consultez Sélectionner une région, un périmètre de déploiement et un point de terminaison. Si vous utilisez Token Plan, définissez |
Content-Type |
| Type de média du message |
Authorization |
| Votre API Key |
x-dashscope-rtc-transport |
| Sélectionner le protocole AOQ |
clientIp | Adresse IP publique du client | Facultatif. S’il est omis, le service utilise l’adresse IP depuis laquelle la passerelle reçoit la requête. S’il est renseigné, il utilise clientIp. Le service sélectionne le meilleur point de terminaison Relay selon l’adresse IP du client. |
Exemple de réponse
Champs de la réponse
Field | Description |
|---|---|
sid | Identifiant unique de la session. |
aoqTokenForClient | Jeton de connexion du client. Transmettez cette valeur au champ token du SDK. |
clientRelayEndpoints | Tableau de points de terminaison Relay. Chaque élément de l’exemple de réponse contient les champs suivants :
Propriétés endpointAdresse du point de terminaison Relay.portPort du point de terminaison Relay.route_indexL’exemple iOS ci-dessous utilise l’indice du tableau lorsque ce champ est absent. |
clientRelayCertFingerprint | Empreinte du certificat TLS Relay. |
sidExpiresInSecs | Durée d’expiration de la session, en secondes. |
extraInfo | Informations supplémentaires.
Propriétés workspaceIdHashHachage de l’ID de l’espace de travail. |
Exemple de connexion du SDK client AOQ
clientIp est un champ facultatif du corps de la requête. S’il est omis, l’adresse IP qui envoie la requête à la passerelle Model Studio est utilisée comme adresse IP du client. S’il est renseigné, la valeur de clientIp est prioritaire. Faites récupérer l’adresse IP réelle du client par votre AppServer métier et transmettez-la pour obtenir le meilleur point d’accès Relay.Déroulement

- Obtenez les informations de connexion via AppServer.
- Créez le moteur SDK et enregistrez les callbacks.
- Configurez les pistes de médias et Data, puis désactivez la transmission des médias en amont.
- Établissez la connexion AOQ et attendez qu’elle soit connectée.
- Configurez le modèle selon son protocole. Après confirmation, activez les médias en amont nécessaires.
- Déconnectez-vous et libérez les ressources une fois l’interaction terminée.
- Les médias audio sont gérés par AOQ SDK, qui assure leur capture, leur traitement, leur envoi, leur réception et leur lecture ; les données Data doivent être envoyées et reçues par l’appelant conformément aux définitions d’événements du modèle cible.
-
Une connexion réussie indique que le canal de communication avec le modèle est établi. Le client ne doit activer les médias en amont nécessaires qu’une fois l’initialisation du modèle terminée. Pour le modèle
qwen-audio-3.1-realtime-plusutilisé dans cet exemple, envoyezsession.update, attendezsession.updated, puis démarrez la transmission des médias.
1. Obtenir les identifiants de connexion
Le client demande les informations de connexion à votre AppServer. AppServer appelle le point de terminaison de connexion Realtime de ce modèle et inclut l’API Key et x-dashscope-rtc-transport: moq dans la requête à la passerelle. Pour le point de terminaison complet, la requête et la description des champs, consultez Authentification par jeton.
Associez la réponse à AoqConnectConfig :
| Réponse de la passerelle | Configuration du SDK |
|---|---|
aoqTokenForClient | token |
sid | sid |
clientRelayCertFingerprint | certFingerprint |
clientRelayEndpoints | relayEndpoints, convertissez chaque point d’accès selon la structure |
extraInfo contient workspaceIdHash | workspaceIdHash |
2. Initialiser le SDK et enregistrer les rappels
Créez le moteur et enregistrez les callbacks pour l’état de la connexion, les messages Data et les erreurs. L’exemple suivant utilise Swift sur iOS :
AoqEngineDelegate ; gérez l’état de la connexion dans onConnectionStatusChange ; analysez les événements du modèle cible dans onDataMsg ; traitez les erreurs du SDK dans onError. Les événements d’erreur renvoyés par le modèle doivent également être traités séparément dans la logique de traitement des messages Data. Pour les interfaces du SDK et la description des erreurs, consultez SDK par plateforme et Référence des fonctionnalités.
3. Configurer le SDK
Sélectionner la direction des médias
Les directions sont définies du point de vue du client. Configurez uniquement les modalités d’entrée et de sortie nécessaires à votre application. N’ajoutez pas de pistes pour les directions inutilisées.
| Direction | Configuration | Utilisation courante |
|---|---|---|
| envoyer l’audio | publiez la piste Audio, définissez l’encodeur audio et configurez la capture intégrée ou externe | conversation vocale |
| recevoir l’audio | abonnez-vous à la piste Audio, définissez le décodeur audio et configurez le lecteur ou la lecture externe | réponse vocale |
Directions des médias pour ce modèle
Le tableau suivant présente les directions de transmission des médias pour ce modèle. Consultez le Périmètre d’application pour connaître les modèles concernés ; pour les autres méthodes de connexion, consultez Qwen-Audio-Realtime.
| 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é |
Configurer les paramètres et pistes média
Configurez séparément l’audio en amont et en aval : utilisez setAudioEncoderConfig pour l’audio en amont et setAudioDecoderConfig pour l’audio en aval. Ces paramètres contrôlent la transmission réseau ; la passerelle convertit l’audio au format requis par le modèle. Configurez l’encodage du transport et le format audio des événements du modèle selon les exigences du SDK et du modèle cible, respectivement.
Démarrez startAudioCapture ou startAudioPlayer selon la direction. Les entrées et sorties personnalisées sont décrites dans la section des fonctionnalités avancées ci-dessous.
Les pistes publishTracks sont envoyées par le client, et les pistes subscribeTracks sont reçues par le client :
| Scenario | publishTracks | subscribeTracks |
|---|---|---|
| conversation vocale | Audio, Data | Audio, Data |
4. Établir la connexion
Renseignez les informations de connexion et la configuration des pistes dans AoqConnectConfig, puis appelez :
onConnectionStatusChange renvoie .connected, puis procédez à l’initialisation du modèle. Le retour de l’appel à connect ne signifie pas que la connexion a réussi.
5. Échanger les événements du modèle et les médias
Envoyer et analyser les événements du modèle
Le client envoie les événements sur la piste Data. Voici un extrait de code Swift pour iOS ; pour les autres interfaces, consultez Référence du SDK iOS :
onDataMsg. Ce modèle identifie les types d’événements par le champ type. Les champs complets, les paramètres et les conditions de fin doivent suivre la documentation du modèle cible.
Activer les médias lorsque le modèle est prêt
Une fois les conditions de disponibilité du modèle, de la session ou de la tâche actuels remplies, activez uniquement les directions en amont configurées. Pour l’entrée vocale, appelez :
input_audio_buffer.append pour envoyer une deuxième fois les données audio. L’audio en aval est traité par le lecteur configuré ou par la logique de lecture externe.
6. Terminer l’interaction et libérer les ressources
Lorsque la connexion n’est plus nécessaire, appelez les interfaces de déconnexion et de libération des ressources d’AOQ SDK depuis votre application :
Envoyer et recevoir des événements sur le canal Data
Le client envoie et reçoit les événements du modèle sur la piste Data d’AOQ SDK. Pendant la connexion, la publication de la piste Data et l’abonnement à celle-ci sont tous deux nécessaires ; pour l’envoi, sérialisez l’événement du modèle dans AoqDataMsg et appelez l’interface d’envoi Data de la plateforme ; à la réception, analysez le message dans le callback onDataMsg. Pour le détail des interfaces, consultez SDK par plateforme.
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.
| 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.
- Avant de terminer, achevez la soumission des entrées et la réception des résultats selon la documentation des événements de ce modèle ; si une lecture complète est nécessaire, ne libérez la connexion qu’après avoir traité l’audio restant dans la file locale.
- 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.
Fonctionnalités avancées
| Fonctionnalité | Cas d’utilisation | Documentation |
|---|---|---|
| Contrôler la transmission audio | attendre que le modèle soit prêt, suspendre l’audio en amont | Gestion de la transmission des flux de médias |
| Périphériques et traitement audio | encodage/décodage, haut-parleurs, mixage de fichiers, callbacks de trames audio | Fonctions audio courantes |
| entrée audio externe | utiliser une source audio côté client | capture audio personnalisée |
| sortie audio externe | traité ou lu côté client | lecture audio personnalisée |
Exemple de configuration de session
qwen-audio-3.1-realtime-plus. L’audio est transmis sur la piste de médias ; n’utilisez pas les événements WebSocket d’envoi des médias.Téléchargement du SDK AOQ
Les notes de version ci-dessous décrivent les fonctionnalités générales d’AOQ SDK ; les médias pris en charge par ce modèle sont détaillés dans Directions de transmission des médias pour ce modèle ci-dessus.
| Version | Plateforme | Téléchargement | Date de publication | Notes de version |
|---|---|---|---|---|
| v1.4.0 | Android | AoqClientSdk-release.aarlibPluginOpus.zip | 2026-10-27 |
|
| iOS | AoqClientSdk.framework.zipAoqScreenShare.framework.zipPluginOpus.framework.zip | |||
| HarmonyOS | AoqClientSdk.harlibPluginOpus.zip | |||
| Windows | AoqClientSdk-windows-x64.zip | |||
| macOS | AoqClientSdk.framework.zipPluginOpus.framework.zip | |||
| Electron | aoq-electron-sdk-1.4.0-59463182.tgzVous pouvez également l’installer avec npm :npm install aoq-electron-sdk@1.4.0-59463182 | |||
| Linux | x86_64 : AoqClientSdk.ziparm64 : AoqClientSdk.zip | |||
| v1.3.0 | Android | 2026-09-18 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Windows | AoqClientSdk-windows-x64.zip | |||
| macOS | ||||
| Electron | Vous pouvez également l’installer avec npm : npm install aoq-electron-sdk@1.3.0-58586345 | |||
| Linux | x86_64: AoqClientSdk.zip arm64: AoqClientSdk.zip | |||
| v1.2.2 | iOS | AoqClientSdk.framework.zip | 2026-09-09 |
|
| v1.2.0 | Android | 2026-08-17 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Windows | ||||
| macOS | ||||
| Electron | Package: aoq-electron-sdk-1.2.0-57407598.tgz Vous pouvez également l’installer avec npm: npm install aoq-electron-sdk@1.2.0-57407598 | |||
| Linux | x86_64: AoqClientSdk.zip arm64: AoqClientSdk.zip | |||
| v1.1.0 | Android | 2026-07-31 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Linux | AoqClientSdk.zip | |||
| v1.0.1 | Android | 2026-07-09 |
| |
| iOS | ||||
| HarmonyOS |