MoYoYoTech/VoiceDialogue
645
1---2title: VoiceDialogue - 智能语音对话系统3license: mit4language:5 - zh6 - en7pipeline_tag: text-to-speech8tags:9 - voice-dialogue10 - speech-recognition11 - text-to-speech12 - large-language-model13 - asr14 - tts15 - llm16 - chinese17 - english18 - real-time19library_name: transformers20---21 22# VoiceDialogue - 智能语音对话系统23 24<div align="center">25 2627282930 31一个集成了语音识别(ASR)、大语言模型(LLM)和文本转语音(TTS)的实时语音对话系统32 33[快速开始](#-快速开始) • [文档导航](#-文档导航) • [贡献指南](docs/contributing.md)34 35</div>36 37## 🎯 项目简介38 39VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端到端的语音交互体验。系统采用模块化设计，具备实时、高精度、多角色的特点。40 41- 🖥️ **图形界面**: 内置 Web 图形界面，浏览器即可使用（选音色、切语言、看实时字幕）42- 🎤 **实时语音识别**: 基于 Qwen3-ASR 的高精度中英文转录（自带标点，支持 52 种语言）43- 🤖 **智能对话生成**: 集成 Qwen3 等大语言模型44- 🔊 **高质量语音合成**: 支持多角色、多风格的语音输出45- 🌐 **Web API 服务**: 提供 HTTP 接口，方便集成46- ⚡ **低延迟处理**: 优化的音频流处理管道47 48> 想要了解更多？请查看 [功能特性详解](docs/features.md)。49 50## 🚀 快速开始51 52> **最简单的方式**：克隆仓库 → 安装依赖 → 启动 → 在浏览器打开图形界面，即可开始语音对话。53> 目前仅支持 **macOS（Apple Silicon）**。54 55### 1. 克隆并安装56 57> **模型分两部分**：58> - **随仓库下载（约 12GB，Git LFS）**：大语言模型、语音合成、参考音色等。59> - **首次启动自动下载（约 4.4GB）**：语音识别引擎 **Qwen3-ASR**，由程序在第一次运行时从 HuggingFace 拉取并缓存到 `~/.cache/huggingface`，之后无需重复下载。60>61> ⚠️ **必须先安装 [Git LFS](https://git-lfs.com)**，否则克隆下来的模型只是几百字节的占位指针，应用无法启动。62 63```bash64# 1) 安装并初始化 Git LFS（只需一次）65brew install git-lfs # 如未安装 Homebrew，见 https://git-lfs.com66git lfs install67 68# 2) 克隆项目（包含约 12GB 模型，体积较大，请耐心等待）69git clone https://huggingface.co/MoYoYoTech/VoiceDialogue70cd VoiceDialogue71 72# 3) 校验模型确实拉取成功（应显示 GB 级大小，而非 100+ 字节）73# 若显示很小，说明 Git LFS 未生效，执行：git lfs pull74ls -lh assets/models/llm/qwen/Qwen3-8B-Q6_K.gguf75 76# 4) 安装依赖（推荐使用 uv）77pip install uv78uv venv79source .venv/bin/activate80 81WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync82 83# 5) 安装额外依赖84uv pip install kokoro-onnx # kokoro-onnx（英文 TTS）85uv pip install numpy==1.26.4 # 固定 numpy 版本86```87 88> 📖 需要更详细的步骤？请查阅 [安装指南](docs/installation.md)，其中包含系统要求和常见问题。89 90### 2. 启动图形界面（推荐）91 92```bash93python main.py --mode api94```95 96启动后，在浏览器中打开：**http://localhost:8000/app/**97 98在界面中即可完成全部操作：99 100- 点击右下角 **⚙️ 设置**，选择**麦克风、回音消除、识别语言、音色**，也可切换**中 / 英界面语言**；101- 点击 **「开始对话」**，即可与 AI 实时语音对话，**字幕会实时显示**。102 103> **首次启动较慢，属正常现象**：程序会自动下载 Qwen3-ASR 模型（约 4.4GB，需联网，下载进度会打印在终端）并转换一次 TTS 权重格式。全部完成后才会就绪，整个过程约几分钟（取决于网速）；之后每次启动只需数十秒。104> 若终端长时间停在下载步骤，请检查网络是否能访问 `huggingface.co`。105 106### 3. 命令行模式（CLI）107 108如果不需要图形界面，也可以直接在终端运行语音对话：109 110```bash111# 启动语音对话（默认中文）112python main.py113 114# 指定语言与音色115python main.py --language en --speaker Heart116 117# 列出可用音频输入设备（如外置麦克风阵列）118python main.py --list-audio-devices119 120# 指定输入设备121python main.py --input-device <设备索引>122```123 124> 详细使用方法请参考 [配置指南](docs/configuration.md) 和 [API 服务指南](docs/api-guide.md)。125 126## 📚 文档导航127 128- 📖 **[安装指南](docs/installation.md)**: 详细的安装步骤和系统要求。129- ⚙️ **[配置指南](docs/configuration.md)**: 如何配置系统参数和高级选项。130- 🎭 **[功能特性](docs/features.md)**: 深入了解项目的所有功能。131- 🌐 **[API 指南](docs/api-guide.md)**: 如何使用和集成 API 服务。132- 🏗️ **[系统架构](docs/architecture.md)**: 了解系统的内部工作原理。133- 📁 **[项目结构](docs/project-structure.md)**: 浏览项目代码和文件组织。134- 🛠️ **[故障排除](docs/troubleshooting.md)**: 常见问题和解决方案。135- 🤝 **[贡献指南](docs/contributing.md)**: 如何为项目做出贡献。136 137## 📄 许可证138 139本项目采用 MIT 许可证开源。140 141## 🙏 致谢142 143如果这个项目对您有帮助，请给我们一个 ⭐️!