File size: 5,477 Bytes
40186e2 7b64dcd 3c70498 7b64dcd 1858ba9 6a33f71 7b64dcd 1858ba9 6a33f71 3c3f610 3c70498 3c3f610 1858ba9 7b64dcd 1858ba9 7b64dcd 3c3f610 040114b 7b64dcd 040114b 7b64dcd 040114b be3d38f a3adfd5 040114b 3c3f610 1858ba9 28762c8 0112f01 6a33f71 3c3f610 7b64dcd 3c3f610 040114b 3c3f610 7b64dcd 3c3f610 de86e54 a3adfd5 3c3f610 de86e54 7b64dcd 3c3f610 a3adfd5 3c3f610 7b64dcd 3c3f610 1858ba9 7b64dcd 1858ba9 7b64dcd 1858ba9 a5d5551 6a33f71 a3adfd5 6a33f71 1858ba9 7b64dcd 1858ba9 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | ---
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 许可证开源。
## 🙏 致谢
如果这个项目对您有帮助，请给我们一个 ⭐️! |