2.4 动态实体QA

Q：上传资源数据返回的状态与查询打包状态有什么区别？

A：上传资源数据时返回的状态代表数据是否上传成功至服务端，主要是用来反馈上传的数据格式是否正确；查询打包状态代表数据上传至后台后是否将这些资源数据处理成功，主要是用来反馈数据能否被正常生效使用。

Q：动态实体上传失败的原因一般有哪些？

A：

  1. res_name未加上命名空间
  2. 上传资源字段与后台不对应

Q：动态实体不能正常生效使用的原因一般有哪些？

A：

  1. 未设置pers_param参数，即生效维度
  2. 上传资源数据时如果是在文本文件里读取的内容，请注意不要将文件的BOM头带入数据中或者直接将其转为无BOM头的文件
  3. aiui.cfg文件里未指定appid
  4. 动态实体词条存在重复项

动态实体

1. 动态实体的定义和维度

实体：就是词库，在语料中与词槽绑定的内容，模板语料中词槽用{}包裹。例：{city}词槽绑定的实体词库包含北京，上海，深圳

动态实体：不同应用或用户，甚至不同的范围里，所用词库内容有所差异，词槽所对应的内容随之改变的词库，例：{phoneNumber}词槽对应的实体，每个用户的通讯录都不同

1.1 动态实体的资源

一个动态实体可以包含多个资源(Resource)，资源定义中包含了资源名称，生效维度、词条字段名、词条别名字段。

实体 - 图1

资源包含以下几个重要属性：

资源名称：词条资源在当前账号下唯一的名字，一般搭配命名空间使用，如在后文中，配置resName字段值为namespace.资源名称（如：OS0000007.entity_app）格式内容。命名空间获取见下文。

资源维度：即词条的生效维度，有应用级、用户级、自定义级，在客户端上传对应的资源数据时，维度信息（包括维度名称和维度值）需要和定义时保持一致。
具体使用可见后文实体上传和请求部分。

生效维度 维度名称 维度值
应用级 appid 如：e0xxxx5e
用户级 uid（SDK) auth_id（http：上传、查询；weboscket：请求） 如：sn007 auth_id需要为32位字符串，包括英文小写字母与数字
自定义级 自定义维度名称，如上图中为custom_id 如：custom_007

词条名字段：默认为name，可在动态实体页面按需修改

词条别名字段：默认为alias，可在动态实体页面按需修改、添加

  1. 一个动态实体下可配置多个维度的资源（见上图）
  2. 如果需要在SDK和websocket使用同一套用户级动态实体内容，需要将uid和auth_id均设置为32位字符串。

1.2 生效维度

1.2.1 应用级

在同一个appid下生效的资源内容

实体 - 图2

举例
以开发《水浒传》和《西游记》2个app为例：

  1. 用户说法：
  2.     《水浒传》：介绍李逵
  3.     《西游记》：介绍孙悟空
  5. 提取说法语料加入小说技能：介绍{name}
《水浒传》和《西游记》均使用了小说技能，但上传的name实体内容不同。
水浒传 name 实体 西游记 name 实体
宋江 唐僧
鲁智深 孙悟空
林冲 猪八戒
…… ……
动态实体(应用级)可以在实体名相同的情况下，为每个 appid 设置不同的词库，永久生效。

1.2.2 用户级

在同一个设备id下生效的资源内容
实体 - 图3 举例
以打电话技能为例： 
  1. 用户说法：打给张三，打给李四
  2. 抽象为技能：打给{contacts}
不同用户的联系人不同，使用用户级动态实体为每个用户配置一个私有词库，永久生效。

1.2.3 自定义级

在同一个自定义级别维度的值下生效的资源内容

实体 - 图4

举例
以全国连锁餐厅点餐 App 为例

  1. 用户说法：我想吃杭椒牛柳，我想吃宫保鸡丁
  2. 抽象为技能：我想吃{meal}
因不同省份的菜单不一样，无法使用同一份实体内容，因此使用自定义级动态实体来支持不同的菜单内容。 新建动态实体meal，在这个实体下添加资源维度为自定义级的资源，如meal_province，资源维度设置为province。
技能工作室内设置如下：

实体 - 图5

可以通过设置维度名 province的维度值为不同省份，上传各个省份的菜单。例如：
维度名 维度值 词条内容
province beijing 北京烤鸭、驴打滚
province guangdong 猪脚饭、卤鹅饭
province shandong 葱烧海参、把子肉
使用自定义级动态实体开发者可以自定义分组，实体设置成功后，只对属于特定分组的终端生效。

2. 动态实体的上传及使用

动态实体的使用有2种方式： WebAPI 接口、 AIUI SDK。 动态实体的使用分三步：
  1. 上传资源：每次上传都会覆盖之前的资源数据
  2. 查询打包状态以生效
  3. 请求命中
Android、iOS、Windows、Linux 推荐通过CMD_SET_PARAMS设置pers_param使之生效，WebSocket API 应用推荐传pers_param参数使之生效。

2.1 WebAPI

通过 HTTP 上传动态实体。
  • 为了授权认证，调用接口需要将nameSpace，nonce，curtime和checkSum信息放在HTTP请求头中。
  • 所有接口统一为UTF-8编码。
  • 所有接口支持http和https。

调用示例Demo

Github

2.1.1 授权认证

必要参数说明

  • AccountKey：账户级Key
  • namespace：命名空间,代表用户唯一标识
AccountKey和namespace可在技能控制台查看相关值：
实体 - 图6 + 资源名称：动态实体里的资源标识，在动态实体中查看

实体 - 图7

调用动态实体相关业务接口时，都需要在Http Request Header中加入以下参数作为授权验证
参数名 说明 是否必须
X-NameSpace namespace，命名空间 是
X-Nonce 随机数（最大长度128个字符） 是
X-CurTime 当前UTC时间戳，从1970年1月1日0点0 分0 秒开始到现在的秒数(String) 是
X-CheckSum MD5(accountKey + Nonce + CurTime),三个参数拼接的字符串，进行MD5哈希计算 是
注意：
  • CheckSum有效期：出于安全性考虑，每个CheckSum的有效期为5分钟(用curTime计算)，同时CurTime要与标准时间同步，否则，时间相差太大，服务端会直接认为CurTime无效。
  • checkSum生成示例： 
  1. accountKey="abcd1234";
  2. Nonce="12";
  3. CurTime="1502607694";
  4. CheckSum=MD5(accountKey+Nonce+CurTime);
  5. //最终CheckSum输出为32位小写字符串 bf5aa1f53bd173cf7413bf370ad4bddc
Copy

IP 白名单
可通过设置ip白名单来限制调用服务的设备来源。

  • 关闭状态：只要appid和appkey正确就能使用AIUI 服务
  • 开启状态：授权认证通过后，系统检查请求方ip是否在白名单中，非白名单ip请求则拒绝服务。

实体 - 图8

拒绝服务结果示例： 
  1. {