Skip to main content

Déroulement des interactions de reconnaissance vocale en temps réel (Qwen-ASR-Realtime)

Qwen-ASR-Realtime reçoit des flux audio et transcrit la parole en temps réel via WebSocket. Ce service prend en charge deux modes d'interaction : Mode VAD et Mode manuel .

Guide d'utilisation : Pour une présentation générale des modèles et des conseils de sélection, consultez Speech-to-text. Pour obtenir des exemples de code, reportez-vous à Real-time speech recognition. Limites de taux : Les appels de modèle sont soumis à des limites de taux. Lorsqu'une limite est dépassée, le serveur renvoie l'erreur Requests rate limit exceeded, please try again later. Réduisez votre taux de requêtes ou le niveau de concurrence, puis réessayez. Pour connaître les limites applicables à chaque modèle, consultez Rate limiting.

Endpoint du service

Utilisez l'URL WebSocket suivante. Le paramètre de requête model spécifie le modèle. Remplacez <model_name> par le nom du modèle :
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>Remplacez {WorkspaceId} par votre Workspace ID réel.
Alibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions China (Beijing) et Singapore. Ces nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • China (Beijing) : passez de dashscope.aliyuncs.com à {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore : passez de dashscope-intl.aliyuncs.com à {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Remplacez {WorkspaceId} par votre Workspace ID réel. Les domaines existants restent pleinement fonctionnels.
Utilisez le schéma wss://. Configurez l'autorisation dans les en-têtes de requête (voir En-têtes de requête). Spécifiez le modèle au moyen du paramètre de requête model.

En-têtes de requête

Incluez les champs suivants dans les en-têtes de requête :

Paramètre

Type

Obligatoire

Description

Authorization

string

Oui

Jeton d'authentification au format Bearer <your_api_key>. Remplacez <your_api_key> par votre clé API.

user-agent

string

Non

Identifiant client permettant au serveur de suivre l'origine des requêtes.

X-DashScope-WorkSpace

string

Non

L'workspace ID Alibaba Cloud Model Studio.

X-DashScope-DataInspection

string

Non

Indique s'il faut activer l'inspection des données. Omettez cet en-tête sauf si cette inspection est nécessaire ; dans ce cas, définissez la valeur sur enable.

L'autorisation est vérifiée lors du handshake WebSocket. Si la clé API est invalide ou manquante, le handshake échoue avec une erreur HTTP 401 ou 403.

Flux d'interaction

Pour plus de détails sur les événements client et serveur, consultez Client events for Qwen-ASR-Realtime et Server events. Qwen-ASR-Realtime prend en charge deux modes d'interaction :
  • Mode VAD (par défaut) : Le serveur utilise la détection d'activité vocale (VAD) pour identifier automatiquement le début et la fin de chaque énoncé. Privilégiez ce mode pour les conversations en temps réel, la transcription de réunions et les scénarios similaires.
  • Mode manuel : Le client contrôle les limites des énoncés. Ce mode est adapté lorsque le client peut déterminer explicitement ces limites, par exemple lors de l'envoi d'un message vocal dans une application de messagerie.
Ce modèle ne renvoie pas d’horodatages par phrase ou par mot de la transcription. Les heures de début et de fin de parole des événements VAD décrivent les limites d’activité vocale ; consultez ces événements pour les champs.

Mode VAD (par défaut)

La valeur serveur par défaut de silence_duration_ms est 800 ; 400 constitue un réglage de référence pour les conversations nécessitant une segmentation plus rapide. La valeur par défaut de threshold est 0.2. Consultez les événements client. Le serveur détecte automatiquement le début et la fin de chaque énoncé. Envoyez le flux audio en continu ; le serveur renvoie la transcription finale de chaque énoncé dès qu'il en détecte la fin. Ce mode convient aux conversations en temps réel, à la transcription de réunions et aux cas d'usage analogues. Activation : Configurez le paramètre session.turn_detection dans l'événement client session.update.
image
  • Le client envoie des événements input_audio_buffer.append pour ajouter des données audio au tampon.
  • Le serveur renvoie un événement input_audio_buffer.speech_started lorsqu'une parole est détectée. Remarque : Si le client envoie session.finish pour terminer la session avant la réception de cet événement, le serveur retourne immédiatement un événement session.finished. Le client doit alors fermer la connexion.
  • Le client continue d'envoyer des événements input_audio_buffer.append pour transmettre l'audio.
  • Une fois tout l'audio envoyé, le client émet un événement session.finish pour clore la session.
    En mode VAD, le client doit envoyer un événement session.finish avant de fermer la connexion. Si le client ferme la connexion WebSocket sans avoir préalablement envoyé session.finish, le serveur abandonne l'élément en cours de traitement et les événements tels que conversation.item.input_audio_transcription.completed ne sont pas remis. Envoyez {"type":"session.finish"} avant d'appeler ws.Close(), puis attendez l'événement session.finished avant de fermer la connexion.
  • Le serveur retourne un événement input_audio_buffer.speech_stopped lorsqu'il détecte la fin de la parole.
  • Le serveur renvoie ensuite un événement input_audio_buffer.committed.
  • Le serveur émet un événement conversation.item.created.
  • Le serveur fournit un événement conversation.item.input_audio_transcription.text contenant les résultats partiels de transcription.
  • Le serveur retourne un événement conversation.item.input_audio_transcription.completed contenant le résultat final de la transcription.
  • Enfin, le serveur envoie un événement session.finished pour signaler la fin de la reconnaissance. Le client doit alors fermer la connexion.

Mode manuel

Dans ce mode, le client maîtrise les limites des énoncés. Après avoir transmis l'audio correspondant à un énoncé complet, le client envoie un événement input_audio_buffer.commit pour notifier le serveur. Cette approche est recommandée lorsque le client peut déterminer explicitement les bornes de l'énoncé, comme c'est le cas pour l'envoi d'un message vocal dans une application de messagerie. Activation : Définissez session.turn_detection sur null dans l'événement client session.update.
image

Exemples

Ces exemples utilisent qwen3-asr-flash-realtime. Obtenez votre clé API et votre Base URL dans la console, puis définissez DASHSCOPE_API_KEY et DASHSCOPE_BASE_URL. Téléchargez l’audio d’exemple sous le nom asr_example.wav : un fichier WAV mono à 16 kHz, encodé en PCM 16 bits.
Le code d'exemple lit le fichier asr_example.pcm (PCM16, 16 kHz, mono). Si vous disposez uniquement d'un fichier MP3, WAV ou d'un format similaire, convertissez-le avec ffmpeg :
ffmpeg -i asr_example.wav -ar 16000 -ac 1 -f s16le asr_example.pcm
  • Java
  • Python
  • Go
  • Node.js
  • C#
  • PHP
Avant d'exécuter l'exemple, installez la dépendance Java-WebSocket :
Maven
<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.6</version>
</dependency>
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20240303</version>
</dependency>
import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;
import org.json.JSONObject;

import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.logging.*;

public class QwenASRRealtimeClient {

    private static final Logger logger = Logger.getLogger(QwenASRRealtimeClient.class.getName());
    private static final String API_KEY = System.getenv("DASHSCOPE_API_KEY");
    private static final String MODEL = "qwen3-asr-flash-realtime";

    // Controls whether to use VAD mode
    private static final boolean enableServerVad = true;

    private static final AtomicBoolean isRunning = new AtomicBoolean(true);
    private static WebSocketClient client;

    public static void main(String[] args) throws Exception {
        initLogger();

        String baseUrl = "wss://" + URI.create(System.getenv("DASHSCOPE_BASE_URL")).getHost() + "/api-ws/v1/realtime";
        String url = baseUrl + "?model=" + MODEL;
        logger.info("Connecting to server: " + url);

        client = new WebSocketClient(new URI(url)) {
            @Override
            public void onOpen(ServerHandshake handshake) {
                logger.info("Connected to server.");
                sendSessionUpdate();
            }

            @Override
            public void onMessage(String message) {
                try {
                    JSONObject data = new JSONObject(message);
                    String eventType = data.optString("type");

                    logger.info("Received event: " + data.toString(2));

                    // The final recognition result is in the transcription.completed event
                    if ("conversation.item.input_audio_transcription.completed".equals(eventType)) {
                        logger.info("Final transcript: " + data.optString("transcript"));
                    }

                    // On receiving the finished event -> stop the sending thread and close the connection
                    if ("session.finished".equals(eventType)) {
                        logger.info("Closing WebSocket connection after session finished...");

                        isRunning.set(false); // Stop the audio sending thread
                        if (this.isOpen()) {
                            this.close(1000, "ASR finished");
                        }
                    }
                } catch (Exception e) {
                    logger.severe("Failed to parse message: " + message);
                }
            }

            @Override
            public void onClose(int code, String reason, boolean remote) {
                logger.info("Connection closed: " + code + " - " + reason);
            }

            @Override
            public void onError(Exception ex) {
                logger.severe("Error: " + ex.getMessage());
            }
        };

        // Add request headers
        client.addHeader("Authorization", "Bearer " + API_KEY);
        client.addHeader("OpenAI-Beta", "realtime=v1");

        client.connectBlocking(); // Block until the connection is established

        // Replace with the path to the audio file to be recognized
        String localAudioPath = "asr_example.pcm";
        Thread audioThread = new Thread(() -> {
            try {
                sendAudio(localAudioPath);
            } catch (Exception e) {
                logger.severe("Audio sending thread error: " + e.getMessage());
            }
        });
        audioThread.start();
    }

    /** Session update event (enable/disable VAD) */
    private static void sendSessionUpdate() {
        JSONObject eventNoVad = new JSONObject()
                .put("event_id", "event_123")
                .put("type", "session.update")
                .put("session", new JSONObject()
                        .put("modalities", new String[]{"text"})
                        .put("input_audio_format", "pcm")
                        .put("sample_rate", 16000)
                        // .put("input_audio_transcription", new JSONObject()
                        //         .put("language", "zh"))
                        .put("turn_detection", JSONObject.NULL) // Manual mode
                );

        JSONObject eventVad = new JSONObject()
                .put("event_id", "event_123")
                .put("type", "session.update")
                .put("session", new JSONObject()
                        .put("modalities", new String[]{"text"})
                        .put("input_audio_format", "pcm")
                        .put("sample_rate", 16000)
                        // .put("input_audio_transcription", new JSONObject()
                        //         .put("language", "zh"))
                        .put("turn_detection", new JSONObject()
                                .put("type", "server_vad")
                                .put("threshold", 0.2)
                                .put("silence_duration_ms", 400))
                );

        if (enableServerVad) {
            logger.info("Sending event (VAD):\n" + eventVad.toString(2));
            client.send(eventVad.toString());
        } else {
            logger.info("Sending event (Manual):\n" + eventNoVad.toString(2));
            client.send(eventNoVad.toString());
        }
    }

    /** Send the audio file stream */
    private static void sendAudio(String localAudioPath) throws Exception {
        Thread.sleep(3000); // Wait for the session to be ready
        byte[] allBytes = Files.readAllBytes(Paths.get(localAudioPath));
        logger.info("File reading started");

        int offset = 0;
        while (isRunning.get() && offset < allBytes.length) {
            int chunkSize = Math.min(3200, allBytes.length - offset);
            byte[] chunk = new byte[chunkSize];
            System.arraycopy(allBytes, offset, chunk, 0, chunkSize);
            offset += chunkSize;

            if (client != null && client.isOpen()) {
                String encoded = Base64.getEncoder().encodeToString(chunk);
                JSONObject eventd = new JSONObject()
                        .put("event_id", "event_" + System.currentTimeMillis())
                        .put("type", "input_audio_buffer.append")
                        .put("audio", encoded);

                client.send(eventd.toString());
                logger.info("Sending audio event: " + eventd.getString("event_id"));
            } else {
                break; // Avoid continuing to send after disconnection
            }

            Thread.sleep(100); // Simulate real-time sending
        }

        logger.info("File reading finished");

        if (client != null && client.isOpen()) {
            // Commit is required in non-VAD mode
            if (!enableServerVad) {
                JSONObject commitEvent = new JSONObject()
                        .put("event_id", "event_789")
                        .put("type", "input_audio_buffer.commit");
                client.send(commitEvent.toString());
                logger.info("Sent commit event for manual mode.");
            }

            JSONObject finishEvent = new JSONObject()
                    .put("event_id", "event_987")
                    .put("type", "session.finish");
            client.send(finishEvent.toString());
            logger.info("Sent finish event.");
        }
    }

    /** Initialize logging */
    private static void initLogger() {
        logger.setLevel(Level.ALL);
        Logger rootLogger = Logger.getLogger("");
        for (Handler h : rootLogger.getHandlers()) {
            rootLogger.removeHandler(h);
        }

        Handler consoleHandler = new ConsoleHandler();
        consoleHandler.setLevel(Level.ALL);
        consoleHandler.setFormatter(new SimpleFormatter());
        logger.addHandler(consoleHandler);
    }
}

SDK disponibles