AIUI文档中心

本文档使用 MrDoc 发布

语义协议：重要字段和通用字段

目录

  1. 消息格式
  2. 应答消息字段定义
    2.1. 语义semantic
    2.2. Data字段
    2.3. 简化图文结果表示
    2.4. moreResults结构表示
  3. 通用功能协议
    3.1.3. 表示交叉路口的location
    3.1.4. 表示区域的location
    3.1.5. 表示位置点的location
    3.2. 时间描述相关协议
    3.3. 标准时间
    3.4. 时间段
    3.5. 偏移时间
    3.6. 重复时间

1. 消息格式

交互返回数据为JSON格式:

点击查看示例 
{
    "data": {
        "result": [
            {
                "airData": 35,
                "date": "2018-02-07",
                "dateLong": 1517932800,
                "humidity": "16%",
                "tempRange": "-9℃ ~ 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",
    "text": "查看北京今天的天气",
    "answer": {
        "text": "\"北京今天多云转晴\"
    },
    "dialog_stat": "DataValid",
    "category" : "IFLYTEK.weather",
    "version" : "10.0",
    "sid": "atn00d35cc3@ch13c70dd605786f1d01"
}

2. 应答消息字段定义

字段名称 字段类型 是否必须 说明
rc int 是 语义理解结果
0（成功）
1（输入异常）
2（系统内部异常）
3（业务操作失败，没搜索到结果或信源异常）
4（说法未命中技能）
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 否 是否有会话历史

2.1. 语义semantic

意图的描述信息，通过该字段定位用户意图，并获取意图图参数，实现技能逻辑处理。

semantic字段说明：

字段名称 字段类型 是否必须 说明
intent String 是 技能中的意图
slots Object 是 参照后续不同技能的定义

slots字段说明：

字段名称 字段类型 是否必须 说明
name String 是 槽位名
value String 是 槽位值

2.2. Data字段

该字段表示应答结果，如果应用本身没有数据源，可以直接选择该结果解析和展现，无需处理语义信息。

字段名称 字段类型 是否必须 说明
header String 否 导语部分
result Object 否 结构化数据；如果没有查到数据，此字段不返回。参照后续不同技能的定义

2.3. 简化图文结果表示

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

字段名称 字段类型 是否必须 说明
“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 否 回答的情绪，取值参见附录的情感标签对照表

2.4. moreResults结构表示

说法命中多个技能时出现moreResults字段，通过moreResults字段来扩展其他意图技能描述。moreResults是一个JSON数组，可以在开放平台配置是否允许多结果。(这里需要针对几个关键字段的特殊处理单独说明，如rc)

示例:

{
    "answer" : {
        "text" : "你想做飞机还是火车?"
    },
    "rc" : 0,
    "semantic" : [
        {
            "intent" :  "QUERY",
            "slots" : [
                    ......
            ]
        }
    ],
    "service" : "flight",
    "text" : "我要去北京",
    "moreResults" : [
        {
            "text" : "我要去北京",
            "rc" : 0,
            "semantic" : [
                    ......
            ],
            "service" : "train"
        }
    ]
}

3. 通用功能协议

本章描述了在各技能中相对通用的字段定义，在具体技能中如果引用相关字段将不再具体描述，直接参考相关章节。例如：在“航班”技能中需要定义“预定时间”，可以直接参考本章节中对“时间点”的定义，而不需要在技能中具体定义。

3.1. 地点描述相关协议

地点的基础描述为基于行政区划的地点定义，在此基础上包括扩展协议：表示道路、表示交叉路口、表示区域、表示位置点。

3.1.1. 基础地点（表示行政区划）的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"
    }
]

3.1.2. 表示道路的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 "
    }
]

3.1.3. 表示交叉路口的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 "
    }
]

3.1.4. 表示区域的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"
    }
]

3.1.5. 表示位置点的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"
    }
]

3.2. 时间描述相关协议

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四种：标准时间，时间段，偏移时间，重复时间。

3.3. 标准时间

datetime格式为：时间类型+YY-MM-DDThh:mm:ss，其中时间类型可选，LC表示阴历，类型为空，则默认表示阳历；日期和时间之间用T分割。suggestDatetime统一表示为阳历时间，年-月-日T时:分:秒；推荐时间不保证准确，用户可以采用，也可以自行计算；suggest字段只精确到天，或者秒，大部分情况下缺失字段用当日的字段补全；阴历年、月说法补全缺失月、日字段为01，并计算阳历时间。

3.4. 时间段

datetime有三种表示方法：起始时间/结束时间，起始时间和结束时间都是基本时间，斜杠”/“前是起始时间,斜杠”/“后是结束时间。

3.5. 偏移时间

datetime为 O+时间段或O-时间段。suggestTime由当前时间加上或减去时间段，计算得到。

3.6. 重复时间

本版本暂不支持。

部分不支持的时间描述格式，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
偏移时间+时间点（暂不支持）
admin 2024年9月13日 16:55 收藏文档