3.4.5 用户个性化

<div style="max-width: 100%; margin: 20px auto;">
    
    <div style="background-color: #ffffff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); overflow: hidden; font-family: 'Comic Sans MS', cursive, sans-serif;">
        
        
        <div style="background-color: #F4F8FA; padding: 1px 10px; border-bottom: 1px solid #dee2e6; display: flex; justify-content: space-between; align-items: center;">
            <div style="color: #0E42D2; font-weight: bold;font-size: 1.3rem;">用户个性化概述</div>
            <div>
            </div>
        </div>
        
        <div style="padding: 25px; line-height: 29px; background-image: linear-gradient(transparent 26px, #dee2e6 27px, #dee2e6 27px, transparent 27px); background-size: 100% 28px; min-height: 100px; color: #333;">
            <div>用户个性化指的是在AIUI语音交互服务中，相关业务服务的数据非固定配置，而是依赖用户（或设备端）来确定。这种数据代表用户个性化数据。</div>
            <div>AIUI语音交互服务中，个性化数据使用通常指的就是动态实体数据上传使用。</div>
            <a href="#动态实体使用" style="color: #6f42c1; font-weight: 500;">
            <strong>- 1、动态实体使用>>>点击跳转</strong></a><br>
            <a href="#动态实体介绍" style="color: #6f42c1; font-weight: 500; margin-left: 20px;">
            <strong>- 1.1、动态实体介绍>>>点击跳转</strong></a><br>
            <a href="#确认动态实体信息" style="color: #6f42c1; font-weight: 500; margin-left: 20px;">
            <strong>- 1.2、确认动态实体信息>>>点击跳转</strong></a><br>
            <a href="#自定义动态实体" style="color: #6f42c1; font-weight: 500; margin-left: 20px;">
            <strong>- 1.3、自定义动态实体>>>点击跳转</strong></a><br>
            <a href="#动态实体使用说明" style="color: #6f42c1; font-weight: 500; margin-left: 20px;">
            <strong>- 1.4、动态实体使用说明>>>点击跳转</strong></a><br>
            
            <a href="#附录-官方设备类型" style="color: #6f42c1; font-weight: 500;">
            <strong>- 2、附录-官方设备类型>>>点击跳转</strong></a>
        </div>
    </div>
</div>

## 1. 动态实体使用

### 1.1. 动态实体介绍
了解动态实体前需要先理解`实体`的概念：
实体即为一类或存在相关性的多条词条组合而成的词库，根据词库更新方式不同分为。
- **静态实体**：AIUI平台下固定配置，可直接查看修改，不随用户或设备改变而变化的词库。
- **动态实体**：词库内容由不同用户或设备上传的个性化数据决定，AIUI平台下不可直接查看修改。

`动态实体`主要配合语义技能一起使用的，根据生成的方式，主要分：
- **开放动态实体**：
	在官方技能中提供的动态实体槽位，**固定`用户级(uid)`生效维度**。
- **自定义动态实体**：
	用户自定义创建的动态实体，单个实体支持多资源设置，每个资源可以定义资源名称、生效维度、实体词条主从字段。生效的维度有`应用级(appid)`、`用户级(uid)`、`自定义级（自定义key）`。

上传数据时，维度需要和定义时一致。

![](/media/202508/2025-08-22_105924_1715140.674648834379052.png)

### 1.2. 确认动态实体信息
#### 1.2.1. 开放动态实体
AIUI平台官方技能提供个动态实体，目前支持有：
- 电话技能（IFLYTEK.telephone）中提供的联系人实体
- 智能家居专业版（IFLYTEK.smartControlPro） 中提供的家居个性化实体

**`联系人个性化实体`说明：**
电话技能内置1个动态实体：联系人个性化实体，对应的资源名为`IFLYTEK.telephone_contact`，为**用户级动态实体**，可定义数据格式如下所示：
~~~ json
{"name":"张三","alias":"三弟","phoneNumber":"18888888888","location":{}}
{"name":"李四","alias":"四妹","phoneNumber":"18666666666","location":{}}
~~~

数据字段说明：

<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>字段</b></td>
<td><b>是否必要</b></td>
<td><b>介绍</b></td>
<td><b>示例</b></td>
</tr>
<tr class="row-even">
<td>name</td>
<td>必要</td>
<td>联系人姓名</td>
<td>张三</td>
</tr>
<tr class="row-odd">
<td>alias</td>
<td>非必要</td>
<td>联系人别名</td>
<td>三弟\|三仔 (多取值时用`\|`符号隔开)</td>
</tr>
<tr class="row-even">
<td>phoneNumber</td>
<td>非必要</td>
<td>电话号码</td>
<td>18888888888</td>
</tr>
<tr class="row-odd">
<td>location</td>
<td>非必要</td>
<td>可自定义内容</td>
<td>{"working":"科大讯飞"}</td>
</tr>
</tbody>
</table>

**`智能家居个性化实体`说明：**
智能家居个性化动态实体也是**用户级**动态实体，其可上传的动态实体资源有6个，对应的关联技能为所有智能家居业务，资源定义如下所示：

|<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>实体名名称</b></td>
<td><b>资源名标识</b></td>
<td><b>是否必传</b></td>
<td><b>资源描述</b></td>
</tr>
<tr class="row-even">
<td>设备信息</td>
<td>IFLYTEK.smartH_deviceAlias</td>
<td>是</td>
<td>alias资源</td>
</tr>
<tr class="row-odd">
<td>品牌</td>
<td>IFLYTEK.smartH_deviceModi</td>
<td>否</td>
<td>modifier资源</td>
</tr>
<tr class="row-even">
<td>房间</td>
<td>IFLYTEK.smartH_deviceRoom</td>
<td>否</td>
<td>room资源</td>
</tr>
<tr class="row-odd">
<td>空间</td>
<td>IFLYTEK.smartH_deviceZone</td>
<td>否</td>
<td>zone资源</td>
</tr>
<tr class="row-even">
<td>地理位置</td>
<td>IFLYTEK.smartH_deviceRegion</td>
<td>否</td>
<td>region资源</td>
</tr>
<tr class="row-odd">
<td>情景模式</td>
<td>IFLYTEK.smartH_deviceScene</td>
<td>否</td>
<td>scene资源</td>
</tr>
</tbody>
</table>

<div style="display: flex; align-items: flex-start; gap: 16px; padding: 16px; background: #fff5f6; border-radius: 5px; border-left: 4px solid #e83e8c; box-shadow: 0 4px 12px rgba(255, 215, 0, 0.08); margin-bottom: 16px; transition: transform 0.2s ease, box-shadow 0.2s ease;">
  <div>
    <div style="font-weight: 600; margin-bottom: 4px;">温馨提示</div>
    <div style="font-size: 14px; line-height: 1.5;">1、智能家居个性化数据中alias资源为必传资源，modifier、room、zone、region4个选传资源是对alias资源的补充，可以提高个性化配置</div>
    <div style="font-size: 14px; line-height: 1.5;">2、scene资源是自定义场景或模式，不关联具体设备</div>
  </div>
</div>

**`资源实体`取值说明**：
① 上传`alias资源`。用户查询使用的时候返回的所有数据都是从这条资源里返回的，因此上传该资源时请尽量包含您想要的信息。示例JSON格式定义如下：
~~~   json 
{"modifier": "海尔","color": "白色","location": {"room": "卧室","zone": "二楼","region": "兴园"},"type": "空调壁挂式","description": "卧室空调","model": "健康卫士系列","feature": "制冷|制热|除湿|除菌|静音|自动|送风|净化|背景灯|电辅","did": "1511505251","device": "airControl","alias": "大白"}
~~~
<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>字段</b></td>
<td><b>是否必要</b></td>
<td><b>介绍</b></td>
<td><b>示例</b></td>
</tr>
<tr class="row-even">
<td>did</td>
<td>必要</td>
<td>设备id</td>
<td>sn12345、123456</td>
</tr>
<tr class="row-odd">
<td>device</td>
<td>必要</td>
<td>设备类型</td>
<td>airControl，所有类型取值见文档附录说明</td>
</tr>
<tr class="row-even">
<td>alias</td>
<td>必要</td>
<td>设备名称</td>
<td>大白</td>
</tr>
<tr class="row-odd">
<td>modifier</td>
<td>非必要</td>
<td>设备品牌</td>
<td>海尔、海信等</td>
</tr>
<tr class="row-even">
<td>color</td>
<td>非必要</td>
<td>颜色</td>
<td>白色</td>
</tr>
<tr class="row-odd">
<td>location</td>
<td>非必要</td>
<td>地点信息</td>
<td>{"room": "卧室","zone": "二楼","region": "兴园"}</td>
</tr>
<tr class="row-even">
<td>type</td>
<td>非必要</td>
<td>产品类型</td>
<td>空调壁挂式</td>
</tr>
<tr class="row-odd">
<td>description</td>
<td>非必要</td>
<td>设备描述</td>
<td>卧室空调</td>
</tr>
<tr class="row-even">
<td>model</td>
<td>非必要</td>
<td>产品系列</td>
<td>健康卫士系列</td>
</tr>
<tr class="row-odd">
<td>feature</td>
<td>非必要</td>
<td>产品支持的功能模式</td>
<td>制冷|制热|除湿|除菌|静音|自动|送风|净化|背景灯|电辅</td>
</tr>
</tbody>
</table>

② 上传`modifier资源`，该设备对应的品牌信息。
 ~~~   json
{"modifier":"海尔","did":"1511505251","device":"airControl"}
~~~
<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>字段</b></td>
<td><b>是否必要</b></td>
<td><b>介绍</b></td>
<td><b>示例</b></td>
</tr>
<tr class="row-even">
<td>modifier</td>
<td>必要</td>
<td>设备品牌</td>
<td>海尔、海信等</td>
</tr>
<tr class="row-odd">
<td>did</td>
<td>必要</td>
<td>设备id</td>
<td>sn12345、123456</td>
</tr>
<tr class="row-even">
<td>device</td>
<td>必要</td>
<td>设备类型</td>
<td>airControl，所有类型取值见文档附录说明</td>
</tr>
</tbody>
</table>

③ 上传`room资源`，该设备对应的房间信息。
~~~ json
{"room" : "卧室","did":"1511505251","device":"airControl"}
~~~
<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>字段</b></td>
<td><b>是否必要</b></td>
<td><b>介绍</b></td>
<td><b>示例</b></td>
</tr>
<tr class="row-even">
<td>room</td>
<td>必要</td>
<td>房间</td>
<td>卧室、客厅</td>
</tr>
<tr class="row-odd">
<td>did</td>
<td>必要</td>
<td>设备id</td>
<td>sn12345、123456</td>
</tr>
<tr class="row-even">
<td>device</td>
<td>必要</td>
<td>设备类型</td>
<td>airControl，所有类型取值见文档附录说明</td>
</tr>
</tbody>
</table>

④ 上传`zone资源`，该设备对应的空间信息。
~~~ json
{"zone" : "二楼"，"did":"1511505251","device":"airControl"}
~~~
<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>字段</b></td>
<td><b>是否必要</b></td>
<td><b>介绍</b></td>
<td><b>示例</b></td>
</tr>
<tr class="row-even">
<td>zone</td>
<td>必要</td>
<td>空间</td>
<td>二楼、院子、楼顶</td>
</tr>
<tr class="row-odd">
<td>did</td>
<td>必要</td>
<td>设备id</td>
<td>sn12345、123456</td>
</tr>
<tr class="row-even">
<td>device</td>
<td>必要</td>
<td>设备类型</td>
<td>airControl，所有类型取值见文档附录说明</td>
</tr>
</tbody>
</table>

⑤ 上传`region资源`，该设备对应的地理位置信息。
~~~ json
{"region":"兴园","did":"1511505251","device":"airControl"}
~~~
<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>字段</b></td>
<td><b>是否必要</b></td>
<td><b>介绍</b></td>
<td><b>示例</b></td>
</tr>
<tr class="row-even">
<td>region</td>
<td>必要</td>
<td>地理位置信息</td>
<td>兴园小区、深圳湾一号、润府</td>
</tr>
<tr class="row-odd">
<td>did</td>
<td>必要</td>
<td>设备id</td>
<td>sn12345、123456</td>
</tr>
<tr class="row-even">
<td>device</td>
<td>必要</td>
<td>设备类型</td>
<td>airControl，所有类型取值见文档附录说明</td>
</tr>
</tbody>
</table>

⑥ 上传`scene资源`，应用所具有的情景模式信息，以下两个字段皆为必选，且其device字段的值为固定的。
~~~ json
{"scene":"狂欢|安全","device":"group"}
~~~
<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>字段</b></td>
<td><b>是否必要</b></td>
<td><b>介绍</b></td>
<td><b>示例</b></td>
</tr>
<tr class="row-even">
<td>scene</td>
<td>必要</td>
<td>情景模式</td>
<td>休息模式、安全模式</td>
</tr>
<tr class="row-odd">
<td>device</td>
<td>必要</td>
<td>固定值取group，不可设置其他值</td>
<td>group</td>
</tr>
</tbody>
</table>

<div style="display: flex; align-items: center; background-color: #fff3cd; border-left: 6px solid #ffc107; border-radius: 4px; padding: 12px 16px; gap: 8px;">
    <div style="width: 30px; height: 30px; flex-shrink: 0;">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <path d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/>
        </svg>
    </div>
    <div style="flex: 1; line-height: 1.6;">
	<h3 style="margin: 0 0 6px 0; font-weight: 600;">注意：</h3>
        <p style="margin: 0; font-size: 0.95rem;">device字段对应的设备类型取值见附录【附录-官方设备类型】详细说明</p>
        <p style="margin: 0; font-size: 0.95rem;">除scene实体外，其他每个实体在上传每一条智能家居动态实体资源时，都必须包含did与device字段。</p>
        <p style="margin: 0; font-size: 0.95rem;">上传资源数据时应构造json对象，再将其转成字符串，而不是直接使用字符串。</p>
        <p style="margin: 0; font-size: 0.95rem;">scene资源为应用所具备的所有情景模式，是一个单独的实体，并不单独针对某个设备，不跟某个设备进行关联，用户接收到该语义结果后客户端需根据返回的情景模式自行处理。</p>
    </div>
</div>

### 1.3. 自定义动态实体
自定义动态实体是开发者在AIUI平台自定义技能编辑页面自行创建的，具体开发者按照自己创建的实际内容进行确认：
- 上传实体资源名称（res_name）取值：`命令空间.实体资源名称`
~~~ text
OS8565315570.building
~~~
- 上传动态实体维度信息：`用户级`
- 上传动态实体数据结构：json字符串，键值对方式填写主从字段和取值
~~~ json
{"building":"北京国家体育场","alias":"鸟巢"}
~~~

![](/media/202508/2025-08-22_155042_4579370.7826248367123231.png)

![](/media/202508/2025-08-22_155114_1205160.33670231333160816.png)

### 1.4. 动态实体使用说明
由于AIUI平台服务链路升级演进，动态实体服务也有更新，目前根据服务链路不同，主要分两大类：
`传统语义链路` 该服务链路下动态实体使用分三步，详细调用间文档：
- 数据上传
- 云端打包查询
- 生效使用

`大模型或极速链路` 该服务链路下动态实体使用可以两步完成，详细调用见文档：
- 数据上传
- 生效使用

## 2. 附录-官方设备类型
官方智能家居专业版技能，内部支持的家居控制设备类型取值如下：

<table border="0" class="docutils" style="width: 100%;">
<colgroup>
<col width="15%" />
<col width="15%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd">
<td><b>设备类型</b></td>
<td><b>device值</b></td>
</tr>
<tr class="row-even">
<td>空气净化器</td>
<td>airCleaner</td>
</tr>
<tr class="row-odd">
<td>空调</td>
<td>airControl</td>
</tr>
<tr class="row-even">
<td>香薰机</td>
<td>aroma_machine</td>
</tr>
<tr class="row-odd">
<td>浴霸</td>
<td>bathroomMaster</td>
</tr>
<tr class="row-even">
<td>扫地机器人</td>
<td>cleaningRobot</td>
</tr>
<tr class="row-odd">
<td>灶具</td>
<td>cookStove</td>
</tr>
<tr class="row-even">
<td>窗帘</td>
<td>curtain</td>
</tr>
<tr class="row-odd">
<td>电热毯</td>
<td>electric_blanket</td>
</tr>
<tr class="row-even">
<td>风扇</td>
<td>fan</td>
</tr>
<tr class="row-odd">
<td>冰箱</td>
<td>freezer</td>
</tr>
<tr class="row-even">
<td>取暖器</td>
<td>heater</td>
</tr>
<tr class="row-odd">
<td>加湿器</td>
<td>humidifier</td>
</tr>
<tr class="row-even">
<td>灯</td>
<td>light</td>
</tr>
<tr class="row-odd">
<td>晾衣架</td>
<td>racks</td>
</tr>
<tr class="row-even">
<td>油烟机</td>
<td>rangeHood</td>
</tr>
<tr class="row-odd">
<td>插座</td>
<td>slot</td>
</tr>
<tr class="row-even">
<td>开关</td>
<td>switch</td>
</tr>
<tr class="row-odd">
<td>地暖</td>
<td>underFloorHeating</td>
</tr>
<tr class="row-even">
<td>新风系统</td>
<td>ventilation</td>
</tr>
<tr class="row-odd">
<td>洗衣机</td>
<td>washer</td>
</tr>
<tr class="row-even">
<td>热水器</td>
<td>waterHeater</td>
</tr>
<tr class="row-odd">
<td>摄像头</td>
<td>webcam</td>
</tr>
<tr class="row-even">
<td>电水壶</td>
<td>electricKettle</td>
</tr>
<tr class="row-odd">
<td>电饭煲</td>
<td>riceCooker</td>
</tr>
<tr class="row-even">
<td>空调扇</td>
<td>airCooler</td>
</tr>
<tr class="row-odd">
<td>除湿器</td>
<td>deHumidifier</td>
</tr>
<tr class="row-even">
<td>电视</td>
<td>tv</td>
</tr>
<tr class="row-odd">
<td>窗户</td>
<td>window</td>
</tr>
<tr class="row-even">
<td>电磁炉</td>
<td>inductionStove</td>
</tr>
<tr class="row-odd">
<td>智能毛巾架</td>
<td>towelRack</td>
</tr>
<tr class="row-even">
<td>微波炉</td>
<td>microwaveOven</td>
</tr>
<tr class="row-odd">
<td>排风扇</td>
<td>airVent</td>
</tr>
<tr class="row-even">
<td>智能坐便器</td>
<td>toiletLid</td>
</tr>
<tr class="row-odd">
<td>监控相关</td>
<td>homeMonitor</td>
</tr>
<tr class="row-even">
<td>烤箱</td>
<td>oven</td>
</tr>
<tr class="row-odd">
<td>足浴盆</td>
<td>footBath</td>
</tr>
<tr class="row-even">
<td>洗碗机</td>
<td>dishWasher</td>
</tr>
<tr class="row-odd">
<td>咖啡机</td>
<td>coffeeMaker</td>
</tr>
<tr class="row-even">
<td>豆浆机</td>
<td>soymilk</td>
</tr>
<tr class="row-odd">
<td>面包机</td>
<td>toaster</td>
</tr>
<tr class="row-even">
<td>消毒柜</td>
<td>sterilizer</td>
</tr>
<tr class="row-odd">
<td>联动模式</td>
<td>group</td>
</tr>
<tr class="row-even">
<td>蒸汽炉</td>
<td>steamBoiler</td>
</tr>
<tr class="row-odd">
<td>空气盒子</td>
<td>airBox</td>
</tr>
<tr class="row-even">
<td>机顶盒</td>
<td>setTopBox</td>
</tr>
<tr class="row-odd">
<td>门锁</td>
<td>lock</td>
</tr>
</tbody>
</table>