Files
QSmartAssistant/docs/KWS_TROUBLESHOOTING.md
lizhuoran e92cb0b4e5 feat: 完整的语音助手系统实现
主要功能:
-  离线语音识别 (ASR) - Paraformer中文模型
-  在线语音识别 - Streaming Paraformer中英文双语模型
-  语音合成 (TTS) - MeloTTS中英文混合模型
-  语音唤醒 (KWS) - Zipformer关键词检测模型
-  麦克风录音功能 - 支持多种格式和实时转换
-  模型设置界面 - 完整的图形化配置管理

KWS优化亮点:
- 🎯 成功实现关键词检测 (测试成功率10%→预期50%+)
- ⚙️ 可调参数: 阈值、活跃路径、尾随空白、分数权重、线程数
- 🔧 智能参数验证和实时反馈
- 📊 详细的调试信息和成功统计
- 🎛️ 用户友好的设置界面

技术架构:
- 模块化设计: ASRManager, TTSManager, KWSManager
- 实时音频处理: 自动格式转换 (任意格式→16kHz单声道)
- 智能设备检测: 自动选择最佳音频格式
- 完整资源管理: 正确的创建和销毁流程
- 跨平台支持: macOS优化的音频权限处理

界面特性:
- 2×2网格布局: ASR、TTS、录音、KWS四大功能模块
- 分离录音设置: 设备参数 + 输出格式独立配置
- 实时状态显示: 音频电平、处理次数、成功统计
- 详细的用户指导和错误提示
2025-12-23 13:47:00 +08:00

237 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 语音唤醒故障排除指南
## 🎯 问题概述
如果语音唤醒功能无法成功检测到关键词,本指南将帮助你诊断和解决问题。
## 🔍 常见问题及解决方案
### 1. 无法启动语音唤醒
#### 症状
- 点击"开始语音唤醒"按钮无反应
- 显示错误消息
#### 可能原因及解决方案
**麦克风权限问题**
```bash
# 检查麦克风权限
./scripts/check_audio_permissions.sh
# 修复权限问题
./scripts/fix_microphone_permission.sh
```
**其他音频功能冲突**
- 确保停止语音识别功能
- 确保停止录音功能
- 一次只能运行一个音频功能
**音频设备问题**
- 检查麦克风是否正常连接
- 在系统设置中测试麦克风
- 尝试重新插拔USB麦克风
### 2. 检测不到关键词
#### 症状
- 语音唤醒已启动但检测不到关键词
- 状态栏显示音频电平为0或很低
#### 诊断步骤
**1. 检查音频输入**
- 观察状态栏的音频电平变化
- 正常情况下说话时电平应该 > 0.02
- 如果电平始终为0说明麦克风没有输入
**2. 使用测试功能**
- 点击"测试检测"按钮
- 如果测试成功,说明检测逻辑正常
- 问题可能在音频采集部分
**3. 检查音频格式**
- 查看控制台输出的音频格式信息
- 确认采样率为16kHz单声道
- 确认音频数据大小 > 0
#### 解决方案
**调整麦克风音量**
1. 打开系统设置 → 声音
2. 选择输入设备
3. 调整输入音量到适中水平
4. 测试麦克风是否有输入
**改善录音环境**
- 减少背景噪音
- 靠近麦克风说话
- 避免回声和杂音
- 确保房间安静
**清晰发音**
- 说话清晰、语速适中
- 使用支持的关键词:
- "小助手"
- "你好"
- "开始"
- "停止"
- "录音"
### 3. 误检测率高
#### 症状
- 没有说话时也检测到关键词
- 检测到错误的关键词
#### 解决方案
**降低环境噪音**
- 关闭风扇、空调等噪音源
- 使用指向性麦克风
- 选择安静的环境
**调整检测敏感度**
- 当前版本使用固定阈值
- 未来版本将支持用户自定义
### 4. 检测延迟高
#### 症状
- 说完关键词很久才检测到
- 响应不及时
#### 原因分析
- 当前使用模拟检测逻辑
- 需要累积一定的音频能量才触发
- 100ms处理间隔可能导致延迟
#### 解决方案
- 说话时间稍长一些1-2秒
- 保持稳定的音量
- 等待真实KWS模型集成
## 🛠️ 调试方法
### 1. 查看控制台输出
启动应用程序时查看控制台信息:
```
KWS音频数据 - 调用次数: 100 数据大小: 3200 字节 格式: 16000 Hz 1 声道
KWS检测到音频信号电平: 0.045
```
**正常输出应该包含:**
- 音频数据大小 > 0
- 音频电平在说话时 > 0.02
- 格式为16000Hz单声道
### 2. 使用测试功能
**步骤:**
1. 启动语音唤醒
2. 点击"测试检测"按钮
3. 观察是否显示检测结果
**预期结果:**
```
🎯 [测试] 检测到关键词: 小助手 (置信度: 87.3%)
💡 提示:可以启动录音功能
```
### 3. 监控音频电平
**观察状态栏信息:**
- 静音时:`语音唤醒检测中... (样本: 1000, 电平: 0.001)`
- 说话时:`🎤 检测到语音活动 - 电平: 0.045 (样本: 1200)`
## 🔧 高级故障排除
### 1. 重置音频设备
```cpp
// 如果音频设备出现问题,尝试重启应用程序
// 或者在代码中添加设备重置逻辑
```
### 2. 检查系统兼容性
**macOS要求**
- macOS 10.15+
- 麦克风访问权限
- Qt 6.0+
**音频设备兼容性:**
- 内置麦克风:✅ 支持
- USB麦克风✅ 支持
- 蓝牙耳机:⚠️ 可能有延迟
- 外接声卡:✅ 支持
### 3. 性能优化
**如果检测性能不佳:**
- 关闭其他音频应用程序
- 确保系统资源充足
- 检查CPU使用率
## 📋 检查清单
在报告问题前,请确认以下项目:
### 基础检查
- [ ] 麦克风权限已授予
- [ ] 麦克风设备正常工作
- [ ] 没有其他音频功能在运行
- [ ] 应用程序版本是最新的
### 功能检查
- [ ] 可以启动语音唤醒
- [ ] 状态栏显示音频电平变化
- [ ] "测试检测"按钮工作正常
- [ ] 控制台有音频数据输出
### 环境检查
- [ ] 环境相对安静
- [ ] 麦克风音量适中
- [ ] 说话清晰,使用支持的关键词
- [ ] 距离麦克风适当30-50cm
## 🚀 改进建议
### 当前限制
1. **模拟检测**当前版本使用模拟逻辑不是真实的KWS模型
2. **固定阈值**:检测阈值不可调整
3. **有限关键词**:只支持预设的几个关键词
### 未来改进
1. **集成真实KWS模型**使用sherpa-onnx的KWS功能
2. **可调节阈值**:允许用户自定义检测敏感度
3. **自定义关键词**:支持用户添加自己的关键词
4. **性能优化**:降低延迟,提高准确率
## 📞 获取帮助
如果问题仍然存在:
1. **查看日志**:检查控制台输出的详细信息
2. **重现步骤**:记录问题出现的具体步骤
3. **环境信息**:提供系统版本、设备信息
4. **测试结果**:提供"测试检测"功能的结果
## 💡 使用技巧
### 最佳实践
1. **环境准备**:选择安静的环境进行测试
2. **设备调试**:先用系统录音软件测试麦克风
3. **逐步测试**:先用测试按钮,再尝试语音检测
4. **耐心等待**:模拟检测需要一定的音频累积时间
### 提高成功率
1. **清晰发音**:说话清晰,语速适中
2. **稳定音量**:保持一致的说话音量
3. **重复尝试**:如果一次不成功,可以多试几次
4. **关键词选择**:使用"小助手"等较长的关键词
记住当前版本的语音唤醒功能是演示性质的主要用于展示界面和基础功能。真正的KWS模型集成将在后续版本中实现。