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
# 使用 conda (推荐)
conda create -n voicedialogue python=3.9
conda activate voicedialogue

# 或使用 venv
python -m venv voicedialogue
source voicedialogue/bin/activate
```

3. **安装核心依赖**
```bash
# whisper.cpp for ASR
WHISPER_COREML=1 pip install git+https://github.com/absadiki/pywhispercpp

# llama.cpp for LLM
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python
```

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

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

# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install ffmpeg
```

### 🎮 运行系统

`VoiceDialogue` 支持两种运行模式：**命令行模式 (CLI)** 和 **API 服务模式**。

#### 1. 命令行模式 (默认)

直接在终端进行实时语音对话。

```bash
# 启动语音对话系统 (默认使用中文，沈逸角色)
python src/VoiceDialogue/main.py

# 指定语言和角色
python src/VoiceDialogue/main.py --language en --speaker Heart

# 查看所有可用角色
python src/VoiceDialogue/main.py --help
```

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

#### 2. API 服务模式

启动一个 Web 服务器，通过 HTTP 请求进行交互。

```bash
# 启动 API 服务器
python src/VoiceDialogue/main.py --mode api

# 指定不同端口和启用热重载
python src/VoiceDialogue/main.py --mode api --port 9000 --reload
```

**API 服务特性**：
- API 文档地址: `http://localhost:8000/docs`
- 支持 TTS 模型管理（查看、加载、删除）
- 实时模型状态监控
- RESTful API 设计

## ⚙️ 配置选项

### 启动参数

通过 `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`
- **自定义**: 你可以修改系统提示词变量的值。

## 📁 项目结构

```text
VoiceDialogue/
├── src/
│   └── VoiceDialogue/
│       ├── main.py              # 主程序入口
│       ├── api/                 # Web API 模块 (FastAPI)
│       │   ├── app.py           # FastAPI 应用实例
│       │   ├── server.py        # uvicorn 服务器
│       │   ├── core/            # 核心配置
│       │   ├── routes/          # API 路由
│       │   ├── schemas/         # 数据模型
│       │   └── middleware/      # 中间件
│       ├── config/              # 配置管理
│       │   └── paths.py         # 路径配置
│       ├── core/                # 核心模块
│       │   └── constants.py     # 全局常量和队列
│       ├── models/              # 数据模型和任务
│       │   ├── language_model.py # 语言模型定义
│       │   └── voice_task.py    # 语音任务定义
│       ├── services/            # 服务模块
│       │   ├── audio/           # 音频处理服务
│       │   │   ├── capture.py   # 回声消除音频捕获
│       │   │   ├── player.py    # 音频播放
│       │   │   ├── generator.py # TTS 音频生成器
│       │   │   └── generators/  # TTS 引擎管理
│       │   ├── speech/          # 语音识别服务
│       │   │   ├── monitor.py   # 语音状态监控
│       │   │   ├── recognizer.py # ASR 识别服务
│       │   │   └── recognizers/ # ASR 引擎管理
│       │   └── text/            # 文本生成服务
│       │       └── generator.py # LLM 文本生成
│       └── utils/               # 工具函数
├── third_party/                 # 第三方库
│   └── moyoyo_tts/             # GPT-SoVITs TTS 引擎
├── tests/                       # 测试文件
├── docs/                        # 文档目录 (空)
├── assets/                      # 资源文件
├── requirements.txt             # 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接口，封装核心服务 |

## 🛠️ 故障排除

### 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 deactivate
conda env remove -n voicedialogue
# ... 重新执行安装步骤 ...
```

### 5. 说话人角色不存在
- **问题**: 指定的说话人不在支持列表中。
- **解决方案**: 使用 `python src/VoiceDialogue/main.py --help` 查看所有可用的说话人角色。

## 📄 许可证

本项目采用 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>