metadata
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 - 智能语音对话系统
🎯 项目简介
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 可用空间 (用于模型文件)
安装步骤
- 克隆项目
git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
cd VoiceDialogue
- 创建并激活虚拟环境
# 使用 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
- 安装项目依赖
# 使用 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
- 安装音频处理工具
# macOS
brew install ffmpeg
- 安装额外依赖
# 安装 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. 命令行模式 (默认)
直接在终端进行实时语音对话。
# 启动语音对话系统 (默认使用中文，沈逸角色)
python main.py
# 或使用 uv
uv run main.py
# 指定语言和角色
python main.py --language en --speaker Heart
# 查看所有可用参数
python main.py --help
首次运行说明：
- 看到 "服务启动成功" 提示后即可开始说话
- 系统会自动检测语音活动并进行识别和回复
2. API 服务模式
启动一个 Web 服务器，通过 HTTP 请求进行交互。
# 启动 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前端的完整应用：
- 首先，激活当前 Python 环境
source .venv/bin/activate
# 或使用 conda
conda activate voicedialogue
- 使用构建脚本
# 使用构建脚本（推荐）
bash scripts/build.sh
# 或分别构建
bash scripts/build-python.sh # 构建Python后端
bash scripts/build-electron.sh # 构建Electron前端
# 清理构建产物
bash scripts/clean.sh
📁 项目结构
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 镜像。
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
rm -rf .venv
uv venv
5. 说话人角色不存在
- 问题: 指定的说话人不在支持列表中。
- 解决方案: 使用
python src/VoiceDialogue/main.py --help查看所有可用的说话人角色。
6. FFmpeg 相关错误
- 问题: 音频处理失败或编解码错误。
- 解决方案: 确保正确安装 FFmpeg：
# 检查 FFmpeg 安装
ffmpeg -version
# 重新安装 FFmpeg
# macOS
brew reinstall ffmpeg
7. Python 版本兼容性
- 问题: Python 版本过低导致的兼容性问题。
- 解决方案: 确保使用 Python 3.11+ 版本：
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！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
如果这个项目对您有帮助，请给我们一个 ⭐️!