模块化全离线智能语音交互系统

基于 Whisper ASR、Qwen LLM 和 Piper TTS 的完全离线语音助手，支持中文对话，适用于 Mac/Linux/RK3576 嵌入式平台。

📋 项目概述

本项目实现了一个完整的离线语音对话系统，无需联网即可实现：

• 🎤 语音识别（ASR）：使用 Whisper base 模型
• 🧠 智能对话（LLM）：使用 Qwen2-1.5B-Instruct 模型
• 🔊 语音合成（TTS）：使用 Piper TTS 引擎

系统架构

flowchart LR
    A[用户说话] --> B[录音模块<br/>sounddevice]
    B --> C[ASR模块<br/>Whisper Base]
    C --> D[LLM模块<br/>Qwen-1.5B]
    D --> E[TTS模块<br/>Piper TTS]
    E --> F[播放回复]
  
    style A fill:#e1f5ff
    style C fill:#fff4e1
    style D fill:#ffe1f5
    style E fill:#e1ffe1
    style F fill:#e1f5ff

Loading

数据流程

sequenceDiagram
    participant User as 👤 用户
    participant Audio as 🎙️ 音频采集
    participant ASR as 🎧 ASR引擎
    participant LLM as 🤖 LLM引擎
    participant TTS as 🔊 TTS引擎
    participant Speaker as 🎵 扬声器

    User->>Audio: 按回车开始说话
    Audio->>Audio: 录音中 (16kHz)
    User->>Audio: 再按回车停止
    Audio->>ASR: 发送音频数据
    ASR->>ASR: Whisper 识别
    ASR->>LLM: "你知道什么是主理人吗?"
    LLM->>LLM: Qwen 推理生成
    LLM->>TTS: "主理人是教会里..."
    TTS->>TTS: Piper 合成
    TTS->>Speaker: 播放语音
    Speaker->>User: 听到回复

Loading

🚀 快速开始

环境要求

• Python: 3.9 - 3.11
• 系统: macOS / Linux
• 内存: 至少 8GB RAM（推荐 16GB）
• 磁盘: 4GB 可用空间（存储模型）

一键安装（推荐）

使用自动安装脚本，一键完成所有准备工作：

# 克隆项目
git clone https://github.com/cosmopolitan033/voice-chat-bot.git
cd voice-chat-bot

# 运行自动安装脚本
./setup.sh

setup.sh 会自动完成：

1. ✅ 检查 Python 环境
2. ✅ 创建虚拟环境（可选）
3. ✅ 安装 Python 依赖（requirements.txt）
4. ✅ 安装 Piper TTS（pip install piper-tts onnxruntime）
5. ✅ 下载所有模型（ASR + LLM + TTS，约 3.2GB）
6. ✅ 验证安装是否成功

安装完成后，直接运行 python voice_chat.py 即可开始使用！

---

手动安装

如果需要手动控制安装过程：

1. 安装依赖

# 克隆项目
git clone https://github.com/cosmopolitan033/voice-chat-bot.git
cd voice-chat-bot

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate

# 安装 Python 依赖
pip install -r requirements.txt

# 安装 Piper TTS
pip install piper-tts onnxruntime

2. 下载模型

项目需要三个模型，总大小约 3.2GB：

方法 A：自动下载（推荐）

# 运行模型下载脚本
python scripts/download_models.py

脚本会自动下载：

• ✅ Whisper Base (140MB) → models/asr/base.pt
• ✅ Qwen2-1.5B (3GB) → models/llm/qwen-1.5b/
• ✅ Piper TTS 中文模型 (60MB) → models/tts/piper/zh_CN-huayan-medium.onnx

**方法 B：手动下载

ASR 模型：

mkdir -p models/asr
cd models/asr
wget https://openaipublic.azureedge.net/main/whisper/models/ed3a0b6b1c0edf879ad9b11b1af5a0e6ab5db9205f891f668f8b0e6c6326e34e/base.pt
cd ../..

LLM 模型：

# 需要 Hugging Face 账号和 git-lfs
git lfs install
git clone https://huggingface.co/Qwen/Qwen2-1.5B-Instruct models/llm/qwen-1.5b

TTS 模型：

mkdir -p models/tts/piper
cd models/tts/piper
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/zh/zh_CN/huayan/medium/zh_CN-huayan-medium.onnx
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/zh/zh_CN/huayan/medium/zh_CN-huayan-medium.onnx.json
cd ../../..

---

3. 运行程序

# 启动语音助手
python voice_chat.py

使用方法：

1. 程序启动后，按 回车 开始录音
2. 对着麦克风说话（例如："你好，介绍一下你自己"）
3. 说完后按 回车 停止录音
4. 系统自动识别 → 思考 → 回复（会播放语音）
5. 输入 q 退出程序

📁 项目结构

voice-chat-bot/
├── modules/                  # 核心模块
│   ├── asr/                 # 语音识别模块
│   │   ├── asr_engine.py   # Whisper ASR 引擎
│   │   └── __init__.py
│   ├── llm/                 # 大语言模型模块
│   │   ├── llm_engine.py   # Qwen LLM 引擎
│   │   └── __init__.py
│   ├── tts/                 # 语音合成模块
│   │   ├── tts_engine.py   # TTS 服务
│   │   ├── piper_engine.py # Piper 引擎
│   │   └── __init__.py
│   └── communication/       # ZeroMQ 通信（预留）
│
├── models/                   # 模型存储（需下载）
│   ├── asr/
│   │   └── base.pt          # Whisper Base (140MB)
│   ├── llm/
│   │   └── qwen-1.5b/       # Qwen 1.5B (3GB)
│   └── tts/
│       └── piper/           # Piper 中文模型 (60MB)
│
├── tests/                    # 测试脚本
│   ├── test_asr_simple.py   # ASR 文件测试
│   ├── test_asr_record.py   # ASR 录音测试
│   ├── test_llm.py          # LLM 对话测试
│   └── test_tts.py          # TTS 合成测试
│
├── scripts/                  # 工具脚本
│   └── download_models.py   # 模型下载脚本
│
├── voice_chat.py            # 主程序（终端控制）
├── voice_assistant.py       # 主程序（按键控制，需 pynput）
├── requirements.txt         # Python 依赖
└── README.md               # 项目文档

🔧 模块说明

ASR 模块（语音识别）

• 模型: OpenAI Whisper Base
• 大小: 140MB
• 精度: Float32
• 采样率: 16kHz
• 语言: 中文（带简体提示词）
• 性能: 4秒音频 → 0.3秒识别

核心代码：

from modules.asr import ASREngine

asr = ASREngine(model_path="models/asr/base.pt", device="cpu")
asr.load_model()
text = asr.transcribe(audio_data, language="zh")

LLM 模块（大语言模型）

• 模型: Qwen2-1.5B-Instruct
• 大小: 3GB
• 参数: 15亿
• 上下文: 支持多轮对话（保留5轮）
• 设备: MPS (Mac) / CUDA (Linux)
• 性能: 生成25字 → 1.5秒

核心代码：

from modules.llm import LLMEngine

llm = LLMEngine(model_path="models/llm/qwen-1.5b")
llm.load_model()
llm.history.set_system_prompt("你是一个友好的助手")
response = llm.generate("你好")

TTS 模块（语音合成）

• 引擎: Piper TTS
• 模型: zh_CN-huayan-medium
• 大小: 60MB
• 音色: 中文女声
• 格式: WAV 16kHz
• 特点: 完全离线，跨平台

核心代码：

from modules.tts import TTSService

tts = TTSService(
    engine_type="piper",
    model_path="models/tts/piper/zh_CN-huayan-medium.onnx"
)
tts.speak("你好，我是语音助手")

📊 性能指标

在 Mac M4 (16GB RAM) 上测试：

模块	输入	输出	耗时	设备
ASR	4.4秒音频	文本	0.32s	CPU
LLM	13字文本	25字回复	1.55s	MPS
TTS	25字文本	5秒音频	6.49s	CPU
总计	-	-	~8s	-

🧪 测试模块

测试各个模块是否正常工作：

# 测试 ASR（文件识别）
python tests/test_asr_simple.py

# 测试 ASR（录音识别）
python tests/test_asr_record.py

# 测试 LLM（文本对话）
python tests/test_llm.py

# 测试 TTS（语音合成）
python tests/test_tts.py

⚙️ 配置选项

编辑 config/config.yaml 自定义配置：

asr:
  model_name: "base"            # tiny/base/small/medium/large
  device: "cpu"                 # cpu/cuda/mps
  language: "zh"

llm:
  model_name: "Qwen2-1.5B-Instruct"
  max_length: 512               # 最大生成长度
  temperature: 0.7              # 温度（0-1）
  max_history_rounds: 5         # 对话历史轮数

tts:
  engine_type: "piper"          # piper/edge-tts
  model_path: "models/tts/piper/zh_CN-huayan-medium.onnx"