docs/troubleshooting.md

故障排除与性能优化

🛠️ 故障排除

1. 模型下载失败

• 问题: 网络连接超时或模型下载失败。
• 解决方案: 设置 Hugging Face 镜像。

export HF_ENDPOINT=https://hf-mirror.com
pip install -U huggingface_hub

2. 音频设备问题

• 问题: 找不到音频设备或权限被拒绝。
• macOS 解决方案: 系统设置 → 隐私与安全性 → 麦克风 → 启用你的终端应用 (如 iTerm, Terminal)。
• Linux 解决方案: sudo usermod -a -G audio $USER，然后重新登录。

3. 内存不足错误 (OOM)

• 问题: CUDA out of memory 或 RAM 不足。
• 解决方案: LLM 是主要的内存消耗者。你可以通过修改 src/VoiceDialogue/services/text/generator.py 来降低资源消耗：
  • 更换模型: 将模型路径指向一个更小的模型（如 7B Q4 量化模型）。
  • 减少批处理大小: 减小模型参数中的 n_batch 值（如 256）。
  • 减少上下文长度: 减小 n_ctx 的值（如 1024）。

4. 依赖包冲突

• 问题: 包版本冲突或导入错误。
• 解决方案: 强烈建议在虚拟环境中安装。如果遇到问题，尝试重建虚拟环境。

# 使用 conda
conda deactivate
conda env remove -n voicedialogue

# 使用 uv
deactivate
rm -rf .venv

5. 说话人角色不存在

• 问题: 指定的说话人不在支持列表中。
• 解决方案: 使用 python main.py --help 查看所有可用的说话人角色。

6. FFmpeg 相关错误

• 问题: 音频处理失败或编解码错误。
• 解决方案: 确保正确安装 FFmpeg：

# 检查 FFmpeg 安装
ffmpeg -version

# 重新安装 FFmpeg
# macOS
brew reinstall ffmpeg

7. Python 版本兼容性

• 问题: Python 版本过低导致的兼容性问题。
• 解决方案: 确保使用 Python 3.9+ 版本：

python --version
# 如果版本过低，请升级或使用虚拟环境

8. 桌面应用相关问题

• 问题: Electron 应用启动失败或功能异常。
• 解决方案:
  • 确保 Node.js 版本 >= 16
  • 重新安装依赖：cd electron-app && npm install
  • 检查 Python 后端是否正常运行

9. 构建打包问题

• 问题: 使用构建脚本失败。
• 解决方案:
  • 确保有执行权限：chmod +x scripts/*.sh
  • 检查所有依赖是否安装完成
  • 查看具体错误日志进行调试

📊 性能优化建议

硬件优化

• 内存: 推荐 32GB RAM 以获得最佳性能
• 存储: 使用 SSD 硬盘可显著提升模型加载速度
• CPU: 多核处理器有助于多线程处理

软件优化

• 模型选择: 根据硬件配置选择合适大小的模型
• 批处理优化: 调整 LLM 的 n_batch 参数
• 音频缓冲: 根据延迟要求调整音频缓冲区大小