Utilisez AOQ pour vous connecter à fun-asr-realtime, diffuser l'audio du microphone et recevoir les résultats de transcription en temps réel. Le code client utilise Android Java ; les autres plateformes prises en charge par AOQ proposent les mêmes interfaces.
Présentation de la solution
fun-asr-realtime transcrit un flux audio en texte ponctué en temps réel. Le SDK AOQ transporte les médias et les événements sur des pistes distinctes : le client envoie l'audio via la piste Audio et utilise la piste Data pour envoyer des événements de contrôle et recevoir des événements de reconnaissance. Le modèle utilise le protocole d'événements Inference, et non le protocole d'événements Realtime.
Cette solution convient aux sous-titres en direct, à la transcription de réunions, à la saisie vocale et aux assistants intelligents. La piste Audio évite d'encoder l'audio dans les messages d'événement, tandis que la piste Data préserve la sémantique des tâches telles que run-task, result-generated et finish-task.
- Le client demande des identifiants de connexion AOQ temporaires au serveur d'application.
- Le serveur d'application utilise une clé API pour demander un jeton à Model Studio et renvoie les champs de connexion au client.
- Le client établit une connexion AOQ et envoie run-task. Après réception de task-started, le client commence à envoyer l'audio du microphone.
- Le serveur renvoie continuellement des événements result-generated. Une fois que le client a envoyé finish-task, il attend le résultat final et task-finished.
Prérequis
- Activez Alibaba Cloud Model Studio et créez une clé API comme décrit dans Obtenir et configurer une clé API. Stockez la clé API uniquement sur le serveur d'application. Ne l'incluez pas dans le code client et ne la commitez pas dans un référentiel de code.
- Sélectionnez un endpoint AOQ pour la région dans laquelle votre application est déployée. Pour choisir l'endpoint, consultez Sélectionner une région, une étendue de déploiement et un endpoint.
- Téléchargez la dernière version du SDK Client AOQ comme indiqué dans Téléchargement du SDK. Ce tutoriel transporte de l'audio PCM et ne nécessite pas le plugin Opus en option.
- Configurez un AppServer selon les Étapes d’authentification AOQ de Fun-ASR-Realtime. Avant chaque nouvelle connexion, le client doit obtenir de nouvelles informations de connexion auprès d’AppServer.
Importer le SDK
Sélectionnez les instructions d'intégration du SDK pour votre plateforme de développement. L'implémentation client utilise Android Java ; les autres plateformes suivent la même conception d'API et le même flux d'événements.
- Android
- iOS
- HarmonyOS
- Linux (Python)
-
Placez AoqClientSdk-release.aar dans app/libs et configurez la dépendance et les ABI dans app/build.gradle :
-
Déclarez les autorisations réseau et d'enregistrement dans AndroidManifest.xml :
- Demandez l'autorisation d'exécution RECORD_AUDIO avant le début de l'enregistrement. La reconnaissance vocale ne nécessite pas l'autorisation CAMERA.
Essayer la démo
Utilisez la démo Android d'Alibaba Cloud Model Studio pour vérifier rapidement la connectivité AOQ. Téléchargez l'APK et configurez la clé API et workspaceId pour tester certains modèles.
Scannez le code QR suivant pour télécharger la démo :

Flux d'implémentation
- Le serveur d'application utilise l'URL du jeton Inference pour obtenir les paramètres de connexion AOQ pour fun-asr-realtime.
- Le client mappe la réponse du jeton à AoqConnectConfig, publie les pistes Audio et Data, et s'abonne à la piste Data.
- Le client configure les paramètres d'encodage audio selon les besoins métier et du modèle, démarre la capture du microphone avec l'envoi audio désactivé, puis établit la connexion AOQ.
- Une fois la connexion établie, le client envoie run-task et active l'envoi sur la piste Audio après réception de task-started.
- Le client gère result-generated dans onDataMsg. Pour arrêter la reconnaissance, il désactive d'abord l'envoi sur la piste Audio, puis envoie finish-task.
- Après réception de task-finished, le client peut démarrer une autre tâche sur la même connexion avec un nouveau task_id, ou se déconnecter et détruire le moteur.

Obtenir un jeton sur le serveur d'application
Définissez DASHSCOPE_API_KEY sur le serveur d'application et envoyez une requête à l'endpoint de la région sélectionnée. clientIp correspond à l'adresse IP publique réelle de l'appareil client. Ce champ est facultatif, mais nous vous recommandons de le fournir afin que le service puisse sélectionner un endpoint de relais approprié.
Champ de réponse | Champ SDK |
aoqTokenForClient | AoqConnectConfig.token |
sid | AoqConnectConfig.sid |
clientRelayCertFingerprint | AoqConnectConfig.certFingerprint |
clientRelayEndpoints | AoqConnectConfig.relayEndpoints |
extraInfo.workspaceIdHash | AoqConnectConfig.workspaceIdHash |
Implémenter le client Android
Les étapes suivantes découpent le code client Android Java selon la séquence réelle de connexion et de tâche. Chaque extrait est tiré de l'exemple complet présenté plus loin dans cette rubrique.
1. Créer le moteur et enregistrer les rappels
Créez un moteur client AOQ et enregistrez les rappels pour les changements d'état de connexion et les événements de la piste Data. Implémentez la logique de rappel pour votre application et démarrez la reconnaissance uniquement après l'établissement de la connexion.
2. Configurer l'encodage audio
Configurez l'encodage audio envoyé au modèle. Définissez le format, la fréquence d'échantillonnage et le nombre de canaux selon les exigences de votre application et du modèle. Le code suivant utilise PCM mono 16 kHz à titre d'exemple. Pour les valeurs prises en charge, consultez les paramètres run-task dans Événements client.
3. Configurer la connexion et les pistes de transport
Configurez la connexion AOQ avec les identifiants renvoyés par le serveur d'application, et sélectionnez les pistes à publier et auxquelles s'abonner selon votre application. Pour la reconnaissance vocale en temps réel, cet exemple publie les pistes Audio et Data et s'abonne à la piste Data.
4. Démarrer la capture audio et établir la connexion
Configurez la capture audio et établissez la connexion AOQ. Choisissez la capture intégrée ou externe, l'activation ou non du mode VoIP, et le nombre de canaux selon votre application. Maintenez l'envoi sur la piste Audio désactivé jusqu'à la réception de task-started.
5. Démarrer une tâche de reconnaissance
Une fois la connexion établie, générez un ID de tâche et envoyez run-task pour démarrer la reconnaissance. Configurez le modèle, le format, sample_rate et d'autres paramètres de tâche pour le modèle et l'entrée audio que vous utilisez. Pour plus de détails, consultez Événements client.
6. Gérer les événements serveur
Gérez les états des tâches, les résultats de reconnaissance et les erreurs, et transmettez les résultats à votre application. Implémentez les rappels selon les exigences de votre interface utilisateur et de la gestion des états. Envoyez l'audio uniquement après réception de task-started, et excluez les événements heartbeat des transcriptions affichées. Pour le schéma de réponse complet, consultez Événements serveur.
7. Terminer la tâche de reconnaissance
Lorsque l'utilisateur termine l'enregistrement en cours, arrêtez l'envoi audio et envoyez finish-task. Maintenez la connexion ouverte jusqu'à l'arrivée de la transcription finale et de task-finished. Vous pouvez ensuite démarrer une autre tâche ou libérer la connexion selon le flux de votre application. Pour le format d'événement, consultez Événements client.
8. Se déconnecter et détruire le moteur
Libérez la capture audio, la connexion AOQ et les ressources du moteur lorsque la page est détruite ou que la reconnaissance n'est plus nécessaire. Choisissez le point de libération selon le cycle de vie de votre application et ne libérez pas les ressources immédiatement après l'envoi de finish-task.
Exemple complet
Cette classe Android Java mappe la réponse JSON du serveur d'application à AoqConnectConfig et combine la logique de connexion, de capture, de tâche et de libération des ressources décrite précédemment.
Exemple d'utilisation
Transmettez la réponse du jeton du serveur d'application à parseConnectConfig et créez le client. La première tâche de reconnaissance démarre automatiquement après l'établissement de la connexion. Le bouton d'arrêt met fin uniquement à la tâche en cours. Libérez la connexion et les ressources locales lorsque la page est détruite.
Exécuter et vérifier
- Démarrez le serveur d'application. Assurez-vous que la requête de jeton renvoie HTTP 200 et inclut sid, aoqTokenForClient, clientRelayEndpoints, clientRelayCertFingerprint et extraInfo.workspaceIdHash.
- Installez et exécutez l'application sur un appareil Android, accordez l'accès au microphone et parlez.
-
Observez les rappels. Une séquence d'événements normale est la suivante :
Scénarios courants
Plusieurs tâches de reconnaissance sur une seule connexion
Après réception de task-finished, appelez beginRecognition pour démarrer une autre tâche sur la même connexion AOQ. Chaque tâche nécessite un nouveau task_id. Vous n'avez pas besoin de demander un autre jeton ou de vous reconnecter tant que la connexion reste active. Si la connexion est fermée, obtenez de nouveaux identifiants de connexion.
Reconnaissance en arrière-plan sur Android
Sur Android 10 ou version ultérieure, utilisez un service de premier plan avec foregroundServiceType=microphone pour continuer la capture du microphone lorsque l'application est en arrière-plan. Démarrez le service pendant que l'application est encore visible pour l'utilisateur.
Dépannage
Problème | Solution |
Échec de la connexion | Assurez-vous que le jeton est valide, que l'endpoint correspond à la région de l'application et que le serveur d'application transmet l'adresse IP publique réelle de l'appareil client. Ne réutilisez pas un jeton après la fermeture de la connexion. |
La tâche démarre mais aucune transcription n'est renvoyée | Activez l'envoi sur la piste Audio uniquement après réception de task-started. Vérifiez le format d'entrée, la fréquence d'échantillonnage et les autres paramètres par rapport aux Événements client pour le modèle. |
La transcription finale n'est pas renvoyée | Désactivez l'envoi sur la piste Audio avant d'envoyer finish-task. Attendez l'événement result-generated final et task-finished au lieu de vous déconnecter immédiatement. |
Échec du chargement du SDK Android | Assurez-vous que le fichier AAR est inclus en tant que dépendance et que l'application empaquette un ABI pris en charge par le SDK : armeabi-v7a ou arm64-v8a. |
Une tâche ultérieure sur la même connexion est rejetée | Assurez-vous que task-finished a été reçu pour la tâche précédente et générez un nouveau task_id pour le prochain événement run-task. |