Server 接入

一、产品介绍

语音识别API,是将录音转为相应的文字的服务。

1.1 适用场景

可适用于语音听写,语音输入法,游戏娱乐,人机交互,智能客服等场景。

1.2 使用限制

需要先前往控制台进行授权操作,才能正常使用在线语音识别。

二、接入说明

2.1 接入步骤

2.1.1 创建语音识别产品

前往控制台产品模块,创建基础技术语音识别产品。

2.1.2 完成产品授权

授权操作详见:配置授权

完成授权后,还需要在控制台上发布产品。

2.1.3 接入在线语音识别API

按照识别接口请求说明和示例完成接入操作。

2.2 API服务地址

在线语音识别的API服务地址为:asr.dui.ai

2.3 请求参数

2.3.1 参数说明

参数名 类型 含义 是否必需 取值示例
context Map      
  productId String 产品id,来自于console的产品发布 必选 -
  userId String uuid,用户的唯一标识 可选 -
  deviceName String uuid,设备的唯一标识,同IoT Device Name授权服务里的deviceName 可选 -
  sdkName String sdk名称 可选 -
request Map      
  requestId String uuid,请求的唯一标识 必选 -
  audio Map      
    audioType String 音频类型 必选 ogg/wav
    sampleRate Integer 采样率 必选 16000
    channel Integer 声道 必选 1
    sampleBytes Integer 采样点精度 必选 2
  asr Map      
    wakeupWord String 当前请求的唤醒词,oneshot使用场景下必须带 可选 你好小驰
    enableRealTimeFeedback Bool 控制启用识别结果实时返回,默认关闭 可选 true/false
    enableVAD Bool 控制启用云端VAD(建议远场识别场景中关闭云端VAD),默认启用 可选 true/false
    enablePunctuation Bool 控制启用结果带标点符号,默认关闭 可选 true/false
   
enableTone
Bool 是否使用拼音带声调 可选 true/false
    language String 指定语种,默认中文 可选 zh-CN
    res String 指定选择何种解决方案 可选 comm/airobot/aihome/aicar
    lmId String 定制语言模型的模型id,来自于语言模型训练服务 可选 -
   
lmList
array 用户定制的语言模型列表 可选 ["1234","abcd"]
   

phraseHints

array

热词识别

可选

[{"type": "vocab", "name": "词库名", "data":["短语1", "短语2"]}]

   

enableNumberConvert

Bool

数字转换, 默认关闭, true开启

可选

true/false

   

enableLanguageClassifier

Bool

语言分类, 默认关闭, true开启

可选

true/false

   

enableSNTime

Bool

rec结果增加时间对齐信息,env参数use_sn_time控制该功能开关,默认关闭

可选

true/false

   

enableConfidence

Bool

置信度

可选

true/false

   

selfCustomWakeupScore

Integer 自定义唤醒词自定义分数 可选 100
    enableEmotion Bool 开启情感识别 可选 true/false
   

enableAudioDetection

Bool

音频检测的功能,该功能主要用于辅助拒识本地误上传的噪声片段,当返回的audio_detection=0时,本地客户端可以忽略这个识别结果,而继续监听,减少交互过程被噪声打断的概率。

可选 true/false

 

2.3.2 REST API

请求格式

POST /runtime/v2/recognize?language=zh-CN&res=comm&productId=xxx HTTP/1.1 
// qurery string里带一些重复的用于调度的参数
Host: asr.dui.ai
Content-Type: multipart/form-data; boundary=b0123456789;
Content-Length: N
--b0123456789
Content-Disposition: form-data; name="params"
 
{
    "context": {
        "productId": "p001", // 必选
        "userId": "u003",    // 可选
        "deviceName": "d002",  // 可选, 同IoT Device Name授权服务里的deviceName
        "sdkName": "dui-asr-android-sdk-6.1" // 可选
    },
    "request": {
        "requestId": "request-id-in-uuid", // 必选
        "audio": {
            "audioType": "wav", // 必选
            "sampleRate": 16000, // 必选
            "channel": 1, // 必选
            "sampleBytes": 2 // 必选
                    },
        "asr": {
            "wakeupWord": "你好小驰", // 可选;当前请求的唤醒词
            "enableRealTimeFeedback": true, //可选;启用结果实时返回
            "enableVAD": true, //可选;启用云端VAD
            "enablePunctuation": true, //可选;启用结果带标点符号
            "language": "zh-CN", //可选; 指定语种
            "res": "comm", //可选;指定选择何种解决方案 [comm, airobot, aihome, aicar]
            "lmId": "custom-lm-id", // 可选, 定制语言模型的模型id
         
        }
    }
}
 
--b0123456789
Content-Disposition: form-data; name="audio"; filename="audio.name"
Content-Type: application/octet-stream
 
content of audio.bin
 
--b0123456789--

2.3.3 WebSocket Protocol

wss://asr.dui.ai/runtime/v2/recognize?language=zh-CN&res=comm&productId=xxx HTTP/1.1 // qurery string里带一些重复的用于调度的参数


建立连接
客户端在和服务端完成websocket协议握手后,向服务端发送一个GET请求,uri是/runtime/v2/recognize, 授权参数在query string中携带; 授权如果不通过,服务端会回复授权不通过的信息, 并且关闭连接。


客户端发送语音请求
在客户端和服务端建立websocket连接后,客户端发送语音请求,首先向服务端发送一个opcode为text的报文,这个报文的payload是一个 json 字符串,示例如下:

{
    "context": {
        "productId": "p001", // 必选
        "userId": "u003",    // 可选
        "deviceName": "d002",  // 可选, 同IoT Device Name授权服务里的deviceName
        "sdkName": "dui-asr-android-sdk-6.1" // 可选
    },
    "request": {
        "requestId": "request-id-in-uuid", // 必选
        "audio": {
            "audioType": "wav", // 必选,建议压缩,格式上支持ogg, wav,mp3,flv,amr
            "sampleRate": 16000, // 必选
            "channel": 1, // 必选
            "sampleBytes": 2 // 必选
                   },
        "asr": {
            "wakeupWord": "你好小驰", // 可选;当前请求的唤醒词
            "enableRealTimeFeedback": true, //可选;启用结果实时返回
            "enableVAD": true, //可选;启用云端VAD
            "enablePunctuation": true, //可选;启用结果带标点符号
            "language": "zh-CN", //可选; 指定语种
            "res": "comm", //可选;指定选择何种解决方案 [comm, airobot, aihome, aicar]
            "lmId": "custom-lm-id", // 可选, 定制语言模型的模型id
                 }
    }
}

然后,客户端向服务端发送语音数据,opcode为binary, 这个报文的payload是语音数据,关建议分帧发送语音数据,每帧语音数据包含100毫秒时间长度的语音。

客户端向服务端发送一个报文表示语音数据发送完毕,这个报文的opcode为binary, payload是空。至此,客户端发送语音请求结束。

2.4 返回结果

2.4.1 参数说明

参数名 类型 说明 取值
eof integer 返回结果是否为最终结果 0: 实时反馈结果, 1: 最后的结果
result Map    
  rec String 不会更改的识别结果 -
  var String 可能会做纠正的识别结果 -

2.4.2 正确返回

1)REST API

{
    "requestId": "request-id-in-uuid",
    "eof": 0, // 0: 实时反馈结果, 1: 最后的结果
    "result": {
       "rec": "导航去香山",   // 已经确定的识别结果, 不重复
       "var": "吧", // 可变识别结果, 这部分不是最终的结果, 可能会变
      
           }
}

注意:在识别结果实时反馈的情景下,当eof为1并且有rec时,这个rec不是表示最终的识别结果。客户端需要缓存之前接收的eof为0,并且rec不为空的结果,并且把这些rec按接收的时间顺序做拼接,取拼接后的字符串作为最终的识别结果。

2)WebSocket Protocol

{
    "requestId": "request-id-in-uuid",
    "eof": 0, // 0: 实时反馈结果, 1: 最后的结果
    "result": {
       "rec": "导航去香山",   // 已经确定的识别结果, 不重复
       "var": "吧", // 可变识别结果, 这部分不是最终的结果, 可能会变
    }
}

2.4.3 错误返回

http code  非200

2.4.4 错误码描述

error ID 错误描述 原因及解决办法
401 需要鉴权 参数错误

2.5 服务示例

2.5.1 Java_基于http协议

点此查看示例

2.5.2 Java_基于websocket协议

点此查看示例

2.5.3 asr在线识别curl命令_基于http协议

curl -H 'Content-Type: multipart/form-data' -F 'params={"context":{"productId": "x","userId":"x","deviceName":"x","sdkName":"x"},"request":{"requestId":"x","audio":{"audioType":"ogg","sampleRate":16000,"channel":1,"sampleBytes":2},"asr":{"res":"comm"}}}' -F "file=@filePath" "https://asr.dui.ai/runtime/v2/recognize?productId=x&apikey=x&res=comm"

2.5.4 Python_基于websocket协议

#!/usr/bin/env python
# coding=utf-8
### websocket模块https://pypi.python.org/pypi/websocket-client
### oggfile是一个speex压缩的ogg文件,文件格式是Ogg data, Speex audio
import websocket
from websocket import ABNF
import time
import thread
import json
import ssl
import uuid
product_id = 'x' #填入产品Id
apikey = 'x' #填入apikey
url = 'ws://asr.dui.ai/runtime/v2/recognize?productId='+product_id+'&apikey='+apikey
oggfile = 'x' #ogg文件的绝对路径
def on_message(ws, message):
    print 'Message>>>>>>>>>>>>>>>>>>>>>>>>'
    print message
    print 'Message<<<<<<<<<<<<<<<<<<<<<<<<'
    ws.close()
def on_error(ws, error):
    print 'error>>>>>>>>>>>>>>>>>>>>>>'
    print error
    print 'error<<<<<<<<<<<<<<<<<<<<<<'
  
def on_close(ws):
    print "### closed ###"
  
def on_open(ws):
    def run(*args):
        content = {
            "context": {
                "productId":product_id,
                "userId": "x",
                "deviceName": "x",
                "sdkName": "x"
            },
            "request": {
                "requestId": str(uuid.uuid1()).replace('-',''),
                "audio": {
                    "audioType": "ogg",
                    "sampleBytes": 2,
                    "sampleRate": 16000,
                    "channel": 1,
                    "compress": "raw"
                },
                "asr":{
                    "enableVAD": True,
                    "enableRealTimeFeedback": False
                }
            }
        }
        ws.send(json.dumps(content))
        step = 400 #如果audioType是wav,此处需要修改为3200
        with open(oggfile, 'rb') as f:
            while True:
                data = f.read(step)
                if data:
                    ws.send(data, ABNF.OPCODE_BINARY)
                if len(data) < step:
                    break
                time.sleep(0.1)
        ws.send('', ABNF.OPCODE_BINARY)
        #print "thread terminating..."
    thread.start_new_thread(run, ())
if __name__ == "__main__":
    ws = websocket.WebSocketApp(url, on_message = on_message,
    on_error = on_error, on_close = on_close)
    ws.on_open = on_open
    ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})

2.6 注意事项

接入在线语音识别服务需要注意以下内容:
1)不支持识别合成音;
2)只支持单声道、16k采样率、一个采样点大小是2个字节的音频文件;
3)ogg音频文件不支持ogg vorbis,只支持ogg speex;
4)基于http协议的识别请求,不支持识别结果实时返回,不支持识别结果中间带标点符号
5) Java项目基于Maven构建,Http和WebSocket实现主类都基于BasicClient类,项目依赖在pom.xml中体现。