主题
查询指令
查询类指令指用户想了解设备当前状态的指令,如「当前灯的亮度是多少」「灯现在是什么模式」。 与普通控制指令(解析意图 → 下发指令)不同,查询类指令必须先拿到设备的实时状态,模型才能组织回复。
设备状态从哪里来,取决于你的设备是接入 小家 IoT 还是 端侧直连设备,两者需要做的事不同。
1. 对接小家 IoT:配置枚举翻译
小家 IoT 的查询类指令,由模型调用 iot_get_device_shadow 工具查询设备影子状态。小家返回值示例:
json
{
"data": {
"扬声器音量": 50,
"灯开关": false,
"灯色温": 4500,
"灯上灯亮度": 50,
"灯照明模式": 0,
"灯延时关灯时长": 15,
"灯夜灯伴睡开关": false
}
}返回值中有三类数据:
- 数值类(如
"灯上灯亮度": 50)、开关类(如"灯夜灯伴睡开关": false):模型可以直接理解含义并回复; - 枚举类(如
"灯照明模式": 0):模型无法直接理解0代表什么,需要参考物模型的定义。
因此,对接小家的查询类指令,核心要做的一件事就是:在 iot_get_device_shadow 工具的「运行时配置」里,通过配置翻译,告诉模型每个枚举 value 编码对应的含义。
配置翻译的流程
第一步:获取影子设备的实际返回值
在调试窗中填写正确的 did,输入一个查询类指令,查看 iot_get_device_shadow 工具的返回内容。
第二步:去小家 IoT 查看物模型,获取枚举项编码及其含义
例如:灯照明模式:0 普通照明;1 恒照;2 睡眠。
第三步:参考运行时配置,写好翻译示例模板
在 iot_get_device_shadow 工具的运行时配置中,用 templateRender 做枚举映射与模板渲染:
json
{
"postHandler": "templateRender",
"templateRender": {
"mappings": {
"light_mode_map": {
"0": "普通照明",
"1": "恒照",
"2": "睡眠"
}
},
"template": "> **当前灯状态**\n> 照明模式={{ light_mode_map[data['灯照明模式'] | string] if data['灯照明模式'] is defined else '未知' }}\n> 色温={{ data['灯色温'] if data['灯色温'] is defined else '--' }} K\n> 上灯亮度={{ data['灯上灯亮度'] if data['灯上灯亮度'] is defined else '--' }}"
}
}mappings:声明枚举编码到中文含义的映射表(如light_mode_map);template:渲染最终回复文本,枚举字段通过映射表翻译,数值 / 开关字段直接取值,并用is defined else兜底缺失字段。
第四步:借助模型生成运行时配置
可以把以下内容一起给到模型,让它帮你产出运行时配置:
- 当前接口返回值;
- 参考示例模板(即第三步的格式);
- 补充的枚举信息(即第二步的编码含义);
- 让模型输出当前接口返回值对应的运行时配置;
- 根据测试返回值,交给模型继续迭代优化配置。
2. 对接端侧直连设备:主动上报状态
若设备为端侧直连(不经 IoT 平台),平台默认不掌握设备的实时状态。此时查询类指令要能正常工作,端侧需要主动上报设备状态:
- 端侧需在周期性、以及状态发生变更时,主动上报设备当前状态;
- 只有端侧上报了状态,模型才能拿到设备当前状态,进而回答查询类指令;
- 若端侧未上报,平台无从获知设备状态,查询类指令将无法正确工作。
状态上报通过端侧上行事件 CLIENT_UPDATE_CHAT_CONTEXT(主动更新对话上下文)完成,将设备状态放入 kvData.status 中上报。
内容示例:
json
{
"code": 200,
"requestId": "1",
"mid": "1",
"contentType": "ACTIVITY",
"content": {
"activityType": "CLIENT_UPDATE_CHAT_CONTEXT",
"effectiveTimeMinutes": 5,
"kvData": {
"自定义字段名": "自定义值"
}
}
}⚠️ kvdata必须上报文本,不要用标识 / 编码类内容,否则模型无法理解。
- ✅ 正确:
开关 = 开、模式 = 手动模式- ❌ 错误:
switch = 1、mode = 0x02
事件字段的完整说明见:CLIENT_UPDATE_CHAT_CONTEXT(主动更新对话上下文)。
在调试窗模拟端侧事件上报
调试窗支持模拟端侧事件上报。无需连接真实设备,即可在调试过程中提供设备状态或闹钟列表数据。
适用场景
- 验证 AIOT 设备控制中的查询类指令,例如查询设备当前的开关、模式或亮度;
- 验证闹钟技能中的查询闹钟能力,例如查询已有闹钟的数量和内容。
操作步骤
在调试窗中打开模拟事件上报;
根据验证场景选择设备状态上报或闹钟列表上报模版;
按需修改事件 payload。例如,模拟设备状态:
json{ "status": "模式=睡眠模式,开关=开" }模拟闹钟列表:
json{ "alar": [ { "id": "a_01", "type": "normal_alarm", "enabled": true, "time": { "hour": 7, "minute": 0 }, "date": "2026-07-28", "repeat": { "mode": "weekly", "weekdays": [1, 2, 3, 4, 5] }, "event_content": "交报告" } ] }点击上报;
上报成功后,在调试窗中输入对应的查询语句,检查回复是否与上报内容一致。
上报的数据将在有效时间内（5分钟）作为端侧设备数据参与对话。通过修改 payload,可以快速验证不同设备状态下的查询结果。
验证结果
- AIOT 查询类指令:AIOT指令中配置相关查询指令，且上报设备状态后,询问"当前灯是什么模式",检查回复是否与上报状态一致;
- 闹钟技能查询:技能列表中添加闹钟技能，且上报闹钟列表后,询问"我有几个闹钟",检查闹钟技能是否正确读取列表。
⚠️ 该功能只能验证下发到端侧的查询指令和闹钟技能的闹钟列表查询两个场景,不能覆盖下发到 IoT 平台的查询指令(小家 IoT 通过
iot_get_device_shadow查询影子状态,不依赖端侧上报)。如果事件 payload 为空、格式不正确或缺少设备身份信息,请根据调试窗返回的错误信息修改后重新上报。
3. 一览对照
| 设备类型 | 状态从哪来 | 你需要做什么 |
|---|---|---|
| 小家 IoT | iot_get_device_shadow 查影子状态 | 在工具运行时配置中,配置枚举 value 的翻译 |
| 端侧直连设备 | 端侧主动上报 | 周期性 + 状态变更时,以文本形式上报设备状态 |