Skip to main content

Saisie vocale avec AOQ et qwen-audio-3.1-asr-flash-streaming

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 :
  1. 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.
  2. 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é.
  3. 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 sendDataMsg pour 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.
  4. 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

  1. 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.
  2. Définissez {endpoint} sur {WorkspaceId}.cn-beijing.maas.aliyuncs.com pour Chine (Pékin) ou {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com pour 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.
  3. Téléchargez la dernière version de l'AOQ Client SDK depuis Téléchargement du SDK.
  4. 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)
  1. Placez libPluginOpus.so du plugin Opus dans app/src/main/jniLibs/armeabi-v7a/ et app/src/main/jniLibs/arm64-v8a/ selon l'ABI. Placez AoqClientSdk-release.aar dans app/libs, puis configurez les dépendances et les ABI prises en charge dans app/build.gradle :
    android {
        defaultConfig {
            minSdk 21
            ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' }
        }
    }
    
    dependencies {
        implementation fileTree(dir: 'libs', include: ['*.aar'])
    }
    
  2. Déclarez les autorisations suivantes dans AndroidManifest.xml :
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    
  3. 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.
curl -X POST \
  "https://{endpoint}/api/v1/webrtc/inference?model=qwen-audio-3.1-asr-flash-streaming" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "x-dashscope-rtc-transport: moq" \
  -d "{\"clientIp\": \"${CLIENT_REAL_IP}\"}"
Champ de réponseChamp du SDK
aoqTokenForClientAoqConnectConfig.token
sidAoqConnectConfig.sid
clientRelayCertFingerprintAoqConnectConfig.certFingerprint
clientRelayEndpointsAoqConnectConfig.relayEndpoints
extraInfo.workspaceIdHashAoqConnectConfig.workspaceIdHash

Implémentation du client

Séquence du client de saisie vocale
Les étapes suivantes utilisent Android et suivent l'ordre d'implémentation. Les autres plateformes utilisent la même conception d'interfaces et le même flux d'événements.

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.
// Create the engine
AoqClientEngine.AoqCreateConfig create = new AoqClientEngine.AoqCreateConfig();
create.workDir = getCacheDir().getAbsolutePath();
engine = AoqClientEngine.createEngine(this, create, new AoqClientListener() {
    @Override
    public void onConnectionStatusChange(
            @NonNull AoqClientEngine.AoqConnectionStatus state) {
        if (state == AoqClientEngine.AoqConnectionStatus.AoqConnectionStatusConnected) {
            // Connected: send run-task (see step 4)
        }
    }

    @Override
    public void onDataMsg(@NonNull AoqClientEngine.AoqDataMsg msg) {
        // Parse server events (see step 5)
    }

    @Override
    public void onError(int code, String message) {
        // Handle errors
    }
});

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.
int SAMPLE_RATE = 16000;

// Configure PCM encoding
AoqClientEngine.AoqAudioCodecConfig codec = new AoqClientEngine.AoqAudioCodecConfig();
codec.codecType = AoqClientEngine.AoqEncoderType.AoqEncoderTypeAudioPCM;
codec.sampleRate = SAMPLE_RATE;
codec.channel = 1;
codec.bitrate = 256000;
engine.setAudioEncoderConfig(codec);

// Register the capture callback
engine.setAudioFrameObserver(new AoqClientListener.AoqAudioFrameListener() {
    @Override
    public void onCapturedAudioFrame(
            @NonNull AoqClientEngine.AoqAudioFrameData frame) {
        if (frame.dataPtr != null && frame.dataSize > 0) {
            // Buffer PCM data in the queue (see step 5)
            pcmQueue.offer(frame.dataPtr, frame.dataSize);
        }
        Arrays.fill(frame.dataPtr, (byte) 0);  // Clear the buffer to prevent outgoing audio media
    }
});

AoqClientEngine.AoqAudioObserverConfig observer = new AoqClientEngine.AoqAudioObserverConfig();
observer.sampleRate = SAMPLE_RATE;
observer.channels = 1;
observer.mode = AoqClientEngine.AoqAudioObserverMode.AoqAudioObserverModeReadWrite;
engine.enableAudioFrameObserver(true,
        AoqClientEngine.AoqAudioSource.AoqAudioSourceCaptured, observer);

// Disable outgoing audio media (send audio over the Data channel)
engine.enableSendMediaStream(AoqClientEngine.AoqTrackType.AoqTrackTypeAudio, false);

// Start capture immediately, without waiting for the connection
engine.startAudioCapture(new AoqClientEngine.AoqAudioCaptureConfig());
Choisissez une seule méthode pour ne pas lancer deux enregistreurs simultanément. Avec une capture personnalisée, l'application assure la conversion de format, la confirmation de l'arrêt et la libération des périphériques audio.

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é.
// Build the connection configuration after obtaining credentials from AppServer
AoqClientEngine.AoqConnectConfig config = new AoqClientEngine.AoqConnectConfig();
config.token = aoqTokenForClient;
config.sid = sid;
config.certFingerprint = clientRelayCertFingerprint;
config.workspaceIdHash = workspaceIdHash;
// Parse relayEndpoints from the response and add them to the configuration

// Publish Audio + Data tracks
AoqClientEngine.AoqTrackParam audioTrack = new AoqClientEngine.AoqTrackParam();
audioTrack.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
config.publishTracks.add(audioTrack);

AoqClientEngine.AoqTrackParam dataTrack = new AoqClientEngine.AoqTrackParam();
dataTrack.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
config.publishTracks.add(dataTrack);

// Subscribe to the Data track
AoqClientEngine.AoqTrackParam subData = new AoqClientEngine.AoqTrackParam();
subData.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
config.subscribeTracks.add(subData);

// Establish the connection
engine.connect(config);

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.
{
  "header": {
    "action": "run-task",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3",
    "streaming": "duplex"
  },
  "payload": {
    "task_group": "audio",
    "task": "asr",
    "function": "recognition",
    "model": "qwen-audio-3.1-asr-flash-streaming",
    "parameters": {
      "format": "pcm",
      "sample_rate": 16000
    },
    "input": {}
  }
}
Les messages de contrôle et d'audio utilisent la même interface sendDataMsg :
String taskId = UUID.randomUUID().toString();
JSONObject root = new JSONObject()
        .put("header", new JSONObject()
                .put("action", "run-task")
                .put("task_id", taskId)
                .put("streaming", "duplex"))
        .put("payload", new JSONObject()
                .put("task_group", "audio")
                .put("task", "asr")
                .put("function", "recognition")
                .put("model", "qwen-audio-3.1-asr-flash-streaming")
                .put("parameters", new JSONObject()
                        .put("format", "pcm")
                        .put("sample_rate", 16000))
                .put("input", new JSONObject()));

AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
msg.data = root.toString().getBytes(StandardCharsets.UTF_8);
engine.sendDataMsg(msg);

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.
{
  "header": {
    "event": "task-started",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3"
  },
  "payload": {}
}
L'exemple contient les champs essentiels de l'événement. Lisez les autres champs selon vos besoins. Consultez Événements du serveur. À ce stade, le tampon contient généralement l'audio capturé pendant la demande d'identifiants, la connexion AOQ et le démarrage de la tâche. Vérifiez que le 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 :
ChampTypeDescription
typestringValeur fixe : input_audio_buffer.append
event_idstringIdentifiant unique de l'événement pour la corrélation et la déduplication
audiostringDonnées audio PCM encodées en Base64
Le client encode le PCM capturé en Base64, l'intègre à ce JSON et l'envoie via 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.
{
    "type": "input_audio_buffer.append",
    "event_id": "event_550e8400-e29b-41d4-a716-446655440000",
    "audio": "AQID//+AgAAEAACAAAAA..."
}
Envoyer les données audio : Lisez le PCM dans la file du tampon, encapsulez-le dans un JSON input_audio_buffer.append et envoyez-le via sendDataMsg :
byte[] pcm = pcmQueue.poll(640);  // Read one PCM frame

if (pcm != null) {
    JSONObject event = new JSONObject()
            .put("type", "input_audio_buffer.append")
            .put("event_id", "event_" + UUID.randomUUID())
            .put("audio", Base64.encodeToString(pcm, Base64.NO_WRAP));

    AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
    msg.data = event.toString().getBytes(StandardCharsets.UTF_8);
    engine.sendDataMsg(msg);
}
Traiter les événements du serveur : Analysez les événements dans le callback onDataMsg. Lancez l'envoi audio sur task-started et analysez les résultats sur result-generated. Consultez Événements du serveur.
JSONObject root = new JSONObject(new String(msg.data, StandardCharsets.UTF_8));
String event = root.optJSONObject("header").optString("event");

if ("task-started".equals(event)) {
    // Model ready: send buffered audio at double speed, then stream in real time
} else if ("result-generated".equals(event)) {
    // Parse recognition results (see step 6)
    JSONObject sentence = root.optJSONObject("payload")
            .optJSONObject("output").optJSONObject("sentence");
    if (sentence != null && !sentence.optBoolean("heartbeat")) {
        String text = sentence.optString("text", "");
        boolean isFinal = sentence.optBoolean("sentence_end");
        // Display recognition results
    }
} else if ("task-finished".equals(event)) {
    // Task finished
} else if ("task-failed".equals(event)) {
    // Task failed
}

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.
private void handleRecognitionResult(JSONObject root) {
    JSONObject payload = root.optJSONObject("payload");
    JSONObject output = payload == null ? null : payload.optJSONObject("output");
    JSONObject sentence = output == null ? null : output.optJSONObject("sentence");
    if (sentence == null || sentence.optBoolean("heartbeat")) return;

    String text = sentence.optString("text", "");
    if (text.isEmpty()) return;
    boolean isFinal = sentence.optBoolean("sentence_end");

    // Display interim results in real time; append final results
    listener.onResult(text, isFinal);
}

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.
L'événement finish-task a la structure suivante :
{
    "header": {
        "action": "finish-task",
        "task_id": "UUID",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}
Envoyez-le via sendDataMsg :
engine.stopAudioCapture();  // Stop capture

// Wait for the buffer to drain, then send finish-task
JSONObject root = new JSONObject()
        .put("header", new JSONObject()
                .put("action", "finish-task")
                .put("task_id", taskId)
                .put("streaming", "duplex"))
        .put("payload", new JSONObject()
                .put("input", new JSONObject()));

AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
msg.data = root.toString().getBytes(StandardCharsets.UTF_8);
engine.sendDataMsg(msg);
Quand le modèle termine, il renvoie l'événement essentiel suivant :
{
  "header": {
    "event": "task-finished",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3"
  },
  "payload": {}
}

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é.
engine.stopAudioCapture();
engine.setAudioFrameObserver(null);
engine.disconnect();
AoqClientEngine.destroy();
engine = null;

Notes d'utilisation

  1. Attendez task-started avant d'envoyer l'audio ; sinon, les données seront ignorées.
  2. Envoyez finish-task seulement lorsque le tampon est vide (queue.size() == 0) afin que le modèle traite le dernier segment audio.
  3. Ne déconnectez pas immédiatement après task-finished. La connexion peut servir à une nouvelle tâche avec un nouveau task_id.
  4. Ignorez les paquets heartbeat (heartbeat: true) dans result-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.
// After the first round finishes (task-finished received)
// Send run-task with a new task_id to start the second round
taskId = UUID.randomUUID().toString();
sendRunTask();

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.

Documentation connexe