Nuwa ASR 实时语音识别协议

1. 简介

Nuwa ASR 通过 WebSocket 提供实时语音识别服务，适用于需要将语音流转换为文本的场景。该协议用于客户端将音频流发送到后端 ASR 服务，并接收实时识别结果。

2. 接入前须知

该接口一般由 Nuwa 平台后台服务对外提供。客户端需要先获取对应服务的访问地址。
音频数据通常为 16k 采样率、单通道 PCM 原始音频。
业务侧可以通过 stype 指定识别引擎：doubao 或 diy。

3. 连接地址

WebSocket 连接

wss://wsapi.nuwaai.com/websk/humanAgent/realasr
wss://wsapi.nuwaai.com/websk/humanAgent/realasr/{stype}

参数说明

参数名称	类型	是否必填	说明
stype	String	否	识别服务类型，支持 `doubao`（默认）和 `diy`

提示

若不指定 stype，服务端默认使用 doubao 识别引擎。

4. 连接示例

示例

const host = 'wss://your-asr-server.example.com';
const stype = 'doubao';
const ws = new WebSocket(`${host}/realasr/${stype}`);

ws.onopen = () => {
  console.log('ASR WebSocket 已连接');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('收到 ASR 消息：', message);
};

ws.onclose = () => {
  console.log('ASR WebSocket 已关闭');
};

ws.onerror = (err) => {
  console.error('ASR WebSocket 错误：', err);
};

5. 客户端发送消息

5.1 文本控制消息

客户端可以发送 JSON 文本消息来控制识别热词。当前协议支持设置热词：

{
  "type": "setHotWords",
  "data": {
    "hotWords": ["咱们", "休息一下", "你好呀"]
  }
}

参数名称	类型	是否必填	说明
type	String	是	消息类型：`setHotWords`
data	Object	是	消息体
data.hotWords	Array	否	热词列表，支持多个字符串

提示

后端会将热词发送给 ASR 引擎以提升识别效果。

5.2 音频二进制消息

客户端通过 WebSocket 的二进制消息发送音频数据：

使用 bytes 类型消息发送原始音频字节。
通常为 16k 采样率、单通道 PCM 音频。

// 发送音频数据块
ws.send(audioArrayBuffer);

6. 服务端返回消息

服务端会将 ASR 结果以 JSON 消息推送给客户端。常见消息类型包括：

type	说明
`asr-text`	实时识别文本结果（增量或全量）
`asr-commit`	识别结果已提交，通常为最终识别文本
`checkToEnd`	识别阶段检查是否结束
`first`	第一帧识别结果或首段结果
`asr-error`	ASR 识别错误

示例：识别结果

{
  "type": "asr-text",
  "data": {
    "content": "今天天气很好"
  }
}

示例：最终提交结果

{
  "type": "asr-commit",
  "data": {
    "content": "今天天气很好"
  }
}

示例：错误通知

{
  "type": "asr-error",
  "data": {
    "message": "识别失败",
    "code": 500
  }
}

7. 识别服务类型说明

stype	说明
`doubao`	默认识别引擎，使用 Doubao ASR 服务
`diy`	自定义识别引擎，使用 Diy ASR 服务

8. 推荐接入流程

建立 WebSocket 连接：/realasr 或 /realasr/{stype}。
（可选）发送 setHotWords 设置热词。
发送音频二进制数据。
持续接收 asr-text 和 asr-commit 消息。
识别完成后关闭 WebSocket 连接。

sequenceDiagram
    participant C as 客户端
    participant S as ASR 服务

    C->>S: 1. 建立 WebSocket 连接
    S-->>C: 2. 连接建立确认
    C->>S: 3. 发送 setHotWords (可选)
    S-->>S: 4. 更新热词配置

    loop 音频流识别
        C->>S: 5. 发送音频二进制数据
        S-->>C: 6. 返回 asr-text 实时识别结果
        C->>S: 7. 持续发送音频数据
        S-->>C: 8. 返回 asr-commit 最终识别结果
    end
    
    C->>S: 9. 关闭 WebSocket 连接