VoiceDialogue / README.md

liumaolin

Update README.md: clarify usage details, add dynamic speaker management, and refine documentation for consistency and completeness.

710072a 8 months ago

preview code

raw

history blame

13.2 kB

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 - 智能语音对话系统

一个集成了语音识别(ASR)、大语言模型(LLM)和文本转语音(TTS)的实时语音对话系统

快速开始 • 功能特性 • 配置说明 • 系统架构 • 故障排除

🎯 项目简介

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

创建并激活虚拟环境

# 使用 conda (推荐)
conda create -n voicedialogue python=3.9
conda activate voicedialogue

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

安装核心依赖

# 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

安装项目依赖

pip install -r requirements.txt

安装音频处理工具

# macOS
brew install ffmpeg

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

🎮 运行系统

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

1. 命令行模式 (默认)

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

# 启动语音对话系统 (默认使用中文，沈逸角色)
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 请求进行交互。

# 启动 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
自定义: 你可以修改系统提示词变量的值。

📁 项目结构

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 镜像。

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

5. 说话人角色不存在

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

📄 许可证

本项目采用 MIT 许可证开源。

🤝 贡献指南

欢迎提交 Pull Request 和 Issue！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

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