README.md

# 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 的完整语音对话系统，实现了端到端的语音交互体验。系统采用模块化设计，支持：

- 🎤 **实时语音识别** - 基于 Whisper 的高精度语音转文本，支持中英文识别
- 🤖 **智能对话生成** - 集成多种大语言模型（Qwen2.5、Llama3、Mistral等）
- 🔊 **高质量语音合成** - 基于 GPT-SoVITS 的多角色语音生成
- 🔇 **回声消除** - 内置音频处理技术，支持实时语音交互
- 🌍 **多语言支持** - 支持中文和英文语音识别与合成
- ⚡ **低延迟处理** - 优化的音频流处理管道，实现流畅对话体验

## ✨ 主要特性

### 🎵 音频处理
- **回声消除音频捕获** - 自动消除回声干扰，提升语音质量
- **语音活动检测(VAD)** - 智能检测用户说话状态，自动开始/停止录制
- **实时音频流处理** - 低延迟音频播放和处理
- **多格式音频支持** - 支持多种音频格式的输入输出

### 🗣️ 语音识别
- **智能语音识别引擎** - 中文使用FunASR高精度识别，其他语言使用Whisper模型
- **FunASR中文优化** - 专为中文语音优化的识别引擎，支持方言和口音识别
- **Whisper多语言支持** - 支持 Medium / Large 模型，覆盖多种国际语言
- **自动语言检测** - 根据配置自动选择最适合的识别引擎
- **实时转录处理** - 流式语音转文本处理，降低响应延迟
- **高精度识别** - 基于最新语音识别技术，提供业界领先的识别准确率


### 🧠 语言模型
支持多种预训练大语言模型：
- **Qwen2.5** (7B/14B) - 阿里巴巴开源的中文优化模型
- **Llama3** (8B) - Meta 开源的通用对话模型  
- **Mistral** (7B) - 高效推理的欧洲开源模型
- **自定义系统提示词** - 可配置 AI 助手的行为风格

### 🎭 语音合成
内置丰富的音色选择，基于 GPT-SoVITS 技术：
- **罗翔** - 法学教授风格，适合严肃话题
- **马保国** - 网络名人风格，轻松幽默
- **沈逸** - 学者风格，理性分析
- **杨幂** - 明星风格，亲和力强
- **周杰伦** - 歌手风格，个性鲜明
- **马云** - 企业家风格，商务感强

## 🚀 快速开始

### 系统要求

- **操作系统**: macOS 14+ (推荐)
- **Python 版本**: 3.9 或更高版本
- **内存要求**: 至少 16GB RAM (推荐 32GB 用于大模型)
- **存储空间**: 至少 20GB 可用空间 (用于模型文件)


### 安装步骤

1. **克隆项目**
```bash
git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
cd VoiceDialogue
```

2. **创建并激活虚拟环境**
```bash
# 使用 conda (推荐)
conda create -n voicedialogue python=3.9
conda activate voicedialogue

# 或使用 virtualenv
python -m venv voicedialogue
source voicedialogue/bin/activate  # Linux/macOS
# voicedialogue\Scripts\activate  # Windows
```

3. **安装 whisper.cpp**
```bash
WHISPER_COREML=1 pip install git+https://github.com/absadiki/pywhispercpp
```
4. **安装 llama.cpp**
```bash
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python
```

5. **安装项目依赖**
```bash
pip install -r requirements.txt
```

6. **安装音频处理工具**
```bash
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt update
sudo apt install ffmpeg

# CentOS/RHEL
sudo yum install ffmpeg

# 或使用 conda
conda install ffmpeg
```

### 🎮 首次运行

```bash
# 启动语音对话系统
python src/VoiceDialogue/main.py
```

**首次运行说明**：
- 系统会自动下载所需的模型文件 (约 5-10GB)
- 下载时间取决于网络速度，请耐心等待
- 模型文件会保存在 `~/.moyoyo_ai/` 目录下
- 看到 "服务启动成功" 提示后即可开始语音对话


## ⚙️ 配置选项

### 基础配置

在 `src/VoiceDialogue/main.py` 的 `main()` 函数中可以自定义以下选项：

```python
def main():
    # 语言设置
    user_language = 'zh'  # 'zh': 中文 | 'en': 英文

    # 系统提示词 - 定义 AI 助手的行为风格
    SYSTEM_PROMPT = (
        "你是善于模拟真实的思考过程的AI助手。"
        "回答时，必须首先生成一个不超过5个字的简短句子，"
        "比如：\"让我想一下\"、\"在我看来\"、\"稍等我理一理\"等，"
        "然后再进行正式回答，保持中文口语化表达。"
    )

    # TTS 语音合成角色
    tts_speaker = '沈逸'  # 可选: 罗翔、马保国、沈逸、杨幂、周杰伦、马云

    # 大语言模型规模
    llm = '14B'  # '7B': 更快推理 | '14B': 更好效果

    # Whisper 语音识别模型
    whisper_model = 'medium'  # 'medium': 平衡速度和精度 | 'large': 最高精度
```

### 高级配置

#### 大语言模型参数调优

```python
# 在 main.py 中的 default_llm_params 字典
default_llm_params = {
    'streaming': True,        # 启用流式输出
    'n_gpu_layers': -1,      # GPU 层数 (-1 为全部)
    'n_batch': 512,          # 批处理大小
    'n_ctx': 2048,           # 上下文长度
    'f16_kv': True,          # 16位浮点数
    'temperature': 0.8,      # 创造性参数 (0.0-1.0)
    'top_k': 50,             # Top-K 采样
    'top_p': 1.0,            # Top-P 采样
}

#### 路径配置

系统使用 `src/VoiceDialogue/config/settings.py` 管理路径配置：

```python
# 默认数据目录
DATA_FOLDER = ~/.moyoyo_ai/

# 模型存储路径
├── llm_models/          # 大语言模型
├── audio_models/        # TTS 语音模型  
├── audio_output/        # 音频输出文件
└── .single_instance_locker  # 单实例锁文件
```

## 📁 项目结构

```text
VoiceDialogue/
├── src/                          # 源代码目录
│   └── VoiceDialogue/           # 主要代码包
│       ├── config/              # 配置管理
│       │   ├── __init__.py
│       │   ├── paths.py         # 路径配置
│       │   └── settings.py      # 系统设置
│       ├── models/              # 模型管理模块
│       │   ├── audio_model.py   # 音频模型管理
│       │   ├── language_model.py # 语言模型管理
│       │   └── voice_model.py   # 语音模型管理
│       ├── services/            # 服务模块
│       │   ├── audio/           # 音频处理服务
│       │   │   ├── aec_audio_capture.py  # 回声消除捕获
│       │   │   ├── audio_answer.py       # TTS 音频生成
│       │   │   └── audio_player.py       # 音频播放
│       │   ├── speech/          # 语音识别服务
│       │   │   ├── speech_monitor.py     # 语音状态监控
│       │   │   └── asr_service.py        # ASR 识别服务
│       │   ├── text/            # 文本生成服务
│       │   │   └── text_generator.py     # LLM 文本生成
│       │   └── core/            # 核心服务
│       ├── utils/               # 工具函数
│       └── main.py              # 主程序入口
├── models/                      # 预训练模型存储
│   └── asr/                     # 语音识别模型
├── resources/                   # 资源文件
│   ├── audio/                   # 音频资源
│   └── libraries/               # 动态库文件
├── third_party/                 # 第三方库
├── tests/                       # 测试文件
├── docs/                        # 文档目录
├── requirements.txt             # Python 依赖
├── .gitignore                   # Git 忽略文件
└── README.md                    # 项目说明文档
```

## 🔧 系统架构

### 数据流程图

```
用户语音输入  →  回声消除  →  语音活动检测  →  语音转录  →  LLM生成回复  →  TTS合成  →  音频输出
    ↑                                                                                 ↓
    └───────────────────────────────── 实时语音交互循环 ─────────────────────────────────┘
```


### 核心组件说明

| 组件 | 功能描述 | 技术实现 |
|------|----------|----------|
| **EchoCancellingAudioCapture** | 回声消除音频捕获 | 实时音频流捕获与预处理 |
| **SpeechStateMonitor** | 语音活动检测 | VAD 算法检测用户说话状态 |
| **WhisperWorker** | 语音识别转录 | OpenAI Whisper 模型推理 |
| **LLMResponseGenerator** | 智能文本生成 | 大语言模型对话生成 |
| **TTSAudioGenerator** | 语音合成 | GPT-SoVITS 文本转语音 |
| **AudioStreamPlayer** | 音频流播放 | 实时音频输出播放 |

### 多线程架构

系统采用多线程并发处理架构，通过消息队列实现组件间通信：

- `audio_frames_queue`: 原始音频帧队列
- `user_voice_queue`: 用户语音片段队列  
- `transcribed_text_queue`: 转录文本队列
- `generated_answer_queue`: 生成回答队列
- `tts_generated_audio_queue`: TTS 音频队列

## 🔍 使用指南

### 基本使用流程

1. **启动系统**: 运行 `python src/VoiceDialogue/main.py`
2. **等待加载**: 首次运行会下载模型，请耐心等待
3. **开始对话**: 看到"服务启动成功"后直接开始说话
4. **语音交互**: 系统会自动检测语音并进行对话
5. **停止系统**: 使用 Ctrl+C 终止程序

### 性能优化建议

#### 硬件优化
- **GPU 加速**: 如有 NVIDIA GPU，确保安装 CUDA 版本的 PyTorch
- **内存管理**: 16GB RAM 可同时运行 14B 模型，8GB RAM 建议使用 7B 模型
- **存储优化**: SSD 硬盘可显著提升模型加载速度

#### 软件优化
```python
# 针对不同硬件配置的推荐设置

# 高性能配置 (16GB+ RAM, GPU)
llm = '14B'
whisper_model = 'large'
default_llm_params['n_batch'] = 1024
default_llm_params['n_ctx'] = 4096

# 平衡配置 (8-16GB RAM)
llm = '7B'
whisper_model = 'medium'
default_llm_params['n_batch'] = 512
default_llm_params['n_ctx'] = 2048

# 轻量配置 (8GB RAM, CPU only)
llm = '7B'
whisper_model = 'medium'
default_llm_params['n_gpu_layers'] = 0
default_llm_params['n_batch'] = 256
```

## 🛠️ 故障排除

### 常见问题及解决方案

#### 1. 模型下载失败
```bash
# 问题: 网络连接超时或模型下载失败
# 解决方案:
export HF_ENDPOINT=https://hf-mirror.com  # 使用镜像站点
pip install -U huggingface_hub
```

#### 2. 音频设备问题
```bash
# 问题: 找不到音频设备或权限被拒绝
# macOS 解决方案:
# 系统偏好设置 → 安全性与隐私 → 隐私 → 麦克风 → 添加终端应用

# Linux 解决方案:
sudo usermod -a -G audio $USER
# 重新登录生效
```

#### 3. 内存不足错误
```python
# 问题: CUDA out of memory 或 RAM 不足
# 解决方案: 降低模型规模和批处理大小
llm = '7B'  # 改为 7B 模型
default_llm_params['n_batch'] = 256  # 减少批处理大小
default_llm_params['n_ctx'] = 1024   # 减少上下文长度
```

#### 4. 依赖包冲突
```bash
# 问题: 包版本冲突或导入错误
# 解决方案: 重新创建虚拟环境
conda deactivate
conda env remove -n voicedialogue
conda create -n voicedialogue python=3.9
conda activate voicedialogue
pip install -r requirements.txt
```

### 调试模式

启用详细日志输出进行问题诊断：

```python
import logging
logging.basicConfig(level=logging.DEBUG)

# 在 main.py 开头添加上述代码
```

### 性能监控

```bash
# 监控系统资源使用情况
# macOS
top -pid $(pgrep -f "python.*main.py")

# Linux  
htop -p $(pgrep -f "python.*main.py")

# 监控 GPU 使用 (NVIDIA)
nvidia-smi -l 1
```

## 📚 相关资源

### 官方文档
- [OpenAI Whisper](https://github.com/openai/whisper)
- [GPT-SoVITS](https://github.com/RVC-Boss/GPT-SoVITS)
- [Qwen2.5 模型](https://huggingface.co/Qwen)
- [LangChain 框架](https://python.langchain.com/)

### 社区支持
- 问题反馈: [GitHub Issues](https://github.com/MoYoYoTech/VoiceDialogue/issues)
- 功能建议: [GitHub Discussions](https://github.com/MoYoYoTech/VoiceDialogue/discussions)

## 📄 许可证

本项目采用 MIT 许可证开源。详细信息请查看 [LICENSE](LICENSE) 文件。

## 🤝 贡献指南

欢迎提交 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">

**如果这个项目对您有帮助，请给我们一个 ⭐️!**

Made with ❤️ by [MoYoYo Tech](https://github.com/MoYoYoTech)

</div>