更新时间:2022-04-26 GMT+08:00
分享

websocket接口

功能介绍

一句话识别websocket接口支持识别1min以内的音频,交互过程如图 客户端和服务端交互流程所示,主要分为开始识别、发送音频数据,结束识别、断开连接四个步骤。

websocket接口同http接口一致按次计费,只要建立连接成功,发送音频,服务开始识别,则本次调用计费生效。如果用户发送错误end请求或者持续20s未发送音频而产生了报错,该次调用依然认为生效。如果连接成功后未发送音频直接断开,或者请求字段不正确而产生异常,则认为本次调用无效,不会纳入计费次数。

图1 客户端和服务端交互流程

wss-URI

  • wss-URI格式

    wss /v1/{project_id}/asr/short-audio

  • 参数说明
    表1 参数说明

    参数名

    是否必选

    说明

    project_id

    项目编号。获取方法,请参见获取项目ID

开始识别

  • 功能介绍

    当wss握手请求收到成功响应后,客户端到服务端的通信协议会升级为Websocket协议。通过Websocket协议,客户端发送开始识别请求,用于配置一句话识别的配置信息。

  • 请求消息
    表2 参数说明

    参数名

    是否必选

    参数类型

    说明

    command

    String

    需设置为START,表示开始识别请求。

    config

    Object

    配置信息。结构信息请参见表 config数据结构

    表3 config数据结构

    参数

    是否必选

    参数类型

    说明

    audio_format

    String

    支持语音的格式,请参见表 audio_format取值范围

    property

    String

    所使用的模型特征串。通常是 “语种_采样率_领域”的形式,例如chinese_8k_common。请参见表 property取值范围

    add_punc

    String

    表示是否在识别结果中添加标点,取值为yes 、 no,默认no。

    digit_norm

    String

    表示是否将语音中的数字识别为阿拉伯数字,取值为yes 、 no,默认为yes。

    interim_results

    String

    是否输出中间结果,可以为yes或no。默认为no,表示不输出中间结果。

    vocabulary_id

    String

    热词表id,不使用热词则不填写。

    创建热词表信息请参考创建热词表

    need_word_info

    String

    表示是否在识别结果中输出分词结果信息,取值为“yes”“no”,默认为“no”

    表4 property取值范围

    property取值

    说明

    chinese_8k_common

    支持采样率为8k的中文普通话语音识别。

    chinese_16k_common

    支持采样率为16k的中文普通话语音识别。

    sichuan_16k_common

    支持采样率为16k的中文普通话与四川话方言语音识别。区域仅支持cn-north-4。

    cantonese_16k_common

    支持采样率为16k的粤语方言语音识别。区域仅支持cn-north-4。

    shanghai_16k_common

    支持采样率为16k的上海话方言语音识别。区域仅支持cn-north-4。

    表5 audio_format取值范围

    audio_format取值

    说明

    pcm16k16bit

    16k16bit单通道录音数据。

    pcm8k16bit

    8k16bit单通道录音数据。

    ulaw16k8bit

    16k8bit ulaw单通道录音数据。

    ulaw8k8bit

    8k8bit ulaw单通道录音数据。

    alaw16k8bit

    16k8bit alaw单通道录音数据。

    alaw8k8bit

    8k8bit alaw单通道录音数据。

    目前仅支持裸音频格式,仅支持pcm编码的wav格式,不支其他wav头或者arm格式的编码。

  • 示例
    {
      "command": "START",
      "config":
      {
        "audio_format": "pcm8k16bit",
        "property": "chinese_8k_common",
        "add_punc": "yes",
        "interim_results": "yes",
        "need_word_info": "yes"
      }
    }
  • 状态码

    状态码请参见状态码

  • 错误码

    错误码请参见错误码

发送音频数据

在收到“开始识别”的响应之后,可以开始发送音频数据。为节省流量,音频以二进制数据帧形式(binary message)的方式发送。

音频数据将分片发送,也即在获得一定量音频数据的同时就可以发送一个binary message,每个分片建议在50ms~1000ms之间,建议在需要实时反馈的情况下100ms,不需要实时反馈的情况下500ms。

结束识别

  • 功能介绍

    对于识别中的对话,需要在Websocket上发送“结束识别”的请求来取消或结束识别。 "结束识别"请求使用文本类型的数据帧(text message)发送,命令和参数以json字符串的形式提供。

  • 请求消息
    表6 参数说明

    参数名

    是否必选

    参数类型

    说明

    command

    String

    设置为END,表示结束识别请求。

  • 示例
    {
      "command": "END"
    }
  • 状态码

    状态码请参见状态码

  • 错误码

错误码请参见错误码

响应结果

  • 开始识别响应
    由于WebSocket是全双工的,因此响应就是从服务器端发送给客户端的消息,但也并不是所有的请求信息都有一条对应的响应。服务器端收到“开始识别”请求时,会给出如下响应消息,以json字符串形式放置在text message中。
    表7 响应参数

    参数名

    参数类型

    说明

    resp_type

    String

    参数值为START,表示开始识别响应。

    trace_id

    String

    服务内部的令牌,可用于在日志中追溯具体流程。

    示例

    {
        "resp_type": "START",
        "trace_id": "567e8537-a89c-13c3-a882-826321939651"
    }
  • 事件响应

    服务器端检测到某些事件时,会给出如下响应消息,以json字符串形式放置在text message中。

    表8 响应参数

    参数名

    参数类型

    说明

    resp_type

    String

    参数值为EVENT,表示开始识别响应。

    trace_id

    String

    服务内部的令牌,可用于在日志中追溯具体流程。

    event

    String

    具体的事件,一句话识别中仅会出现"EXCEEDED_AUDIO”,当输入音频超过1min时,会返回该事件。

    timestamp

    Integer

    保留字段。将来会用于此事件发生的具体时间,以会话开始作为0点,单位为ms。

    示例

    {
      "resp_type": "EVENT",
      "trace_id": "567e8537-a89c-13c3-a882-826321939651",
      "event": "EXCEEDED_AUDIO",
      "timestamp": 1500
    }
  • 结果响应

    服务端在收到客户端发送的连续音频数据后, 当服务端识别出结果后会实时向客户端按句推送识别结果响应消息, 以json字符串形式放置在text message中。

    表9 响应参数

    参数名

    参数类型

    说明

    resp_type

    String

    参数值为RESULT,表示识别结果响应。

    trace_id

    String

    服务内部的令牌,可用于在日志中追溯具体流程。

    segments

    Array of objects

    多句结果。

    请参考表 segment 数据结构

    表10 segment 数据结构

    参数名

    参数类型

    说明

    start_time

    Integer

    一句的起始时间戳,单位为ms。

    end_time

    Integer

    一句的结束时间戳,单位为ms。

    is_final

    Boolen

    true表示是最终结果, false表示为中间临时结果。

    result

    Object

    调用成功表示识别结果,调用失败时无此字段。

    请参考表 result数据结构

    表11 result数据结构

    参数名

    参数类型

    说明

    text

    String

    识别结果。

    score

    Float

    识别结果的置信度,取值范围:0~1。此值仅会在最终结果时被赋值,在中间结果时统一置为“0.0”

    说明:

    目前置信度作用不是太大,请勿过多依赖此值。

    word_info

    Array of Object

    分词输出列表。

    表12 word_info 数据结构

    参数名

    是否必选

    参数类型

    说明

    start_time

    Integer

    起始时间

    end_time

    Integer

    结束时间

    word

    String

    分词

    示例

    {
      "resp_type": "RESULT",
      "trace_id": "567e8537-a89c-13c3-a882-826321939651",
      "segments":
      [
        {
          "start_time": 100,
          "end_time": 1500,
          "is_final": false,
          "result":
          {
            "text": "第一句中间结果",    
            "word_info": [
                         {
                            "start_time": 100,
                            "end_time": 800,
                            "word": "第一"
                        },
                        {
                            "start_time": 800,
                            "end_time": 1000,
                            "word": "句"
                        },
                        {
                            "start_time": 1000,
                             "end_time": 1500,
                             "word": "结果"
                        }
                    ],
             "score": 0.0
          },
        },
      ]
    }
  • 错误响应

    错误响应,包括如下情况:

    • 配置串错误,包括存在不识别的配置串,或者配置串值的范围不合法。
    • 时序不正确,比如连续发送两次“开始识别”指令。
    • 识别过程中发生错误,比如音频解码发生错误。

    表13 响应参数

    参数名

    参数类型

    说明

    resp_type

    String

    参数值为ERROR,表示错误响应。

    trace_id

    String

    服务内部的跟踪令牌,可用于在日志中追溯具体流程。

    在某些错误情况下,可能没有此字段。

    error_code

    String

    错误码列表。详细错误码解释,请参见错误码

    error_msg

    String

    返回错误信息。

    示例

    {
        "resp_type": "ERROR",
        "trace_id": "567e8537-a89c-13c3-a882-826321939651",
        "error_code": "SIS.0002",
        "error_msg": "***"
    }
  • 结束识别响应

    服务器端收到“结束识别”请求时或语音识别过程中发生错误,服务端会向客户端推送如下响应消息,以json字符串形式放置在text message中。

    表14 响应参数

    参数名

    参数类型

    说明

    resp_type

    String

    参数值为END,表示结束识别响应。

    trace_id

    String

    服务内部的令牌,可用于在日志中追溯具体流程。

    reason

    String

    结束原因,详情请参见表 结束原因表

    表15 结束原因表

    参数名

    说明

    NORMAL

    正常结束。

    ERROR

    识别过程中发生错误。

    示例

    {
        "resp_type": "END",
        "trace_id": "567e8537-a89c-13c3-a882-826321939651",
        "reason": "NORMAL",
    }

代码示例

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.WebSocket;
import okhttp3.WebSocketListener;
import okio.ByteString;

/**
 * 此demo仅供测试使用,强烈建议使用SDK
 * 使用前需已配置okhttp、okio jar包。jar包可通过下载SDK获取。
 */
public class SasrWebsocketDemo {
  public void sasrWebsocketDemo() {
    try {
      // endpoint和projectId需要替换成实际信息。
      String url = "wss://{{endpoint}}/v1/{{project_id}}/asr/short-audio";
      String token = "对应region的token";
      byte[] data = null;  // 存放将要发送音频的byte数组
      OkHttpClient okHttpClient = new OkHttpClient();
      Request request = new Request.Builder().url(url).header("X-Auth-Token", token).build();
      WebSocket webSocket = okHttpClient.newWebSocket(request, new MyListener());
      webSocket.send("{\"command\": \"START\", \"config\": {\"audio_format\": \"pcm8k16bit\", \"property\": \"chinese_8k_common\"}}");
      webSocket.send(ByteString.of(data));  // audio太大注意要分片发送,否则会报错。建议分片大小3200
      webSocket.send("{  \"command\": \"END\"}");
      Thread.sleep(10000);
      webSocket.close(1000, null);

    } catch (Exception e) {
      e.printStackTrace();
    }

  }

  class MyListener extends WebSocketListener {
    @Override

    public void onOpen(WebSocket webSocket, Response response) {
      System.out.println("conneected");
    }

    @Override
    public void onClosed(WebSocket webSocket, int code, String reason) {

      System.out.println("closed");
    }

    @Override
    public void onFailure(WebSocket webSocket, Throwable t, Response response) {
      t.printStackTrace();
    }

    @Override
    public void onMessage(WebSocket webSocket, String text) {
      System.out.println(text);
    }

  }

  public static void main(String[] args) {
    SasrWebsocketDemo sasrWebsocketDemo = new SasrWebsocketDemo();
    sasrWebsocketDemo.sasrWebsocketDemo();
  }
}

分享:

    相关文档

    相关产品

close