开发文档

1、概述

科大讯飞Athena系统,是一个集人工智能对话、语义理解以及智能问答能力的技术性平台,通过AIUI开放平台对外开放,面向广大开发者提供一站式语义、对话解决方案。

该系统提供覆盖多个垂直领域的语义、对话技能,提供海量开放问答库;通过AIUI开放平台,也支持开发者自定义技能和问答库。

支持Andriod、IOS、JAVA、Linux等多终端接入,通过多样化的结果输出,满足应用的个性化需求。

2、应答消息格式

交互返回协议为JSON格式,内容示例如下:

    {
        "answer" : {
            "text" : "\"合肥\"今天\"中雨\", \"15℃\", \"东北风微风\", 雨天出行记得准备带伞"
        },
        "data" : {
            "result" : [
                {
                    ......
                }
            ]
        },
        "dialog_stat" : "DataValid",
        "text" : "合肥的天气",
        "service" : "weather",
        "rc" : 0,
        "semantic" : [
            {
                "intent" :  "QUERY",
                "slots" : {
                     ......
                }
            }
        ]
    }
3、应答消息字段定义
字段名称 字段类型 是否必须 说明
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 在存在多个候选结果时,用于提供更多的结果描述

3.1 应答码

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

应答码 说明
"rc"
0 操作成功
1 输入异常
2 系统内部异常
3 业务操作失败,错误信息在error字段描述
4 文本没有匹配的技能场景,技能不理解或不能处理该文本

3.2 语义结构化表示

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

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

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

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

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

3.3 结构化数据表示

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

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

3.4 简化图文结果表示

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

字段名称 字段类型 是否必须 说明
"answer"
type String 显示的类型,通过这个类型,可以确定数据的返回内容和客户端的显示内容:
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 回答的情绪,取值参见附录的情感标签对照表

3.5 moreResults结构表示

当用户的文本可能存在多个对应的意图技能时,应用可以选择返回多候选的应答结果,协议会通过moreResults字段来扩展后续的其他意图技能描述。moreResults是一个JSON数组,用户可以在开放平台配置是否允许多结果。(这里需要针对几个关键字段的特殊处理单独说明,如rc)

示例:

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

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

4.1 地点描述相关协议

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

4.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"
			}
		]
	

4.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 "
			}
		]
	

4.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 "
			}
		]
	

4.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"
			}
		]
	

4.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"
			}
		]
	

4.2 时间描述相关协议

时间描述的基础是描述了时间点的协议,在此基础上包括扩展协议:时间段协议、不同时间点、无法解析的时间说法。

slots中表示时间协议字段如下:

字段名称 说明
name 固定为datetime
value 原始输入中匹配上的关于时间的文本
normValue JSON String类型,为日期的归一化格式表示

日期归一化格式说明如下:

字段名称 说明
datetime 开放给开发者的使用的时间协议,用户可以根据该协议字符计算时间
suggestDatetime 推荐时间供开发者选择使用

4.2.1 基础描述(表示时间点)的datetime

采用[LC] [YY-MM-DD]T[hh:mm:ss][AM/PM]的格式表示基本时间。

其中:

LC: 表示阴历

YY-MM-DD: 表示年-月-日

T:标识后面为时间字段

hh:mm:ss: 表示时:分:秒

AM/PM: 表示上午/下午

支持说法范围为:基本时间说法、日期、时间、日期+时间、节日、阴历时间等。

示例: 明天下午三点

		{
			"name": "datetime",
			"value": "明天下午3点",
			"normValue": "{\"datetime\":\"2017-06-07T15:00:00\",\"suggestDatetime\":\"2017-06-07T15:00:00\"}"
		}
	

示例: 后天下午

		{
			"name": "datetime",
			"value": "后天下午",
			"normValue": "{\"datetime\":\"2017-06-09TPM\"}"
		}
	

示例: 2017年中秋节

		{
			"name": "datetime",
			"value": "2017年中秋节",
			"normValue":"{\"datetime\":\"LC 2017-08-15\",\"suggestDatetime\":\"2017-10-04\"}"
		}
	

4.2.2 表示时间段的datetime

采用 ”基础时间”/”基础时间” 方式表示时间段。

示例: 明天下午3点到5点

		{
			"name": "datetime",
			"value": "明天下午3点到5点",
			"normValue":"{\"datetime\":\"2017-06-08T15:00:00/2017-06-08T17:00:00\",\"suggestDatetime\":\"2017-06-08T15:00:00/2017-06-08T17:00:00\"}"
		}
	

示例: 下周三到周日

		{
			"name": "datetime",
			"value": "下周三到下周日",
			"normValue":"{\"datetime\":\"2017-06-14/2017-06-11\",\"suggestDatetime\":\"2017-06-14/2017-06-18\"}"
		}