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

唤醒词模型 ​模型下载（必需） ​重要说明: 项目不包含模型文件，需要提前下载配置。

官方模型下载地址 ​官方模型列表: 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. 选择配置方案 ​方案一：精度优先（推荐）

bashcd 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 # 可选方案二：速度优先

bashcd 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",

"NUM_THREADS": 4,

"PROVIDER": "cpu",

"MAX_ACTIVE_PATHS": 2,

"KEYWORDS_SCORE": 1.8,

"KEYWORDS_THRESHOLD": 0.2,

"NUM_TRAILING_BLANKS": 1

}

}配置参数详解 ​参数默认值说明调优建议USE_WAKE_WORDtrue启用语音唤醒功能-MODEL_PATH"models"模型文件目录确保路径正确NUM_THREADS4处理线程数电脑性能好可设置6-8PROVIDER"cpu"推理引擎可选: cpu, cuda, coremlMAX_ACTIVE_PATHS2搜索路径数减少提升速度，增加提升准确性KEYWORDS_SCORE1.8关键词增强分数提高减少误检，降低提升灵敏度KEYWORDS_THRESHOLD0.2检测阈值降低提升灵敏度，提高减少误检NUM_TRAILING_BLANKS1尾随空白数量通常保持1自定义唤醒词 ​当前支持的唤醒词 ​1. 小爱同学 (x iǎo ài t óng x ué)

2. 你好问问 (n ǐ h ǎo w èn w èn)

3. 小艺小艺 (x iǎo y ì x iǎo y ì)

4. 小米小米 (x iǎo m ǐ x iǎo m ǐ)

5. 你好小智 (n ǐ h ǎo x iǎo zh ì)

6. 贾维斯 (j iā w éi s ī)添加新唤醒词 ​方法1: 编辑关键词文件 ​编辑 models/keywords.txt，按格式添加：

# 格式：拼音分解 @中文原文

x iǎo zh ì @小智

n ǐ h ǎo x iǎo zh ì @你好小智

j iā w éi s ī @贾维斯

k āi sh ǐ g ōng z uò @开始工作方法2: 使用拼音转换工具 ​pythonfrom 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))唤醒词选择建议 ​推荐的唤醒词特点 ​长度适中: 2-4个字符发音清晰: 避免相似音混淆独特性强: 避免日常对话常用词朗朗上口: 容易记忆和发音示例好的唤醒词 ​- 你好小智 # 4字，独特，清晰

- 贾维斯 # 3字，独特，科技感

- 开始工作 # 4字，明确意图

- 小助手 # 3字，简单易记避免使用 ​- 嗯 # 太短，容易误触

- 你好 # 太常用

- 请帮我做一个计划 # 太长

- 谢谢 # 日常用语使用方法 ​启动流程 ​启动程序：

bashcd /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.py2. 响应速度慢 ​症状: 唤醒词识别延迟大

解决方案:

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运行可定制: 支持自定义唤醒词易集成: 与现有音频处理完美融合现在你可以享受智能、快速、准确的语音唤醒体验了！