# talk

**Repository Path**: theyn/talk

## Basic Information

- **Project Name**: talk
- **Description**: ASR（听） + LLM（想） + TTS（说）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语音助手（Vosk + 本地 GGUF 大模型 + edge-tts）

基于 Python + PyQt5 实现的桌面语音助手，支持：
- **语音识别**：Vosk 离线中文识别
- **语音对话**：本地 GGUF 大模型（llama-cpp-python 加载，流式输出，无需 Ollama）
- **文字对话**：界面底部输入框直接发送文字对话
- **语音合成**：edge-tts 在线神经语音（接近真人、多种中文音色）

## 目录结构

```
main.py                 # PyQt5 主界面（启动入口，位于项目根目录）
app/voice_assistant/
  __init__.py           # 模块说明
  asr.py                # Vosk 语音识别
  llm.py                # 本地 GGUF 大模型推理（llama-cpp-python）
  tts.py                # 语音合成（EspeakTTS 离线 + EdgeTTS 在线）
  audio.py              # 录音 / 播放封装
  models/               # 模型目录（Vosk + GGUF，不入版本库）
    vosk-model-small-cn-0.22/   # Vosk 中文模型（解压后）
    qwen2.5-1.5b-instruct-q4_k_m.gguf  # 对话大模型（默认）
docs/
  多种语音对话方案对比.md   # ASR/TTS/LLM 选型对比
  嵌入式部署可行性.md       # RK3568/RK3588 移植可行性分析
```

## 安装依赖

```bash
pip install -r requirements.txt
```

Python 包：`PyQt5`、`vosk`、`pyaudio`、`llama-cpp-python`、`edge-tts`、`pygame`。

> 注：
> - `llama-cpp-python` 默认编译 CPU 版；如需 GPU 加速请参考其官方文档安装 CUDA 版本。
> - `edge-tts`、`pygame` 官方 PyPI 源（清华镜像可能未同步 edge-tts）：
>   `pip install --index-url https://pypi.org/simple/ edge-tts pygame`

## 模型准备

模型统一放到 `app/voice_assistant/models/` 目录（已被 `.gitignore` 忽略，不入库）。

### 1. Vosk 中文模型
下载并解压到 `app/voice_assistant/models/`：
- 推荐小模型：`vosk-model-small-cn-0.22`（约 42MB）
- 下载地址：<https://alphacephei.com/vosk/models>

### 2. 本地 GGUF 大模型
下载一个 **GGUF 量化模型**放到 `app/voice_assistant/models/`（或界面配置区指定路径）。

推荐模型（HuggingFace / ModelScope）：
- **Qwen2.5-1.5B-Instruct**（当前默认）：
  - HuggingFace：`https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF`
  - ModelScope（国内加速）：`https://modelscope.cn/models/qwen/Qwen2.5-1.5B-Instruct-GGUF`
  - 下载 `qwen2.5-1.5b-instruct-q4_k_m.gguf`（约 1GB）

> 量化说明：`q4_k_m` 表示 4bit 量化，内存占用小、速度快。
> 注意：`llama-cpp-python` 0.3.34 不支持 Qwen3 模型（会乱码/复述），请使用 Qwen2.5 系列。

## 运行

```bash
python main.py
```

## 使用说明

1. 启动后，底部配置区可修改 Vosk 模型目录、GGUF 模型路径/文件、音色、系统提示词。
2. **按住**顶部「按住说话」按钮开始录音，界面实时显示识别中间结果；**松开**后整段识别并对话。
3. **文字对话**：在底部输入框输入文字，按回车或点「发送」即可对话（与语音共享同一上下文）。
4. 回复完成后点击「朗读回复」，用 edge-tts 按所选音色朗读。
5. 「清空对话」可重置会话上下文。

### edge-tts 音色（界面可切换）

- `zh-CN-XiaoxiaoNeural` 晓晓 · 女
- `zh-CN-YunxiNeural` 云希 · 男
- `zh-CN-XiaoyiNeural` 晓伊 · 女
- `zh-CN-YunjianNeural` 云健 · 男
- `zh-CN-YunyangNeural` 云扬 · 男
- `zh-CN-liaoning-XiaobeiNeural` 晓北 · 女（东北口音）

## 常见问题

- **识别无结果**：检查 Vosk 模型目录是否正确、麦克风是否可用。
- **GGUF 模型未找到**：确认 `.gguf` 文件已放到 `app/voice_assistant/models/`，或在配置区指定完整路径。
- **加载模型卡顿/慢**：首次加载大模型需数秒到数十秒（取决于模型大小与 CPU），属正常现象。
- **朗读失败/无声音**：edge-tts **需要联网**；无网络时无法合成（状态栏会提示「edge-tts: 不可用」）。
- **朗读有延迟**：edge-tts 在线合成有 1~3 秒首包网络延迟，属正常。
- **录音杂音/延迟**：默认采样率 16k 单声道为 Vosk 最佳配置，请勿改动。

## 已知限制

- edge-tts 依赖微软在线服务，**必须联网**；如需完全离线可切换 `EspeakTTS`（`tts.py` 已保留）。
- Vosk 小模型对安静环境识别较好，复杂噪声环境准确率会下降。
- 本地 GGUF 模型受硬件限制，参数量越大回复越聪明但越慢；建议按内存选择量化模型。