语音命令词配置实战：免唤醒失效与舵机异常排查
前言
在语音产品开发领域深耕多年，你会发现命令词配置看似基础，却是Bug高发区。多数情况下模组硬件本身正常，症结往往藏在配置细节里。本文不绕弯子，直接基于近期技术交流群内五个真实案例，深度剖析常见命令词配置问题，提供系统化排查思路与可落地方案。
案例一：免唤醒命令词无响应的完整排查
问题现象
有开发者反馈，配置好的免唤醒命令词完全没有反应，而唤醒词却能正常触发。这个问题相当棘手。
根因分析
根据官方文档明确规范，命令词内严禁包含任何标点符号，包括空格、逗号、句号等。这是导致免唤醒命令词失效的头号诱因。
官方规范需严格执行：
- 命令词中禁止出现空格、逗号、句号等标点符号。
- 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 oven”完全匹配（100%），而与防误词条“please open”的相似度仅约60%，因此防误效果受限是必然的。
三种解决方案
方案一：扩充防误识别词列表
please open | peace open | pleas open方案二：针对特定命令词手动降低灵敏度
- 在语音平台后台，找到该命令词的“特定命令词阈值”设置。
- 适当调低灵敏度，即增大数值。
方案三：优化命令词本身的设计
原命令：please open oven
优化后：turn on oven / activate oven配置检查清单
- [ ] 防误识别词是否涵盖发音相似的多种变体？
- [ ] 是否考虑了口音差异？例如 what's vs what is，sure vs show。
- [ ] 命令词本身是否与日常用语过度接近？
- [ ] 是否尝试调整过特定命令词的阈值？
案例三：舵机只往一个方向转动的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