README.md

---
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">

![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Platform](https://img.shields.io/badge/Platform-macOS-lightgrey.svg)
![Version](https://img.shields.io/badge/Version-1.0.0-orange.svg)

一个集成了语音识别(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>