跳转到主要内容
Qwen-Audio-ASR-Streaming

WebSocket 接入指南

本文介绍通过 WebSocket 连接访问 Qwen-Audio-ASR-Streaming 实时语音识别服务的接口地址、请求头和交互流程。

接口地址

WebSocket URL 固定如下: wss://maas.qianwenaiapi.com/api-ws/v1/inference

请求头

请求头中需添加如下信息:
参数类型是否必选说明
Authorizationstring是鉴权令牌,格式为 Bearer $DASHSCOPE_API_KEY,将 $DASHSCOPE_API_KEY 替换为实际的 API Key。
user-agentstring否客户端标识,便于服务端追踪来源。
X-DashScope-DataInspectionstring否是否启用数据合规检测功能。默认不传或设为enable。如非必要,请勿启用该参数。
Authorization 鉴权在 WebSocket 握手阶段验证。如果 API Key 无效或缺失,握手将失败并返回 HTTP 401/403 错误。

交互流程

客户端事件和服务端事件的详细说明,请参见客户端事件和服务端事件。
WebSocket 语音识别交互时序
按时间顺序,客户端与服务端的交互流程如下:
  1. 建立连接:客户端与服务端建立 WebSocket 连接。
  2. 开启任务:客户端发送 run-task 指令以开启任务,并接收服务端返回的 task-started 事件,标志着任务已成功开启,可以进行后续步骤。
  3. 发送音频流:客户端开始发送二进制音频(须为单声道音频),并同时接收服务端持续返回的 result-generated 事件,该事件包含语音识别结果。
  4. 通知服务端结束任务:客户端发送 finish-task 指令通知服务端结束任务,并继续接收服务端返回的 result-generated 事件。
  5. 任务结束:客户端收到服务端返回的 task-finished 事件,标志着任务结束。
  6. 关闭连接:客户端关闭 WebSocket 连接。

调用示例

以下示例使用 qwen-audio-3.1-asr-flash-streaming。在控制台获取 API Key 和 Base URL,分别配置环境变量 DASHSCOPE_API_KEY 和 DASHSCOPE_BASE_URL。 下载示例音频并保存为 asr_example.wav。音频为 16 kHz、单声道、16-bit PCM 编码的 WAV 文件。
  • Java
  • Python
  • Go
  • Node.js
  • C#
  • PHP
在运行示例前,请确保已安装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.ByteBuffer;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.UUID;
import java.util.concurrent.atomic.AtomicBoolean;

public class FunASRRealtimeClient {

    private static final String API_KEY = System.getenv("DASHSCOPE_API_KEY");
    private static final String URL = "wss://" + URI.create(System.getenv("DASHSCOPE_BASE_URL")).getHost() + "/api-ws/v1/inference";
    private static final String AUDIO_FILE = "asr_example.wav"; // 替换为您的音频文件路径
    private static final String MODEL = "qwen-audio-3.1-asr-flash-streaming";

    // 生成32位随机ID
    private static final String TASK_ID = UUID.randomUUID().toString().replace("-", "").substring(0, 32);

    private static final AtomicBoolean taskStarted = new AtomicBoolean(false);
    private static WebSocketClient client;

    public static void main(String[] args) throws Exception {
        client = new WebSocketClient(new URI(URL)) {
            @Override
            public void onOpen(ServerHandshake handshake) {
                System.out.println("连接到服务器");
                sendRunTask();
            }

            @Override
            public void onMessage(String data) {
                JSONObject message = new JSONObject(data);
                String event = message.getJSONObject("header").getString("event");
                switch (event) {
                    case "task-started":
                        System.out.println("任务开始");
                        taskStarted.set(true);
                        new Thread(FunASRRealtimeClient::sendAudioStream).start();
                        break;
                    case "result-generated":
                        JSONObject payload = message.getJSONObject("payload");
                        String text = payload.getJSONObject("output").getJSONObject("sentence").getString("text");
                        System.out.println("识别结果:" + text);
                        if (payload.has("usage")) {
                            System.out.println("任务音频时长(秒):" + payload.getJSONObject("usage").get("duration"));
                        }
                        break;
                    case "task-finished":
                        System.out.println("任务完成");
                        close();
                        break;
                    case "task-failed":
                        String errMsg = message.getJSONObject("header").optString("error_message");
                        System.err.println("任务失败:" + errMsg);
                        close();
                        break;
                    default:
                        System.out.println("未知事件:" + event);
                }
            }

            @Override
            public void onClose(int code, String reason, boolean remote) {
                if (!taskStarted.get()) {
                    System.err.println("任务未启动,关闭连接");
                }
            }

            @Override
            public void onError(Exception ex) {
                System.err.println("WebSocket错误:" + ex.getMessage());
            }
        };
        client.addHeader("Authorization", "bearer " + API_KEY);
        client.connectBlocking();
    }

    // 发送run-task指令
    private static void sendRunTask() {
        JSONObject runTask = new JSONObject()
                .put("header", new JSONObject()
                        .put("action", "run-task")
                        .put("task_id", TASK_ID)
                        .put("streaming", "duplex"))
                .put("payload", new JSONObject()
                        .put("task_group", "audio")
                        .put("task", "asr")
                        .put("function", "recognition")
                        .put("model", MODEL)
                        .put("parameters", new JSONObject()
                                .put("sample_rate", 16000)
                                .put("format", "wav"))
                        .put("input", new JSONObject()));
        client.send(runTask.toString());
    }

    // 发送音频流(每100ms发送一个二进制chunk)
    private static void sendAudioStream() {
        int chunkSize = 3200; // 100ms @ 16kHz 16bit 单声道
        try {
            byte[] audio = Files.readAllBytes(Paths.get(AUDIO_FILE));
            int offset = 0;
            while (offset < audio.length) {
                int end = Math.min(offset + chunkSize, audio.length);
                byte[] chunk = new byte[end - offset];
                System.arraycopy(audio, offset, chunk, 0, end - offset);
                client.send(ByteBuffer.wrap(chunk));
                offset = end;
                Thread.sleep(100);
            }
            System.out.println("音频流结束");
            sendFinishTask();
        } catch (Exception e) {
            System.err.println("读取音频文件错误:" + e.getMessage());
            client.close();
        }
    }

    // 发送finish-task指令
    private static void sendFinishTask() {
        JSONObject finishTask = new JSONObject()
                .put("header", new JSONObject()
                        .put("action", "finish-task")
                        .put("task_id", TASK_ID)
                        .put("streaming", "duplex"))
                .put("payload", new JSONObject()
                        .put("input", new JSONObject()));
        client.send(finishTask.toString());
    }
}