Connexion AOQ à Qwen-Omni-Realtime
Périmètre d’application
Ce document concerne Qwen-Omni-Realtime. La documentation d’intégration existante couvre qwen3.8-omni-flash-realtime, qwen3.5-omni-plus-realtime et qwen3.5-omni-flash-realtime. Le modèle de l’exemple est qwen3.8-omni-flash-realtime.
- 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 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.
- Pour capturer l’audio avec un microphone ou la vidéo avec une caméra, demandez les autorisations nécessaires selon les 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.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime-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.
- Le SDK AOQ gère la capture, le traitement, la transmission, la réception et la lecture des médias. Votre application doit échanger les messages Data selon les définitions d’événements du modèle cible.
-
Une connexion réussie indique que le canal de transmission vers le modèle est établi ; le client ne doit activer les médias en amont nécessaires qu’après l’initialisation complète du modèle. Pour le modèle d’exemple
qwen3.8-omni-flash-realtimede cette page, envoyezsession.updateet attendezsession.updatedavant de commencer 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 les directions 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 |
|---|---|---|
| envoie l’audio | publie la piste Audio, définit l’encodeur audio et configure la capture intégrée ou externe | conversation vocale |
| reçoit l’audio | s’abonne à la piste Audio, définit le décodeur audio et configure le lecteur ou la lecture externe | réponse vocale |
| envoie la vidéo | publie la piste Video et configure la caméra ou l’entrée vidéo externe ainsi que les paramètres d’encodage | envoie la vidéo aux modèles prenant en charge les entrées visuelles |
| reçoit la vidéo | ce modèle ne prend pas en charge la sortie vidéo | ne configurez pas d’abonnement vidéo |
Directions des médias pour ce modèle
Le tableau ci-dessous 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 d’intégration, consultez Qwen-Omni-Realtime.
| Modèle ou application | Envoyer de l’audio | Recevoir de l’audio | Envoyer de la vidéo | Recevoir de la vidéo |
|---|---|---|---|---|
| Qwen-Omni-Realtime | activez lorsqu’une entrée vocale est nécessaire | activez lorsqu’une réponse vocale est nécessaire | activez lorsqu’une entrée visuelle est nécessaire | 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, startAudioPlayer ou startVideoCapture selon vos besoins. Pour personnaliser les entrées et sorties, consultez les 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 |
| conversation vocale avec entrée visuelle | Audio, Video, 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 :
.video uniquement lorsqu’une entrée vidéo est nécessaire.
Transmettez l’audio et la vidéo sur leurs pistes média, et les événements et textes sur les pistes Data. Par exemple, Omni via AOQ ne nécessite pas input_audio_buffer.append ni input_image_buffer.append pour renvoyer les mêmes médias. Traitez l’audio descendant avec le lecteur configuré ou votre 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-Omni-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 et vidéo sont transmises sur les pistes de médias. Lorsque vous consultez la documentation des événements du modèle, l’encapsulation des médias et les modes d’interaction disponibles restent définis par les méthodes de connexion décrites ici ; ils n’appliquent pas directement la méthode WebSocket d’envoi des médias.
Fonctionnalités avancées
| Fonctionnalité | Cas d’utilisation | Documentation |
|---|---|---|
| Contrôler séparément la transmission audio et vidéo | Attendre que le modèle soit prêt, suspendre les médias montants ou activer la vidéo selon les besoins | Gestion de la transmission des médias |
| Périphériques et traitement audio | Encodage, décodage, haut-parleurs, mixage de fichiers et rappels de trames audio | Fonctionnalités audio courantes |
| Entrée audio externe | Utiliser une source audio fournie par l’application | Capture audio personnalisée |
| Sortie audio externe | Traiter ou lire l’audio de sortie dans votre application | Lecture audio personnalisée |
| Capture et entrée vidéo | Utiliser une caméra ou des images fournies par l’application | Fonctionnalités vidéo courantes, Entrée vidéo personnalisée |
Exemple de configuration de session
qwen3.8-omni-flash-realtime. L’audio et la vidéo sont transmis sur les pistes de médias ; les événements WebSocket d’envoi des médias ne sont pas utilisés.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 |
Références des événements
Tutoriels par scénario
- Utiliser AOQ avec qwen3.5-omni-plus-realtime pour des appels en temps réel
- Créer des conversations vocales push-to-talk avec qwen3.8-omni-flash-realtime via AOQ