MoYoYoTech/VoiceDialogue

1# 故障排除与性能优化2 3## 🛠️ 故障排除4 5### 1. 模型下载失败6- **问题**: 网络连接超时或模型下载失败。7- **解决方案**: 设置 Hugging Face 镜像。8```bash9export HF_ENDPOINT=https://hf-mirror.com10pip install -U huggingface_hub11```12 13### 2. 音频设备问题14- **问题**: 找不到音频设备或权限被拒绝。15- **macOS 解决方案**: 系统设置 → 隐私与安全性 → 麦克风 → 启用你的终端应用 (如 iTerm, Terminal)。16- **Linux 解决方案**: `sudo usermod -a -G audio $USER`，然后重新登录。17 18### 3. 内存不足错误 (OOM)19- **问题**: `CUDA out of memory` 或 RAM 不足。20- **解决方案**: LLM 是主要的内存消耗者。你可以通过修改 `src/VoiceDialogue/services/text/generator.py` 来降低资源消耗：21    - **更换模型**: 将模型路径指向一个更小的模型（如 7B Q4 量化模型）。22    - **减少批处理大小**: 减小模型参数中的 `n_batch` 值（如 `256`）。23    - **减少上下文长度**: 减小 `n_ctx` 的值（如 `1024`）。24 25### 4. 依赖包冲突26- **问题**: 包版本冲突或导入错误。27- **解决方案**: 强烈建议在虚拟环境中安装。如果遇到问题，尝试重建虚拟环境。28```bash29# 使用 conda30conda deactivate31conda env remove -n voicedialogue32 33# 使用 uv34deactivate35rm -rf .venv36```37 38### 5. 说话人角色不存在39- **问题**: 指定的说话人不在支持列表中。40- **解决方案**: 使用 `python main.py --help` 查看所有可用的说话人角色。41 42### 6. FFmpeg 相关错误43- **问题**: 音频处理失败或编解码错误。44- **解决方案**: 确保正确安装 FFmpeg：45```bash46# 检查 FFmpeg 安装47ffmpeg -version48 49# 重新安装 FFmpeg50# macOS51brew reinstall ffmpeg52 53```54 55### 7. Python 版本兼容性56- **问题**: Python 版本过低导致的兼容性问题。57- **解决方案**: 确保使用 Python 3.9+ 版本：58```bash59python --version60# 如果版本过低，请升级或使用虚拟环境61```62 63### 8. 桌面应用相关问题64- **问题**: Electron 应用启动失败或功能异常。65- **解决方案**: 66  - 确保 Node.js 版本 >= 1667  - 重新安装依赖：`cd electron-app && npm install`68  - 检查 Python 后端是否正常运行69 70### 9. 构建打包问题71- **问题**: 使用构建脚本失败。72- **解决方案**: 73  - 确保有执行权限：`chmod +x scripts/*.sh`74  - 检查所有依赖是否安装完成75  - 查看具体错误日志进行调试76 77## 📊 性能优化建议78 79### 硬件优化80- **内存**: 推荐 32GB RAM 以获得最佳性能81- **存储**: 使用 SSD 硬盘可显著提升模型加载速度82- **CPU**: 多核处理器有助于多线程处理83 84### 软件优化85- **模型选择**: 根据硬件配置选择合适大小的模型86- **批处理优化**: 调整 LLM 的 `n_batch` 参数87- **音频缓冲**: 根据延迟要求调整音频缓冲区大小