Skip to main content

Bonnes pratiques de reconnaissance vocale

Préparez l’audio, réutilisez les connexions, gérez la concurrence Java et les tâches asynchrones, et traitez les erreurs des applications de reconnaissance vocale.

Préparer l’audio d’entrée

Vérifiez le format, la fréquence d’échantillonnage, les canaux et la durée de l’entrée selon les spécifications audio du modèle cible.
  • Privilégiez la qualité de capture et réduisez le bruit ambiant et l’écho. Avant d’activer la réduction du bruit ou l’AEC, comparez les résultats avant et après traitement sur un même jeu audio représentatif transcrit manuellement.
  • Pour l’audio téléphonique à 8 kHz, choisissez un modèle et une fréquence d’échantillonnage correspondants.
  • Choisissez un modèle qui prend en charge la langue et le dialecte de l’audio.
  • Si la reconnaissance des termes spécialisés est imprécise, configurez les mots-clés ou l’enrichissement contextuel selon Améliorer la précision de reconnaissance.
  • Vérifier le format audio
  • Convertir l’encodage et la fréquence d’échantillonnage
  • Découper l’audio
  • Extraire l’audio d’une vidéo
Utilisez FFprobe pour vérifier le conteneur, le codec, la fréquence d’échantillonnage et le nombre de canaux :
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.mp3

Choisir une méthode d’entrée de fichier

Les méthodes d’entrée de fichier dépendent de l’API. Par exemple, Qwen-Audio-ASR-Flash accepte les URL de fichiers audio et les URI de données Base64. Encodez l’audio local sous forme d’URI de données Base64 pour le soumettre directement. Pour l’encodage et les exemples d’appel, consultez API HTTP Flash. Lors de la soumission d’un fichier par URL, assurez-vous que le service peut télécharger l’audio pendant le traitement. Vérifiez les autorisations, l’expiration de l’URL et l’accès depuis le réseau public. En production, hébergez les fichiers dans un stockage stable tel qu’OSS et soumettez leurs URL. Réutilisez les fichiers déjà transférés lors des traitements par lots. Avant d’utiliser le transfert de fichiers locaux d’un SDK, vérifiez les limites de cette interface. Pour le mécanisme de fichiers temporaires et ses conditions, consultez Obtenir une URL de fichier temporaire.

Gérer les tâches et les connexions en temps réel

Le protocole run-task / finish-task de Qwen-Audio-ASR-Message, Qwen-Audio-ASR-Streaming, Fun-ASR-Realtime et Paraformer permet de réutiliser une connexion de façon séquentielle :
  1. Envoyez run-task avec un task_id unique. Attendez task-started avant d’envoyer l’audio.
  2. Après l’envoi audio, envoyez finish-task avec le même task_id.
  3. Attendez l’événement serveur task-finished pour confirmer la fin.
  4. Démarrez la tâche suivante sur la même connexion avec un nouveau task_id. N’exécutez pas plusieurs tâches simultanément sur une connexion.
Qwen3-ASR-Realtime utilise un protocole de session. Fermez explicitement la connexion à la fin de la session. Pour les procédures de connexion et de terminaison, consultez Déroulement des échanges Qwen3-ASR-Realtime.

Traiter les connexions inactives ou défaillantes

  • La connexion se ferme automatiquement si aucune nouvelle tâche ne démarre pendant environ 60 secondes après la fin. Établissez une nouvelle connexion après une longue période d’inactivité.
  • Après un échec, une interruption réseau ou une erreur de protocole, fermez l’ancienne connexion et créez un nouvel objet. Invalidez les objets du pool au lieu de les restituer comme disponibles.
  • Fermez le pool et ses connexions à l’arrêt de l’application ou du service de reconnaissance.

Gérer les silences prolongés pendant une tâche

Si une tâche en cours doit recevoir de l’audio silencieux en continu, configurez heartbeat=true selon son API et continuez à transmettre des données silencieuses dans l’encodage requis. Après la fin de la tâche, gérez les connexions inactives selon la section précédente. Consultez les références suivantes pour les paramètres des modèles. Événements client Message | Événements client Streaming | Événements client Fun-ASR | Événements client Paraformer

Configurer la concurrence Java

Réservez un objet Recognition à chaque tâche en cours et restituez-le uniquement après sa réussite. L’exemple suivant gère ces objets avec Commons Pool 2. Créez le pool une seule fois et réutilisez-le entre les appels.

Ajouter les dépendances

Effectuez d’abord Obtenir une clé API et Installer un SDK. L’exemple complet de cette section nécessite DashScope Java SDK 2.18.0 ou une version ultérieure. Les configurations suivantes utilisent DashScope Java SDK 2.23.2 et Commons Pool 2.12.0 :
  • Maven
  • Gradle
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>2.23.2</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-pool2</artifactId>
    <version>2.12.0</version>
</dependency>

Distinguer les capacités de connexion, d’objets et de requêtes

Le SDK lit les trois variables d’environnement DASHSCOPE_ suivantes. Définissez-les avant de démarrer le processus. Le code de cet exemple lit RECOGNITION_OBJECTPOOL_SIZE.
Variable d’environnementDéfautRôle
DASHSCOPE_CONNECTION_POOL_SIZE32Connexions HTTP inactives conservées par le client OkHttp partagé du SDK.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS32Capacité d’ordonnancement concurrent des requêtes asynchrones du SDK. Les requêtes excédentaires attendent.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST32Capacité de planification des requêtes asynchrones par hôte.
RECOGNITION_OBJECTPOOL_SIZE500Nombre total d’objets autorisés par cet exemple, contrôlé par maxTotal de Commons Pool.
La concurrence désigne le nombre de tâches exécutées simultanément ; le RPS est le nombre de requêtes par seconde. Dimensionnez les threads de travail et le pool d’objets selon la concurrence de l’application, puis contrôlez la fréquence de lancement des tâches selon les Limites de débit du modèle.
Les valeurs suivantes servent de référence pour dimensionner une application Paraformer de reconnaissance en temps réel. La concurrence par serveur correspond au nombre de tâches actives simultanément. Le serveur exécute uniquement cette application.
  • Pour les connexions HTTP inactives, partez d’une capacité d’au moins deux fois la concurrence de pointe, puis ajustez.
  • Initialement, fixez les capacités d’ordonnancement asynchrone globale et par hôte à cette même valeur, puis ajustez selon les files observées.
  • Pour le pool d’objets de reconnaissance, partez de 1,5 à 2 fois la concurrence de pointe. La valeur par défaut de 500 est un paramètre de l’application d’exemple.
Serveur Alibaba CloudConcurrence de référenceCapacité du pool d’objetsConnexions HTTP inactives
4 vCPU, 8 GiB1005002000
8 vCPU, 16 GiB2005002000
16 vCPU, 32 GiB4005002000
Ces réglages concernent un serveur dédié à l’application de reconnaissance en temps réel Paraformer. Ajustez la capacité selon le débit audio, les ressources du client et la charge applicative. Pour les limites des API de modèles, consultez Limites de débit.

Implémenter un pool d’objets de reconnaissance

Suivez le cycle de vie ci-dessous. Lorsque maxTotal est atteint et qu’aucun objet n’est disponible, borrowObject attend qu’un objet soit rendu. Les objets sont créés à la demande et les connexions WebSocket sont établies au lancement des requêtes de reconnaissance.
  1. Empruntez un objet Recognition, démarrez la reconnaissance et envoyez l’audio.
  2. Envoyez la commande de fin et attendez la confirmation. Pour les appels asynchrones, vérifiez aussi le rappel d’erreur.
  3. Après réussite, appelez returnObject pour permettre la réutilisation.
  4. En cas d’échec ou d’interruption, appelez invalidateObject. La méthode destroyObject de la fabrique ferme la connexion.
  5. Une fois toutes les tâches terminées, fermez le pool pour libérer les connexions des objets inactifs.
Enregistrez le code dans RecognitionPoolExample.java. Préparez asr-example.pcm en PCM mono, 16 kHz, 16 bits, définissez DASHSCOPE_API_KEY, puis remplacez l’espace de travail et l’adresse par la configuration de la région cible (voir Points de terminaison). L’exemple utilise trois threads de travail pour traiter neuf tâches.
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionResult;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import org.apache.commons.pool2.BasePooledObjectFactory;
import org.apache.commons.pool2.PooledObject;
import org.apache.commons.pool2.impl.DefaultPooledObject;
import org.apache.commons.pool2.impl.GenericObjectPool;
import org.apache.commons.pool2.impl.GenericObjectPoolConfig;

import java.io.InputStream;
import java.nio.ByteBuffer;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.concurrent.atomic.AtomicReference;

public class RecognitionPoolExample {
    private static final int WORKERS = 3;
    private static final int TASKS = 9;
    private static final int COMPLETION_TIMEOUT_SECONDS = 60;

    public static void main(String[] args) {
        int exitCode = 0;
        try {
            run(args);
        } catch (Exception e) {
            e.printStackTrace();
            exitCode = 1;
        }
        // Exit this standalone example after all owned resources are closed.
        System.exit(exitCode);
    }

    private static void run(String[] args) throws Exception {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            throw new IllegalArgumentException("Set DASHSCOPE_API_KEY first");
        }
        // Replace {WorkspaceId} with the workspace ID for the endpoint region.
        Constants.baseWebsocketApiUrl =
                "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
        Path audio = Paths.get(args.length == 0 ? "asr-example.pcm" : args[0]);
        if (!Files.isReadable(audio)) {
            throw new IllegalArgumentException("Audio file is not readable: " + audio);
        }
        int capacity = Integer.parseInt(System.getenv().getOrDefault(
                "RECOGNITION_OBJECTPOOL_SIZE", "500"));
        if (capacity <= 0) {
            throw new IllegalArgumentException("Pool size must be positive");
        }
        GenericObjectPoolConfig<Recognition> config = new GenericObjectPoolConfig<>();
        config.setMaxTotal(capacity);
        config.setMaxIdle(capacity);
        config.setBlockWhenExhausted(true);
        config.setMinIdle(0);

        GenericObjectPool<Recognition> pool =
                new GenericObjectPool<>(new RecognitionFactory(), config);
        ExecutorService executor = Executors.newFixedThreadPool(WORKERS);
        ExecutorService completionExecutor = Executors.newFixedThreadPool(WORKERS);
        try {
            List<Callable<Void>> tasks = new ArrayList<>();
            for (int i = 0; i < TASKS; i++) {
                tasks.add(() -> {
                    recognize(pool, audio, apiKey, completionExecutor);
                    return null;
                });
            }
            // Wait for every task, then propagate any task failure.
            List<Future<Void>> results = executor.invokeAll(tasks);
            for (Future<Void> result : results) {
                result.get();
            }
        } finally {
            executor.shutdown();
            completionExecutor.shutdownNow();
            try {
                if (!executor.awaitTermination(1, TimeUnit.MINUTES)) {
                    executor.shutdownNow();
                }
                if (!completionExecutor.awaitTermination(1, TimeUnit.MINUTES)) {
                    completionExecutor.shutdownNow();
                }
            } finally {
                pool.close();
                System.out.printf("Pool closed: created=%d, destroyed=%d, active=%d, idle=%d%n",
                        pool.getCreatedCount(), pool.getDestroyedCount(),
                        pool.getNumActive(), pool.getNumIdle());
            }
        }
    }

    private static void recognize(GenericObjectPool<Recognition> pool,
                                  Path audio, String apiKey,
                                  ExecutorService completionExecutor) throws Exception {
        // Example timeout; adjust it to the application's queueing policy.
        Recognition recognizer = pool.borrowObject(Duration.ofSeconds(30));
        boolean reusable = false;
        AtomicReference<Exception> failure = new AtomicReference<>();
        CountDownLatch completed = new CountDownLatch(1);
        try (InputStream input = Files.newInputStream(audio)) {
            RecognitionParam param = RecognitionParam.builder()
                    .model("qwen-audio-3.1-asr-flash-streaming")
                    .apiKey(apiKey).format("pcm").sampleRate(16000).build();
            ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
                @Override
                public void onEvent(RecognitionResult result) {
                    if (result.isSentenceEnd() && result.getSentence() != null) {
                        System.out.println(result.getSentence().getText());
                    }
                }

                @Override
                public void onComplete() {
                    completed.countDown();
                }

                @Override
                public void onError(Exception error) {
                    failure.set(error);
                    completed.countDown();
                }
            };
            recognizer.call(param, callback);
            // 100 ms of PCM16 mono audio at 16 kHz is 3,200 bytes.
            byte[] buffer = new byte[3200];
            int count;
            while ((count = input.read(buffer)) != -1) {
                if (failure.get() != null) {
                    throw failure.get();
                }
                recognizer.sendAudioFrame(ByteBuffer.wrap(buffer, 0, count));
                Thread.sleep(100);
                buffer = new byte[3200];
            }
            // stop() blocks in the SDK, so apply the deadline to the stop call itself.
            long deadline = System.nanoTime()
                    + TimeUnit.SECONDS.toNanos(COMPLETION_TIMEOUT_SECONDS);
            Future<?> stopTask = completionExecutor.submit(recognizer::stop);
            try {
                stopTask.get(Math.max(0, deadline - System.nanoTime()), TimeUnit.NANOSECONDS);
                long remaining = Math.max(0, deadline - System.nanoTime());
                if (!completed.await(remaining, TimeUnit.NANOSECONDS)) {
                    throw new TimeoutException("Timed out waiting for task completion");
                }
            } finally {
                stopTask.cancel(true);
            }
            if (failure.get() != null) {
                throw failure.get();
            }
            reusable = true;
            System.out.printf("Completed: request_id=%s, first_packet_ms=%d, last_packet_ms=%d%n",
                    recognizer.getLastRequestId(), recognizer.getFirstPackageDelay(),
                    recognizer.getLastPackageDelay());
        } finally {
            if (reusable) {
                pool.returnObject(recognizer);
            } else {
                // destroyObject closes the connection before discarding the object.
                pool.invalidateObject(recognizer);
            }
        }
    }

    private static class RecognitionFactory extends BasePooledObjectFactory<Recognition> {
        @Override
        public Recognition create() {
            return new Recognition();
        }

        @Override
        public PooledObject<Recognition> wrap(Recognition recognizer) {
            return new DefaultPooledObject<>(recognizer);
        }

        @Override
        public void destroyObject(PooledObject<Recognition> object) {
            if (object.getObject().getDuplexApi() != null) {
                object.getObject().getDuplexApi().close(1000, "pool cleanup");
            }
        }
    }
}
L’exemple fixe à 30 secondes l’attente d’emprunt d’un objet et à 60 secondes l’attente de fin de tâche. Ces valeurs sont ajustables. En capture directe, adaptez l’attente à la latence de démarrage autorisée et bornez le nombre de tâches en file. En changeant la source audio, conservez la confirmation de fin, l’invalidation après échec et la libération des ressources.

Préchauffer les connexions et mesurer la latence

Préchauffez les connexions en envoyant de véritables requêtes de reconnaissance afin d’établir des connexions WebSocket réutilisables par les tâches suivantes.
  1. Avant les mesures, envoyez des requêtes au niveau de concurrence prévu en production. Une à deux minutes constituent un point de départ à ajuster à la charge.
  2. Vérifiez la présence de connexions réutilisables avant de mesurer le régime stable. Distinguez les mesures de démarrage à froid et de régime stable.
  3. Les connexions peuvent se fermer pendant l’inactivité et devoir être recréées. Répétez le préchauffage si nécessaire avant de nouvelles mesures.
Mesurez les latences du premier et du dernier paquet fournies par le SDK ainsi que la latence de bout en bout de l’application. Précisez les points de départ et de fin de chaque mesure. La mise en file, la connexion, l’envoi audio et le traitement du service influencent des indicateurs différents et doivent être observés séparément.

Gérer les travaux de transcription asynchrones

Pour les transcriptions par lots avec une forte concurrence, privilégiez les callbacks de fin de tâche afin de réduire les requêtes d’interrogation. Pour la configuration et le format des événements, consultez Configurer les callbacks de tâches asynchrones. À la réception d’une notification de fin, identifiez la tâche métier avec data.task_id et vérifiez data.task_status. Si la tâche a réussi mais que la notification ne contient pas le résultat requis, interrogez l’API HTTP du modèle, puis téléchargez et enregistrez les fichiers de transcription.

Contrôler les débits de soumission, de requête et de téléversement

  • Soumission des tâches : contrôlez la fréquence de soumission selon les Limites de débit du modèle cible.
  • Requêtes d’état : l’API de requête a une limite par défaut de 20 QPS, qui peut être portée à 100 QPS (contactez votre responsable de compte Alibaba Cloud pour demander une augmentation), par compte principal Alibaba Cloud, utilisateurs RAM compris. Pour l’interrogation périodique, partez d’un intervalle de 2 à 5 secondes et ajustez-le au nombre de tâches afin de respecter la limite totale. Pour les requêtes, les requêtes par lots et l’annulation, consultez Gérer les tâches asynchrones.
  • Téléversement de fichiers temporaires : l’API d’obtention des informations d’authentification de téléversement est limitée à 100 QPS par compte principal Alibaba Cloud et par modèle. Cette limite ne peut pas être augmentée. Utilisez un stockage stable tel qu’OSS en production et à forte concurrence. Pour la procédure et les limites des fichiers temporaires, consultez Obtenir une URL de fichier temporaire.

Enregistrer rapidement les résultats

Téléchargez et enregistrez les fichiers de résultats dès que la tâche réussit. Par exemple, le champ transcription_url de API HTTP Qwen-Audio-ASR-Filetrans est valide pendant 24 heures. Téléchargez et conservez les résultats avant son expiration.
  • Si la réponse contient un tableau results, vérifiez chaque subtask_status avant de télécharger le JSON de transcription des fichiers traités avec succès. Conservez les horodatages, les locuteurs et les autres champs nécessaires à l’application.
  • Conservez l’association tâche-fichier et l’état final. En cas d’échec de téléchargement, gardez la tâche et réessayez pendant la validité de l’URL.

Gérer les erreurs et les nouvelles tentatives

Décidez de réessayer selon le type d’erreur. Enregistrez l’ID de requête, l’ID de tâche, le modèle, la région et l’étape en échec pour distinguer les problèmes d’entrée ou d’autorisation des incidents temporaires.
ProblèmeAction
Fichier d’entrée ou paramètres invalidesVérifiez l’URL, l’encodage, la fréquence, les canaux et les plages de paramètres. Corrigez avant de soumettre à nouveau.
Authentification ou point de terminaison incorrectVérifiez la clé API, l’espace de travail et la région du point de terminaison, puis corrigez selon le message d’erreur.
Limitation de débitRéduisez la fréquence des requêtes ou des démarrages et suivez Limites de débit. Évitez les boucles de réessai immédiates.
Expiration réseau, interruption ou erreur serveur temporaire (5xx)Pour les échecs de requête ou de téléchargement, utilisez des reprises avec temporisation progressive, en limitant le nombre d’essais et l’attente totale. Après une expiration de délai à la soumission asynchrone, interrogez la tâche si un task_id a été reçu. Sinon, décidez d’une nouvelle soumission selon la tolérance de l’application aux traitements et frais en double.
Échec d’une tâche ou d’un fichier asynchroneConservez les erreurs de tâche et de fichier, identifiez leur cause, puis décidez de corriger l’entrée ou de resoumettre.
Utilisez un délai exponentiel avec une variation aléatoire et limitez le nombre de reprises et l’attente totale. Par exemple, autorisez au plus trois reprises et ajustez les limites au budget de latence de l’application. Après une déconnexion en temps réel, fermez l’ancienne connexion et créez une tâche avec un nouvel ID. Repérez la position audio du dernier résultat final confirmé. Renvoyez au besoin l’audio non confirmé depuis le tampon de l’application, puis fusionnez et dédupliquez les résultats selon les positions dans l’audio d’origine.

Documentation associée