# 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
偏移时间+时间点(暂不支持)