自定义指令集

自定义指令集是企业根据自家硬件配置的私有指令集,与型号一一绑定,是驱动 AIoT 设备真正「动起来」的核心资源。

关于「指令 vs 技能」的边界,详见 指令库总览;想使用平台预置的通用指令,请转至 系统指令。

1. 指令配置的本质:三个正交维度

指令配置的本质洞察是:虽然设备千差万别,但它们的差异只发生在 3 个正交维度上。

维度	回答的问题	对应字段
① 物理归属	这条能力「长在哪儿」?	型号 / 品类 / 部件
② 能力结构	这个硬件能做什么?	控制项 / 操作行为
③ 数据类型	用户传什么形态的值?	开关 / 枚举 / 数值

这三个维度互相正交、互不影响——改一个不会影响另外两个。理解了它们的边界,配置就会变得非常清晰。

2. 核心名词解释

在开始配置之前,先建立统一的术语认知,避免配置错位:

概念	说明	示例
型号	在 型号库 中创建,描述一个具体产品的物理属性	智能台灯 097、洗衣机 086
品类	一类产品的统称	台灯、洗衣机、机器人
部件	一个型号内部可独立控制的子结构	主灯/氛围灯、上桶/下桶
指令集	在「资源管理 → 指令库」中创建,描述某型号支持的控制能力;创建时必须绑定一个型号	台灯标准指令集
指令(控制项)	硬件设备的一个可控对象 + 它支持的若干操作行为	音量控制、亮度控制
指令(非控制项)	机器人动作等需要扩展性和特殊逻辑的指令	机械臂前进 30 厘米
产品	在 产品管理 中创建,绑定型号后会自动带入该型号的指令集;同时需开启 AIoT 指令 技能方可启用设备控制链路	—

3. 维度详解

维度 ① · 物理归属——回答「这条能力长在哪儿」

每条指令都必须钉在一台具体硬件、甚至一个具体部件上。例如:

• 同样是「开关」,装在洗衣机上和装在灯上,作用对象完全不同;
• 同样是「杀菌」,作用在双筒洗衣机的「上筒」还是「下筒」,是两件事。

归属链:

型号 (品类、部件清单)
    ↓
指令集 (指向某个型号)
    ↓
指令 (隶属指令集;可选 parts 限定作用部件)

实操要点:先把「型号 / 品类 / 部件」在 型号库 中沉淀清楚,再去建指令集;一旦部件清单变化,下游所有指令的「作用部件」配置都可能受影响。

维度 ② · 能力结构——回答「这个硬件能做什么」

每台设备都有一组可控对象(亮度、温度、音量、模式……),每个可控对象都支持若干动作(打开、关闭、设置、查询、调高、调低)。

关键洞察:用户嘴里的「动作动词」 ≠ 硬件层面的「独立指令」。

• 「调大音量」和「调小音量」,在语言上是两个动作;
• 在硬件层面,它们是同一个能力(音量)的两种调节方向。

✅ 正确做法:1 个控制项(音量)+ 4 个操作行为(设置 / 查询 / 调高 / 调低) ❌ 错误做法:拆成 4 条独立指令

字段结构:

能力结构
├── 控制项
│   ├── name         指令控制项名称(中文)
│   ├── controlCode  控制项编码(全英文)
│   └── controlAlias 控制项别名
└── 操作行为
    ├── opCode   set / query / increase / decrease / on / off
    ├── opName   设置 / 查询 / 调高 / 调低 / 打开 / 关闭
    └── examples 用户口语例句列表

维度 ③ · 数据类型——回答「用户传什么形态的值」

三种数据类型的选择原则——问自己:能否用一句话描述「目标值」?

能否用一句话描述目标值?
├─ 不能,只有「开 / 关 / 暂停」这种二元(或三元)状态 → SWITCH 开关型
│    例:制氧机开关、分子筛开关、提示音开关
├─ 能,目标值是"数字 + 单位",有最小/最大值范围     → NUMERIC 数值型
│    例:流量档位 15、温度 1630℃、定时 5~120 分钟
└─ 能,目标值是"有限的标签集合",没有数学大小关系   → 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 协议值,可选「打开/关闭」行为
• ENUM → 必须列枚举清单,可选「设置/查询」行为
• NUMERIC → 必须填 min/max/单位/步长,可选「设置/查询/调高/调低」行为

4. 配置流程总览

step1  在「型号库」登记型号
       ↓ (沉淀品类 / 部件 / IoT 平台)
step2  在「指令库」创建指令集,并与型号绑定
       ↓ (指令集即"这台型号能听懂的命令清单")
step3  在指令集下新建指令
       ↓ (选对类型 → 配字段 → 写例句)
step4  在「产品管理」中创建产品,绑定型号
       ↓ (开启「AIot 指令」即可加载指令)
       发布产品

5. 详细操作步骤

5.1 创建型号

进入【资源管理 > 型号库】,点击【新建型号】:

• 产品型号名称:自定义;
• 产品品类:即一类产品的统称,不确定时可选「通用」;
• 产品部件:一个型号内部可独立控制的子结构(例如主灯、氛围灯);若无相关需求可不填;
• IoT 平台:若该设备的指令需要经 IoT 平台转发,则需要选择对应的 IoT 平台;若指令直达设备,可不选;
• 指令描述:描述产品型号的主要能力和属性。

更详细的字段说明,请参见 型号库。

5.2 创建指令集

进入【资源管理 > 指令库】,点击【新建】:

• 指令集名称:自定义;
• 产品型号:选择唯一产品型号(一个指令集只能绑定一个型号;若需多型号复用,请使用 5.4 复制指令集);
• 指令集描述:30 字以内;
• 是否需要执行反馈:
  • 开启 → 硬件执行完指令后会进行语音播报或文字回复;
  • 关闭 → 硬件仅执行动作,不发声(静默执行,详见 静默指令)。

5.3 新建指令

5.3.1 控制项指令

适用于设备的标准功能点:开关、亮度、音量、温度、模式、风速、档位等可被抽象为「开关切换 / 档位选择 / 数值调节」的通用场景。

配置字段:

• 控制项名称:如「音量」「亮度」;
• 控制项别名:兼容不同系统或场景的命名习惯;
• 控制项编码(controlCode):全英文,可包含 - / _;
  • ⚠️ 同一个型号下指令的编码不能重复!
• 指令下发方式:
  • 端侧:指令不经云端平台直接发往设备;
  • IoT 平台:指令经过 IoT 平台转发至设备。
• 作用部件:可指定该指令仅作用于某些部件;若产品无部件或该指令作用于所有部件,可不选;
• 数据类型:SWITCH / ENUM / NUMERIC(详见维度 ③);
• 操作行为:从设置 / 查询 / 调高 / 调低中勾选,一条指令可包含多个操作行为;

自定义操作行为

当预设的 4 种操作行为无法满足业务需求时(如「开始」「暂停」「切换」「重置」等),可点击操作行为列表最后的【+ 添加自定义操作行为】按钮,动态添加自定义操作行为。

• ⚠️ 操作行为需与设备物模型 / IoT 接口定义的动词完全一致。例如:设备物模型为「开始测量」,则填写「开始」。名称不一致将导致设备无法识别指令。

• ⚠️ 当数据类型为开关时,系统操作行为的「设置」即等于「打开」「关闭」,无需重复设置相关自定义操作行为。

• 例句:点击操作行为后的【操作例句】,定义用户说什么话会触发该指令;

• 参数配置(随数据类型而变):

  • 开关型:开关状态映射(如 {"on": "ON", "off": "OFF"}),值必须与设备协议完全一致;
  • 枚举型:枚举项编码(通常为数字,建议按顺序)、枚举项名称、枚举项别名;
  • 数值型:最小值 / 最大值 / 间距 /默认值 / 单位 / 单位别名。
    • 「间距」是指默认步长,即用户 query 为「调低一点」时那个「一点」。

5.3.2 非控制项指令

适用于非标准功能:机器人动作、机械臂操作等私有协议指令。用户可自定义指令名称、识别规则和参数槽位。

配置字段:

• 指令名称;
• 指令编码:全英文;
• 识别提示词:用于定义指令的触发规则(「什么时候触发」+ 「什么时候不触发」);
• 操作行为:非控制项指令仅支持「设置」一种;
• 例句:作为指令识别的参考;
• 槽位:用户输入中需要提取的关键参数。
  • 字段名:全英文;
  • 槽值类型:数值 / 文本 / 枚举;
  • 槽值提取提示词:引导系统从用户输入中提取槽值的关键词或规则。

举例:机器人前进指令,识别提示词 = 「当用户希望机器人向前移动一定距离时触发,常见表述如『往前走』『前进 N 米』」,槽位 distance = 数值,提示词 = 「提取移动距离,单位换算为厘米」。

5.4 复制指令集

由于一个指令集只能绑定一个产品型号,若想实现不同型号复用一个指令集,可通过【复制指令集】实现。

5.5 使用指令

• 新版(推荐):2026 年 5 月 21 日版本更新后,指令集直接绑定产品型号。创建产品时绑定的「产品型号」可决定当前产品可用的指令范围,该型号下的所有指令集会被自动带入产品智能体中。
  • ⚠️ 由产品型号自动带入的指令集,必须在产品-智能体下开启 AIoT 指令 后才能生效。
• 旧版兼容:在产品智能体编辑页面点击【添加指令】,可选择系统指令或 2026 年 5 月 21 日前创建的自定义指令集。

5.6 AIot指令

在智能体编辑页面,开启 AIot 设备控制 后,可使用当前产品型号下所有指令集:

5.6.1 任务规划器开关

规划器主要解决复杂任务的拆解、多轮澄清与参数提取。

• 何时关闭：当产品交互足够简单——例如只做单步控制、指令表达明确、无需澄清或串联多个动作时，可以关闭规划层。关闭后链路仅走意图层 + 执行层，少了一层处理，响应更快、也更稳定可控；相应地会失去自动拆解与追问澄清的能力。
• 何时开启：交互越复杂越应开启规划层。

💡 建议按产品实际复杂度选择：交互越复杂越应开启规划层，越简单直接则越适合关闭。

5 垫句

垫句是设备执行指令前后播报的一句话或音效,用于承接对话、提升自然感(如「好的,马上为您打开」)。

• 垫句与 静默指令 存在联动关系:

指令集「执行反馈开关」	垫句列表	最终表现
开启	有内容	设备执行 + 播报垫句 + 播报执行反馈
开启	空	设备执行 + 播报执行反馈
关闭	有内容	设备执行 + 播报垫句(无执行反馈)
关闭	空	完全静默(仅执行动作)

6. 配置示例

示例 A(控制项):智能台灯亮度调节

• 控制项名称:亮度
• 控制项编码:brightness
• 数据类型:NUMERIC(数值型)
• 参数:最小值 0 / 最大值 100 / 单位 「%」/ 间距 10 / 默认值 50
• 操作行为:设置、查询、调高、调低
• 例句:
  • 设置 → 「把灯调到 80%」「亮度设为 60」
  • 查询 → 「现在亮度是多少」
  • 调高 → 「再亮一点」「调亮 20」
  • 调低 → 「暗一点」

示例 B(非控制项):机器人前进

• 指令名称:前进
• 指令编码:move_forward
• 识别提示词:「当用户希望机器人向前移动一定距离时触发,常见表述如『往前走』『前进 N 米』『向前走 XX 厘米』;若用户明确说『后退』『左转』等其他方向,不触发本指令。」
• 例句:「往前走 30 厘米」「前进两米」「向前一点」
• 槽位:
  • distance(数值型):提取移动距离,统一换算为厘米。

7. 批量测试

配置完成后,进入指令集详情页可对指令进行批量测试,以验证 LLM 对指令的识别准确率。

核心机制:

• 泛化倍数:平台会基于每个操作行为的例句,自动扩充为若干条测试 query(首次默认扩充 5 倍);
• 整体准确率:一次批量测试跑完后,汇总所有 query 的识别命中率,作为该指令集的整体质量指标;
• 明细列表:可下钻到每条 query 的识别结果(命中的指令 / 操作行为 / 参数值),快速定位错误 case。

优化流程(详见 指令的测试和调优):

1. 跑批测试     → 得到整体准确率 + 明细
2. 归因错误 case → 是例句不够 / 数据类型选错 / 编码冲突 / prompt 冲突?
3. 修改指令配置  → 补例句 / 换类型 / 拆指令
4. 版本化保存    → 记录本次配置差异
5. 回归跑批      → 对比准确率是否上升,是否引入新的错误 case

8. 相关链接

• 上级导航:指令库总览
• 前置资源:型号库 · AIoT 指令 · 产品管理·技能配置
• 进阶主题:
  • 定时指令——让指令按时间自动触发
  • 指令的测试和调优——三阶验证 + 归因决策树
  • 静默指令——两开关联动实现无声执行
  • 设备状态查询与冲突判断——查询类指令与状态冲突场景的两条实现链路