| # VoiceDialogue 安装指南 | |
| 本文档提供 VoiceDialogue 智能语音对话系统的详细安装说明。 | |
| ## 系统要求 | |
| 在开始安装之前，请确保您的系统满足以下要求： | |
| - **操作系统**: macOS 14+ (推荐) | |
| - **Python 版本**: 3.9 或更高版本 | |
| - **内存要求**: 至少 16GB RAM (推荐 32GB 用于大模型) | |
| - **存储空间**: 至少 20GB 可用空间 (用于模型文件) | |
| ## 安装步骤 | |
| ### 1. 克隆项目 | |
| ```bash | |
| git clone https://huggingface.co/MoYoYoTech/VoiceDialogue | |
| cd VoiceDialogue | |
| ``` | |
| ### 2. 创建并激活虚拟环境 | |
| 建议使用虚拟环境来避免依赖冲突： | |
| ```bash | |
| # 使用 uv (推荐) | |
| pip install uv | |
| uv venv | |
| source .venv/bin/activate | |
| # 或使用 conda | |
| conda create -n voicedialogue python=3.11 | |
| conda activate voicedialogue | |
| # 或使用 venv | |
| python -m venv voicedialogue | |
| source voicedialogue/bin/activate | |
| ``` | |
| ### 3. 安装项目依赖 | |
| ```bash | |
| # 使用 uv (推荐) | |
| WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync | |
| # 或使用 pip | |
| WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" pip install -r requirements.txt | |
| ``` | |
| ### 4. 安装音频处理工具 | |
| ```bash | |
| # macOS | |
| brew install ffmpeg | |
| ``` | |
| ### 5. 安装额外依赖 | |
| ```bash | |
| # 安装 kokoro-onnx | |
| uv pip install kokoro-onnx | |
| # 或 | |
| pip install kokoro-onnx | |
| # 重新安装指定版本的 numpy | |
| uv pip install numpy==1.26.4 | |
| # 或 | |
| pip install numpy==1.26.4 | |
| ``` | |
| ## 验证安装 | |
| 安装完成后，可以通过以下命令验证安装是否成功： | |
| ```bash | |
| # 查看帮助信息 | |
| python main.py --help | |
| # 启动系统（默认使用中文，沈逸角色） | |
| python main.py | |
| ``` | |
| 如果看到 "服务启动成功" 提示，说明安装成功。 | |
| ## 故障排除 | |
| ### 1. 模型下载失败 | |
| - **问题**: 网络连接超时或模型下载失败。 | |
| - **解决方案**: 设置 Hugging Face 镜像。 | |
| ```bash | |
| export HF_ENDPOINT=https://hf-mirror.com | |
| pip install -U huggingface_hub | |
| ``` | |
| ### 2. 音频设备问题 | |
| - **问题**: 找不到音频设备或权限被拒绝。 | |
| - **macOS 解决方案**: 系统设置 → 隐私与安全性 → 麦克风 → 启用你的终端应用 (如 iTerm, Terminal)。 | |
| ### 3. 内存不足错误 (OOM) | |
| - **问题**: `CUDA out of memory` 或 RAM 不足。 | |
| - **解决方案**: LLM 是主要的内存消耗者。你可以通过修改 `src/VoiceDialogue/services/text/generator.py` 来降低资源消耗： | |
| - **更换模型**: 将模型路径指向一个更小的模型（如 7B Q4 量化模型）。 | |
| - **减少批处理大小**: 减小模型参数中的 `n_batch` 值（如 `256`）。 | |
| - **减少上下文长度**: 减小 `n_ctx` 的值（如 `1024`）。 | |
| ### 4. 依赖包冲突 | |
| - **问题**: 包版本冲突或导入错误。 | |
| - **解决方案**: 强烈建议在虚拟环境中安装。如果遇到问题，尝试重建虚拟环境。 | |
| ```bash | |
| # 使用 conda | |
| conda deactivate | |
| conda env remove -n voicedialogue | |
| # 使用 uv | |
| rm -rf .venv | |
| uv venv | |
| ``` | |
| ### 5. FFmpeg 相关错误 | |
| - **问题**: 音频处理失败或编解码错误。 | |
| - **解决方案**: 确保正确安装 FFmpeg： | |
| ```bash | |
| # 检查 FFmpeg 安装 | |
| ffmpeg -version | |
| # 重新安装 FFmpeg | |
| # macOS | |
| brew reinstall ffmpeg | |
| ``` | |
| ### 6. Python 版本兼容性 | |
| - **问题**: Python 版本过低导致的兼容性问题。 | |
| - **解决方案**: 确保使用 Python 3.11+ 版本： | |
| ```bash | |
| python --version | |
| # 如果版本过低，请升级或使用虚拟环境 | |
| ``` | |
| ## 下一步 | |
| 安装完成后，您可以： | |
| 1. [查看使用指南](../README.md#🖥️-应用模式) 了解如何使用系统 | |
| 2. [查看配置选项](../README.md#⚙️-配置选项) 了解如何自定义配置 | |
| 3. [查看系统架构](../README.md#🔧-系统架构) 了解系统工作原理 | |
| 如果遇到其他问题，请查看 [完整故障排除指南](../README.md#🛠️-故障排除) 或提交 Issue。 |