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"
}

应答消息字段定义

字段名称字段类型是否必须说明
rcint应答码(response code)
errorObject错误信息
textString用户的输入,可能和请求中的原始text不完全一致,因服务器可能会对text进行语言纠错
vendorString技能提供者,不存在时默认表示为IFLYTEK提供的开放技能
serviceString技能的全局唯一名称,一般为vendor.name,vendor不存在时默认为IFLYTEK提供的开放技能。
semanticObject本次语义(包括历史继承过来的语义)结构化表示,各技能自定义
dataObject数据结构化表示,各技能自定义
answerObject对结果内容的最简化文本/图片描述,各技能自定义
dialog_statString用于客户端判断是否使用信源返回数据
moreResultsObject在存在多个候选结果时,用于提供更多的结果描述
shouldEndSessionBoolean当该字段为空或为 true 时表示技能已完成一次对话,如果为 false 时,表示技能期待用户输入,远场交互设备此时应该主动打开麦克风拾音

应答码

用于标识用户请求响应的状态,它包含用户操作成功或异常等几个方面的状态编号。当存在多个候选的响应结果时,每个响应结果内都必须包含相应的rc码,便于客户端对每个响应包进行识别和操作。

应答码说明
"rc"
0操作成功
1输入异常
2系统内部异常
3业务操作失败,没搜索到结果或信源异常
4文本没有匹配的技能场景,技能不理解或不能处理该文本

语义结构化表示

表示对用户文本的语义意图描述信息,通过该字段应用可以精确定位用户的意图,并获取具体的意图内容参数,在应用中实现对应的技能逻辑处理。

semantic是一个JSON数组,每个对象表示一种可能的语义理解方式,数组中每个成员对象说明如下。

字段名称字段类型是否必须说明
"semantic"
intentString技能中的意图
slotsObject参照后续不同技能的定义

slots是一个JSON数组,每个对象表示一个语义槽位信息,数组中的成员对象说明如下。

字段名称字段类型是否必须说明
"slot"
nameString槽位名
valueString槽位值

结构化数据表示

除了返回对用户意图的描述,对于一些技能,也支持返回对用户文本的应答结果。该字段表示对应答结果的结构化描述信息,如果应用本身没有特定数据源,可以直接选择该结构化的结果进行解析和处理展现,无需处理语义信息。

字段名称字段类型是否必须说明
"data"
headerString导语部分
resultObject结构化数据;如果没有查到数据,此字段不返回。参照后续不同技能的定义

简化图文结果表示

对于一些技能,支持直接返回一段文本应答结果,同时辅助一张图片和相关链接。应用可以无需解析和提取语义/结果的结构化数据信息,直接显示该字段的图文信息。同时用户可以选择通过开放平台编辑和上传/导入图文应答信息,快速自定义扩展应用交互。

字段名称字段类型是否必须说明
"answer"
typeString显示的类型,通过这个类型,可以确定数据的返回内容和客户端的显示内容,默认值为 T 。 T:text数据 U:url数据 TU:text+url数据 IT:image+text数据 ITU:image+text+url数据
textString通用的文字显示,属于text数据
imgUrlString图片的链接地址,属于image数据
imgDescString图片的描述文字
urlStringurl链接
urlDescStringurl链接的描述文字
emotionString回答的情绪,取值参见附录的情感标签对照表

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值可能为空值,请开发者注意解析!

时间类型子类型说法举例datetimeSuggestTimedate格式说明SuggestTime格式说明
基本时间2017年20172017-03-20
2018年20182018-03-20
今年20182018-03-20
明年20192019-03-20
后年20202020-03-20
农历2015年LC20152015-02-19
三月2018-032018-03-20
上个月2018-022018-02-20
下个月2018-042018-04-20
腊月LC2018-122019-01-06
正月LC2018-012018-02-16
2017年三月2017-032017-03-20
去年三月2017-032017-03-20
明年三月2019-032019-03-20
上旬2018-03-012018-03-01旬精确到起始日
中旬2018-03-112018-03-11
下旬2018-03-212018-03-21
三月上旬2018-03-012018-03-01
四月中旬2018-04-112018-04-11
五月下旬2018-05-212018-05-21
2014年三月下旬2014-03-212014-03-21
下周2018-03-272018-03-271,未指定周几,按照当前weeday指定 2,第几周说法有歧义,可能是normal时间,也有可能是便宜时间,此文档按照标准时间识别
上周2018-03-132018-03-13
2017年第十周2017-02-282017-02-28
去年第五周2017-01-242017-01-24
四月第二周2018-04-032018-04-03
三月份第二周2018-03-062018-03-06
第三周周三下午五点半2018-01-17T17:30:002018-01-17T17:30:00
去年三月份第一周2017-03-072017-03-07
day三号2018-03-032018-03-03年+节日可以精确推导日期,所以datetime给出的是日期
五号2018-03-052018-03-05
初十LC2018-03-102018-04-25
三月五号2018-03-052018-03-05
2017年十月一号2017-10-012017-10-01
上个月三号2018-02-032018-02-03
weekday周一2018-03-192018-03-19
周日2018-03-252018-03-25
上周一2018-03-192018-03-19
下周一2018-03-192018-03-19
周末2018-03-242018-03-24
2015年第四周周一2015-01-192015-01-19
2015年四月第二周周一2015-04-062015-04-06
2015年四月第二个周一2015-04-062015-04-06
festival清明节清明2018-04-05
端午节端午节2018-06-18
2017年国庆节2017-10-012017-10-01
明年端午2019-06-072019-06-07
时间口语time上午TAM2018-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
下午TPM2018-03-20T13:00:00
明天上午2018-03-21TAM2018-03-21T06:00:00
周一下午2018-03-19TPM2018-03-19T13:00:00
2017年四月五号上午2017-04-05TAM2017-04-05T06:00:00
国庆节晚上国庆节TNI2018-10-01T20:00:00
前年中秋节下午2016-09-15TPM2016-09-15T13:00:00
上个月三号中午2018-02-03TMID2018-02-03T12:00:00
十号下午2018-03-10TPM2018-03-10T13:00:00
时分秒三点十分零五秒T03:10:052018-03-20T03:10:05
三点十分T03:10:002018-03-20T03:10:00
三点半T03:30:002018-03-20T03:30:00
三点一刻T03:15:002018-03-20T03:15:00
2017年三月八号十五点三十分钟十秒2017-03-08T15:30:102017-03-08T15:30:10
三月八号十五点三十分钟十秒2018-03-08T15:30:102018-03-08T15:30:10
八号十五点三十分钟十秒2018-03-08T15:30:102018-03-08T15:30:10
2017年三月八号下午三点2017-03-08T03:00:002018-03-20T03:00:00
三月八号下午十五点2018-03-08T15:00:002018-03-20T15:00:00
八号上午十点2018-03-08T10:00:002018-03-20T10:00:00
时间段起始点/结束点三号到五号2018-03-03/2018-03-052018-03-03/2018-03-05
周一下午到周二上午2018-03-19TPM/2018-03-20TAM2018-03-19T13:00:00/2018-03-20T06:00:00
三月中旬到下旬2018-03-11/2018-03-212018-03-11/2018-03-21
2017年三月四号上午五点到下午7点2017-03-04T05:00:00/2017-03-04T19:00:002017-03-04T05:00:00/2017-03-04T19:00:00
2017年三月四号下午五点到7点2017-03-04T17:00:00/2017-03-04T19:00:002017-03-04T17:00:00/2017-03-04T19:00:00
时间段(暂不支持)一个小时
三天零2个小时
一年零两个月三天
一年零两个月三天零2个半小时
起始点/[时间段][时间段]/结束点(暂不支持)未来三天
过去七天
重复时间重复时间段(暂不支持)每2个月
每两个星期
每一年零三个月
每一年零三个月五天六个半小时
重复时间点(暂不支持)每年
每月
每年三月
每周二下午三点
每周末
每年三月五号下午五点半
偏移时间偏移时间第二天O+1D2018-03-21
前一天O-1D2018-03-19
两天三个小时后O+2D3h2018-03-22T17:13:52
半个小时之前O-30m2018-03-20T13:43:52
1年零3个月之后O+1Y3M2019-06-20
偏移时间+时间点(暂不支持)
AIUI文档中心