一、产品介绍

基于websocket协议API请求DUI全链路产品，获得对话交互结果

1.1 适用场景

• 轻量级嵌入式设备，基于协议开发
• 采用云对云的方式，使用DUI全链路产品，基于协议开发
• 其他特殊场景，需要基于协议开发
• 支持语音,文本,意图三种输入

1.2 使用限制

需要先前往控制台创建全链路产品，并且将产品成功发布，才能正常使用基于websocket协议的API

二、接入说明

2.1 接入前的准备

• 登录DUI控制台
• 创建全链路产品
• 进行产品配置
• 添加技能
• 进行产品测试
• 配置授权
• 发布产品

2.2 建立websocket连接

本API正式环境的地址是wss://dds.dui.ai/dds/v3/[分支号]，其中[分支号]是DUI控制台分支管理页面的内容。如下图所示

2.2.1连接上需要携带的公共参数

连接上需要携带的授权参数，包含了授权参数，授权有两种场景，一种是设备对接云，一种是云对云；

2.2.2设备对接云端API的授权参数

获取deviceName，需要走设备激活流程。

2.2.3云端对接云端的授权参数

2.2.4一条完整的云端对接云端的连接示例

wss://dds.dui.ai/dds/v3/test?serviceType=websocket&productId=278578090&apikey=0ddddeeeeeeeeeeee88888888260c8ab

2.2.5在以下情况下建立连接会失败

• 产品没有发布
• 产品分支号没有对应已经发布过的产品版本
• 授权参数不正确，服务端鉴权不通过

2.2.6正确建立websocket连接的报文

2.2.7连接上支持用户级鉴权

wss://dds.dui.ai/dds/v3/test?serviceType=websocket&productId=278578090&apikey=0ddddeeeeeeeeeeee88888888260c8ab&accessToken=xxxx

2.3 发送语音请求

websocket连接建立成功之后，调用端首先向服务端发送一个opcode为text的报文；

这个报文的payload是一个json字符串；

2.3.1语音请求text参数

[
    {
        "type": "vocab",
        "name": "行政区",
        "data":["黄浦区"]
    }
]

目前只适用于加速离线一把说这一种场景（2s~5s音频一把送，asrParams.enableOfflineMode:true）
注意在加速完成之后，后续的在线音频流需要调用端保证重新发不含enableOfflineMode参数的start报文

{
    "latitude": 25.79952408587054,
    "longitude":110.92025591449065
}

2.3.2语音请求binary数据

调用端发送完opcode为text的报文之后，接着发送语音数据，opcode为binary, payload是语音数据；

语音数据建议分帧发送，每帧包含的语音时长是100毫秒；

语音数据发送完毕之后，需要再发送一个opcode为binary，payload是空，表示语音数据发送完毕；

2.3.3 全链路语音请求交互时序图

2.4 发送文本请求

2.4.1文本请求参数

{
    "latitude": 25.79952408587054,
    "longitude":110.92025591449065,
	"enablePredict":true, // 开启预测
	"enableTextFilter":true // 开启文本请求拒识
}

text请求报文示例

{
    "topic":"nlu.input.text",
    "recordId":"19557b26631c4c8ca397e685460addfe",
    "refText":"奶牛英文怎么说",
}

2.5 发送触发意图请求

2.5.1触发意图请求参数

{
    "latitude": 25.79952408587054,
    "longitude":110.92025591449065
}

text请求报文示例

{
    "topic":"dm.input.intent"
    "recordId":"f0444b311c900bb18ab54d77deb1edbd",
    "sessionId":"c6e2eb99f0d87a4f27de09908b143132",
    "skill":"新版天气",
    "task":"天气",
    "intent":"天气数据后台获取",
    "slots":[
        {
            "name":"city",
            "value":"深圳",
        }
     ]
}

2.6 发送数据

包含native api查询数据、其他多模态数据

text请求报文示例

{
    "topic":"dm.input.data",
    "recordId":"b187d0a13ada41e8aea631f0475cf981",
    "sessionId":"389691adaa554d63b76d6737130cfd4b",
    "duiWidget":"list",
    "count":5,
    "type":"list",
    "content":[
        {
            "title":"NAERSILING(深圳宝安国际机场T3航站楼)",
            "subTitle":"深圳机场T3航站楼4楼6号门"
        },
        {
            "title":"麦当劳(T3航站楼二店)",
            "subTitle":"机场三道1001号T3航站楼5层"
        },
        {
            "title":"NiCE(深圳宝安国际机场T3航站楼)",
            "subTitle":"宝安国际机场t3航站楼4号门"
        },
        {
            "title":"泡泡玛特门店(深圳机场T3航站楼)",
            "subTitle":"宝安国际机场航站楼3C-04-07号铺"
        },
        {
            "title":"LANCOME(深圳宝安国际机场T3航站楼)",
            "subTitle":"宝安国际机场T3航站楼四楼"
        }
    ]
}

2.7 回复的对话结果（包括触发意图回复结果）

当请求的text报文没有aiType字段时，回复的是对话结果

2.7.1对话结果参数

5dde41305ce0a54ea7a8db3e

list:
"list": [
    {
        "audioUrl":"https:\/\/cdn.caitun.com\/audio\/882eb9fc-23da-4c92-9f87-60acf3cbd80f.mp3",
        "type":"audio"
    },
    {
        "type":"text",
        "text":"狗狗开始睡觉了，你的狗狗活力指数现在为87.10。你的狗狗将在今天13点35分自动醒来。"
        "speakUrl": "https:\/\/dds-ack.dui.ai\/runtime\/v1\/cache\/1360b1e6af7fec84f73118ec4ed78568?productId=278586436"
    }
]

dm.ouput回复示例

{    
    "topic":"dm.output",
    "recordId":"1360b1e6af7fec84f73118ec4ed78568",
    "sessionId":"73ab6db6e09a47b6824088fd81e2c523",
    "contextId":"73ab6db6e09a47b6824088fd81e2c523",
    "skill":"天琴天气",
    "skillId":"2021050600000006"
    "speakUrl":"https:\/\/dds-ack.dui.ai\/runtime\/v1\/cache\/1360b1e6af7fec84f73118ec4ed78568?productId=278586436"
    "dm":{
        "input":"今天天气怎么样",
        "taskId":"5dde41305ce0a54ea7a8db3e",
        "task":"天气"
        "intentId":"617f5dfa08bda80001550cf5",
        "intentName":"天气",
        "shouldEndSession":false,
        "status":0,
        "nlg":"今天深圳市的天气晴，15~23℃，微风，1~2级。"
    }
}

2.7.2对话中间结果（全双工独有）

{
    "dm":{
        "context":{},
        "runSequence":"commandFirst",
        "command":{
            "api":"discardResponse"
			"params":{
				"type":"nluDiscard"					//  如果是 discardResponse，此时标示拒识类型，nluDiscard：语义拒识， asrDiscard:识别拒识，dmDiscard：对话拒识， dmModelDiscard:模型拒识
			}
        },
        "shouldEndSession":false
    },
    "topic":"dm.rt.output",                         //dm.rt.output，表示该消息为全双工对话中的中间反馈消息。
    "recordId":"b56305154f1d4fbc8af90b9b36cbbc90",
    "contextId":"5ce4918ace8c45279b24e0be6c848246",
	"recordList":{},
    "sessionId":"5ce4918ace8c45279b24e0be6c848246"
}

2.8 回复的语义结果

当请求的text报文有aiType字段,并且aiType字段为nlu时，回复的是语义结果

2.8.1语义结果参数

nlu.output回复示例

{
    "topic":"nlu.output",
    "recordId":"283765edd8fcf004d065879ed940c1a9",
    "skillId":"2021050600000006",
    "skill":"天琴天气"
    "nlu":{
        "input":"今天天气怎么样",
        "skillId":"2021050600000006",
        "skill":"天琴天气",
        "skillVersion":"5",
        "semantics":{
            "request":{
                "confidence":1,
                "slots":[
                    {
                        "pos":[
                            0,
                            1
                        ],
                        "value":"20211125",
                        "name":"日期",
                        "rawvalue":"今天",
                        "rawpinyin":"jin tian"
                    },
                    {
                        "value":"天气",
                        "name":"intent"
                    }
                ],
                "slotcount":2,
                "task":"天气"
            }
        }
        
        "version":"2019.1.15.20:40:58",
        "res":"5dde41305ce0a54ea7a8db3e",
        "timestamp":1637825187,
        "loadtime":29.94482421875,
        "inittime":4.20166015625,
        "systime":301.86401367188
    }
} 

2.9 回复的识别结果

当请求的text报文有aiType字段,并且aiType字段为asr时，回复的是识别结果

2.9.1识别结果参数

注：在识别结果实时反馈的情景下，需要使用下述方法获取最终识别结果：

1.使用/dds/v3以下接口时，回复报文中没有topic字段，需要对json报文做如下逻辑：当eof为1并且有text时，这个text不表示最终的识别结果。

调用端需要缓存之前接收的eof为0，并且text不为空的结果，并且把这些text按接收的时间顺序做拼接，取拼接后的字符串作为最终的识别结果。

2.使用/dds/v3及以上接口时，回复报文中一定含有topic字段，调用端的判断逻辑是：当topic == "asr.speech.text" 时，缓存并拼接text字段；当topic == "asr.speech.result"时，此时的text字段表示最终识别结果，此时需要丢弃之前的缓存

 中间识别结果示例

{
    "topic":"asr.speech.text",
    "recordId":"e78a386a37bb8f1ca38c4d43689af5bb",
    "sessionId":"33022982c1324360828802e4bd1728f6"
    "var":"今天 天气",
    "eof":0  
}

最终识别结果示例

{
    "topic":"asr.speech.result",
    "recordId":"728d6b38c2b60fba7364acc21093d8bb",
    "sessionId":"66e14207b8a34386b7103bd8875d8242",
    "text":"今天天气怎么样？",
    "pinyin":"jin tian tian qi zen me yang",
    "eof":1,
    "conf":1,
    "emotion":"sad",
    "age":"adult",
    "gender":"female",
    "emotionScore":5.287,
    "genderScore":3.91,
    "ageScore":7.557
}

识别错误结果示例

{
    "topic":"asr.error",
    "recordId":"18e9d1dd9ebd8c30edcf265ade7ddc23",
    "text":"",
    "eof":1,
    "errId":"010307",
    "errMsg":"asr calc service close socket."
}

2.9.2 声纹结果

当请求参数携带asrPlus，并且开启时，会返回声纹结果，topic为 asrplus.voiceprint.result， 仅表示声纹验证有结果，即有确定的结果，验证出来说话人在和不在给定的用户列表里都属于声纹验证有结果

"100001"

声纹结果示例

{
    "topic":"asrplus.voiceprint.result",
    "recordId":"92750db07cacaa94c4c22567bfa2b4a4",
    "sessionId":"03eb1dcb019341b8a6fe6aeca68afd90",
    "speakerLabels":[
        {
            "bg":240,
            "ed":1520,
            "speakerId":"9527110",
            "rec":"今天 星期天 明天 星期一",
            "errno":0,
            "error":""
        }
    ]
}

2.9.3 声纹错误

当请求参数携带asrPlus，并且开启时，会返回声纹结果，topic为 asrplus.voiceprint.error

声纹错误示例

{
    "topic":"asrplus.voiceprint.error",
    "recordId":"40b1fdd687d95183ecb2b67075f40c9f",
    "error":{
        "errId":"010363",
        "errMsg":"voiceprint server returns errno: 42203, error: 未找到匹配的注册声纹"
    }
}

2.9.4 vad结果

当请求中开启了enableCloudVAD后，服务会返回一条特定的响应，表示云端vad start， 报文如下:

vad结果示例

{
    "topic":"asr.vad.start",
    "recordId":"f05575e1086eec347646aaab36dd3759",
    "sessionId":"0ab50a8e46f04992b3c4c4931efc5e1f",
    "vadState":1
}

2.9.5 一句话识别结果（全双工独有）

当调用端触发vad end通知服务端，或者服务端主动触发vad end后，服务端会返回这条消息

{
    "pinyin":"su zhou de tian qi",
    "recordId":"DUIAUTOTEST-05373b8c933238867924afffc82eb5dc:67efb0a443ef47cd8d2bea58adb8eba8:d92579b6db544f849d58b430f1982ff3",
    "topic":"asr.speech.sentence",
    "sessionId":"da2a433c49494406ad65826f81f560e8",
    "requestId":"d016df6b6151460ea5ba91fa06c7bb34",
    "sentence":"苏州的天气"
}

2.9.6 取消识别

用于调用端在某些场景下，触发vad start之后，又不想关心当前语音交互结果了，此时可以发送取消识别的报文，报文示例如下

{
    "topic": "recorder.stream.cancel",
    "recordId": "f988431eb2f74fbc97aa650b90d40e64"
}

3.0 多模态数据同步请求

3.0.1同步合成音播放状态（全双工要求）

多模态同步接口，上传客户端状态给服务端；新添加 dispatchEvent字段，用于上传事件给中控，而不透传给技能服务，此消息对话中控无回复，报文示例如下

{
    "topic": "dm.context.sync",
    "sessionId":"123456",
	"skillId":"2017112800000011", 
    "async":{
        "dispatchEvent":{           //客户端上传事件给中控，该事件为中控消费，不会传给技能服务；该字段存在时，task，intent，skillid，slots，widget为非必选字段
            "playerState":"off",    //取值范围on/off，分别代表客户端开始／停止 提示音播报, 
									//on上传上来时，同样可以暂停当前会话超时统计，直到下次off上来开始统计
        },
        "task":"导航",
        "intent":"导航",
        "skillId":"2017112800000011",
        "slots":{

        },
        "widget":{

        }
    }
}

3.0.2同步当前对话状态（全双工要求）

多模态同步接口，上传客户端状态给服务端，报文示例如下

{
	"topic": "dm.context.sync",
	"skillId":"2017112800000011",	// 最新的skillId
    "sessionId":"123456",
    "async":{
        "task":"导航",			// 最新的task
        "intent":"导航",			// 最新的意图
		"skill":"xxx",			// 最新的skillName
        "skillId":"2017112800000011",	// 最新的skillId
        "slots":[{                  	// 既往的slots数据
                "name":"目的地",         // 必选         
                "value":"北京",          // 必选
                "rawpinyin":"bei jing", // 可选
                "rawvalue":"北京"        // 可选
            }
		],
        "widget":{
			"type":"xxx",           // 控件类型："text", "content", "list", "media"， "web", "custom"
            "name":"xxx",           // 控件名称,必须有,默认default
            #attributes#,           // 各个控件数据格式抽象，格式见上,格式参考https://wiki.aispeech.com.cn/pages/viewpage.action?pageId=1214998
        }
    }
}

可以一次性同步多个技能上下文，报文示例如下

{
	"topic": "dm.context.sync",
	"skillId":"2017112800000011",	// 最新的skillId
    "sessionId":"123456",	
	"async":[{                 // 多模态特性所需的状态同步, 一次性同步多个上下文 add 20230523 v2，一次性同步多个技能上下文，同时
            "intent":"导航",             // 最新的意图
            "task":"导航",               // 最新的task
            "skill":"xxx",              // 最新的skillName
            "slots":[{                  // 既往的slots数据
                "name":"目的地",         // 必选         
                "value":"北京",          // 必选
                "rawpinyin":"bei jing", // 可选
                "rawvalue":"北京"        // 可选
            }],
            "widget":{                  // 存在控件数据时上传，而且只上传更新后的数据
                "type":"xxx",           // 控件类型："text", "content", "list", "media"， "web", "custom"
                "name":"xxx",           // 控件名称,必须有,默认default
                #attributes#,           // 各个控件数据格式抽象，格式见上
            }
        }
        ,{                 // 多模态特性所需的状态同步, 同dm.context.sync
            "intent":"导航",             // 最新的意图
            "task":"导航",               // 最新的task
            "skill":"xxx",              // 最新的skillName
            "slots":[{                  // 既往的slots数据
                "name":"目的地",         // 必选         
                "value":"北京",          // 必选
                "rawpinyin":"bei jing", // 可选
                "rawvalue":"北京"        // 可选
            }],
            "widget":{                  // 存在控件数据时上传，而且只上传更新后的数据
                "type":"xxx",           // 控件类型："text", "content", "list", "media"， "web", "custom"
                "name":"xxx",           // 控件名称,必须有,默认default
                #attributes#,           // 各个控件数据格式抽象，格式见上
            }
        }]
}

3.0.3同步清除当前上下文状态（全双工独有）

多模态同步接口，清除当前会话上下文，此消息对话中控无回复

{
    "topic": "dm.context.sync",
    "sessionId":"DUIddeeeeeeeeeeee88888888260c8ab",
    "async":{
        "dispatchEvent":{           //客户端上传事件给中控，该事件为中控消费，不会传给技能服务；该字段存在时，task，intent，skillid，slots，widget为非必选字段
 			"endSkillEx":"true",    //取值范围"true"，分别需要清除上下文信息
        }
    }
}

3.0.4同步更新会话超时时间（全双工独有）

多模态同步接口，增加或减少会话超时时间，此消息对话中控无回复

{
    "topic": "dm.context.sync",
    "sessionId":"DUIddeeeeeeeeeeee88888888260c8ab",
    "async":{
        "dispatchEvent":{           //客户端上传事件给中控，该事件为中控消费，不会传给技能服务；该字段存在时，task，intent，skillid，slots，widget为非必选字段
            "updateSessionTimeout":"5000",    //更新会话超时,更新后会话超时重新计时
        }
    }
}

3.1 重新加载连接级参数

在不重建ws连接的前提下，通过topic:connection.reload来完成服务端连接级变量的重置，这种参数的用途是干预后续的请求，如中控和对话使用context.attributes的场景

请求报文示例

{
    "topic":"connection.reload",
    "recordId":"xx",
    "sessionId":"xx",
    "context":{
        "attributes":{
            "key":"value"
        }
    }
}

context字段可以不携带，此时云端的行为是完成连接级变量的重置，如设备级热词，设备级tts发音人等
如果携带context字段，context.attributes下一级的字段是自定义的，云端的行为会merge上一次recorder.stream.start报文中上传的context.attributes,完成请求级参数的重置

下面给出一个merge行为的实际示例

1 调用端在t1时刻上传了recorder.stream.start报文，其中含有context.attributes信息，如下

{
    "context":{
        "attributes":{
            "pictureId":"123"
            "other":"abc"
        }
    }
}

2 调用端在t2时刻上传了connection.reload报文，其中含有context.attributes信息，如下

{
    "context":{
        "attributes":{
            "pictureId":"456"
        }
    }
}

3 dds在t3时刻收到上述报文，在t4时刻收到最终识别结果，此时，dds服务向中控服务传的报文如下

{
    "context":{
        "attributes":{
            "pictureId":"456"
            "other":"abc"
        }
    }
}

回复报文如下

成功

{
    "topic":"connection.reload.result",
    "recordId":"xx",
    "sessionId":"xx"
}

失败

{
    "topic":"connection.reload.result",
    "recordId":"xx",
    "sessionId":"xx",
    "error":{
        "errId":"010107",
        "errMsg":"reload connection context error"
    }
}

在设置失败的情况下会携带error字段

3.2 错误码列表

ps:在调用端可以忽略下述错误码

010105 检测到敏感词
010305 识别结果为空

010400 说法未标注

010403 说法命中退出词

010504 错误重试次数超过限制

010505 命中兜底技能

010507 命中BA技能

080012 本地api调用超时

三、上传配置

3.1上传技能级配置

上传的数据仅在指定的技能中使用，如用户微信是否在登录状态。

3.2上传系统级配置

上传的数据是公用的，有多个技能会关心并使用此类配置。如设备所在位置信息。

3.3 上传配置回复

3.4 指定技能调度黑名单

{
    "topic":"system.settings",
    "recordId":"xxxx",
    "settings":[
        {
            "key":"excludeDispatchSkillList",
            "value":"['skillid1', 'skillid2', 'skillid3']"
        }
    ]
}

3.5 指定技能调度白名单

{
    "topic":"system.settings",
    "recordId":"xxxx",
    "settings":[
        {
            "key":"dispatchSkillList",
            "value":"['skillid1', 'skillid2', 'skillid3']"
        }
    ]
}

四、特定的使用场景

4.1 半双工场景下使用云端vad的要求

• 接收线程收到topic:asr.error后，要通知发送线程返回start状态，重新发送text报文
• 接收线程收到topic:dm.output后，要通知发送线程返回start状态，重新发送text报文
• 接收线程/协程收到topic:dm.output，并且结果中有shouldEndSession:true，此时表示多轮对话结束，要通知发送线程返回init状态，等待下一次唤醒