---
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">

![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Platform](https://img.shields.io/badge/Platform-macOS-lightgrey.svg)
![Version](https://img.shields.io/badge/Version-1.2.0-orange.svg)

一个集成了语音识别(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 许可证开源。

## 🙏 致谢

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