本文档介绍如何通过WebSocket协议实时访问语音识别服务 (ASR)，主要包含鉴权相关、协议详情、常见问题和使用Demo四部分。

ASR 服务使用的域名是 wss://openspeech.bytedance.com/api/v2/asr。

设置鉴权内容，请参考鉴权方法。

交互流程

3.1. WebSocket 二进制协议

WebSocket 使用二进制协议传输数据。协议的组成由至少 4 个字节的可变 header、payload size 和 payload 三部分组成，其中 header 描述消息类型、序列化方式以及压缩格式等信息，payload size 是 payload 的长度，payload 是具体负载内容，依据消息类型不同 payload 内容不同。

需注意：协议中整数类型的字段都使用大端表示。

3.1.1. header 数据格式

3.1.2. header 字段描述

3.2. 请求流程

3.2.1. 建立连接

根据 WebSocket 协议本身的机制，client 会发送 HTTP GET 请求和 server 建立连接做协议升级。

需要在其中根据身份认证协议加入鉴权签名头。设置方法请参考鉴权方法。

3.2.2. 发送 full client request

WebSocket 建立连接后，发送的第一个请求是 full client request。格式是：

• Header： 3.1.1 描述的 4 字节头。
• Payload size： 是按 Header 中指定压缩方式压缩 payload 后的长度，使用大端表示。
• Payload： 包含音频的元数据以及 server 所需的相关参数，一般是 JSON 格式。具体的参数字段见下表：

参数示例：

{
    "app": {
        "appid": "",
        "token": "",
        "cluster": ""
    },
    "user": {
        "uid": "388808088185088"
    },
    "audio": {
        "format": "wav",
        "rate": 16000,
        "bits": 16,
        "channel": 1,
        "language": "zh-CN"
    },
    "request": {
        "reqid": "a3273f8ee3db11e7bf2ff3223ff33638",
        "workflow": "audio_in,resample,partition,vad,fe,decode",
        "sequence": 1,
        "nbest": 1,
        "show_utterances": true
    }
}

3.2.3. 发送 audio only request

Client 发送 full client request 后，再发送包含音频数据的 audio-only client request。音频应采用 full client request 中指定的格式（音频格式、编解码器、采样率、声道）。格式如下：

Payload 是使用指定压缩方法，压缩音频数据后的内容。可以多次发送 audio only request 请求，例如在识别中，如果每次发送 100ms 的音频数据，那么 audio only request 中的 Payload 就是 100ms 的音频数据。

3.2.4 full server response

Client 发送的 full client request 和 audio only request，服务端都会返回 full server response。格式如下：

Payload 内容是包含识别结果的 JSON 格式，字段说明如下：

{
  "reqid": "0ce870af-c0f0-4208-aae7-bd7cdf063567",
  "code": 1000,
  "message": "Success",
  "sequence": -1,
  "result": [
    {
      "text": "这是字节跳动， 今日头条母公司。",
      "utterances": [
        {
          "definite": true,
          "end_time": 1705,
          "start_time": 0,
          "text": "这是字节跳动，",
          "words": [
            {
              "blank_duration": 0,
              "end_time": 860,
              "start_time": 740,
              "text": "这"
            },
            {
              "blank_duration": 0,
              "end_time": 1020,
              "start_time": 860,
              "text": "是"
            },
            {
              "blank_duration": 0,
              "end_time": 1200,
              "start_time": 1020,
              "text": "字"
            },
            {
              "blank_duration": 0,
              "end_time": 1400,
              "start_time": 1200,
              "text": "节"
            },
            {
              "blank_duration": 0,
              "end_time": 1560,
              "start_time": 1400,
              "text": "跳"
            },
            {
              "blank_duration": 0,
              "end_time": 1640,
              "start_time": 1560,
              "text": "动"
            }
          ]
        },
        {
          "definite": true,
          "end_time": 3696,
          "start_time": 2110,
          "text": "今日头条母公司。",
          "words": [
            {
              "blank_duration": 0,
              "end_time": 3070,
              "start_time": 2910,
              "text": "今"
            },
            {
              "blank_duration": 0,
              "end_time": 3230,
              "start_time": 3070,
              "text": "日"
            },
            {
              "blank_duration": 0,
              "end_time": 3390,
              "start_time": 3230,
              "text": "头"
            },
            {
              "blank_duration": 0,
              "end_time": 3550,
              "start_time": 3390,
              "text": "条"
            },
            {
              "blank_duration": 0,
              "end_time": 3670,
              "start_time": 3550,
              "text": "母"
            },
            {
              "blank_duration": 0,
              "end_time": 3696,
              "start_time": 3670,
              "text": "公"
            },
            {
              "blank_duration": 0,
              "end_time": 3696,
              "start_time": 3696,
              "text": "司"
            }
          ]
        }
      ]
    }
  ],
  "addition": {
    "duration": "3696",
    "logid": "20230606120441ECA45EBB4E6A6B036C55"
  }
}

3.2.5. Error message from server

当 server 发现无法解决的二进制/传输协议问题时，将发送 Error message from server 消息（例如，client 以 server 不支持的序列化格式发送消息）。格式如下：

• Header： 3.1.1 描述的 4 字节头。
• Error message code： 错误码，使用大端表示。
• Error message size： 错误信息长度，使用大端表示。
• Error message： 错误信息。

3.2.6. 示例

3.2.6.1. 示例：客户发送 3 个请求

下面的 message flow 会发送多次消息，每个消息都带有版本、header 大小、保留数据。由于每次消息中这些字段值相同，所以有些消息中这些字段省略了。

Message flow:

• client 发送 "Full client request"

  • version: b0001 (4 bits)
  • header size: b0001 (4 bits)
  • message type: b0001 (Full client request) (4bits)
  • message type specific flags: b0000 (none) (4bits)
  • message serialization method: b0001 (JSON) (4 bits)
  • message compression: b0001 (Gzip) (4bits)
  • reserved data: 0x00 (1 byte)
  • payload size = Gzip 压缩后的长度
  • payload: json 格式的请求字段经过 Gzip 压缩后的数据

• server 响应 "Full server response"

  • version: b0001
  • header size: b0001
  • message type: b1001 (Full server response)
  • message type specific flags: b0000 (none)
  • message serialization method: b0001 (JSON 和请求相同)
  • message compression: b0001 (Gzip 和请求相同)
  • reserved data: 0x00
  • payload size = Gzip 压缩后数据的长度
  • payload: Gzip 压缩后的响应数据

• client 发送包含第一包音频数据的 "Audio only client request"

  • version: b0001
  • header size: b0001
  • message type: b0010 (audio only client request)
  • message type specific flags: b0000 (payload 不设置 sequence number)
  • message serialization method: b0000 (none - raw bytes)
  • message compression: b0001 (Gzip)
  • reserved data: 0x00
  • payload size = Gzip 压缩后的音频长度
  • payload: 音频数据经过 Gzip 压缩后的数据

• server 响应 "Full server response"

  • message type: 0b1001 - Full server response
  • message specific flags: 0b0000 (none)
  • message serialization: 0b0001 (JSON, 和请求相同)
  • message compression 0b0001 (Gzip, 和请求相同)
  • reserved data: 0x00
  • payload size = Gzip 压缩后数据的长度
  • payload: Gzip 压缩后的响应数据

• client 发送包含最后一包音频数据（通过 message type specific flags) 的 "Audio-only client request"，

  • message type: b0010 (audio only client request)
  • message type specific flags: b0010 (最后一包音频)
  • message serialization method: b0000 (none - raw bytes)
  • message compression: b0001 (Gzip)
  • reserved data: 0x00
  • payload size = Gzip 压缩后的音频长度
  • payload: Gzip 压缩后的音频数据

• server 响应 "Full server response" - 最终回应及处理结果

  • message type: b1001 (Full server response)
  • message type specific flags: b0000 (none)
  • message serialization method: b0001 (JSON)
  • message compression: b0001 (Gzip)
  • reserved data: 0x00
  • payload size = Gzip 压缩后的 JSON 长度
  • payload: Gzip 压缩后的 JSON 数据

3.3. 错误码

1. 如何返回全部分句或单个分句的结果

默认每次返回所有分句结果。
如果想每次只返回当前分句结果，则设置 show_utterances=true 和 result_type=single；
如果当前分句结果是中间结果，则返回 utterances 中的 definite=false；
如果是分句最终结果，则返回 utterances 中的definite=true。

2. 如何开启 ITN、顺滑、标点

可通过workflow 参数，控制是否开启 ITN，标点或顺滑。
workflow 默认值是 audio_in,resample,partition,vad,fe,decode，只进行识别；
如果要开启 ITN 在 workflow 中增加 "itn"， audio_in,resample,partition,vad,fe,decode,itn；
如果要开启顺滑在 workflow 中增加 "nlu_ddc"，audio_in,resample,partition,vad,fe,decode,nlu_ddc；
如果要开启标点在 workflow 中增加 "nlu_punctuate"， audio_in,resample,partition,vad,fe,decode,nlu_punctuate；
同时开启 itn, 顺滑和标点的 workflow 是 audio_in,resample,partition,vad,fe,decode,itn,nlu_ddc,nlu_punctuate。

Demo 中需要填写 appid、access_token、access_secret、cluster 字段信息，这些信息可以从控制台创建应用开通服务获得。

Python

streaming_asr_demo.py

12.06KB

C++

asr_cpp_demo.tar.gz

142.36MB

JAVA

java_asr_client.tar.gz

24.05KB

Go

asr_go_demo.go

9.31KB