前言
在语音产品开发过程中，命令词配置是最基础也是最容易出现问题的一环。许多开发者遇到的问题并非模组硬件故障，而是配置细节处理不当。本文基于近期技术交流群中的五个真实案例，系统讲解常见命令词配置问题的排查思路与解决方案。
案例一：免唤醒命令词无响应的完整排查
问题现象
用户反馈：设置好的免唤醒命令词完全没有反应，但唤醒词可以正常响应。
根因分析
根据官方文档，命令词不能包含标点符号（空格、逗号、句号等）。这是导致免唤醒词失效的最常见原因。
官方规范：
- 命令词中不能有空格、逗号、句号等标点符号
- CI系列多单词命令词需用中横线
-连接（如OPEN-DOOR） - SU系列多单词命令词用空格分隔（如
open door）
排查步骤
检查命令词格式
- 确认命令词中是否包含标点符号
- 检查是否有不必要的空格
验证词条有效性
- 将疑似有问题的命令词复制到回复语中
- 如果能播报说明词条本身有效，问题在配置
对比测试
- 测试一个简单的命令词（如"打开"）验证功能
- 确认是词条问题还是其他配置问题
解决方案
| 错误示例 | 正确写法 |
|---|---|
썬셰이드-열어（混合语言） | 遮阳帘打开 或 sunshade open |
打 开 台灯（含空格） | 打开台灯 |
打开台灯，（含逗号） | 打开台灯 |
CI系列英文命令词格式规范
正确格式：HELLO-AIR-CONDITIONING
错误格式：HELLO AIR CONDITIONING # SU系列才用空格
错误格式：hello_air_conditioning # 不用下划线案例二：防误识别词对免唤醒词无效问题
问题现象
用户配置了防误识别词"please open"，但免唤醒词"please open oven"仍然能被误触发"please open"。
根本原因
防误识别词的工作原理是降低匹配度，而非完全屏蔽。当目标命令词与防误识别词发音差异较大时，防误效果有限。
技术原理
用户说的：please open oven
目标命令：please open oven（相似度100%）
防误词条：please open（相似度约60%）在这种情况下，"please open oven"与目标命令的相似度远高于防误词条，所以防误效果有限。
三种解决方案
方案一：添加更多防误识别词
please open | peace open | pleas open方案二：调整特定命令词阈值
- 在平台中找到该命令词的"特定命令词阈值"设置
- 适当调低灵敏度（数值调大）
方案三：优化命令词设计
原命令：please open oven
优化后：turn on oven / activate oven配置检查清单
- [ ] 防误识别词是否包含相似发音的多个变体
- [ ] 是否考虑了口音差异（如peace vs please）
- [ ] 命令词本身是否与日常用语过于接近
- [ ] 是否尝试过调整特定命令词阈值
案例三：舵机只往一个方向转动的360°/180°识别问题
问题现象
用户使用SG90舵机，按教程配置后，命令执行有回复但舵机只往一个方向转动然后停止，无法实现来回摇摆。
根本原因
SG90舵机有180度和360度两种版本，用户可能购买了360度版本而使用的是180度教程配置。
区分方法
| 特征 | 180度舵机 | 360度舵机 |
|---|---|---|
| 转动范围 | 有机械限位 | 可连续旋转 |
| 控制方式 | PWM控制角度 | PWM控制速度/方向 |
| 典型应用 | 机械臂、云台 | 车轮、传送带 |
| 识别方法 | 转到限位会卡住 | 可以整圈转动 |
解决方案
确认舵机类型后再配置：
- 手动测试：用手转动舵机，180度版本有机械限位
- 观察外观：部分360度版本会有标识
- 更换配置：确认类型后使用对应的配置方法
PWM配置对比
180度舵机：
- PWM周期：20ms（50Hz）
- 控制范围：0.5ms~2.5ms高电平
- 对应角度：0°~180°
360度舵机：
- PWM周期：20ms（50Hz）
- 1.5ms高电平：停止
- <1.5ms：一个方向旋转
- >1.5ms：另一个方向旋转案例四：UART0与UART1串口选择困惑
问题现象
用户疑问："UART0是烧录脚，UART1是发送脚，所以控制详情中应该配置为UART1吗？"
正确理解
UART0和UART1都可以配置为串口输出，烧录口配置只影响日志输出，不影响烧录功能。
引脚功能对照
| 引脚 | 主要功能 | 备注 |
|---|---|---|
| UART0 | 烧录+调试日志 | B6/B7（SU-03T） |
| UART1 | 通用串口通信 | 可配置为输出/输入 |
| 烧录口配置 | 选择日志输出串口 | 不影响烧录功能 |
配置建议
- 调试阶段：配置UART0为烧录口，方便查看日志
- 应用阶段：根据实际通信需求选择UART0或UART1
- 双串口需求：部分模组支持UART0和UART1同时使用
案例五：串口输入条件判断配置位置
问题现象
用户反馈："不知道在哪里写条件，比如当输入的16进制数为多少时触发一个动作。"
正确配置流程
串口输入触发的条件判断不在串口输入配置中，而是在命令词的条件判断中配置。
完整配置步骤
启用串口输入
版本配置 → 事件触发 → 添加事件触发 触发类型：串口输入 串口选择：UART1 消息号：01配置参数赋给变量
控制详情 → 添加控制 → 参数赋给变量 输入参数：消息号01的参数值 目标变量：var1添加条件判断
控制详情 → 添加控制 → 条件判断 条件：当变量var1等于0x01时 执行动作：GPIO输出/串口输出等
数据帧格式
输入格式：AA 55 [消息号] [参数值] 55 AA
示例：AA 55 01 01 55 AA（消息号01，参数值01）通用排查流程图
发现问题
│
├─→ 命令词无响应？
│ ├─→ 检查标点符号
│ ├─→ 验证词条有效性
│ └─→ 对比测试简单命令
│
├─→ 误识别问题？
│ ├─→ 检查命令词相似度
│ ├─→ 添加防误识别词
│ └─→ 调整特定命令词阈值
│
├─→ 硬件不工作？
│ ├─→ 确认硬件型号
│ ├─→ 检查接线是否正确
│ └─→ 验证配置参数匹配
│
└─→ 找不到配置位置？
├─→ 参考官方文档
├─→ 查看配置流程图
└─→ 咨询技术支持命令词配置速查表
中文命令词规范
| 项目 | 规范 | ||
|---|---|---|---|
| 长度 | 2-6个字 | ||
| 禁用字符 | 空格、逗号、句号、标点 | ||
| 多条命令 | 用` | `分隔，无空格 | |
| 示例 | `打开台灯\ | 开灯\ | 亮灯` |
英文命令词规范（CI系列）
| 项目 | 规范 |
|---|---|
| 大小写 | 全部大写 |
| 多单词 | 用-连接 |
| 示例 | OPEN-DOOR |
英文命令词规范（SU系列）
| 项目 | 规范 |
|---|---|
| 大小写 | 支持大小写 |
| 多单词 | 用空格分隔 |
| 示例 | open door |
总结
命令词配置问题的核心在于遵循规范和系统排查：
- 格式第一：严格按照官方规范编写命令词，避免标点符号
- 系统排查：遇到问题时从最简单的配置开始验证
- 善用工具：利用平台的验证功能和日志输出定位问题
- 参考文档：遇到不确定的配置先查阅官方FAQ
- 寻求支持：技术交流群和官方客服都是可用的求助渠道
经验之谈：大多数配置问题都源于对规则的理解偏差。在遇到问题时，先用一个最简单的示例验证功能是否正常，再逐步恢复复杂配置，往往能快速定位问题所在。
参考资料
- SmartPi平台配置参数详解：
/docs/platform-configuration/firmware-config-parameters.md - SU-03T平台与固件FAQ：
/docs/faq-platform-and-firmware/faq-platform-and-firmware-su-03t.md - CI-03T语音调优FAQ：
/docs/faq-voice-tuning/faq-voice-tuning-ci-03t.md
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。