全部产品
云市场
云游戏

接口说明

更新时间:2020-09-28 13:56:06

对长时间的语音数据流进行识别,适用于会议演讲、视频直播等长时间不间断识别的场景。

功能简介

NUI SDK提供更小的工具包和更完善的状态管理。为满足不同用户需求,NUI SDK既能提供全链路的语音能力,同时可做原子能力SDK进行使用,并保持接口的统一。

使用须知

  • 输入格式:PCM编码、16bit采样位数、单声道(mono)。

  • 音频采样率:8000Hz/16000Hz。

  • 设置返回结果:是否返回中间识别结果、在后处理中添加标点、将中文数字转为阿拉伯数字输出。

  • 设置多语言识别:在管控台编辑项目中进行模型选择,详情请参见模型选择

服务地址

访问类型

说明

URL

外网访问

所有服务器均可使用外网访问URL(SDK中默认设置了外网访问URL)。

wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1

上海ECS内网访问

使用阿里云上海ECS(ECS地域为华东2(上海)),可使用内网访问URL。 ECS的经典网络不能访问AnyTunnel,即不能在内网访问语音服务;如果希望使用AnyTunnel,需要创建专有网络在其内部访问。

说明

  • 使用内网访问方式,将不产生ECS实例的公网流量费用。

ws://nls-gateway.cn-shanghai-internal.aliyuncs.com:80/ws/v1

交互流程

实时语音识别交互流程

说明

所有服务端的响应都会在返回信息的header包含表示本次识别任务的task_id参数,请记录该值,如果出现错误,请将task_id和错误信息提交到工单。

1. 鉴权和初始化

客户端在与服务端建立WebSocket连接时,使用Token进行鉴权。关于Token获取请参见获取Token

初始化参数如下。

参数

类型

是否必选

说明

workspace

String

工作目录路径,SDK从该路径读取配置文件。

app_key

String

管控台创建项目的appkey。

token

String

请确保该Token可以使用并在有效期内。

说明

Token可以在初始化时设置,也可通过参数设置进行更新。

device_id

String

设备标识,唯一表示一台设备(如Mac地址/SN/UniquePsuedoID)。

debug_path

String

debug目录。当初始化SDK时的save_log参数取值为true时,该目录用于保存中间音频文件。

save_wav

String

当初始化SDK时的save_log参数取值为true时,该参数生效。表示是否保存音频debug,该数据保存在debug目录中,需要确保debug_path有效可写。

2. 开始识别

客户端发起实时语音识别请求前需要进行参数设置,各参数由SDK中setParams接口以JSON格式设置,该参数设置一次即可。各参数含义如下。

参数

类型

是否必选

说明

appkey

String

管控台创建的项目appkey,一般在初始化时设置。

token

String

如果需要更新,则进行设置。

service_type

Int

需要请求的语音服务类型,实时语音识别为“4”。

direct_ip

String

支持客户端自行DNS解析后传入IP进行访问。

nls_config

JsonObject

访问语音服务相关的参数配置,详情请参见下表。

参数nls_config配置如下。

参数

类型

是否必选

说明

sr_format

String

音频编码格式,支持OPUS编码和PCM原始音频。默认值:OPUS。

说明

如果使用8000Hz采样率,则只支持PCM格式。

sample_rate

Integer

音频采样率,默认值:16000Hz。根据音频采样率在管控台对应项目中配置支持该采样率及场景的模型。

enable_intermediate_result

Boolean

是否返回中间识别结果,默认值:False。

enable_punctuation_prediction

Boolean

是否在后处理中添加标点,默认值:False。

enable_inverse_text_normalization

Boolean

是否在后处理中执行ITN。设置为true时,中文数字将转为阿拉伯数字输出,默认值:False。

说明

不会对词信息进行ITN转换。

customization_id

String

自学习模型ID。

vocabulary_id

String

定制泛热词ID。

max_sentence_silence

Integer

语音断句检测阈值,静音时长超过该阈值被认为断句。取值范围:200ms~2000ms,默认值:800ms。

enable_words

Boolean

是否开启返回词信息。默认值:False。

enable_ignore_sentence_timeout

Boolean

是否忽略实时识别中的单句识别超时。默认值:False。

disfluency

Boolean

是否对识别文本进行顺滑(去除语气词、重复说等)。默认值:False。

vad_model

String

设置服务端的vad模型id,默认无需设置。

speech_noise_threshold

float

噪音参数阈值,取值范围:-1~+1。

  • 取值越接近-1,判定为语音的概率越大,亦即有可能更多噪声被当作语音被误识别。

  • 取值越接近+1,判定为噪音的越多,亦即有可能更多语音被当作噪音被拒绝掉。

说明

该参数属高级参数,调整需谨慎并进行重点测试。

3. 发送数据

客户端循环发送语音数据,持续接收识别结果:

  • EVENT_SENTENCE_START事件表示服务端检测到了一句话的开始。实时语音识别服务的智能断句功能会判断出一句话的开始与结束,如:

    {
        "header": {
            "namespace": "SpeechTranscriber",
            "name": "SentenceBegin",
            "status": 20000000,
            "message_id": "a426f3d4618447519c9d85d1a0d1****",
            "task_id": "5ec521b5aa104e3abccf3d361822****",
            "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
            "index": 1,
            "time": 0
        }
    }

    header对象参数说明:

    参数

    类型

    说明

    namespace

    String

    消息所属的命名空间。

    name

    String

    消息名称。SentenceBegin表示一个句子的开始。

    status

    Integer

    状态码。表示请求是否成功,参见错误码

    message_id

    String

    本次消息的ID,由SDK自动生成。

    task_id

    String

    任务全局唯一ID,请记录该值,便于排查问题。

    status_text

    String

    状态消息。

    payload对象参数说明:

    参数

    类型

    说明

    index

    Integer

    句子编号,从1开始递增。

    time

    Integer

    当前已处理的音频时长,单位:毫秒。

  • 若enable_intermediate_result设置为true,SDK会持续多次通过onNuiEventCallback回调上报EVENT_ASR_PARTIAL_RESULT事件,即中间识别结果,如:

    {
        "header": {
            "namespace": "SpeechTranscriber",
            "name": "TranscriptionResultChanged",
            "status": 20000000,
            "message_id": "dc21193fada84380a3b6137875ab****",
            "task_id": "5ec521b5aa104e3abccf3d361822****",
            "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
            "index": 1,
            "time": 1835,
            "result": "北京的天",
            "confidence": 1.0,
            "words": [{
                "text": "北京",
                "startTime": 630,
                "endTime": 930
            }, {
                "text": "的",
                "startTime": 930,
                "endTime": 1110
            }, {
                "text": "天",
                "startTime": 1110,
                "endTime": 1140
            }]
        }
    }
    说明

    header对象中name参数取值为TranscriptionResultChanged表示句子的中间识别结果。其余参数说明参见上述表格。

    payload对象参数说明:

    参数

    类型

    说明

    index

    Integer

    句子编号,从1开始递增。

    time

    Integer

    当前已处理的音频时长,单位:毫秒。

    result

    String

    当前句子的识别结果。

    words

    List< Word >

    当前句子的词信息,需要将enable_words设置为true。

    confidence

    Double

    当前句子识别结果的置信度,取值范围0.0~1.0,值越大表示置信度越高。

  • EVENT_SENTENCE_END事件表示服务端检测到了一句话的结束,并返回该句话的识别结果,如:

    {
        "header": {
            "namespace": "SpeechTranscriber",
            "name": "SentenceEnd",
            "status": 20000000,
            "message_id": "c3a9ae4b231649d5ae05d4af36fd****",
            "task_id": "5ec521b5aa104e3abccf3d361822****",
            "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
            "index": 1,
            "time": 1820,
            "begin_time": 0,
            "result": "北京的天气。",
            "confidence": 1.0,
            "words": [{
                "text": "北京",
                "startTime": 630,
                "endTime": 930
            }, {
                "text": "的",
                "startTime": 930,
                "endTime": 1110
            }, {
                "text": "天气",
                "startTime": 1110,
                "endTime": 1380
            }]
        }
    }
    说明

    header对象中name参数取值为SentenceEnd表示句子识别结束。其余参数说明参见上述表格。

    payload对象参数说明:

    参数

    类型

    说明

    index

    Integer

    句子编号,从1开始递增。

    time

    Integer

    当前已处理的音频时长,单位:毫秒。

    begin_time

    Integer

    当前句子对应的SentenceBegin事件的时间,单位:毫秒。

    result

    String

    当前句子的识别结果。

    words

    List< Word >

    当前句子的词信息,需要将enable_words设置为true。

    confidence

    Double

    当前句子识别结果的置信度,取值范围0.0~1.0,值越大表示置信度越高。

    其中,Word对象:

    参数

    类型

    说明

    text

    String

    文本。

    startTime

    Integer

    词开始时间,单位:毫秒。

    endTime

    Integer

    词结束时间,单位:毫秒。

4. 结束识别

客户端通知服务端语音数据发送完毕,服务端识别结束后通知客户端识别完毕。

错误码

实时语音识别的错误码信息,请参见错误码