# voice_chat
**Repository Path**: whererose/voice_chat
## Basic Information
- **Project Name**: voice_chat
- **Description**: # Voice Chat - 实时语音对话系统 让 AI 开口说话，就像和朋友聊天一样自然。
## ✨ 这是什么？
一个 开箱即用 的实时语音对话系统，支持多厂商 ASR + LLM + TTS 组合，让你用代码快速搭建自己的"语音助手"。
核心亮点：
- 🚀 低延迟流式对话 - 边说边听边回复，不用等完整回复
- 🎯 智能打断机制 - 随时打断 AI，毫秒级响应
- 🔇 频谱 VAD
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-04
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 🎙️ Voice Chat - 让 AI 开口说话
**一个开箱即用的实时语音对话系统，支持多厂商 ASR + LLM + TTS**
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](./tests/)
[快速开始](#-快速开始) • [演示](#-演示) • [文档](#-文档) • [贡献](#-贡献)
---
## 🌟 为什么选择 Voice Chat？
想象一下：你对着电脑说话，AI 立刻用自然的声音回复你，就像和朋友聊天一样流畅。
**这不是幻想，这就是 Voice Chat。**
### ✨ 核心亮点
| 特性 | 说明 |
|------|------|
| 🚀 **超低延迟** | 流式处理，边说边听边回复，首句 1-3 秒出声 |
| 🎯 **智能打断** | 随时打断 AI，毫秒级响应，真正的对话体验 |
| 🔇 **频谱 VAD** | 区分人声和环境噪声，拍手/挪凳子不会误触发 |
| 🔊 **回声消除** | 扬声器播放时也能准确识别用户说话 |
| 🔌 **多厂商支持** | 火山引擎 / 阿里通义 / OpenAI，一键切换 |
| 🛡️ **生产级稳定** | 35+ 单元测试，自动重连，错误恢复 |
---
## 🎯 两种运行模式
### 模式一：分离模式（推荐）
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 用户 │ → │ ASR │ → │ LLM │ → │ TTS │ → 播放
│ 说话 │ │ 语音识别 │ │ 大模型 │ │ 语音合成 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
```
**优势：**
- 各服务独立，可自由组合不同厂商
- LLM 可选 doubao-seed-evolving 等先进模型
- 适合需要灵活配置的场景
### 模式二：实时全双工模式
```
┌─────────┐ ┌─────────┐
│ 用户 │ ←── WebSocket ──→ │ AI │
│ 说话 │ 单条长连接 │ 全链路 │
└─────────┘ └─────────┘
```
**优势：**
- 服务端完成 ASR + LLM + TTS 全链路
- 更低延迟，更接近真人对话体验
- 适合追求极致响应的场景
---
## 🚀 快速开始
### 1️⃣ 环境准备
```bash
# Ubuntu/Debian
sudo apt install -y python3-dev portaudio19-dev
# macOS
brew install portaudio
```
### 2️⃣ 安装
```bash
# 克隆项目
git clone https://gitee.com/ying_cheng_li/voice_chat.git
cd voice_chat
# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -e .
```
### 3️⃣ 配置 API Key
创建 `.env` 文件：
```bash
# 火山引擎 API Key（用于 ASR/TTS/Chat）
VOLCENGINE_API_KEY=your-api-key-here
# 或使用其他厂商
# DASHSCOPE_API_KEY=your-dashscope-key
# OPENAI_API_KEY=your-openai-key
```
### 4️⃣ 运行
```bash
python -m voice_chat.main
```
**就这么简单！** 对着麦克风说话，AI 会实时回复你。
---
## 🎬 演示
### 使用场景
- 🏠 **智能家居助手** - 语音控制家电，查询天气
- 🚗 **车载语音系统** - 导航、音乐、电话
- 📚 **教育辅导** - 语音问答，语言学习
- 🏥 **医疗咨询** - 语音问诊，健康建议
- 🎮 **游戏 NPC** - 智能对话，剧情互动
---
## 🏗️ 架构设计
```
┌─────────────────────────────────────────────────┐
│ Conversation │
│ 对话生命周期管理 + 事件路由 │
└──────┬──────────────┬──────────────┬────────────┘
│ │ │
▼ ▼ ▼
Audio Audio Provider
Capture Player (ASR/LLM/TTS)
音频采集 音频播放 厂商适配器
│ │ │
└──────────────┴──────────────┘
AEC 回声消除
```
**核心模块：**
| 模块 | 职责 |
|------|------|
| `dialogue.py` | 对话状态机（IDLE → LISTENING → THINKING） |
| `conversation.py` | 对话协调器，串联各模块 |
| `audio.py` | 音频采集与播放 |
| `aec.py` | 回声消除处理器 |
| `providers/` | 厂商适配器（火山引擎/阿里/OpenAI） |
---
## 🧪 测试覆盖
**35+ 单元测试**，覆盖核心路径：
- ✅ 对话状态机流转
- ✅ ASR 断句与重连逻辑
- ✅ 音频播放与 AEC 交互
- ✅ 全双工协议验证
- ✅ TTS 协议与生命周期
```bash
# 运行全部测试
pytest
# 或单独运行
python tests/test_dialogue.py
python tests/test_asr_reconnect.py
```
---
## 📚 文档
- [ARCHITECTURE.md](./ARCHITECTURE.md) - 详细架构文档
- [docs/design/](./docs/design/) - 设计文档
- [docs/history/](./docs/history/) - 开发历史
---
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
### 接入新厂商
如果你想接入新的语音服务厂商，只需 3 步：
1. 实现 `BaseRealtimeProvider` 基类
2. 在 `providers/factory.py` 注册
3. 完成！上层代码无需任何修改
---
## 💖 支持项目
**如果觉得对你有帮助，请打赏一杯奶茶钱吧 🥤**
**扫码打赏，支持开源**
---
## 📄 许可证
MIT License
---
**⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！**
---
## 🔗 相关链接
- [火山引擎](https://www.volcengine.com/) - 字节跳动云服务
- [阿里通义](https://tongyi.aliyun.com/) - 阿里云 AI 服务
- [OpenAI](https://openai.com/) - GPT 系列模型
---
**Made with ❤️ by Voice Chat Team**