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,
    "category" : "IFLYTEK.weather",
    "version" : "158.0",
    "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 时，表示技能期待用户输入，远场交互设备此时应该主动打开麦克风拾音
category String 是 技能类别
version String 否 版本
uuid String 是 同sid（历史字段，请忽略）
used_state Object 是 交互使用状态（历史字段，请忽略）
state Object 是 交互状态（历史字段，请忽略）
sid String 是 会话id，用于标识会话，调试时提供给讯飞帮助定位问题
save_history Boolean 否 是否有会话历史

# 应答码

用于标识用户请求响应的状态，它包含用户操作成功或异常等几个方面的状态编号。当存在多个候选的响应结果时，每个响应结果内都必须包含相应的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
偏移时间+时间点（暂不支持）

← Request_2.1协议 →