| --- |
| 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"> |
|
|
|  |
|  |
|  |
|  |
|
|
| 一个集成了语音识别(ASR)、大语言模型(LLM)和文本转语音(TTS)的实时语音对话系统 |
|
|
| [快速开始](#-快速开始) • [文档导航](#-文档导航) • [贡献指南](docs/contributing.md) |
|
|
| </div> |
|
|
| ## 🎯 项目简介 |
|
|
| VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端到端的语音交互体验。系统采用模块化设计，具备实时、高精度、多角色的特点。 |
|
|
| - 🖥️ **图形界面**: 内置 Web 图形界面，浏览器即可使用（选音色、切语言、看实时字幕） |
| - 🎤 **实时语音识别**: 基于 Qwen3-ASR 的高精度中英文转录（自带标点，支持 52 种语言） |
| - 🤖 **智能对话生成**: 集成 Qwen3 等大语言模型 |
| - 🔊 **高质量语音合成**: 支持多角色、多风格的语音输出 |
| - 🌐 **Web API 服务**: 提供 HTTP 接口，方便集成 |
| - ⚡ **低延迟处理**: 优化的音频流处理管道 |
|
|
| > 想要了解更多？请查看 [功能特性详解](docs/features.md)。 |
|
|
| ## 🚀 快速开始 |
|
|
| > **最简单的方式**：克隆仓库 → 安装依赖 → 启动 → 在浏览器打开图形界面，即可开始语音对话。 |
| > 目前仅支持 **macOS（Apple Silicon）**。 |
|
|
| ### 1. 克隆并安装 |
|
|
| > **模型分两部分**： |
| > - **随仓库下载（约 12GB，Git LFS）**：大语言模型、语音合成、参考音色等。 |
| > - **首次启动自动下载（约 4.4GB）**：语音识别引擎 **Qwen3-ASR**，由程序在第一次运行时从 HuggingFace 拉取并缓存到 `~/.cache/huggingface`，之后无需重复下载。 |
| > |
| > ⚠️ **必须先安装 [Git LFS](https://git-lfs.com)**，否则克隆下来的模型只是几百字节的占位指针，应用无法启动。 |
|
|
| ```bash |
| # 1) 安装并初始化 Git LFS（只需一次） |
| brew install git-lfs # 如未安装 Homebrew，见 https://git-lfs.com |
| git lfs install |
| |
| # 2) 克隆项目（包含约 12GB 模型，体积较大，请耐心等待） |
| git clone https://huggingface.co/MoYoYoTech/VoiceDialogue |
| cd VoiceDialogue |
| |
| # 3) 校验模型确实拉取成功（应显示 GB 级大小，而非 100+ 字节） |
| # 若显示很小，说明 Git LFS 未生效，执行：git lfs pull |
| ls -lh assets/models/llm/qwen/Qwen3-8B-Q6_K.gguf |
| |
| # 4) 安装依赖（推荐使用 uv） |
| pip install uv |
| uv venv |
| source .venv/bin/activate |
| |
| WHISPER_COREML=1 CMAKE_ARGS="-DGGML_METAL=on" uv sync |
| |
| # 5) 安装额外依赖 |
| uv pip install kokoro-onnx # kokoro-onnx（英文 TTS） |
| uv pip install numpy==1.26.4 # 固定 numpy 版本 |
| ``` |
|
|
| > 📖 需要更详细的步骤？请查阅 [安装指南](docs/installation.md)，其中包含系统要求和常见问题。 |
|
|
| ### 2. 启动图形界面（推荐） |
|
|
| ```bash |
| python main.py --mode api |
| ``` |
|
|
| 启动后，在浏览器中打开：**http://localhost:8000/app/** |
|
|
| 在界面中即可完成全部操作： |
|
|
| - 点击右下角 **⚙️ 设置**，选择**麦克风、回音消除、识别语言、音色**，也可切换**中 / 英界面语言**； |
| - 点击 **「开始对话」**，即可与 AI 实时语音对话，**字幕会实时显示**。 |
|
|
| > **首次启动较慢，属正常现象**：程序会自动下载 Qwen3-ASR 模型（约 4.4GB，需联网，下载进度会打印在终端）并转换一次 TTS 权重格式。全部完成后才会就绪，整个过程约几分钟（取决于网速）；之后每次启动只需数十秒。 |
| > 若终端长时间停在下载步骤，请检查网络是否能访问 `huggingface.co`。 |
|
|
| ### 3. 命令行模式（CLI） |
|
|
| 如果不需要图形界面，也可以直接在终端运行语音对话： |
|
|
| ```bash |
| # 启动语音对话（默认中文） |
| python main.py |
| |
| # 指定语言与音色 |
| python main.py --language en --speaker Heart |
| |
| # 列出可用音频输入设备（如外置麦克风阵列） |
| python main.py --list-audio-devices |
| |
| # 指定输入设备 |
| python main.py --input-device <设备索引> |
| ``` |
|
|
| > 详细使用方法请参考 [配置指南](docs/configuration.md) 和 [API 服务指南](docs/api-guide.md)。 |
|
|
| ## 📚 文档导航 |
|
|
| - 📖 **[安装指南](docs/installation.md)**: 详细的安装步骤和系统要求。 |
| - ⚙️ **[配置指南](docs/configuration.md)**: 如何配置系统参数和高级选项。 |
| - 🎭 **[功能特性](docs/features.md)**: 深入了解项目的所有功能。 |
| - 🌐 **[API 指南](docs/api-guide.md)**: 如何使用和集成 API 服务。 |
| - 🏗️ **[系统架构](docs/architecture.md)**: 了解系统的内部工作原理。 |
| - 📁 **[项目结构](docs/project-structure.md)**: 浏览项目代码和文件组织。 |
| - 🛠️ **[故障排除](docs/troubleshooting.md)**: 常见问题和解决方案。 |
| - 🤝 **[贡献指南](docs/contributing.md)**: 如何为项目做出贡献。 |
|
|
| ## 📄 许可证 |
|
|
| 本项目采用 MIT 许可证开源。 |
|
|
| ## 🙏 致谢 |
|
|
| 如果这个项目对您有帮助，请给我们一个 ⭐️! |
