Ce tutoriel explique comment utiliser l'AOQ SDK avec qwen-audio-3.1-asr-flash-streaming pour implémenter la saisie vocale.
Vue d'ensemble de la solution
Dans une interaction de saisie vocale classique, l'utilisateur clique sur le bouton de saisie vocale et commence immédiatement à parler. Les résultats s'affichent en temps réel dans le champ de saisie. L'implémentation du client repose sur les points suivants :
- Capture immédiate : Lancez la capture audio et le stockage des données PCM dans un tampon dès le clic, tout en demandant les identifiants et en établissant la connexion de manière asynchrone. La connexion prend du temps et l'utilisateur peut déjà parler : stockez d'abord l'audio, puis envoyez-le.
- Rattrapage à vitesse double : Une fois la connexion établie et l'événement de disponibilité du modèle reçu, envoyez l'audio stocké à vitesse double. Passez ensuite à l'envoi en temps réel lorsque le retard est rattrapé.
- Audio sur le canal Data : qwen-audio-3.1-asr-flash-streaming utilise le protocole Inference (run-task / finish-task). Ce scénario nécessite de stocker l'audio avant son envoi à vitesse double. Utilisez
sendDataMsgpour transmettre l'audio sous forme de messages JSON. Le serveur AOQ prend en charge ce format de messages audio JSON et les convertit automatiquement en données binaires à transmettre au modèle. - Résultats intermédiaires et finaux : Le modèle renvoie continuellement des résultats. Affichez les résultats intermédiaires (
sentence_end: false) en temps réel et ajoutez les résultats finaux (sentence_end: true) au champ de saisie.
Préparation
Prérequis
- Activez Alibaba Cloud Model Studio et obtenez une clé API conformément à Obtenir et configurer une clé API. Conservez la clé uniquement sur l'AppServer. Ne l'intégrez pas au code client et ne la validez pas dans un dépôt de code.
- Définissez
{endpoint}sur{WorkspaceId}.cn-beijing.maas.aliyuncs.compour Chine (Pékin) ou{WorkspaceId}.ap-southeast-1.maas.aliyuncs.compour Singapour. Remplacez le placeholder par l'ID réel de votre workspace et utilisez la clé API de la région et du workspace correspondants. - Téléchargez la dernière version de l'AOQ Client SDK depuis Téléchargement du SDK.
- Configurez un AppServer selon les Étapes d’authentification AOQ de Qwen-Audio-ASR-Streaming. Avant chaque nouvelle connexion, le client doit obtenir de nouvelles informations de connexion auprès d’AppServer.
Importer le SDK
Téléchargez le dernier AOQ Client SDK depuis Téléchargement du SDK et importez celui de votre plateforme. Les exemples suivants utilisent Android. Les autres plateformes emploient la même conception d'interfaces et le même flux d'événements.
- Android
- iOS
- HarmonyOS
- Linux (Python)
-
Placez
libPluginOpus.sodu plugin Opus dansapp/src/main/jniLibs/armeabi-v7a/etapp/src/main/jniLibs/arm64-v8a/selon l'ABI. PlacezAoqClientSdk-release.aardansapp/libs, puis configurez les dépendances et les ABI prises en charge dansapp/build.gradle: -
Déclarez les autorisations suivantes dans
AndroidManifest.xml: -
Demandez l'autorisation
RECORD_AUDIOà l'exécution avant d'utiliser le microphone.
Obtenir un token sur l'AppServer
AppServer appelle l’API d’allocation de Model Studio et renvoie le jeton, le SID, les points de terminaison Relay et les autres informations nécessaires au SDK pour établir une connexion.
| Champ de réponse | Champ du SDK |
|---|---|
aoqTokenForClient | AoqConnectConfig.token |
sid | AoqConnectConfig.sid |
clientRelayCertFingerprint | AoqConnectConfig.certFingerprint |
clientRelayEndpoints | AoqConnectConfig.relayEndpoints |
extraInfo.workspaceIdHash | AoqConnectConfig.workspaceIdHash |
Implémentation du client

1. Créer le moteur et enregistrer les callbacks
Créez une instance AoqClientEngine et enregistrez les callbacks d'état de connexion et de messages Data. Envoyez run-task une fois la connexion établie. Le callback de messages Data traite les événements du serveur.
2. Configurer l'encodage audio et démarrer la capture
Configurez l'encodage PCM (16 kHz, mono), enregistrez un callback avec setAudioFrameObserver pour obtenir les données PCM, puis appelez enableSendMediaStream(Audio, false) pour désactiver l'envoi des médias audio (l'audio passe par le canal Data). Appelez enfin startAudioCapture() pour lancer la capture.
Cet exemple utilise la capture intégrée à l'AOQ SDK et obtient les données PCM via onCapturedAudioFrame. Vous pouvez aussi implémenter votre propre capture, par exemple avec AudioRecord sur Android. Ajoutez les données PCM à la file du tampon : la logique d'envoi ultérieure reste identique.
- Méthode A : Capture intégrée au SDK
- Méthode B : Capture personnalisée
Le code appelle
startAudioCapture, récupère le PCM via onCapturedAudioFrame et le copie dans le tampon de l'application. Enregistrez le callback de capture brute AoqAudioSourceCaptured afin de stocker l'audio avant l'établissement de la connexion.3. Configurer les identifiants et les pistes, puis se connecter
Renseignez AoqConnectConfig avec les identifiants renvoyés par l'AppServer. Publiez les pistes Audio + Data et abonnez-vous à la piste Data. La déclaration de la piste Audio est nécessaire à la connexion, mais l'envoi des médias audio est désactivé. L'audio est réellement transmis sur le canal Data.
La piste Audio doit être publiée : Le modèle ASR exige sa déclaration lors de la connexion ; sans elle, la connexion échoue. Les données audio passent par le canal Data dans des messages
input_audio_buffer.append, et non par le canal média audio. Appelez enableSendMediaStream(Audio, false) avant la connexion pour empêcher le SDK d'envoyer automatiquement l'audio capturé.4. Envoyer run-task pour lancer la reconnaissance
Après la connexion, générez un nouveau task_id pour chaque séquence de saisie vocale, par exemple avec UUID.randomUUID().toString(). Dans le callback de connexion réussie, envoyez le JSON suivant via sendDataMsg. N'envoyez run-task qu'une seule fois par séquence.
L'événement run-task a la structure suivante. L'ID de tâche est illustratif : remplacez-le par celui généré pour la séquence actuelle. Consultez Événements du client.
sendDataMsg :
5. Envoyer l'audio stocké à vitesse double après task-started
Analysez le JSON dans onDataMsg. Passez l'état d'envoi à prêt uniquement après réception de l'événement suivant pour la tâche actuelle.
task_id des réponses correspond à la tâche actuelle. Un task-started dupliqué ne doit pas lancer une deuxième boucle d'envoi.
Format des messages audio : Le protocole Inference de qwen-audio-3.1-asr-flash-streaming (Événements du client) ne définit que deux événements de contrôle : run-task et finish-task. L'audio lui-même n'est pas envoyé sous forme d'événement JSON. Le canal Data AOQ exige toutefois des messages JSON pour l'audio. AOQ encapsule donc l'audio dans un événement input_audio_buffer.append au niveau du SDK :
| Champ | Type | Description |
|---|---|---|
type | string | Valeur fixe : input_audio_buffer.append |
event_id | string | Identifiant unique de l'événement pour la corrélation et la déduplication |
audio | string | Données audio PCM encodées en Base64 |
sendDataMsg. Le serveur AOQ décode audio en PCM binaire et le transmet au modèle ASR selon son protocole. Le client n'a pas à gérer l'encapsulation des trames binaires. Vérifiez que le format PCM (fréquence d'échantillonnage, nombre de canaux et profondeur de bits) correspond à format et sample_rate déclarés dans run-task.
input_audio_buffer.append et envoyez-le via sendDataMsg :
onDataMsg. Lancez l'envoi audio sur task-started et analysez les résultats sur result-generated. Consultez Événements du serveur.
6. Traiter et afficher les résultats
L'événement result-generated contient la phrase reconnue et des champs comme text et sentence_end. Affichez les résultats intermédiaires en temps réel et ajoutez les résultats finaux au champ de saisie. Consultez Événements du serveur pour les définitions.
7. Envoyer finish-task pour terminer la reconnaissance
Quand l'utilisateur termine la saisie, appelez d'abord engine.stopAudioCapture() pour arrêter la capture. Attendez que tout le PCM restant dans le tampon soit envoyé, puis envoyez finish-task pour informer le serveur que l'envoi audio est terminé. Consultez Événements du client pour les définitions.
task_id doit correspondre à celui du run-task de la séquence actuelle.sendDataMsg :
8. Déconnecter et détruire le moteur
Après réception de task-finished, libérez les ressources comme suit si vous n'avez plus besoin de réutiliser la connexion. Libérez-les également en cas d'erreur ou de délai d'attente dépassé.
Notes d'utilisation
- Attendez
task-startedavant d'envoyer l'audio ; sinon, les données seront ignorées. - Envoyez
finish-taskseulement lorsque le tampon est vide (queue.size() == 0) afin que le modèle traite le dernier segment audio. - Ne déconnectez pas immédiatement après
task-finished. La connexion peut servir à une nouvelle tâche avec un nouveautask_id. - Ignorez les paquets heartbeat (
heartbeat: true) dansresult-generated; ce ne sont pas des résultats de reconnaissance.
Scénarios courants
Plusieurs reconnaissances sur une même connexion
La connexion reste disponible après task-finished. Le client peut renvoyer run-task avec un nouveau task_id pour démarrer une autre séquence sans se reconnecter. Cette méthode convient à la saisie vocale continue et réduit les délais dus aux connexions répétées.
Implémenter une capture personnalisée
Cet exemple utilise la capture intégrée à l'AOQ SDK (startAudioCapture + onCapturedAudioFrame), mais une capture personnalisée est aussi possible. Ajoutez le PCM (16 kHz, mono, 16 bits) à PcmQueue. La logique de rattrapage et d'envoi ultérieure reste identique.