Hugging Face's logo

MoYoYoTech
/
VoiceDialogue

Text-to-Speech
Transformers
ONNX
GGUF
Chinese
English
voice-dialogue
speech-recognition
large-language-model
asr
tts
llm
chinese
english
real-time
conversational
Model card Files
xet
Community
1
VoiceDialogue / README.md
liumaolin
Integrate FunASR service.
516d7b8
preview code
|
raw
history blame
13.4 kB

VoiceDialogue - 智能语音对话系统

Python License Platform Version

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

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

🎯 项目简介

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. 克隆项目
git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
cd VoiceDialogue
  1. 创建并激活虚拟环境
# 使用 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
  1. 安装 whisper.cpp
WHISPER_COREML=1 pip install git+https://github.com/absadiki/pywhispercpp
  1. 安装 llama.cpp
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python
  1. 安装项目依赖
pip install -r requirements.txt
  1. 安装音频处理工具
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt update
sudo apt install ffmpeg

# CentOS/RHEL
sudo yum install ffmpeg

# 或使用 conda
conda install ffmpeg

🎮 首次运行 

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

首次运行说明：

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

⚙️ 配置选项

基础配置

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

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': 最高精度

高级配置

大语言模型参数调优 

# 在 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  # 单实例锁文件

📁 项目结构 

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 硬盘可显著提升模型加载速度

软件优化 

# 针对不同硬件配置的推荐设置

# 高性能配置 (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. 模型下载失败 

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

2. 音频设备问题 

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

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

3. 内存不足错误 

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

4. 依赖包冲突 

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

调试模式

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

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

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

性能监控 

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

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

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

📚 相关资源

官方文档

社区支持

📄 许可证

本项目采用 MIT 许可证开源。详细信息请查看 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

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

Made with ❤️ by MoYoYo Tech