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

Utilice el SDK de Java de DashScope para llamar a Qwen-ASR-Realtime.

Requisitos previos

• DashScope SDK 2.22.5 o posterior (Instalar el SDK)
• Obtener una clave API
• Comprenda el flujo de interacción entre el cliente y el servidor

Modos de interacción

Qwen-ASR-Realtime admite dos modos para decidir cuándo procesar el audio:

Para obtener detalles sobre cada modo, consulte Modo VAD y Modo manual.

Ejemplo completo

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";

Parámetros de solicitud

Parámetros de conexión (OmniRealtimeParam)

Establezca estos parámetros con los métodos encadenados de la clase 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/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();

Configuración de la sesión (OmniRealtimeConfig)

Establezca estos parámetros con los métodos encadenados de la clase 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();

Parámetros de transcripción (OmniRealtimeTranscriptionParam)

Establezca estos parámetros con los métodos setter de la clase OmniRealtimeTranscriptionParam.

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

Interfaces clave

OmniRealtimeConversation

Importación: com.alibaba.dashscope.audio.omni.OmniRealtimeConversation

Esta clase gestiona el ciclo de vida de WebSocket: conexión al servidor, envío de audio y finalización de la sesión.

Crear una conversación

OmniRealtimeConversation conversation =
        new OmniRealtimeConversation(param, callback);

Crea una nueva instancia de conversación con los parámetros de conexión y el controlador de devoluciones de llamada especificados.

Conectar al servidor

conversation.connect();

Abre una conexión WebSocket. El servidor responde con eventos session.created y session.updated.

Lanza: NoApiKeyException, InterruptedException.

Configurar la sesión

conversation.updateSession(config);

Actualiza la configuración de la sesión después de establecer la conexión. El servidor responde con un evento session.updated. Si no se llama, el servidor utiliza la configuración predeterminada.

Enviar datos de audio

conversation.appendAudio(audioBase64);

Agrega un segmento de audio codificado en Base64 al búfer de audio del servidor.

• Modo VAD (enableTurnDetection=true): El servidor detecta los límites del habla y decide cuándo procesar el búfer.
• Modo manual (enableTurnDetection=false): El audio se acumula en el búfer hasta que llama a commit() para activar el reconocimiento. Cada evento puede contener hasta 15 MiB de datos de audio.

Confirmar el búfer de audio

conversation.commit();

Envía el audio almacenado en el búfer para su reconocimiento. El servidor responde con un evento input_audio_buffer.committed.

Este método solo está disponible en modo manual (enableTurnDetection=false). Se produce un error si el búfer de audio está vacío.

Finalizar la sesión

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

Notifica al servidor que termine de procesar cualquier audio restante y finalice la sesión. El servidor responde con un evento session.finished.

Cuándo llamar:

• Modo VAD: Después de terminar de enviar audio.
• Modo manual: Después de llamar a commit().

Cerrar la conexión

conversation.close();

Detiene la tarea y cierra la conexión WebSocket inmediatamente.

Obtener IDs de sesión y respuesta

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

• getSessionId() devuelve el ID de sesión de la tarea actual.
• getResponseId() devuelve el ID de respuesta de la respuesta más reciente del servidor.

OmniRealtimeCallback

Importación: com.alibaba.dashscope.audio.omni.OmniRealtimeCallback

Herede esta clase e implemente los métodos de devolución de llamada para gestionar los eventos del servidor.