|
|
--- |
|
|
title: VoiceDialogue - 智能语音对话系统 |
|
|
license: mit |
|
|
language: |
|
|
- zh |
|
|
- en |
|
|
pipeline_tag: text-to-speech |
|
|
tags: |
|
|
- voice-dialogue |
|
|
- speech-recognition |
|
|
- text-to-speech |
|
|
- large-language-model |
|
|
- asr |
|
|
- tts |
|
|
- llm |
|
|
- chinese |
|
|
- english |
|
|
- real-time |
|
|
library_name: transformers |
|
|
--- |
|
|
|
|
|
# VoiceDialogue - 智能语音对话系统 |
|
|
|
|
|
<div align="center"> |
|
|
|
|
|
 |
|
|
 |
|
|
 |
|
|
 |
|
|
|
|
|
一个集成了语音识别(ASR)、大语言模型(LLM)和文本转语音(TTS)的实时语音对话系统 |
|
|
|
|
|
[快速开始](#-快速开始) • [功能特性](#-主要特性) • [配置说明](#-配置选项) • [系统架构](#-系统架构) • [故障排除](#-故障排除) |
|
|
|
|
|
</div> |
|
|
|
|
|
## 🎯 项目简介 |
|
|
|
|
|
VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端到端的语音交互体验。系统采用模块化设计，支持： |
|
|
|
|
|
- 🎤 **实时语音识别** - 基于 FunASR 和 Whisper 的高精度语音转文本 |
|
|
- 🤖 **智能对话生成** - 集成 Qwen2.5 等多种大语言模型 |
|
|
- 🔊 **高质量语音合成** - 基于 GPT-SoVITs 和 Kokoro TTS 的多角色语音生成 |
|
|
- 🌐 **Web API 服务** - 提供 HTTP 接口，方便与其他应用集成 |
|
|
- 🔇 **回声消除** - 内置音频处理技术，支持实时语音交互 |
|
|
- ⚡ **低延迟处理** - 优化的音频流处理管道，实现流畅对话体验 |
|
|
|
|
|
## ✨ 主要特性 |
|
|
|
|
|
### 🎵 音频处理 |
|
|
- **回声消除音频捕获** - 自动消除回声干扰，提升语音质量 |
|
|
- **语音活动检测(VAD)** - 智能检测用户说话状态，自动开始/停止录制 |
|
|
- **实时音频流处理** - 低延迟音频播放和处理 |
|
|
|
|
|
### 🗣️ 语音识别 |
|
|
- **智能语音识别引擎** - 中文使用FunASR高精度识别，其他语言使用Whisper模型 |
|
|
- **自动语言切换** - 根据启动参数自动选择最优识别引擎 |
|
|
- **实时转录处理** - 流式语音转文本处理，降低响应延迟 |
|
|
|
|
|
### 🧠 语言模型 |
|
|
- **Qwen2.5 (14B)** - 内置阿里巴巴开源的中文优化模型 |
|
|
- **LangChain 集成** - 方便扩展和支持更多语言模型 |
|
|
- **自定义系统提示词** - 可在代码中配置 AI 助手的行为风格 |
|
|
|
|
|
### 🎭 语音合成 |
|
|
项目集成了两种先进的语音合成技术，支持动态说话人管理： |
|
|
|
|
|
#### GPT-SoVITs 技术（中文角色） |
|
|
基于 GPT-SoVITs 的中文语音合成，支持以下角色： |
|
|
- **罗翔** (Luo Xiang) - 法学教授风格，具有幽默风趣和深入浅出的讲解风格 |
|
|
- **马保国** (Ma Baoguo) - 太极大师风格，带有标志性的口音和语调特色 |
|
|
- **沈逸** (Shen Yi) - 学者风格，具有理性分析风格和富有磁性的嗓音 |
|
|
- **杨幂** (Yang Mi) - 明星风格，拥有清甜动人的声线和自然流畅的表达方式 |
|
|
- **周杰伦** (Zhou Jielun) - 歌手风格，具有标志性的说话风格和音乐气质 |
|
|
- **马云** (Ma Yun) - 企业家风格，富有激情的演讲风格和商业洞察表达方式 |
|
|
|
|
|
#### Kokoro TTS 技术（英文角色） |
|
|
基于 Kokoro TTS 的英文语音合成，支持以下角色： |
|
|
- **Heart** - 温暖亲切的英语女性语音，声音富有感情色彩 |
|
|
- **Bella** - 优质的英语女性语音，具有清晰自然的发音和良好的表现力 |
|
|
- **Nicole** - 高质量的英语女性语音，发音清晰准确，语调自然流畅 |
|
|
|
|
|
#### 技术特点 |
|
|
- **智能引擎选择** - 系统根据内容语言自动选择最适合的TTS引擎 |
|
|
- **动态说话人管理** - 支持运行时动态加载和切换说话人 |
|
|
- **高质量合成** - 采用先进的神经网络技术，生成自然流畅的语音 |
|
|
- **可扩展架构** - 模块化设计，方便添加更多语音角色和TTS引擎 |
|
|
|
|
|
### ⚙️ 服务模式 |
|
|
- **命令行模式 (CLI)** - 在终端中直接运行，提供实时语音交互体验 |
|
|
- **API 服务模式** - 启动一个 FastAPI Web 服务器，提供 HTTP 接口进行交互 |
|
|
|
|
|
## 🚀 快速开始 |
|
|
|
|
|
### 系统要求 |
|
|
|
|
|
- **操作系统**: 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 |
|
|
``` |
|
|
|
|
|
### 🖥️ 应用模式 |
|
|
|
|
|
#### 1. 命令行模式 (默认) |
|
|
|
|
|
直接在终端进行实时语音对话。 |
|
|
|
|
|
```bash |
|
|
# 启动语音对话系统 (默认使用中文，沈逸角色) |
|
|
python main.py |
|
|
# 或使用 uv |
|
|
uv run main.py |
|
|
|
|
|
# 指定语言和角色 |
|
|
python main.py --language en --speaker Heart |
|
|
|
|
|
# 查看所有可用参数 |
|
|
python main.py --help |
|
|
``` |
|
|
|
|
|
**首次运行说明**： |
|
|
- 看到 "服务启动成功" 提示后即可开始说话 |
|
|
- 系统会自动检测语音活动并进行识别和回复 |
|
|
|
|
|
#### 2. API 服务模式 |
|
|
|
|
|
启动一个 Web 服务器，通过 HTTP 请求进行交互。 |
|
|
|
|
|
```bash |
|
|
# 启动 API 服务器 |
|
|
python main.py --mode api |
|
|
# 或使用 uv |
|
|
uv run main.py --mode api |
|
|
|
|
|
# 指定不同端口和启用热重载 |
|
|
python main.py --mode api --port 9000 --reload |
|
|
``` |
|
|
|
|
|
**API 服务特性**： |
|
|
- API 文档地址: `http://localhost:8000/docs` |
|
|
- 支持 TTS 模型管理（查看、加载、删除） |
|
|
- 实时模型状态监控 |
|
|
- RESTful API 设计 |
|
|
|
|
|
#### 3. 桌面应用模式 (Electron) |
|
|
提供图形界面的桌面应用程序。 |
|
|
|
|
|
|
|
|
## ⚙️ 配置选项 |
|
|
|
|
|
### 启动参数 |
|
|
|
|
|
通过 `main.py` 的命令行参数可以方便地进行配置： |
|
|
|
|
|
| 参数 | 缩写 | 可选值 | 默认值 | 描述 | |
|
|
|---|---|---|---|---| |
|
|
| `--mode` | `-m` | `cli`, `api` | `cli` | 设置运行模式 | |
|
|
| `--language`| `-l` | `zh`, `en` | `zh` | (CLI模式) 设置用户语言 | |
|
|
| `--speaker` | `-s` | (动态获取) | `沈逸` | (CLI模式) 设置TTS语音角色 | |
|
|
| `--host` | | IP地址 | `0.0.0.0` | (API模式) 服务器主机 | |
|
|
| `--port` | `-p` | 端口号 | `8000` | (API模式) 服务器端口 | |
|
|
| `--reload`| | 无 | `False` | (API模式) 启用热重载 | |
|
|
|
|
|
**支持的说话人角色**（动态加载）: |
|
|
- **中文角色**：`罗翔`, `马保国`, `沈逸`, `杨幂`, `周杰伦`, `马云` |
|
|
- **英文角色**：`Heart`, `Bella`, `Nicole` |
|
|
|
|
|
### 高级配置 |
|
|
|
|
|
#### 大语言模型 (LLM) |
|
|
|
|
|
- **模型路径和参数**: LLM 的模型和推理参数目前在代码中硬编码，方便快速启动。 |
|
|
- **文件位置**: `src/VoiceDialogue/services/text/generator.py` |
|
|
- **自定义**: 你可以修改 `LLMResponseGenerator` 类中的配置。 |
|
|
|
|
|
#### 语音识别 (ASR) |
|
|
|
|
|
- **引擎自动选择**: 系统会根据 `--language` 参数自动选择最合适的 ASR 引擎。 |
|
|
- **模型配置**: ASR 模型的具体配置位于 `src/VoiceDialogue/services/speech/recognizers/manager.py`。 |
|
|
|
|
|
#### 系统提示词 (System Prompt) |
|
|
|
|
|
- **功能**: 定义 AI 角色的行为和说话风格。 |
|
|
- **文件位置**: `src/VoiceDialogue/services/text/generator.py` |
|
|
- **自定义**: 你可以修改系统提示词变量的值。 |
|
|
|
|
|
### 构建完整应用 |
|
|
项目提供了完整的构建脚本，可以一键构建包含Python后端和Electron前端的完整应用： |
|
|
|
|
|
1. 首先，激活当前 Python 环境 |
|
|
|
|
|
```bash |
|
|
source .venv/bin/activate |
|
|
# 或使用 conda |
|
|
conda activate voicedialogue |
|
|
``` |
|
|
|
|
|
2. 使用构建脚本 |
|
|
|
|
|
```bash |
|
|
# 使用构建脚本（推荐） |
|
|
bash scripts/build.sh |
|
|
|
|
|
# 或分别构建 |
|
|
bash scripts/build-python.sh # 构建Python后端 |
|
|
bash scripts/build-electron.sh # 构建Electron前端 |
|
|
|
|
|
# 清理构建产物 |
|
|
bash scripts/clean.sh |
|
|
``` |
|
|
|
|
|
|
|
|
## 📁 项目结构 |
|
|
|
|
|
```text |
|
|
VoiceDialogue/ |
|
|
├── src/ |
|
|
│ └── voice_dialogue/ # 主要源代码目录 |
|
|
│ ├── __init__.py # 包初始化文件 |
|
|
│ ├── cli/ # 命令行界面模块 |
|
|
│ │ └── args.py # 命令行参数解析 |
|
|
│ ├── api/ # Web API 模块 (FastAPI) |
|
|
│ │ ├── app.py # FastAPI 应用实例 |
|
|
│ │ ├── server.py # uvicorn 服务器 |
|
|
│ │ ├── core/ # API 核心配置 |
|
|
│ │ ├── routes/ # API 路由 |
|
|
│ │ ├── schemas/ # 数据模型 |
|
|
│ │ ├── dependencies/ # API 依赖项 |
|
|
│ │ └── middleware/ # 中间件 |
|
|
│ ├── config/ # 配置管理 |
|
|
│ │ ├── paths.py # 路径配置 |
|
|
│ │ └── speaker_config.py # 说话人配置 |
|
|
│ ├── core/ # 核心模块 |
|
|
│ │ ├── constants.py # 全局常量和队列 |
|
|
│ │ └── launcher.py # 系统启动器 |
|
|
│ ├── models/ # 数据模型和任务 |
|
|
│ ├── services/ # 服务模块 |
|
|
│ │ ├── audio/ # 音频处理服务 |
|
|
│ │ ├── speech/ # 语音识别服务 |
|
|
│ │ └── text/ # 文本生成服务 |
|
|
│ └── utils/ # 工具函数 |
|
|
├── electron-app/ # Electron 桌面应用 |
|
|
│ ├── main.js # Electron 主进程 |
|
|
│ ├── preload.js # 预加载脚本 |
|
|
│ ├── loading.html # 加载页面 |
|
|
│ ├── utils.js # 工具函数 |
|
|
│ ├── package.json # Electron 依赖配置 |
|
|
│ ├── assets/ # Electron 资源文件 |
|
|
│ ├── build/ # 构建配置 |
|
|
│ └── python-dist/ # Python 分发包 |
|
|
├── scripts/ # 构建和部署脚本 |
|
|
│ ├── build.sh # 主构建脚本 |
|
|
│ ├── build-python.sh # Python 打包脚本 |
|
|
│ ├── build-electron.sh # Electron 打包脚本 |
|
|
│ └── clean.sh # 清理脚本 |
|
|
├── third_party/ # 第三方库 |
|
|
│ ├── moyoyo_tts/ # GPT-SoVITs TTS 引擎 |
|
|
│ └── AECAudioRecorder/ # 回声消除音频录制器 |
|
|
├── assets/ # 资源文件 |
|
|
├── dist/ # 分发包输出目录 |
|
|
├── build/ # 构建临时文件 |
|
|
├── tests/ # 测试文件 |
|
|
├── docs/ # 文档目录 |
|
|
├── main.py # 项目启动入口 |
|
|
├── pyproject.toml # 项目配置文件 (uv) |
|
|
├── requirements.txt # Python 依赖 |
|
|
├── uv.lock # uv 锁定文件 |
|
|
├── .python-version # Python 版本配置 |
|
|
└── README.md # 项目说明文档 |
|
|
``` |
|
|
|
|
|
## 🔧 系统架构 |
|
|
|
|
|
### 数据流程图 (CLI 模式) |
|
|
``` |
|
|
用户语音输入 → 回声消除 → 语音活动检测 → 语音转录 (ASR) → LLM生成回复 → TTS合成 → 音频输出 |
|
|
↑ ↓ |
|
|
└─────────────────────────────── 实时语音交互循环 ────────────────────────────────┘ |
|
|
``` |
|
|
|
|
|
|
|
|
### 核心组件说明 |
|
|
|
|
|
| 组件 | 功能描述 | 技术实现 | |
|
|
|------|----------|----------| |
|
|
| **EchoCancellingAudioCapture** | 回声消除音频捕获 | 实时音频流捕获与预处理 | |
|
|
| **SpeechStateMonitor** | 语音活动检测 | VAD 算法检测用户说话状态 | |
|
|
| **ASRWorker** | 语音识别转录 | FunASR / Whisper 模型推理 | |
|
|
| **LLMResponseGenerator** | 智能文本生成 | Qwen2.5 (llama.cpp) 对话生成 | |
|
|
| **TTSAudioGenerator** | 语音合成 | GPT-SoVITs / Kokoro TTS 文本转语音 | |
|
|
| **AudioStreamPlayer** | 音频流播放 | 实时音频输出播放 | |
|
|
| **FastAPI App** | API服务 | 提供HTTP接口，封装核心服务 | |
|
|
|
|
|
### 多线程架构 |
|
|
|
|
|
系统采用多线程设计，各组件通过队列进行通信： |
|
|
|
|
|
- **音频采集线程**: 持续捕获音频数据 |
|
|
- **语音监测线程**: 检测用户语音活动 |
|
|
- **ASR线程**: 语音识别处理 |
|
|
- **LLM线程**: 文本生成处理 |
|
|
- **TTS线程**: 语音合成处理 |
|
|
- **音频播放线程**: 音频输出播放 |
|
|
|
|
|
## 🛠️ 故障排除 |
|
|
|
|
|
### 1. 模型下载失败 |
|
|
- **问题**: 网络连接超时或模型下载失败。 |
|
|
- **解决方案**: 设置 Hugging Face 镜像。 |
|
|
```bash |
|
|
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. 依赖包冲突 |
|
|
- **问题**: 包版本冲突或导入错误。 |
|
|
- **解决方案**: 强烈建议在虚拟环境中安装。如果遇到问题，尝试重建虚拟环境。 |
|
|
```bash |
|
|
# 使用 conda |
|
|
conda deactivate |
|
|
conda env remove -n voicedialogue |
|
|
|
|
|
# 使用 uv |
|
|
rm -rf .venv |
|
|
uv venv |
|
|
``` |
|
|
|
|
|
### 5. 说话人角色不存在 |
|
|
- **问题**: 指定的说话人不在支持列表中。 |
|
|
- **解决方案**: 使用 `python src/VoiceDialogue/main.py --help` 查看所有可用的说话人角色。 |
|
|
|
|
|
### 6. FFmpeg 相关错误 |
|
|
- **问题**: 音频处理失败或编解码错误。 |
|
|
- **解决方案**: 确保正确安装 FFmpeg： |
|
|
```bash |
|
|
# 检查 FFmpeg 安装 |
|
|
ffmpeg -version |
|
|
|
|
|
# 重新安装 FFmpeg |
|
|
# macOS |
|
|
brew reinstall ffmpeg |
|
|
|
|
|
``` |
|
|
|
|
|
### 7. Python 版本兼容性 |
|
|
- **问题**: Python 版本过低导致的兼容性问题。 |
|
|
- **解决方案**: 确保使用 Python 3.11+ 版本： |
|
|
```bash |
|
|
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` 参数 |
|
|
- **音频缓冲**: 根据延迟要求调整音频缓冲区大小 |
|
|
|
|
|
## 📄 许可证 |
|
|
|
|
|
本项目采用 MIT 许可证开源。 |
|
|
|
|
|
## 🤝 贡献指南 |
|
|
|
|
|
欢迎提交 Pull Request 和 Issue！ |
|
|
|
|
|
1. Fork 本仓库 |
|
|
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) |
|
|
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) |
|
|
4. 推送到分支 (`git push origin feature/AmazingFeature`) |
|
|
5. 开启 Pull Request |
|
|
|
|
|
--- |
|
|
|
|
|
<div align="center"> |
|
|
|
|
|
**如果这个项目对您有帮助，请给我们一个 ⭐️!** |
|
|
|
|
|
</div> |
