语音唤醒功能

概述

py-xiaozhi 集成了基于 Sherpa-ONNX 的高精度语音唤醒功能，支持自定义唤醒词和实时检测。使用轻量级关键词检测模型，提供毫秒级响应速度。

唤醒词模型

内置模型（开箱即用）

仓库已经在 models/zh 与 models/en 目录内置了 Sherpa-ONNX 关键词检测模型，可直接使用：

models/zh：中文模型（默认 MODEL_PATH），keywords.txt 中预置「小爱同学」唤醒词，可配合 WAKE_WORD_LANG: "zh" 使用，支持自行追加其他拼音行。
models/en：英文模型（BPE 单元），keywords.txt 默认包含 MOSS 激活词，可配合 WAKE_WORD_LANG: "en" 使用。
每个目录都已包含 encoder.onnx/decoder.onnx/joiner.onnx/tokens.txt/keywords.txt，无需额外下载即可运行。
如需自定义唤醒词，只需编辑对应语言目录下的 keywords.txt，并在 WAKE_WORD_OPTIONS 中切换 MODEL_PATH 与 WAKE_WORD_LANG。

语言	`MODEL_PATH`	`WAKE_WORD_LANG`	默认 `keywords.txt` 激活词	示例 `WAKE_WORD` 值
中文	`models/zh`	`zh`	`小爱同学`	`小爱同学`
英文	`models/en`	`en`	`MOSS`	`MOSS`

切换语言时请同时：

调整 WAKE_WORD_OPTIONS.MODEL_PATH 指向目标语言目录；
设置 WAKE_WORD_OPTIONS.WAKE_WORD_LANG 为 zh 或 en；
更新 WAKE_WORD_OPTIONS.WAKE_WORD 为当前 keywords.txt 中存在的短语（例如 MOSS 或 小爱同学）；
若编辑了 keywords.txt，确保新唤醒词的拼写/拼音与配置保持一致，否则检测不到。

仅当你想更新模型版本或替换为其他训练集时，再按下方步骤重新下载模型文件。

模型下载（可选）

重要说明: 如果要更换模型，请提前下载配置。

官方模型下载地址

官方模型列表: https://csukuangfj.github.io/sherpa/onnx/kws/pretrained_models/index.html
推荐模型: sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01

下载和配置步骤

1. 下载模型包

bash

# 方法1：直接下载（推荐）
cd /Users/junsen/Desktop/workspace/py-xiaozhi
wget https://github.com/k2-fsa/sherpa-onnx/releases/download/kws-models/sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2

# 解压
tar xvf sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2

# 方法2：使用ModelScope
pip install modelscope
python -c "
from modelscope import snapshot_download
snapshot_download('pkufool/sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01', cache_dir='./models')
"

2. 配置模型文件

模型包下载后包含以下文件：

sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01/
├── encoder-epoch-12-avg-2-chunk-16-left-64.int8.onnx    # 速度优先
├── encoder-epoch-12-avg-2-chunk-16-left-64.onnx         # 
├── encoder-epoch-99-avg-1-chunk-16-left-64.int8.onnx    # 速度优先 
├── encoder-epoch-99-avg-1-chunk-16-left-64.onnx         # 精度优先
├── decoder-epoch-12-avg-2-chunk-16-left-64.onnx         #
├── decoder-epoch-99-avg-1-chunk-16-left-64.onnx         # 精度优先
├── joiner-epoch-12-avg-2-chunk-16-left-64.int8.onnx     # 速度优先
├── joiner-epoch-12-avg-2-chunk-16-left-64.onnx          #
├── joiner-epoch-99-avg-1-chunk-16-left-64.int8.onnx     # 速度优先
├── joiner-epoch-99-avg-1-chunk-16-left-64.onnx          # 精度优先
├── tokens.txt                    # Token映射表（必需）
├── keywords_raw.txt              # 原始关键词（可选，用于生成）
├── keywords.txt                  # 现成的
├── test_wavs/                    # 测试音频（可选）
├── configuration.json            # 模型元信息（可选）
└── README.md                     # 说明文档（可选）

3. 选择配置方案

方案一：精度优先（推荐）

bash

cd sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01

# 复制精度优先的epoch-99 fp32三件套
cp encoder-epoch-99-avg-1-chunk-16-left-64.onnx ../models/encoder.onnx
cp decoder-epoch-99-avg-1-chunk-16-left-64.onnx ../models/decoder.onnx  
cp joiner-epoch-99-avg-1-chunk-16-left-64.onnx ../models/joiner.onnx

# 复制配套文件
cp tokens.txt ../models/tokens.txt
cp keywords_raw.txt ../models/keywords_raw.txt  # 可选

方案二：速度优先

bash

cd sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01

# 复制速度优先的epoch-99 int8三件套
cp encoder-epoch-99-avg-1-chunk-16-left-64.int8.onnx ../models/encoder.onnx
cp decoder-epoch-99-avg-1-chunk-16-left-64.onnx ../models/decoder.onnx
cp joiner-epoch-99-avg-1-chunk-16-left-64.int8.onnx ../models/joiner.onnx

# 复制配套文件  
cp tokens.txt ../models/tokens.txt

注意事项:

不要混用fp32与int8：三个模型文件必须保持一致的精度
优先选择epoch-99：比epoch-12训练更充分，精度更高
必需文件：encoder.onnx + decoder.onnx + joiner.onnx + tokens.txt + keywords.txt

最终模型文件结构

配置完成后，你的models目录应该包含：

models/
├── encoder.onnx      # 编码器模型（重命名后）
├── decoder.onnx      # 解码器模型（重命名后） 
├── joiner.onnx       # 连接器模型（重命名后）
├── tokens.txt        # 拼音Token映射表（228行版本）
├── keywords.txt      # 关键词配置文件（需创建）
└── keywords_raw.txt  # 原始关键词文件（可选）

模型性能对比

模型版本	文件大小	推理速度	识别精度	资源占用	推荐场景
epoch-99 fp32	~13MB	中等	最高	中等	桌面电脑（推荐）
epoch-99 int8	~4MB	快	高	低	移动设备/资源受限
epoch-12 fp32	~13MB	中等	中高	中等	一般使用
epoch-12 int8	~4MB	最快	中等	最低	极速响应需求

启用语音唤醒

配置文件设置

编辑 config/config.json：

json

{
  "WAKE_WORD_OPTIONS": {
    "USE_WAKE_WORD": true,
    "MODEL_PATH": "models/zh",
    "NUM_THREADS": 4,
    "PROVIDER": "cpu",
    "MAX_ACTIVE_PATHS": 2,
    "KEYWORDS_SCORE": 1.8,
    "KEYWORDS_THRESHOLD": 0.2,
    "NUM_TRAILING_BLANKS": 1,
    "WAKE_WORD": "小爱同学",
    "WAKE_WORD_LANG": "zh"
  }
}

切换到英文唤醒词只需把 MODEL_PATH 改成 models/en、把 WAKE_WORD 改成 MOSS，并同步把 WAKE_WORD_LANG 设置为 en。无论选择哪种语言，WAKE_WORD 必须与对应 keywords.txt 中的某一行一致。

配置参数详解

参数	默认值	说明	调优建议
`USE_WAKE_WORD`	`true`	启用语音唤醒功能	-
`MODEL_PATH`	`"models/zh"`	模型文件目录	中文用 `models/zh`，英文用 `models/en`
`NUM_THREADS`	`4`	处理线程数	电脑性能好可设置6-8
`PROVIDER`	`"cpu"`	推理引擎	可选: cpu, cuda, coreml
`MAX_ACTIVE_PATHS`	`2`	搜索路径数	减少提升速度，增加提升准确性
`KEYWORDS_SCORE`	`1.8`	关键词增强分数	提高减少误检，降低提升灵敏度
`KEYWORDS_THRESHOLD`	`0.2`	检测阈值	降低提升灵敏度，提高减少误检
`NUM_TRAILING_BLANKS`	`1`	尾随空白数量	通常保持1
`WAKE_WORD`	`"小爱同学"`	唤醒词文本，用于 UI 提示及日志	必须存在于 `keywords.txt`
`WAKE_WORD_LANG`	`"zh"`	唤醒词语言（`zh`/`en`）	与 `MODEL_PATH` 匹配

自定义唤醒词

推荐方式：设置窗口一键保存

打开桌面端 UI，进入 设置 → 唤醒词（src/ui/gui/qml/windows/settings/WakeWordTab.qml）。
勾选“启用唤醒词”，在输入框里直接键入中文或英文短语（例如“你好小智”或 “Hey Moss”）。
输入过程中会实时显示“转换预览”，中文版自动转拼音，英文版使用 BPE tokens，并标出语言标签。
点击“保存唤醒词”，系统会调用 convert_wake_word()（src/ui/shared/models/settings_model.py:314-365）：
- 自动识别语言，更新 WAKE_WORD、WAKE_WORD_LANG 与 MODEL_PATH；
- 将生成的关键词写入对应目录（models/zh/keywords.txt 或 models/en/keywords.txt）；
- 保持配置文件与 UI 状态同步。

该方式适合 1 个主唤醒词的场景；保存时会覆盖目标 keywords.txt 中的内容。如果你需要同时保留多条候选或批量管理，请改用下方“手动添加”。

当前支持的唤醒词

仓库默认随模型提供一组中英文唤醒词，启动后即可使用：

中文（models/zh/keywords.txt）

x iǎo ài t óng x ué @小爱同学

将 WAKE_WORD 设为 小爱同学、WAKE_WORD_LANG 设为 zh 即可直接唤醒；若你新增“中国好助手”等自定义词，也要同步修改这两项。

英文（models/en/keywords.txt）

▁MO S S @MOSS

英文关键词使用 Sherpa-ONNX 的 SentencePiece/BPE tokens，首个 ▁ 代表词首。设置 MODEL_PATH: "models/en"、WAKE_WORD: "MOSS"、WAKE_WORD_LANG: "en" 即可使用。

手动添加新唤醒词（高级选项）

方法1: 直接编辑关键词文件

根据所选语言编辑对应文件：

中文：编辑 models/zh/keywords.txt，一行一个唤醒词，使用“拼音+@原文”格式；
英文：编辑 models/en/keywords.txt，一行一个唤醒词，使用 SentencePiece tokens（示例：▁HE L LO ▁X I AO ▁Z H I @HELLO XIAOZHI）。推荐使用 Sherpa-ONNX 提供的转换脚本或参照现有示例保持大小写与空格。

# 格式：拼音分解 @中文原文
x iǎo zh ì @小智
n ǐ h ǎo x iǎo zh ì @你好小智
j iā w éi s ī @贾维斯
k āi sh ǐ g ōng z uò @开始工作

编辑完成后，记得把 WAKE_WORD 更新成新唤醒词文本，并确认 WAKE_WORD_LANG 与目录匹配，否则唤醒不会触发。若之后再次使用设置界面的“保存唤醒词”，该文件会被覆盖为单行。

方法2: 使用拼音转换工具

python

from pypinyin import lazy_pinyin, Style

def generate_keyword_line(text):
    pinyin_list = lazy_pinyin(text, style=Style.TONE3, neutral_tone_with_five=True)
    processed_pinyin = [py.rstrip('12345') for py in pinyin_list]
    pinyin_str = ' '.join(processed_pinyin)
    return f'{pinyin_str} @{text}'

# 生成新唤醒词
wake_words = ['小助手', '开始工作', '星期五']
for word in wake_words:
    print(generate_keyword_line(word))

唤醒词选择建议

示例好的唤醒词

- 你好小智    # 4字，独特，清晰
- 贾维斯      # 3字，独特，科技感
- 开始工作    # 4字，明确意图
- 小助手      # 3字，简单易记

避免使用

- 嗯         # 太短，容易误触
- 你好       # 太常用
- 请帮我做一个计划 # 太长
- 谢谢       # 日常用语

使用方法

启动流程

启动程序：

bash

cd /Users/junsen/Desktop/workspace/py-xiaozhi
python main.py

模型加载：
- 系统自动加载Sherpa-ONNX模型
- 初始化关键词检测器
- 进入唤醒词监听状态
语音唤醒：
- 清晰说出配置的唤醒词
- 系统自动切换到LISTENING状态
- 开始语音对话

使用技巧

最佳唤醒方式

音量适中: 正常说话音量
语速自然: 不要太快或太慢
发音清晰: 特别注意声调
环境安静: 减少背景噪音

性能优化

速度优化配置

json

{
  "WAKE_WORD_OPTIONS": {
    "NUM_THREADS": 6,           // 提高线程数
    "MAX_ACTIVE_PATHS": 1,      // 减少搜索路径
    "KEYWORDS_THRESHOLD": 0.15, // 降低阈值提高灵敏度
    "KEYWORDS_SCORE": 1.5       // 降低分数提升速度
  }
}

精度优化配置

json

{
  "WAKE_WORD_OPTIONS": {
    "NUM_THREADS": 4,           // 适中线程数
    "MAX_ACTIVE_PATHS": 3,      // 增加搜索路径
    "KEYWORDS_THRESHOLD": 0.25, // 提高阈值减少误检
    "KEYWORDS_SCORE": 2.2       // 提高分数增强准确性
  }
}

性能监控

检查当前性能：

python

# 在应用中查看统计信息
stats = wake_word_detector.get_performance_stats()
print(f"引擎: {stats['engine']}")
print(f"线程数: {stats['num_threads']}")
print(f"检测阈值: {stats['keywords_threshold']}")
print(f"运行状态: {stats['is_running']}")

故障排除

常见问题

1. 唤醒词无响应

症状: 说出唤醒词没有反应

解决方案:

bash

# 检查配置
grep -A 10 "WAKE_WORD_OPTIONS" config/config.json

# 检查模型文件
ls -la models/

# 测试功能
python test_new_keywords.py

2. 响应速度慢

症状: 唤醒词识别延迟大

解决方案:

json

{
  "WAKE_WORD_OPTIONS": {
    "KEYWORDS_THRESHOLD": 0.15,  // 降低阈值
    "NUM_THREADS": 6,            // 增加线程
    "MAX_ACTIVE_PATHS": 1        // 减少搜索路径
  }
}

3. 误检频繁

症状: 经常误触发唤醒

解决方案:

json

{
  "WAKE_WORD_OPTIONS": {
    "KEYWORDS_THRESHOLD": 0.3,   // 提高阈值
    "KEYWORDS_SCORE": 2.5,       // 提高分数
    "MAX_ACTIVE_PATHS": 3        // 增加搜索路径
  }
}

4. 模型加载失败

症状: 启动时报模型文件错误

解决方案:

bash

# 检查文件完整性
ls -la models/
file models/*.onnx
file models/tokens.txt

# 重新验证模型
python test_new_keywords.py

调试命令

bash

# 查看系统日志
tail -f logs/app.log | grep -i kws

# 监控性能
top -p $(pgrep -f "python main.py")

# 测试音频设备
python -c "import sounddevice as sd; print(sd.query_devices())"

高级配置

环境适配

安静环境（办公室）

json

{
  "WAKE_WORD_OPTIONS": {
    "KEYWORDS_THRESHOLD": 0.15,
    "KEYWORDS_SCORE": 1.5,
    "MAX_ACTIVE_PATHS": 1
  }
}

嘈杂环境（开放空间）

json

{
  "WAKE_WORD_OPTIONS": {
    "KEYWORDS_THRESHOLD": 0.25,
    "KEYWORDS_SCORE": 2.5,
    "MAX_ACTIVE_PATHS": 3
  }
}

与AEC集成

语音唤醒与回声消除（AEC）完美集成：

json

{
  "AEC_OPTIONS": {
    "ENABLED": true,              // AEC为唤醒词提供干净音频
    "ENABLE_PREPROCESS": true     // 噪声抑制提升检测准确性
  },
  "WAKE_WORD_OPTIONS": {
    "USE_WAKE_WORD": true         // 使用AEC处理后的音频
  }
}

性能基准

在标准配置下的预期性能：

指标	目标值	说明
响应延迟	< 1秒	从说话到检测完成
检测准确率	> 95%	正确识别设定唤醒词
误检率	< 5%	错误触发频率
CPU占用	< 30%	持续运行时的资源消耗
内存占用	< 100MB	模型和缓冲区内存使用

总结

Sherpa-ONNX 语音唤醒功能特点:

高精度: 基于深度学习的端到端检测
低延迟: 毫秒级响应速度
低资源: 轻量级模型，适合PC运行
可定制: 支持自定义唤醒词
易集成: 与现有音频处理完美融合

现在你可以享受智能、快速、准确的语音唤醒体验了！

语音唤醒功能 ​

概述 ​

唤醒词模型 ​

内置模型（开箱即用） ​

模型下载（可选） ​

官方模型下载地址 ​

下载和配置步骤 ​

1. 下载模型包 ​

2. 配置模型文件 ​

3. 选择配置方案 ​

最终模型文件结构 ​

模型性能对比 ​

启用语音唤醒 ​

配置文件设置 ​

配置参数详解 ​

自定义唤醒词 ​

推荐方式：设置窗口一键保存 ​

当前支持的唤醒词 ​

手动添加新唤醒词（高级选项） ​

方法1: 直接编辑关键词文件 ​

方法2: 使用拼音转换工具 ​

唤醒词选择建议 ​

推荐的唤醒词特点 ​

示例好的唤醒词 ​

避免使用 ​

使用方法 ​

启动流程 ​

使用技巧 ​

最佳唤醒方式 ​

性能优化 ​

速度优化配置 ​

精度优化配置 ​

性能监控 ​

故障排除 ​

常见问题 ​

1. 唤醒词无响应 ​

2. 响应速度慢 ​

3. 误检频繁 ​

4. 模型加载失败 ​

调试命令 ​

高级配置 ​

环境适配 ​

安静环境（办公室） ​

嘈杂环境（开放空间） ​

与AEC集成 ​

性能基准 ​

总结 ​

语音唤醒功能

概述

唤醒词模型

内置模型（开箱即用）

模型下载（可选）

官方模型下载地址

下载和配置步骤

1. 下载模型包

2. 配置模型文件

3. 选择配置方案

最终模型文件结构

模型性能对比

启用语音唤醒

配置文件设置

配置参数详解

自定义唤醒词

推荐方式：设置窗口一键保存

当前支持的唤醒词

手动添加新唤醒词（高级选项）

方法1: 直接编辑关键词文件

方法2: 使用拼音转换工具

唤醒词选择建议

推荐的唤醒词特点

示例好的唤醒词

避免使用

使用方法

启动流程

使用技巧

最佳唤醒方式

性能优化

速度优化配置

精度优化配置

性能监控

故障排除

常见问题

1. 唤醒词无响应

2. 响应速度慢

3. 误检频繁

4. 模型加载失败

调试命令

高级配置

环境适配

安静环境（办公室）

嘈杂环境（开放空间）

与AEC集成

性能基准

总结