Skip to main content

Guia de conexão por WebSocket

O Qwen-ASR-Realtime recebe fluxos de áudio e transcreve a fala em tempo real via WebSocket. O service oferece suporte a dois modos de interação: VAD mode e Manual mode .

Guia do usuário: Para obter visões gerais dos modelos e orientações de seleção, consulte Speech-to-text. Para códigos de exemplo, veja Real-time speech recognition. Limites de taxa: As chamadas de modelo estão sujeitas a limites de taxa. Quando um limite é excedido, o servidor retorna o erro Requests rate limit exceeded, please try again later. Reduza sua taxa de solicitações ou a simultaneidade e tente novamente. Para verificar os limites de cada modelo, consulte Rate limiting.

Endpoint do service

Utilize a seguinte URL WebSocket. O parâmetro de consulta model especifica o modelo. Substitua <model_name> pelo nome do modelo desejado:
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>Substitua {WorkspaceId} pelo seu Workspace ID real.
O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos a migração para os novos domínios:
  • China (Beijing): de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Substitua {WorkspaceId} pelo seu Workspace ID real. Os domínios existentes permanecem totalmente funcionais.
Use o esquema wss://. Defina a autorização nos cabeçalhos da solicitação (consulte Request headers). Especifique o modelo por meio do parâmetro de consulta model.

Cabeçalhos da solicitação

Inclua os seguintes campos nos cabeçalhos da solicitação:

Parâmetro

Tipo

Obrigatório

Descrição

Authorization

string

Sim

Token de autenticação no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API.

user-agent

string

Não

Identificador do cliente que auxilia o servidor a rastrear as origens das solicitações.

X-DashScope-WorkSpace

string

Não

O workspace ID do Alibaba Cloud Model Studio.

X-DashScope-DataInspection

string

Não

Indica se a inspeção de dados deve ser ativada. Omita este cabeçalho, a menos que a inspeção seja necessária; nesse caso, defina o valor como enable.

A autorização é verificada durante o handshake do WebSocket. Se a chave de API for inválida ou estiver ausente, o handshake falhará com um erro HTTP 401 ou 403.

Fluxos de interação

Para detalhes sobre eventos do cliente e do servidor, consulte Client events for Qwen-ASR-Realtime e Server events. O Qwen-ASR-Realtime oferece suporte a dois modos de interação:
  • Modo VAD (padrão): O servidor utiliza detecção de atividade de voz (VAD) para identificar automaticamente o início e o fim de cada enunciado. Este modo é ideal para conversas em tempo real, transcrição de reuniões e cenários semelhantes.
  • Modo manual: O cliente controla os limites do enunciado. Utilize esta opção quando o cliente puder determinar esses limites explicitamente, como ao enviar uma mensagem de voz em um aplicativo de mensagens.
Este modelo não retorna carimbos de tempo por frase ou palavra da transcrição. Os horários de início e fim da fala nos eventos VAD descrevem os limites da atividade de voz; consulte esses eventos para os campos.

Modo VAD (padrão)

O padrão do servidor para silence_duration_ms é 800; 400 é uma referência para conversas que exigem segmentação mais rápida. O padrão de threshold é 0.2. Consulte Eventos do cliente para a configuração completa. O servidor detecta automaticamente o início e o fim de cada enunciado. Envie o fluxo de áudio continuamente; o servidor retornará a transcrição final de cada enunciado assim que detectar seu término. Recomenda-se este modo para conversas em tempo real, transcrição de reuniões e casos de uso similares. Para ativar: Configure o parâmetro session.turn_detection no evento session.update do cliente.
image

Modo manual

Neste modo, o cliente gerencia os limites dos enunciados. Depois de transmitir o áudio correspondente a um enunciado completo, o cliente dispara um evento input_audio_buffer.commit para notificar o servidor. Essa abordagem é indicada quando o cliente consegue determinar tais limites de forma explícita, por exemplo, ao gravar e enviar uma mensagem de voz em um aplicativo de chat. Para ativar: Defina session.turn_detection como null no evento session.update do cliente.
image

Exemplos de chamada

Os exemplos usam qwen3-asr-flash-realtime. Obtenha a chave de API e a Base URL no console e defina DASHSCOPE_API_KEY e DASHSCOPE_BASE_URL. Baixe o áudio de exemplo como asr_example.wav: um arquivo WAV mono de 16 kHz com codificação PCM de 16 bits.
O código de exemplo lê asr_example.pcm (PCM16, 16 kHz, mono). Caso você tenha apenas um arquivo MP3, WAV ou formato similar, converta-o com o ffmpeg:
ffmpeg -i asr_example.wav -ar 16000 -ac 1 -f s16le asr_example.pcm
No modo não-VAD (Manual), recomendamos que a duração acumulada do áudio enviado em uma única sessão não ultrapasse 60 segundos.
  • Java
  • Python
  • Go
  • Node.js
  • C#
  • PHP
Antes de executar o exemplo, instale a dependência 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);
    }
}