MoYoYoTech/VoiceDialogue

1# VoiceDialogue 安装指南2 3本文档提供 VoiceDialogue 智能语音对话系统的详细安装说明。4 5## 系统要求6 7在开始安装之前，请确保您的系统满足以下要求：8 9- **操作系统**: macOS 14+ (推荐)10- **Python 版本**: 3.9 或更高版本11- **内存要求**: 至少 16GB RAM (推荐 32GB 用于大模型)12- **存储空间**: 至少 20GB 可用空间 (用于模型文件)13 14## 安装步骤15 16### 1. 克隆项目17 18```bash19git clone https://huggingface.co/MoYoYoTech/VoiceDialogue20cd VoiceDialogue21```22 23### 2. 创建并激活虚拟环境24 25建议使用虚拟环境来避免依赖冲突：26 27```bash28# 使用 uv (推荐)29pip install uv30uv venv31source .venv/bin/activate32 33# 或使用 conda34conda create -n voicedialogue python=3.1135conda activate voicedialogue36 37# 或使用 venv38python -m venv voicedialogue39source voicedialogue/bin/activate40```41 42### 3. 安装项目依赖43 44```bash45# 使用 uv (推荐)46WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync47 48# 或使用 pip49WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" pip install -r requirements.txt50```51 52### 4. 安装音频处理工具53 54```bash55# macOS56brew install ffmpeg57```58 59### 5. 安装额外依赖60 61```bash62# 安装 kokoro-onnx63uv pip install kokoro-onnx64# 或65pip install kokoro-onnx66 67# 重新安装指定版本的 numpy68uv pip install numpy==1.26.469# 或70pip install numpy==1.26.471```72 73## 验证安装74 75安装完成后，可以通过以下命令验证安装是否成功：76 77```bash78# 查看帮助信息79python main.py --help80 81# 启动系统（默认使用中文，沈逸角色）82python main.py83```84 85如果看到 "服务启动成功" 提示，说明安装成功。86 87## 故障排除88 89### 1. 模型下载失败90- **问题**: 网络连接超时或模型下载失败。91- **解决方案**: 设置 Hugging Face 镜像。92```bash93export HF_ENDPOINT=https://hf-mirror.com94pip install -U huggingface_hub95```96 97### 2. 音频设备问题98- **问题**: 找不到音频设备或权限被拒绝。99- **macOS 解决方案**: 系统设置 → 隐私与安全性 → 麦克风 → 启用你的终端应用 (如 iTerm, Terminal)。100 101### 3. 内存不足错误 (OOM)102- **问题**: `CUDA out of memory` 或 RAM 不足。103- **解决方案**: LLM 是主要的内存消耗者。你可以通过修改 `src/VoiceDialogue/services/text/generator.py` 来降低资源消耗：104    - **更换模型**: 将模型路径指向一个更小的模型（如 7B Q4 量化模型）。105    - **减少批处理大小**: 减小模型参数中的 `n_batch` 值（如 `256`）。106    - **减少上下文长度**: 减小 `n_ctx` 的值（如 `1024`）。107 108### 4. 依赖包冲突109- **问题**: 包版本冲突或导入错误。110- **解决方案**: 强烈建议在虚拟环境中安装。如果遇到问题，尝试重建虚拟环境。111```bash112# 使用 conda113conda deactivate114conda env remove -n voicedialogue115 116# 使用 uv117rm -rf .venv118uv venv119```120 121### 5. FFmpeg 相关错误122- **问题**: 音频处理失败或编解码错误。123- **解决方案**: 确保正确安装 FFmpeg：124```bash125# 检查 FFmpeg 安装126ffmpeg -version127 128# 重新安装 FFmpeg129# macOS130brew reinstall ffmpeg131```132 133### 6. Python 版本兼容性134- **问题**: Python 版本过低导致的兼容性问题。135- **解决方案**: 确保使用 Python 3.11+ 版本：136```bash137python --version138# 如果版本过低，请升级或使用虚拟环境139```140 141## 下一步142 143安装完成后，您可以：144 1451. [查看使用指南](../README.md#🖥️-应用模式) 了解如何使用系统1462. [查看配置选项](../README.md#⚙️-配置选项) 了解如何自定义配置1473. [查看系统架构](../README.md#🔧-系统架构) 了解系统工作原理148 149如果遇到其他问题，请查看 [完整故障排除指南](../README.md#🛠️-故障排除) 或提交 Issue。