关键词增强最佳实践

1. 功能介绍

keywords_boost（关键词增强）用于加速固定短指令的响应，例如“下一首”“打开台灯”。系统在接收语音的同时检测已配置的关键词，有机会在语音识别（ASR）输出完整句子之前，提前将指令交给后续处理流程。

它适合“说完一个短语就希望立即响应”的交互。它不是通用 ASR 热词纠错功能，也不会自动补齐设备控制能力：播放音乐、控制台灯等动作，仍需先接入对应的工具或业务服务。实际响应速度还受音频采集、网络、打断策略、意图处理及业务执行耗时影响，不承诺固定的端到端延迟。

2. 哪些场景适合开启

3. 接入步骤

第一步：确认业务能力和运行环境

开启前，确认对应的 唤醒词、MCP 工具、FunctionCall 或 Topic 已接入，常规语音路径能够正确处理目标指令。

第二步：配置明确的触发词

检测词表复用以下已加载的配置：

• 唤醒／打断词。
• MCP、Topic、FunctionCall 的触发词词表。

对于业务指令，建议在对应工具、话题或函数上明确配置 triggers。以下仅展示单个能力条目中的触发词片段，需要合并到对应能力的完整配置中，不能作为独立接入请求使用：

1{
2  "triggers": ["打开空调", "关闭空调"]
3}

配置时注意：

• 配置了 triggers 的条目，使用触发词作为表达来源，不使用该条目的示例语句作为匹配表达。
• 检测词表会合并、去重并过滤空值。关键词仅支持中文，中英混合的也不支持，当前会过滤非中文字符的条目。
• 检测词表在智能体进程启动时随检测服务连接一次性下发，内容为启动时刻已加载的唤醒／打断词与各类 Keywords。修改触发词后需要重启智能体实例（或按平台流程重新拉起），新词表才会随新连接重新下发；仅重新进入会话不会刷新词表，存量连接也不会热更新。

第三步：开启功能

在智能体配置 BRTC_AGENT_CFG 中合并以下片段；平台字段的具体填写位置请以交付环境的配置入口为准：

1{
2  "keywords_boost": {
3    "enabled": true,
4    "wait_ms": 0
5  }
6}

wait_ms: 0 表示不额外等待后续 ASR 上下文；如果命中时已经存在识别上下文，系统仍会先检查该上下文是否与指令相符。它不代表整个业务动作零延迟完成。

第四步：验证并逐步上线

先用少量指令在真实设备上对比关闭和开启后的表现，覆盖安静、噪声、远场以及智能体正在播报的场景。确认动作正确、误触发可接受、下一轮对话正常，再逐步扩展用户范围和触发词数量。

4. 触发词设计建议

优先使用“动作 + 对象”等含义完整、边界清楚的短语。同一个动作可以配置用户常说的几种表达，但不建议堆叠大量含义模糊的变体。

还应排查前缀重叠，例如同时配置“打开台灯”和“打开台灯定时”。用户尚未说完时，短词可能先命中；需要后续语义才能区分的操作，更适合交给完整语音理解流程。

5. 如何权衡速度与误触发

系统会结合已经到达的 ASR 文本校验关键词：识别文本与指令词都会转成拼音后逐字比较，识别文本必须是指令词的前缀（同音字视为一致）。识别文本在指令词之前还有内容（如「帮我打开台灯」）、或已超出指令词长度（如「打开台灯定时」）时，快捷路径会拒绝该候选，由常规语音流程继续处理。若 ASR 已断句输出完整句子且候选仍在等待，快捷路径会让位给整句处理。

但上下文校验依赖信息到达时机。特别是 wait_ms: 0 时，如果否定词、条件或后续内容尚未被 ASR 识别，关键词可能已经确认。因此不能将它理解为“保证识别所有否定句和复杂句”。

如果测试中出现长句、否定句误触发，可以试验一个正的 wait_ms，为 ASR 上下文留出更多时间。例如：

1{
2  "keywords_boost": {
3    "enabled": true,
4    "wait_ms": 200
5  }
6}

这里的 200 仅是调优试验值，不是经过统一验证的推荐值，也不是误触发保护阈值。等待窗口内收到新的、不同的 ASR 部分文本后，计时可能重新开始；窗口到期且候选未被拒绝时，会默认确认。因此 wait_ms 不是从命中开始计算的固定总耗时上限，也不能保证消除误触发。

建议先优化触发词，再一次只调整一个参数，对比正确执行率、误触发率和端到端耗时。如果加大等待窗口后加速收益很小，应重新判断该场景是否适合快捷指令。

6.常见问题

开启后为什么没有明显变快？

先确认该指令确实进入检测词表、检测服务已经接入、会话已重新建立，再检查打断策略及后续业务耗时。关键词提前命中只减少链路中的一部分等待，无法缩短所有业务处理时间。

为什么在智能体说话时没有立即执行？

快捷指令仍需经过现有打断判定。当前策略不允许本次快捷执行时，会交给常规语音流程继续处理；开启该功能不会自动绕过打断规则。

为什么命中了关键词，却没有完成设备操作？

命中只表示识别到了候选指令。实际操作还依赖后续路由、参数、权限和业务服务，需要分开核对“命中”“进入业务处理”和“动作成功”三个结果。

能否仅在 keywords_boost 中增加一个 keywords 数组？

当前该配置对象提供 enabled 和 wait_ms。请在对应能力的触发词配置中维护业务表达，或维护已有唤醒／打断词；不要在该对象中添加未经支持的词表字段。

修改了触发词，为什么没有生效？

检测词表在进程启动时随连接一次性下发，重新进入会话不会重新下发；同时未配置 triggers 的条目只有在 enableScalarIntent 开启时才会加载示例语句，纯英文、纯数字或纯符号的条目也会被过滤。请重启智能体实例后，按上述条件核对配置再验证。

如何关闭？

将 keywords_boost.enabled 设为 false，重启智能体实例（当前版本配置在进程启动时加载）后验证。关闭后，语音请求使用常规识别及处理路径。