Alibaba Cloud Model Studio:Qwen-ASR-Realtime Java SDK - API reference

Utilisez le SDK DashScope pour Java afin d'appeler Qwen-ASR-Realtime.

Prérequis

• SDK DashScope version 2.22.5 ou ultérieure (Installer le SDK)
• Obtenir une clé API
• Maîtriser le flux d'interaction entre le client et le serveur

Modes d'interaction

Qwen-ASR-Realtime propose deux modes pour déterminer le moment de traitement de l'audio :

Pour plus de détails sur chaque mode, reportez-vous aux sections Mode VAD et Mode manuel.

Exemple complet

ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm

import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.sound.sampled.LineUnavailableException;
import java.io.File;
import java.io.FileInputStream;
import java.util.Base64;
import java.util.Collections;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.atomic.AtomicReference;

public class Qwen3AsrRealtimeUsage {
    private static final Logger log = LoggerFactory.getLogger(Qwen3AsrRealtimeUsage.class);
    private static final int AUDIO_CHUNK_SIZE = 1024; // Audio chunk size in bytes
    private static final int SLEEP_INTERVAL_MS = 30;  // Sleep interval in milliseconds

    public static void main(String[] args) throws InterruptedException, LineUnavailableException {
        CountDownLatch finishLatch = new CountDownLatch(1);

        OmniRealtimeParam param = OmniRealtimeParam.builder()
                .model("qwen3-asr-flash-realtime")
                // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
                .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
                // The API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
                // If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: .apikey("sk-xxx")
                .apikey(System.getenv("DASHSCOPE_API_KEY"))
                .build();

        OmniRealtimeConversation conversation = null;
        final AtomicReference<OmniRealtimeConversation> conversationRef = new AtomicReference<>(null);
        conversation = new OmniRealtimeConversation(param, new OmniRealtimeCallback() {
            @Override
            public void onOpen() {
                System.out.println("connection opened");
            }
            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch(type) {
                    case "session.created":
                        System.out.println("start session: " + message.get("session").getAsJsonObject().get("id").getAsString());
                        break;
                    case "conversation.item.input_audio_transcription.completed":
                        System.out.println("transcription: " + message.get("transcript").getAsString());
                        finishLatch.countDown();
                        break;
                    case "input_audio_buffer.speech_started":
                        System.out.println("======VAD Speech Start======");
                        break;
                    case "input_audio_buffer.speech_stopped":
                        System.out.println("======VAD Speech Stop======");
                        break;
                    case "conversation.item.input_audio_transcription.text":
                        System.out.println("transcription: " + message.get("text").getAsString() + message.get("stash").getAsString());
                        break;
                    default:
                        break;
                }
            }
            @Override
            public void onClose(int code, String reason) {
                System.out.println("connection closed code: " + code + ", reason: " + reason);
            }
        });
        conversationRef.set(conversation);
        try {
            conversation.connect();
        } catch (NoApiKeyException e) {
            throw new RuntimeException(e);
        }

        OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
        transcriptionParam.setLanguage("zh");
        transcriptionParam.setInputAudioFormat("pcm");
        transcriptionParam.setInputSampleRate(16000);

        OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
                .transcriptionConfig(transcriptionParam)
                .build();
        conversation.updateSession(config);

        String filePath = "your_audio_file.pcm";
        File audioFile = new File(filePath);
        if (!audioFile.exists()) {
            log.error("Audio file not found: {}", filePath);
            return;
        }

        try (FileInputStream audioInputStream = new FileInputStream(audioFile)) {
            byte[] audioBuffer = new byte[AUDIO_CHUNK_SIZE];
            int bytesRead;
            int totalBytesRead = 0;

            log.info("Starting to send audio data from: {}", filePath);

            // Read and send audio data in chunks
            while ((bytesRead = audioInputStream.read(audioBuffer)) != -1) {
                totalBytesRead += bytesRead;
                String audioB64 = Base64.getEncoder().encodeToString(audioBuffer);
                // Send audio chunk to conversation
                conversation.appendAudio(audioB64);

                // Add small delay to simulate real-time audio streaming
                Thread.sleep(SLEEP_INTERVAL_MS);
            }

            log.info("Finished sending audio data. Total bytes sent: {}", totalBytesRead);

        } catch (Exception e) {
            log.error("Error sending audio from file: {}", filePath, e);
        }

        //send session.finish and wait for finish and close
        conversation.endSession();
        log.info("task finished");

        System.exit(0);
    }
}
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

Paramètres de requête

Paramètres de connexion (OmniRealtimeParam)

Définissez ces paramètres à l'aide des méthodes chaînées de la classe OmniRealtimeParam.

OmniRealtimeParam param = OmniRealtimeParam.builder()
        .model("qwen3-asr-flash-realtime")
        // Endpoint for the Singapore region.
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
        // The API keys for the Singapore and Beijing regions are different.
        // To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
        // If you have not configured an environment variable, replace the following line with .apikey("sk-xxx").
        .apikey(System.getenv("DASHSCOPE_API_KEY"))
        .build();

Configuration de session (OmniRealtimeConfig)

Définissez ces paramètres via les méthodes chaînées de la classe OmniRealtimeConfig.

OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
transcriptionParam.setLanguage("zh");
transcriptionParam.setInputSampleRate(16000);
transcriptionParam.setInputAudioFormat("pcm");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
        .enableTurnDetection(true)
        .turnDetectionType("server_vad")
        .turnDetectionThreshold(0.0f)
        .turnDetectionSilenceDurationMs(400)
        .transcriptionConfig(transcriptionParam)
        .build();

Paramètres de transcription (OmniRealtimeTranscriptionParam)

Configurez ces paramètres au moyen des méthodes setter de la classe OmniRealtimeTranscriptionParam.

OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
transcriptionParam.setLanguage("zh");
transcriptionParam.setInputSampleRate(16000);
transcriptionParam.setInputAudioFormat("pcm");

Interfaces clés

OmniRealtimeConversation

Importation : com.alibaba.dashscope.audio.omni.OmniRealtimeConversation

Cette classe gère le cycle de vie WebSocket : connexion au serveur, envoi de l'audio et clôture de la session.

Créer une conversation

OmniRealtimeConversation conversation =
        new OmniRealtimeConversation(param, callback);

Crée une nouvelle instance de conversation avec les paramètres de connexion et le gestionnaire de callback spécifiés.

Se connecter au serveur

conversation.connect();

Ouvre une connexion WebSocket. Le serveur répond par les événements session.created et session.updated.

Exceptions levées : NoApiKeyException, InterruptedException.

Configurer la session

conversation.updateSession(config);

Met à jour la configuration de la session une fois la connexion établie. Le serveur répond par un événement session.updated. En l'absence d'appel, le serveur applique les paramètres par défaut.

Envoyer des données audio

conversation.appendAudio(audioBase64);

Ajoute un segment audio encodé en Base64 au tampon audio côté serveur.

• Mode VAD (enableTurnDetection=true) : Le serveur détecte les limites de la parole et décide du moment de traitement du tampon.
• Mode manuel (enableTurnDetection=false) : L'audio s'accumule dans le tampon jusqu'à l'appel de commit() pour déclencher la reconnaissance. Chaque événement peut contenir jusqu'à 15 Mio de données audio.

Soumettre le tampon audio

conversation.commit();

Soumet l'audio mis en tampon pour reconnaissance. Le serveur répond par un événement input_audio_buffer.committed.

Cette méthode n'est disponible qu'en mode manuel ( enableTurnDetection=false ). Une erreur survient si le tampon audio est vide.

Terminer la session

conversation.endSession();  // synchronous
// or
conversation.endSessionAsync();  // asynchronous

Signale au serveur de finir le traitement de l'audio restant et de clore la session. Le serveur répond par un événement session.finished.

Moments d'appel recommandés :

• Mode VAD : Après avoir terminé l'envoi de l'audio.
• Mode manuel : Après avoir appelé commit().

Fermer la connexion

conversation.close();

Arrête la tâche et ferme immédiatement la connexion WebSocket.

Obtenir les ID de session et de réponse

String sessionId = conversation.getSessionId();
String responseId = conversation.getResponseId();

• getSessionId() renvoie l'ID de session de la tâche en cours.
• getResponseId() renvoie l'ID de la réponse serveur la plus récente.

OmniRealtimeCallback

Importation : com.alibaba.dashscope.audio.omni.OmniRealtimeCallback

Héritez de cette classe et implémentez les méthodes de callback pour traiter les événements serveur.