# AIUI 语义协议
# 消息格式概览
交互返回协议为JSON格式,一个典型示例如下:
{
"data": {
"result": [
{
"airData": 35,
"airQuality": "优",
"city": "北京",
"date": "2018-02-07",
"dateLong": 1517932800,
"exp": {
"ct": {
"expName": "穿衣指数",
"level": "冷",
"prompt": "天气冷,建议着棉服、羽绒服、皮夹克加羊毛衫等冬季服装。年老体弱者宜着厚棉衣、冬大衣或厚羽绒服。"
}
},
"humidity": "16%",
"lastUpdateTime": "2018-02-07 11:00",
"pm25": "9",
"temp": 1,
"tempRange": "-9℃ ~ 2℃",
"weather": "多云转晴",
"weatherType": 1,
"wind": "北风4-5级",
"windLevel": 2
}
]
},
"rc": 0,
"semantic": [
{
"intent": "QUERY",
"slots": [
{
"name": "datetime",
"value": "今天",
"normValue": "{\"datetime\":\"2018-02-07\",\"suggestDatetime\":\"2018-02-07\"}"
},
{
"name": "location.city",
"value": "北京市",
"normValue": "北京市"
},
{
"name": "subfocus",
"value": "天气状态"
}
]
}
],
"service": "weather",
"state": {
"fg::weather::default::default": {
"state": "default"
}
},
"text": "查看北京今天的天气",
"uuid": "atn00d35cc3@ch13c70dd605786f1d01",
"shouldEndSession": "true",
"used_state": {
"state_key": "fg::weather::default::default",
"state": "default"
},
"answer": {
"text": "\"北京今天多云转晴\",\"-9℃ ~ 2℃\",\"北风4-5级\""
},
"dialog_stat": "DataValid",
"save_history": true,
"sid": "atn00d35cc3@ch13c70dd605786f1d01"
}
# 应答消息字段定义
字段名称 | 字段类型 | 是否必须 | 说明 |
---|---|---|---|
rc | int | 是 | 应答码(response code) |
error | Object | 否 | 错误信息 |
text | String | 是 | 用户的输入,可能和请求中的原始text不完全一致,因服务器可能会对text进行语言纠错 |
vendor | String | 否 | 技能提供者,不存在时默认表示为IFLYTEK提供的开放技能 |
service | String | 是 | 技能的全局唯一名称,一般为vendor.name,vendor不存在时默认为IFLYTEK提供的开放技能。 |
semantic | Object | 否 | 本次语义(包括历史继承过来的语义)结构化表示,各技能自定义 |
data | Object | 否 | 数据结构化表示,各技能自定义 |
answer | Object | 否 | 对结果内容的最简化文本/图片描述,各技能自定义 |
dialog_stat | String | 否 | 用于客户端判断是否使用信源返回数据 |
moreResults | Object | 否 | 在存在多个候选结果时,用于提供更多的结果描述 |
shouldEndSession | Boolean | 否 | 当该字段为空或为 true 时表示技能已完成一次对话,如果为 false 时,表示技能期待用户输入,远场交互设备此时应该主动打开麦克风拾音 |
# 应答码
用于标识用户请求响应的状态,它包含用户操作成功或异常等几个方面的状态编号。当存在多个候选的响应结果时,每个响应结果内都必须包含相应的rc码,便于客户端对每个响应包进行识别和操作。
应答码 | 说明 |
---|---|
"rc" | |
0 | 操作成功 |
1 | 输入异常 |
2 | 系统内部异常 |
3 | 业务操作失败,没搜索到结果或信源异常 |
4 | 文本没有匹配的技能场景,技能不理解或不能处理该文本 |
# 语义结构化表示
表示对用户文本的语义意图描述信息,通过该字段应用可以精确定位用户的意图,并获取具体的意图内容参数,在应用中实现对应的技能逻辑处理。
semantic是一个JSON数组,每个对象表示一种可能的语义理解方式,数组中每个成员对象说明如下。
字段名称 | 字段类型 | 是否必须 | 说明 |
---|---|---|---|
"semantic" | |||
intent | String | 是 | 技能中的意图 |
slots | Object | 是 | 参照后续不同技能的定义 |
slots是一个JSON数组,每个对象表示一个语义槽位信息,数组中的成员对象说明如下。
字段名称 | 字段类型 | 是否必须 | 说明 |
---|---|---|---|
"slot" | |||
name | String | 是 | 槽位名 |
value | String | 是 | 槽位值 |
# 结构化数据表示
除了返回对用户意图的描述,对于一些技能,也支持返回对用户文本的应答结果。该字段表示对应答结果的结构化描述信息,如果应用本身没有特定数据源,可以直接选择该结构化的结果进行解析和处理展现,无需处理语义信息。
字段名称 | 字段类型 | 是否必须 | 说明 |
---|---|---|---|
"data" | |||
header | String | 否 | 导语部分 |
result | Object | 否 | 结构化数据;如果没有查到数据,此字段不返回。参照后续不同技能的定义 |
# 简化图文结果表示
对于一些技能,支持直接返回一段文本应答结果,同时辅助一张图片和相关链接。应用可以无需解析和提取语义/结果的结构化数据信息,直接显示该字段的图文信息。同时用户可以选择通过开放平台编辑和上传/导入图文应答信息,快速自定义扩展应用交互。
字段名称 | 字段类型 | 是否必须 | 说明 |
---|---|---|---|
"answer" | |||
type | String | 否 | 显示的类型,通过这个类型,可以确定数据的返回内容和客户端的显示内容,默认值为 T 。 T:text数据 U:url数据 TU:text+url数据 IT:image+text数据 ITU:image+text+url数据 |
text | String | 是 | 通用的文字显示,属于text数据 |
imgUrl | String | 否 | 图片的链接地址,属于image数据 |
imgDesc | String | 否 | 图片的描述文字 |
url | String | 否 | url链接 |
urlDesc | String | 否 | url链接的描述文字 |
emotion | String | 否 | 回答的情绪,取值参见附录的情感标签对照表 |
# moreResults结构表示
当用户的文本可能存在多个对应的意图技能时,应用可以选择返回多候选的应答结果,协议会通过moreResults字段来扩展后续的其他意图技能描述。moreResults是一个JSON数组,用户可以在开放平台配置是否允许多结果。(这里需要针对几个关键字段的特殊处理单独说明,如rc)
示例:
{
"answer" : {
"text" : "你想做飞机还是火车?"
},
"rc" : 0,
"semantic" : [
{
"intent" : "QUERY",
"slots" : [
......
]
}
],
"service" : "flight",
"text" : "我要去北京",
"moreResults" : [
{
"text" : "我要去北京",
"rc" : 0,
"semantic" : [
......
],
"service" : "train"
}
]
}
# 通用功能协议
本章描述了在各技能中相对通用的字段定义,在具体技能中如果引用相关字段将不再具体描述,直接参考相关章节。例如:在“航班”技能中需要定义“预定时间”,可以直接参考本章节中对“时间点”的定义,而不需要在技能中具体定义。
# 地点描述相关协议
地点的基础描述为基于行政区划的地点定义,在此基础上包括扩展协议:表示道路、表示交叉路口、表示区域、表示位置点。
# 基础地点(表示行政区划)的location
name字段名 | 是否必须 | 说明(value取值) |
---|---|---|
location.type | 是 | 取LOC_BASIC |
location.country | 否 | 国别简称(参见附录的对照表) |
location.province | 否 | 省全称(包括直辖市、台) |
location.provinceAddr | 否 | 省简称 |
location.city | 否 | 市全称(包括港澳) |
location.cityAddr | 否 | 市简称 |
location.area | 否 | 县区 |
location.areaAddr | 否 | 县区简称 |
location.country、location.province、location.city、location.area这4种元素必须至少出现一种 |
示例:合肥市包河区
"slots": [
{
"name": "location.area",
"value": "包河区"
},
{
"name": "location.areaAddr",
"value": "包河"
},
{
"name": "location.city",
"value": "合肥市"
},
{
"name": "location.cityAddr",
"value": "合肥"
},
{
"name": "location.type",
"value": "LOC_BASIC"
}
]
# 表示道路的location
name字段名 | 是否必须 | 说明(value取值) |
---|---|---|
location.type | 是 | 取LOC_STREET |
location.country | 否 | 国别简称(参见附录的对照表) |
location.province | 否 | 省全称(包括直辖市、台) |
location.provinceAddr | 否 | 省简称 |
location.city | 是 | 市全称(包括港澳), CURRENT_CITY代表当前城市 |
location.cityAddr | 否 | 市简称 |
location.area | 否 | 县区 |
location.areaAddr | 否 | 县区简称 |
location.street | 是 | 道路名称 |
city、street必选,其他元素可选,当用户没有输入城市,city为”CURRENT_CITY” |
示例:合肥市长江西路
"slots": [
{
"name": "location. street",
"value": "长江西路"
},
{
"name": "location.city",
"value": "合肥市"
},
{
"name": "location.cityAddr",
"value": "合肥"
},
{
"name": "location.type",
"value": " LOC_STREET "
}
]
# 表示交叉路口的location
name字段名 | 是否必须 | 说明(value取值) |
---|---|---|
location.type | 是 | 取LOC_CROSS |
location.country | 否 | 国别简称(参见附录的对照表) |
location.province | 否 | 省全称(包括直辖市、台) |
location.provinceAddr | 否 | 省简称 |
location.city | 是 | 市全称(包括港澳), CURRENT_CITY代表当前城市 |
location.cityAddr | 否 | 市简称 |
location.area | 否 | 县区 |
location.areaAddr | 否 | 县区简称 |
location.street | 是 | 道路名称 |
location.streets | 否 | 交口的另一道路名称 |
city、street必选,其他元素可选,当用户没有输入城市而又没有上传所在城市信息,city为”CURRENT_CITY” |
示例:合肥市望江西路和永和路交口
"slots": [
{
"name": "location. street",
"value": "望江西路"
},
{
"name": "location. streets",
"value": "永和路"
},
{
"name": "location.city",
"value": "合肥市"
},
{
"name": "location.cityAddr",
"value": "合肥"
},
{
"name": "location.type",
"value": " LOC_ CROSS "
}
]
# 表示区域的location
name字段名 | 是否必须 | 说明(value取值) |
---|---|---|
location.type | 是 | 取LOC_REGION |
location.country | 否 | 国别简称(参见附录的对照表) |
location.province | 否 | 省全称(包括直辖市、台) |
location.provinceAddr | 否 | 省简称 |
location.city | 是 | 市全称(包括港澳), CURRENT_CITY代表当前城市 |
location.cityAddr | 否 | 市简称 |
location.area | 否 | 县区 |
location.areaAddr | 否 | 县区简称 |
location.street | 否 | 道路名称 |
location.region | 是 | 区域名称 |
city、region必选,其他元素可选,当用户没有输入城市而又没有上传所在城市信息,比如“西直门”,city为“CURRENT_CITY” |
示例:合肥市三里庵
"slots": [
{
"name": "location. region",
"value": "三里庵"
},
{
"name": "location.city",
"value": "合肥市"
},
{
"name": "location.cityAddr",
"value": "合肥"
},
{
"name": "location.type",
"value": " LOC_ REGION"
}
]
# 表示位置点的location
name字段名 | 是否必须 | 说明(value取值) |
---|---|---|
location.type | 是 | 取LOC_POI |
location.country | 否 | 国别简称(参见附录的对照表) |
location.province | 否 | 省全称(包括直辖市、台) |
location.provinceAddr | 否 | 省简称 |
location.city | 是 | 市全称(包括港澳), CURRENT_CITY代表当前城市 |
location.cityAddr | 否 | 市简称 |
location.area | 否 | 县区 |
location.areaAddr | 否 | 县区简称 |
location.street | 否 | 道路名称 |
location.region | 否 | 区域名称 |
location.poi | 是 | 机构等名称,CURRENT_POI表示当前地点 |
city、poi必选,其他元素可选,当用户没有输入城市而又没有上传所在城市信息, city为“CURRENT_CITY” |
示例:合肥市三里庵国购广场
"slots": [
{
"name": "location. region",
"value": "三里庵"
},
{
"name": "location. poi",
"value": "国购广场"
},
{
"name": "location.city",
"value": "合肥市"
},
{
"name": "location.cityAddr",
"value": "合肥"
},
{
"name": "location.type",
"value": " LOC_POI"
}
]
# 时间描述相关协议
datetime 4.0协议格式
{
"name":"datetime",
"begin":0,
"end":9,
"value":"明天下午3点到5点",
"normValue":"
{
"datetime":"2018-03-07T15:00:00/2018-03-07T17:00:00",
"suggestDatetime":"2018-03-07T15:00:00/2018-03-07T17:00:00"
}
}
normValue中分为datetime和suggestDatetime,以明天上午为例:
datatime为 2018-03-29TAM
suggestDatatime为 2018-03-29T06:00:00
datetime字段的内容是依据当前文本的语义,理解得到的时间表示。suggestDatetime的内容是经过上下文理解,推理得到的相对精确的时间。开发者可以先检查是否存在"O+"或者"O-"字符,进行偏移时间解析,如果不是偏移时间,则使用“/”分割日期时间段为独立的日期时间,然后对每个日期时间使用“T”分割日期和时间,分别解析前段的日期内容和后段的时间内容。
其中,时间分为4四种:标准时间,时间段,偏移时间,重复时间。
# 标准时间
datetime格式为:时间类型+YY-MM-DDThh:mm:ss,其中时间类型可选,LC表示阴历,类型为空,则默认表示阳历;日期和时间之间用T分割。suggestDatetime统一表示为阳历时间,年-月-日T时:分:秒;推荐时间不保证准确,用户可以采用,也可以自行计算;suggest字段只精确到天,或者秒,大部分情况下缺失字段用当日的字段补全;阴历年、月说法补全缺失月、日字段为01,并计算阳历时间。
# 时间段
datetime有三种表示方法:起始时间/结束时间,起始时间和结束时间都是基本时间,斜杠"/"前是起始时间,斜杠"/"后是结束时间。
# 偏移时间
datetime为 O+时间段或O-时间段。suggestTime由当前时间加上或减去时间段,计算得到。
# 重复时间
本版本暂不支持。
部分不支持的时间描述格式,normValue.datetime和normValue.suggestDatetime值可能为空值,请开发者注意解析!
时间类型 | 子类型 | 说法举例 | datetime | SuggestTime | date格式说明 | SuggestTime格式说明 |
---|---|---|---|---|---|---|
基本时间 | 年 | 2017年 | 2017 | 2017-03-20 | ||
2018年 | 2018 | 2018-03-20 | ||||
今年 | 2018 | 2018-03-20 | ||||
明年 | 2019 | 2019-03-20 | ||||
后年 | 2020 | 2020-03-20 | ||||
农历2015年 | LC2015 | 2015-02-19 | ||||
月 | 三月 | 2018-03 | 2018-03-20 | |||
上个月 | 2018-02 | 2018-02-20 | ||||
下个月 | 2018-04 | 2018-04-20 | ||||
腊月 | LC2018-12 | 2019-01-06 | ||||
正月 | LC2018-01 | 2018-02-16 | ||||
2017年三月 | 2017-03 | 2017-03-20 | ||||
去年三月 | 2017-03 | 2017-03-20 | ||||
明年三月 | 2019-03 | 2019-03-20 | ||||
旬 | 上旬 | 2018-03-01 | 2018-03-01 | 旬精确到起始日 | ||
中旬 | 2018-03-11 | 2018-03-11 | ||||
下旬 | 2018-03-21 | 2018-03-21 | ||||
三月上旬 | 2018-03-01 | 2018-03-01 | ||||
四月中旬 | 2018-04-11 | 2018-04-11 | ||||
五月下旬 | 2018-05-21 | 2018-05-21 | ||||
2014年三月下旬 | 2014-03-21 | 2014-03-21 | ||||
周 | 下周 | 2018-03-27 | 2018-03-27 | 1,未指定周几,按照当前weeday指定 2,第几周说法有歧义,可能是normal时间,也有可能是便宜时间,此文档按照标准时间识别 | ||
上周 | 2018-03-13 | 2018-03-13 | ||||
2017年第十周 | 2017-02-28 | 2017-02-28 | ||||
去年第五周 | 2017-01-24 | 2017-01-24 | ||||
四月第二周 | 2018-04-03 | 2018-04-03 | ||||
三月份第二周 | 2018-03-06 | 2018-03-06 | ||||
第三周周三下午五点半 | 2018-01-17T17:30:00 | 2018-01-17T17:30:00 | ||||
去年三月份第一周 | 2017-03-07 | 2017-03-07 | ||||
日 | day | 三号 | 2018-03-03 | 2018-03-03 | 年+节日可以精确推导日期,所以datetime给出的是日期 | |
五号 | 2018-03-05 | 2018-03-05 | ||||
初十 | LC2018-03-10 | 2018-04-25 | ||||
三月五号 | 2018-03-05 | 2018-03-05 | ||||
2017年十月一号 | 2017-10-01 | 2017-10-01 | ||||
上个月三号 | 2018-02-03 | 2018-02-03 | ||||
weekday | 周一 | 2018-03-19 | 2018-03-19 | |||
周日 | 2018-03-25 | 2018-03-25 | ||||
上周一 | 2018-03-19 | 2018-03-19 | ||||
下周一 | 2018-03-19 | 2018-03-19 | ||||
周末 | 2018-03-24 | 2018-03-24 | ||||
2015年第四周周一 | 2015-01-19 | 2015-01-19 | ||||
2015年四月第二周周一 | 2015-04-06 | 2015-04-06 | ||||
2015年四月第二个周一 | 2015-04-06 | 2015-04-06 | ||||
festival | 清明节 | 清明 | 2018-04-05 | |||
端午节 | 端午节 | 2018-06-18 | ||||
2017年国庆节 | 2017-10-01 | 2017-10-01 | ||||
明年端午 | 2019-06-07 | 2019-06-07 | ||||
时间 | 口语time | 上午 | TAM | 2018-03-20T06:00:00 | 目前支持的口语time:早上(AM),上午(AM),凌晨(EAM),清晨(AM),一早(AM),早晨(AM),清早(AM),头晌(MID),中午(MID),正午(MID),晌午(MID),傍晌(EV),下午(PM),傍晚(EV),黄昏(EV),夜里(NI),深夜(LNI),晚上(NI),夜晚(NI),午夜(MNI),半夜(MNI) | AM06:00:00 EAM 01:00:00 MID 12:00:00 EV18:00:00 PM13:00:00 NI20:00:00 LNI 22:00:00 MNI 23:59:59 |
下午 | TPM | 2018-03-20T13:00:00 | ||||
明天上午 | 2018-03-21TAM | 2018-03-21T06:00:00 | ||||
周一下午 | 2018-03-19TPM | 2018-03-19T13:00:00 | ||||
2017年四月五号上午 | 2017-04-05TAM | 2017-04-05T06:00:00 | ||||
国庆节晚上 | 国庆节TNI | 2018-10-01T20:00:00 | ||||
前年中秋节下午 | 2016-09-15TPM | 2016-09-15T13:00:00 | ||||
上个月三号中午 | 2018-02-03TMID | 2018-02-03T12:00:00 | ||||
十号下午 | 2018-03-10TPM | 2018-03-10T13:00:00 | ||||
时分秒 | 三点十分零五秒 | T03:10:05 | 2018-03-20T03:10:05 | |||
三点十分 | T03:10:00 | 2018-03-20T03:10:00 | ||||
三点半 | T03:30:00 | 2018-03-20T03:30:00 | ||||
三点一刻 | T03:15:00 | 2018-03-20T03:15:00 | ||||
2017年三月八号十五点三十分钟十秒 | 2017-03-08T15:30:10 | 2017-03-08T15:30:10 | ||||
三月八号十五点三十分钟十秒 | 2018-03-08T15:30:10 | 2018-03-08T15:30:10 | ||||
八号十五点三十分钟十秒 | 2018-03-08T15:30:10 | 2018-03-08T15:30:10 | ||||
2017年三月八号下午三点 | 2017-03-08T03:00:00 | 2018-03-20T03:00:00 | ||||
三月八号下午十五点 | 2018-03-08T15:00:00 | 2018-03-20T15:00:00 | ||||
八号上午十点 | 2018-03-08T10:00:00 | 2018-03-20T10:00:00 | ||||
时间段 | 起始点/结束点 | 三号到五号 | 2018-03-03/2018-03-05 | 2018-03-03/2018-03-05 | ||
周一下午到周二上午 | 2018-03-19TPM/2018-03-20TAM | 2018-03-19T13:00:00/2018-03-20T06:00:00 | ||||
三月中旬到下旬 | 2018-03-11/2018-03-21 | 2018-03-11/2018-03-21 | ||||
2017年三月四号上午五点到下午7点 | 2017-03-04T05:00:00/2017-03-04T19:00:00 | 2017-03-04T05:00:00/2017-03-04T19:00:00 | ||||
2017年三月四号下午五点到7点 | 2017-03-04T17:00:00/2017-03-04T19:00:00 | 2017-03-04T17:00:00/2017-03-04T19:00:00 | ||||
时间段(暂不支持) | 一个小时 | |||||
三天零2个小时 | ||||||
一年零两个月三天 | ||||||
一年零两个月三天零2个半小时 | ||||||
起始点/[时间段][时间段]/结束点(暂不支持) | 未来三天 | |||||
过去七天 | ||||||
重复时间 | 重复时间段(暂不支持) | 每2个月 | ||||
每两个星期 | ||||||
每一年零三个月 | ||||||
每一年零三个月五天六个半小时 | ||||||
重复时间点(暂不支持) | 每年 | |||||
每月 | ||||||
每年三月 | ||||||
每周二下午三点 | ||||||
每周末 | ||||||
每年三月五号下午五点半 | ||||||
偏移时间 | 偏移时间 | 第二天 | O+1D | 2018-03-21 | ||
前一天 | O-1D | 2018-03-19 | ||||
两天三个小时后 | O+2D3h | 2018-03-22T17:13:52 | ||||
半个小时之前 | O-30m | 2018-03-20T13:43:52 | ||||
1年零3个月之后 | O+1Y3M | 2019-06-20 | ||||
偏移时间+时间点(暂不支持) |