主题
指令配置
指令配置是指仅通过控制项、操作行为、数据类型、参数约束等字段描述设备能力,无需编写提示词。
优先使用指令配置;只有当能力表达不了时,才逐级升到 提示词编写 。
1. 指令配置的本质:三个正交维度
指令配置的本质洞察是:虽然设备千差万别,但它们的差异只发生在 3 个正交维度上。
| 维度 | 回答的问题 | 对应字段 |
|---|---|---|
| ① 物理归属 | 这条能力「长在哪儿」? | 型号 / 品类 / 部件 |
| ② 能力结构 | 这个硬件能做什么? | 控制项 / 操作行为 |
| ③ 数据类型 | 硬件接收什么形态的值? | 数据类型/参数配置 |
2. 核心名词解释
在开始配置之前,先建立统一的术语认知,避免配置错位:
| 概念 | 说明 | 示例 |
|---|---|---|
| 型号（device) | 在创建产品的时候填写产品型号字段,描述一个具体产品的物理属性;产品创建后不可改 | 智能台灯 097、洗衣机 086 |
| 品类(domain) | 一类产品的统称 | 台灯、洗衣机、机器人 |
| 部件 | 一个型号内部可独立控制的子结构，仅需为多部件设备填写，单部件或无细分结构的产品可留空该字段。 | 主灯/氛围灯、上桶/下桶 |
| 指令集 | 描述某型号支持的控制能力合集 | 台灯标准指令集 |
| 指令(控制项) | 硬件设备的一个可控对象 + 它支持的若干操作行为 | 开关控制、音量控制、亮度控制 |
| 指令(非控制项) | 机器人动作等需要扩展性和特殊逻辑的指令 | 机械臂前进 30 厘米 |
3. 维度详解
维度 ① · 物理归属——回答「这条能力长在哪儿」
每条指令都必须钉在一台具体硬件、甚至一个具体部件上。例如:
- 同样是「开关」,装在洗衣机上和装在灯上,作用对象完全不同;
- 同样是「杀菌」,作用在双筒洗衣机的「上筒」还是「下筒」,是两件事。
归属链:
型号 (品类、部件)
↓
指令集
↓
指令实操要点:在创建产品时将「型号 / 品类 / 部件 / IOT平台」沉淀清楚;一旦产品上的部件字段变化,下游所有指令的「作用部件」的配置都可能受影响。
💡 产品型号建后不可改:新建产品时手写产品型号、品类、IOT 平台、部件;型号一经创建即锁定,编辑态不可修改。
维度 ② · 能力结构——回答「这个硬件能做什么」
每台设备都有一组可控对象(亮度、温度、音量、模式……),每个可控对象都支持若干动作(打开、关闭、设置、查询、调高、调低)。
关键洞察:用户嘴里的「动作动词」 ≠ 硬件层面的「独立指令」。
- 「调大音量」和「调小音量」,在语言上是两个动作;
- 在硬件层面,它们是同一个能力(音量)的两种调节方向。
✅ 正确做法:1 个控制项(音量)+ 4 个操作行为(设置 / 查询 / 调高 / 调低) ❌ 错误做法:拆成 4 条独立指令
字段结构:
能力结构
├── 控制项
│ ├── name 指令控制项名称(中文)
│ ├── controlCode 控制项编码(全英文)
│ └── controlAlias 控制项别名
└── 操作行为
├── opCode set / query / increase / decrease / on / off
├── opName 设置 / 查询 / 调高 / 调低 / 打开 / 关闭
└── examples 用户口语例句列表维度 ③ · 数据类型——回答「硬件接收什么形态的值」
三种数据类型的选择原则——问自己:指令「目标值」的形态?
目标值的形态?
├─ 只有「开 / 关 / 暂停」这种二元(或三元)状态 → SWITCH 开关型
│ 例:打开制氧机开关、打开分子筛开关、打开提示音开关
├─ 目标值是"数字 + 单位",有最小/最大值范围 → NUMERIC 数值型
│ 例:流量档位设置成15、温度设置成30℃
└─ 目标值是"有限的标签集合",没有数学大小关系 → ENUM 枚举型
例:洗涤模式(智能洗 / 快洗 / 羊毛洗)、风量档位(强 / 中 / 弱)ENUM 与 数值 易错点剖析:
| 用户说话方式 | value 装什么 | 应该选 | 原因 |
|---|---|---|---|
| 「调到 3 档」 | 标签 3(绝对目标) | ENUM 或 数值 | 取值在有限集 {1,2,3,4,5},两者都能承载 |
| 「调到最大 / 最小」 | 归一后的标签 5 / 1 | ENUM 或 数值 | 仍落在有限集 |
| 「调高 1 档 / 再大 2 档」 | 1 / 2 / …任意增量 | 必须用 数值 | value 是开放正整数集,ENUM 无法列全 |
一句话判断法:有没有「调高 / 调低 相对调节任意值」?
- 有 → 数值(value 要装增量,ENUM 装不下任意正整数)
- 没有 → 都可以
三种类型一旦敲定,平台会自动派生参数配置:
- SWITCH → 配 on/off 或 0/1 需要与预期协议值保持一致,
- ENUM → 必须列枚举清单，枚举项别名为枚举值的其他同义词
- NUMERIC → 填 min/max/单位/间距,其中间距是指当用户query为“调高一点”时的那个“一点”的默认值。
4. 配置流程总览
step1 创建产品时定义硬件信息
↓ (沉淀型号 / 品类 / 部件 / IoT 平台)
step2 开启AIOT指令开关，新建指令集
↓ (指令集即"这台设备能听懂的命令清单")
step3 在指令集下新建指令
↓ (选择控制项/非控制项指令 → 配字段 → 写例句)
step4 调试与修改
↓
发布产品5. 详细操作步骤
5.1 新建指令集
开启AIOT指令开关，提示词选择「根据指令集生成」，点击新建指令集
- 指令集名称:自定义;
- 是否需要执行反馈:开启后，硬件在执行完指令后会进行语音播报或文字回复（如：“已为您关闭台灯”）；关闭则仅执行动作，不发出声音;
5.2 新建指令
5.2.1 控制项指令
适用于设备的标准功能点:开关、亮度、音量、温度、模式、风速、档位等可被抽象为「开关切换 / 档位选择 / 数值调节」的通用场景。
配置字段:
控制项名称:如「音量」「亮度」;
控制项别名:兼容不同系统或场景的命名习惯;
控制项编码(controlCode):全英文,可包含
-/_;- ⚠️ 同一个产品下指令的编码不能重复!
指令下发方式:
- 端侧:指令不经云端平台直接发往设备;
- IoT 平台:指令经过 IoT 平台转发至设备。
作用部件:可指定该指令仅作用于某些部件;若产品无部件或该指令作用于所有部件,可不选;
数据类型:SWITCH / ENUM / NUMERIC(详见维度 ③);
操作行为:从设置 / 查询 / 调高 / 调低中勾选,一条指令可包含多个操作行为;
自定义操作行为: 当预设的 4 种操作行为无法满足业务需求时(如「开始」「暂停」「切换」「重置」等),可点击操作行为列表最后的【+ 添加自定义操作行为】按钮,动态添加自定义操作行为。
⚠️ 操作行为需与设备物模型 / IoT 接口定义的动词完全一致。例如:设备物模型为「开始测量」,则填写「开始」。名称不一致将导致设备无法识别指令。
⚠️ 当数据类型为开关时,系统操作行为的「设置」即包含了「打开」「关闭」行为,无需重复设置相关自定义操作行为。
例句:点击操作行为后的【操作例句】,定义用户说什么话会触发该指令。例句支持配置正例和反例,帮助模型判断「什么时候进入这个指令、什么时候不要进入」:
- 正例:用户这样说应当命中本指令(如「打开灯」);
- 反例:用户这样说不应命中本指令,即使字面高度相似(如给「关闭按摩」配置反例「关闭按摩枕」)。
- 反例的典型场景——区分相似指令:假设有两条指令,一个控制项是「按摩」,另一个控制项是「按摩枕」。当用户说「关闭按摩枕」时,由于字面包含「按摩」,很容易误触发「关闭按摩」。此时给「关闭按摩」配置一条反例「关闭按摩枕」(这句话不要进入本指令),再给「关闭按摩枕」配置一条正例「关闭按摩枕」(这句话应命中本指令),两者配合模型即可正确区分。
参数配置(随数据类型而变):
- 开关型:开关状态映射(如
{"on": "ON", "off": "OFF"}),值必须与设备协议完全一致; - 枚举型:枚举项编码(通常为数字,建议按顺序)、枚举项名称、枚举项别名;
- 数值型:最小值 / 最大值 / 间距 / 默认值 / 单位 / 单位别名。
- 「间距」是指默认步长,即用户 query 为「调低一点」时那个「一点」。
- 开关型:开关状态映射(如
5.3.2 非控制项指令
适用于非标准功能:机器人动作、机械臂操作等私有协议指令。用户可自定义指令名称、识别规则和参数槽位。
配置字段:
- 指令名称;
- 指令编码:全英文;
- 识别提示词:用于定义指令的触发规则(「什么时候触发」+ 「什么时候不触发」);
- 操作行为:非控制项指令仅支持「设置」一种;
- 例句:作为指令识别的参考;
- 槽位:用户query中需要提取的关键参数。
- 字段名:全英文;
- 槽值类型:数值 / 文本 / 枚举;
- 槽值提取提示词:引导系统从用户输入中提取槽值的关键词或规则。
举例:机器人前进指令,识别提示词 = 「当用户希望机器人向前移动一定距离时触发,常见表述如『往前走』『前进 N 米』」,槽位 distance = 数值,提示词 = 「提取移动距离,单位换算为厘米」。
6. 配置示例和下发协议示例
以下四个示例覆盖「IOT 平台转发 / 端侧直连」× 「控制项 / 非控制项」的典型配置方式,可对照参考。
示例一:IOT 平台转发 · 开关类控制项(打开灯)
预期下发协议
json
{
"kw": {
"intents": [
{ "intent": "打开灯", "domain": "灯" }
]
}
}配置方式
- 创建产品:品类选择灯(品类即协议中的
domain,必须与协议值完全一致,否则无法下发);IOT 平台选择小家;进入产品后打开 AIOT 开关,新建指令集 → 新建控制项指令; - 操作行为 = 灯(而非「开关」),因为预期协议中
intent = 打开灯;- 说明:
intent = 操作行为 + 控制项名称;
- 说明:
- 控制项编码:自定义,同一型号下不重复即可;
- 指令下发方式:选择 IOT 平台;
- 数据类型:开关;
- 操作行为勾选**「设置」**,添加例句「打开灯」——即当用户 query = 打开灯时下发该指令。
💡 数据类型为开关时,勾选「设置」即同时包含打开 + 关闭两种行为。
示例二:IOT 平台转发 · 带部件的数值类控制项(调高上灯亮度)
预期下发协议
json
{
"kw": {
"intents": [
{
"intent": "调高上灯亮度",
"domain": "灯",
"value": "10",
"unit": "度"
}
]
}
}配置方式
- 创建产品:品类选择灯(=
domain,必须与协议值完全一致);IOT 平台选择小家;部件添加「上灯」;进入产品后打开 AIOT 开关,新建指令集 → 新建控制项指令; - 当产品有部件时,
intent = 操作行为 + 部件 + 控制项名称; - 控制项名称 = 亮度;控制项编码:自定义;
- 指令下发方式:IOT 平台;作用部件:选择上灯;
- 数据类型:数值;操作行为:调高;例句:「上灯亮度调高 10 度」;
- 最大值、最小值、间距、单位、单位别名、默认值,按硬件物模型或业务规则自行配置。
示例三:端侧直连 · 数值类控制项(设置色温)
不经过 IOT 平台转发,由端侧直接接收指令。
预期下发协议
json
{
"instructions": [
{
"action": "temp",
"args": { "type": "set", "value": 40 },
"desc": "色温设置为40度"
}
]
}其中 action = 控制项编码,故端侧直连设备的控制项编码必须严格按预期接收协议来写;type = 操作行为;value = 从 query 中提槽出的数值。
配置方式
- 创建产品:品类选择灯,IOT 平台字段留空即可;
- 控制项名称 = 色温;控制项编码 = temp;
- 下发方式勾选端侧;数据类型:数值;操作行为:设置;
- 例句:「色温调整为 80」(任意数值)。
示例四:端侧直连 · 非控制项指令(机器人前进 1 米)
预期下发协议
json
{
"instructions": [
{
"action": "robot_move_forward",
"args": { "distance": 100 },
"desc": "往前走1米"
}
]
}配置方式
- 新建指令时选择非控制项;
- 指令名称:前进;指令编码:move_forward;
- 识别提示词:「当用户希望机器人向前移动一定距离时触发,常见表述如『往前走』『前进 N 米』『向前走 XX 厘米』;若用户明确说『后退』『左转』等其他方向,不触发本指令。」
- 例句:「往前走 30 厘米」「前进两米」「向前一点」;
- 槽位:
distance(数值型)——提取移动距离,统一换算为厘米。