Découvrez le flux du SDK client AOQ : obtenir les identifiants, initialiser le SDK, configurer les directions des médias, se connecter, échanger des événements et libérer les ressources.
AOQ transmet l’audio, la vidéo et les événements du modèle sur des pistes distinctes. Le SDK gère la capture, l’encodage, le décodage, le transport et la lecture des médias. Votre application envoie les événements et traite les réponses sur les pistes Data. Sélectionnez les directions des médias et le protocole d’événements requis par le modèle cible.
Prérequis
-
Effectuez les préparatifs de la Présentation des connexions et vérifiez le modèle cible, la région et la prise en charge d’AOQ.
-
Importez le SDK de votre plateforme depuis Téléchargement du SDK. Si vous utilisez Opus, importez le plugin correspondant.
-
Implémentez l’Authentification par jeton sur votre serveur d’application (AppServer). Conservez la clé API sur AppServer et fournissez des identifiants de connexion temporaires au client.
RemarqueDemandez l’autorisation du microphone ou de la caméra uniquement si une capture est nécessaire. Par exemple, la synthèse vocale ne nécessite aucune de ces autorisations.
Flux de travail
- Obtenez les identifiants de connexion via AppServer.
- Créez le moteur du SDK et enregistrez les rappels.
- Configurez les pistes média et Data, et désactivez la transmission des médias montants.
- É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 montants nécessaires.
- Déconnectez-vous et libérez les ressources à la fin de l’interaction.
Remarque
-
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 signifie que le canal de transport vers le modèle est établi. Si votre application nécessite des opérations préalables, comme la configuration d’une voix, terminez la configuration du modèle avant d’envoyer des médias. Par exemple, les modèles Realtime doivent attendre
session.updated, et les modèles Inference doivent attendretask-started. Le client ne peut activer les médias montants nécessaires qu’après la réussite de l’initialisation du modèle.
1. Obtenir les identifiants de connexion
Le client demande des identifiants à AppServer. Celui-ci sélectionne le point de terminaison Realtime ou Inference du modèle cible et envoie la clé API et l’en-tête x-dashscope-rtc-transport: moq à la passerelle. Pour les points de terminaison, les requêtes et les 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 de terminaison dans la structure requise |
extraInfo.workspaceIdHash | workspaceIdHash |
Obtenez de nouveaux identifiants pour chaque nouvelle connexion. La réutilisation d’une session ou le démarrage d’une autre tâche sur la même connexion dépend du protocole du modèle cible.
2. Initialiser le SDK et enregistrer les rappels
Créez le moteur et enregistrez les rappels pour l’état de connexion, les messages Data et les erreurs. L’exemple suivant utilise Swift sur iOS :
let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)
Implémentez AoqEngineDelegate : gérez l’état de connexion dans onConnectionStatusChange, analysez les événements du modèle dans onDataMsg et traitez les erreurs du SDK dans onError. Traitez séparément les événements d’erreur du modèle dans le gestionnaire des messages Data. Pour les interfaces et erreurs du SDK, consultez SDK client AOQ.
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 |
|---|---|---|
| Envoyer de l’audio | Publier une piste Audio, configurer l’encodeur et utiliser la capture intégrée ou externe | Reconnaissance vocale, conversation et traduction |
| Recevoir de l’audio | S’abonner à une piste Audio, configurer le décodeur et utiliser la lecture intégrée ou externe | Synthèse vocale et réponses orales |
| Envoyer de la vidéo | Publier une piste Video et configurer la caméra ou l’entrée externe et l’encodage | Fournir des images à un modèle prenant en charge l’entrée visuelle |
| Recevoir de la vidéo | Configurer l’abonnement et la réception uniquement si le modèle ou l’application prend explicitement en charge la sortie vidéo | Consulter la documentation du modèle ou de l’application cible |
Les pistes Data sont indépendantes de ces quatre directions : publiez une piste Data pour envoyer les événements du modèle et abonnez-vous pour recevoir les réponses. Les entrées et sorties textuelles nécessitent également des pistes Data.
Choisir les directions pour votre modèle
Le tableau suivant présente des configurations courantes. Pour les modèles et versions pris en charge, consultez Présentation de Realtime API et la documentation du 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-Omni-Realtime | Pour l’entrée vocale | Pour les réponses orales | Pour l’entrée visuelle | Non pris en charge |
| Qwen-Audio-Realtime | Pour les conversations vocales | Pour les réponses orales | Non pris en charge | Non pris en charge |
| Qwen-Audio-TTS, CosyVoice | Non pris en charge | Activé | Non pris en charge | Non pris en charge |
| Qwen-Audio-ASR-Streaming, Qwen-Audio-ASR-Message | Activé | Non pris en charge | Non pris en charge | Non pris en charge |
| Fun-ASR-Realtime | Activé | Non pris en charge | Non pris en charge | Non pris en charge |
| Qwen-LiveTranslate-Realtime | Pour l’entrée vocale | Pour les traductions orales | Selon la version et le scénario | Non pris en charge |
| multimodal-dialog | Selon l’entrée de l’application | Selon la sortie de l’application | Selon les capacités de l’application | Uniquement si l’application le prend explicitement en charge |
Configurer les paramètres et pistes média
Configurez séparément l’audio montant et descendant : utilisez setAudioEncoderConfig pour l’audio montant et setAudioDecoderConfig pour l’audio descendant. 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 selon les exigences respectives du SDK et du modèle cible.
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 :
| Scénario | publishTracks | subscribeTracks |
|---|---|---|
| Conversation vocale | Audio, Data | Audio, Data |
| Conversation vocale avec entrée visuelle | Audio, Video, Data | Audio, Data |
| Reconnaissance vocale | Audio, Data | Data |
| Synthèse vocale | Data | Audio, Data |
Désactivez les médias montants avant la connexion pour éviter que des entrées n’atteignent le modèle avant qu’il soit prêt :
engine.enableSendMediaStream(.audio, enable: false)
engine.enableSendMediaStream(.video, enable: false)
La capture, la publication des pistes et l’autorisation d’envoi sont des opérations distinctes. Désactiver la transmission n’arrête pas la capture locale et n’affecte pas les événements Data. Activer la transmission ne crée pas les pistes qui n’ont pas été ajoutées.
4. Établir la connexion
Renseignez AoqConnectConfig avec les identifiants et la configuration des pistes, puis appelez :
engine.connect(connectConfig)
Attendez .connected dans onConnectionStatusChange avant d’initialiser le modèle. Le retour de 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
Envoyez les événements sur la piste Data. Exemple Swift sur iOS :
// Build eventJSON according to the target model client event protocol.
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)
Analysez les réponses dans onDataMsg. Ne supposez pas que tous les événements utilisent type : les événements Realtime utilisent généralement type, tandis que les événements serveur Inference utilisent header.event. Consultez la documentation du modèle pour les champs, paramètres et conditions de fin.
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 satisfaites, activez uniquement les directions montantes configurées. Pour une entrée vocale, appelez :
engine.enableSendMediaStream(.audio, enable: true)
Activez .video uniquement si une entrée vidéo est nécessaire. La synthèse vocale (TTS) utilise du texte en entrée et ne nécessite ni audio ni vidéo montants.
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 depuis votre application les interfaces de déconnexion et de libération des ressources du SDK AOQ :
engine.disconnect()
AoqClientEngine.destroy()
Après une déconnexion inattendue, effacez l’état de disponibilité de l’application et suivez Gestion de l’état de connexion. Initialisez à nouveau le modèle après la reconnexion.
Envoyer et recevoir des événements sur les pistes Data
Publiez les pistes Data et abonnez-vous à celles-ci lors de la connexion. Pour envoyer un événement, sérialisez-le dans AoqDataMsg et appelez engine.send(msg). Analysez les messages reçus dans onDataMsg.
Respectez les définitions des événements client du modèle cible pour les noms, champs, paramètres et moments d’envoi. Respectez ses définitions des événements serveur pour analyser les réponses, changements d’état, résultats et erreurs. Envoyez les événements d’initialisation requis par le modèle, puis les événements textuels et de contrôle nécessaires à votre application.
| Modèle ou application | Événements client (envoi) | Événements serveur (réception) |
|---|---|---|
| Qwen-Omni-Realtime | Événements client | Événements serveur |
| Qwen-Audio-Realtime | Événements client | Événements serveur |
| Qwen-Audio-TTS, CosyVoice | Événements client | Événements serveur |
| Qwen-Audio-ASR-Streaming | Événements client | Événements serveur |
| Qwen-Audio-ASR-Message | Événements client | Événements serveur |
| Fun-ASR-Realtime | Événements client | Événements serveur |
| Qwen-LiveTranslate-Realtime | Événements client | Événements serveur |
| multimodal-dialog | Input Message dans le protocole d’interaction | Output Message dans le protocole d’interaction |
La suite d’interaction multimodale définit les deux directions dans un même protocole. Sélectionnez les définitions correspondant à la version du modèle utilisée ; les modèles ne partagent pas tous un schéma d’événements unique.
Respectez également les règles suivantes :
-
Identifiez les types d’événements et les identifiants de corrélation selon le modèle. Realtime utilise généralement
type; les clients Inference utilisentheader.action, les serveursheader.event, et les tâches sont corrélées partask_id. -
Gérez la confirmation d’initialisation, la soumission des entrées, l’annulation des réponses et la fin des tâches sur les pistes Data conformément au protocole. Ces opérations sont distinctes de la fermeture de la connexion de transport.
-
Par exemple, les modèles Inference utilisent
finish-taskpour terminer une tâche ettask-finishedpour confirmer sa fin. Recevez les résultats restants avant de libérer la connexion. Si une lecture complète est nécessaire, attendez également la lecture de l’audio local en attente. -
Les médias utilisent les pistes média. Lorsque vous consultez la documentation des événements du modèle, suivez cette page AOQ pour le transport des médias et les modes d’interaction disponibles ; ne reprenez pas les mécanismes d’envoi de médias de WebSocket.
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 |
Les contrôles de transmission n’affectent que les médias. L’annulation des réponses et la soumission des tours nécessitent toujours les événements du modèle cible.
Bonnes pratiques
-
Appels Omni en temps réel : entrée audio/vidéo, réponses orales et événements de session.
-
Omni avec bouton de parole : entrée contrôlée par bouton et tours manuels.
-
Conversations vocales Qwen-Audio : audio bidirectionnel.
-
Synthèse vocale Qwen-Audio : texte en entrée sur les pistes Data et parole en sortie sur les pistes Audio.
-
Reconnaissance vocale Fun-ASR : audio en entrée sur les pistes Audio et résultats de reconnaissance sur les pistes Data.