Update README.md: revise feature descriptions, add new Web API service section, update supported TTS models and characters, and include enhanced installation and usage instructions.

README.md

@@ -17,11 +17,11 @@
 
 VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端到端的语音交互体验。系统采用模块化设计，支持：
 
-- 🎤 **实时语音识别** - 基于 Whisper 的高精度语音转文本，支持中英文识别
-- 🤖 **智能对话生成** - 集成多种大语言模型（Qwen2.5、Llama3、Mistral等）
-- 🔊 **高质量语音合成** - 基于 GPT-SoVITS 的多角色语音生成
+- 🎤 **实时语音识别** - 基于 FunASR 和 Whisper 的高精度语音转文本
+- 🤖 **智能对话生成** - 集成 Qwen2.5 等多种大语言模型
+- 🔊 **高质量语音合成** - 基于 GPT-SoVITs 和 Kokoro TTS 的多角色语音生成
+- 🌐 **Web API 服务** - 提供 HTTP 接口，方便与其他应用集成
 - 🔇 **回声消除** - 内置音频处理技术，支持实时语音交互
-- 🌍 **多语言支持** - 支持中文和英文语音识别与合成
 - ⚡ **低延迟处理** - 优化的音频流处理管道，实现流畅对话体验
 
 ## ✨ 主要特性
@@ -30,32 +30,44 @@ VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端
 - **回声消除音频捕获** - 自动消除回声干扰，提升语音质量
 - **语音活动检测(VAD)** - 智能检测用户说话状态，自动开始/停止录制
 - **实时音频流处理** - 低延迟音频播放和处理
-- **多格式音频支持** - 支持多种音频格式的输入输出
 
 ### 🗣️ 语音识别
 - **智能语音识别引擎** - 中文使用FunASR高精度识别，其他语言使用Whisper模型
-- **FunASR中文优化** - 专为中文语音优化的识别引擎，支持方言和口音识别
-- **Whisper多语言支持** - 支持 Medium / Large 模型，覆盖多种国际语言
-- **自动语言检测** - 根据配置自动选择最适合的识别引擎
+- **自动语言切换** - 根据启动参数自动选择最优识别引擎
 - **实时转录处理** - 流式语音转文本处理，降低响应延迟
-- **高精度识别** - 基于最新语音识别技术，提供业界领先的识别准确率
-
 
 ### 🧠 语言模型
-支持多种预训练大语言模型：
-- **Qwen2.5** (7B/14B) - 阿里巴巴开源的中文优化模型
-- **Llama3** (8B) - Meta 开源的通用对话模型  
-- **Mistral** (7B) - 高效推理的欧洲开源模型
-- **自定义系统提示词** - 可配置 AI 助手的行为风格
+- **Qwen2.5 (14B)** - 内置阿里巴巴开源的中文优化模型
+- **LangChain 集成** - 方便扩展和支持更多语言模型
+- **自定义系统提示词** - 可在代码中配置 AI 助手的行为风格
 
 ### 🎭 语音合成
-内置丰富的音色选择，基于 GPT-SoVITS 技术：
-- **罗翔** - 法学教授风格，适合严肃话题
-- **马保国** - 网络名人风格，轻松幽默
-- **沈逸** - 学者风格，理性分析
-- **杨幂** - 明星风格，亲和力强
-- **周杰伦** - 歌手风格，个性鲜明
-- **马云** - 企业家风格，商务感强
+项目集成了两种先进的语音合成技术，提供丰富的音色选择：
+
+#### GPT-SoVITs 技术（中文角色）
+基于 GPT-SoVITs 的中文语音合成，支持以下角色：
+- **罗翔** - 法学教授风格，具有幽默风趣和深入浅出的讲解风格
+- **马保国** - 太极大师风格，带有标志性的口音和语调特色
+- **沈逸** - 学者风格，具有理性分析风格和富有磁性的嗓音
+- **杨幂** - 明星风格，拥有清甜动人的声线和自然流畅的表达方式
+- **周杰伦** - 歌手风格，具有标志性的说话风格和音乐气质
+- **马云** - 企业家风格，富有激情的演讲风格和商业洞察表达方式
+
+#### Kokoro TTS 技术（英文角色）
+基于 Kokoro TTS 的英文语音合成，支持以下角色：
+- **Heart** - 温暖亲切的英语女性语音，声音富有感情色彩
+- **Bella** - 优质的英语女性语音，具有清晰自然的发音和良好的表现力
+- **Nicole** - 高质量的英语女性语音，发音清晰准确，语调自然流畅
+
+#### 技术特点
+- **智能引擎选择** - 系统根据内容语言自动选择最适合的TTS引擎
+- **高质量合成** - 采用先进的神经网络技术，生成自然流畅的语音
+- **多角色支持** - 提供多样化的音色选择，满足不同场景需求
+- **可扩展架构** - 模块化设计，方便添加更多语音角色和TTS引擎
+
+### ⚙️ 服务模式
+- **命令行模式 (CLI)** - 在终端中直接运行，提供实时语音交互体验
+- **API 服务模式** - 启动一个 FastAPI Web 服务器，提供 HTTP 接口进行交互
 
 ## 🚀 快速开始
 
@@ -66,7 +78,6 @@ VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端
 - **内存要求**: 至少 16GB RAM (推荐 32GB 用于大模型)
 - **存储空间**: 至少 20GB 可用空间 (用于模型文件)
 
-
 ### 安装步骤
 
 1. **克隆项目**
@@ -81,165 +92,167 @@ cd VoiceDialogue
 conda create -n voicedialogue python=3.9
 conda activate voicedialogue
 
-# 或使用 virtualenv
+# 或使用 venv
 python -m venv voicedialogue
-source voicedialogue/bin/activate  # Linux/macOS
-# voicedialogue\Scripts\activate  # Windows
+source voicedialogue/bin/activate
 ```
 
-3. **安装 whisper.cpp**
+3. **安装核心依赖**
 ```bash
+# whisper.cpp for ASR
 WHISPER_COREML=1 pip install git+https://github.com/absadiki/pywhispercpp
-```
-4. **安装 llama.cpp**
-```bash
+
+# llama.cpp for LLM
 CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python
 ```
 
-5. **安装项目依赖**
+4. **安装项目依赖**
 ```bash
 pip install -r requirements.txt
 ```
 
-6. **安装音频处理工具**
+5. **安装音频处理工具**
 ```bash
 # macOS
 brew install ffmpeg
 
-# Ubuntu/Debian
-sudo apt update
-sudo apt install ffmpeg
+# Linux (Ubuntu/Debian)
+sudo apt update && sudo apt install ffmpeg
+```
+
+### 🎮 运行系统
 
-# CentOS/RHEL
-sudo yum install ffmpeg
+`VoiceDialogue` 支持两种运行模式：**命令行模式 (CLI)** 和 **API 服务模式**。
 
-# 或使用 conda
-conda install ffmpeg
-```
+#### 1. 命令行模式 (默认)
 
-### 🎮 首次运行
+直接在终端进行实时语音对话。
 
 ```bash
-# 启动语音对话系统
+# 启动语音对话系统 (默认使用中文)
 python src/VoiceDialogue/main.py
+
+# 指定语言和角色
+python src/VoiceDialogue/main.py --language en --speaker "Yang Mi"
 ```
 
 **首次运行说明**：
-- 系统会自动下载所需的模型文件 (约 5-10GB)
-- 下载时间取决于网络速度，请耐心等待
-- 模型文件会保存在 `~/.moyoyo_ai/` 目录下
-- 看到 "服务启动成功" 提示后即可开始语音对话
+- 系统会自动下载所需的模型文件 (约 10-15GB)，请耐心等待。
+- 模型文件会保存在 `~/.moyoyo_ai/` 目录下。
+- 看到 "服务启动成功" 提示后即可开始说话。
+
+#### 2. API 服务模式
+
+启动一个 Web 服务器，通过 HTTP 请求进行交互。
+
+```bash
+# 启动 API 服务器
+python src/VoiceDialogue/main.py --mode api
 
+# 指定不同端口
+python src/VoiceDialogue/main.py --mode api --port 9000
+```
+- API 文档地址: `http://localhost:8000/docs`
 
 ## ⚙️ 配置选项
 
-### 基础配置
+### 启动参数
 
-在 `src/VoiceDialogue/main.py` 的 `main()` 函数中可以自定义以下选项：
+通过 `main.py` 的命令行参数可以方便地进行配置：
 
-```python
-def main():
-    # 语言设置
-    user_language = 'zh'  # 'zh': 中文 | 'en': 英文
-
-    # 系统提示词 - 定义 AI 助手的行为风格
-    SYSTEM_PROMPT = (
-        "你是善于模拟真实的思考过程的AI助手。"
-        "回答时，必须首先生成一个不超过5个字的简短句子，"
-        "比如：\"让我想一下\"、\"在我看来\"、\"稍等我理一理\"等，"
-        "然后再进行正式回答，保持中文口语化表达。"
-    )
-
-    # TTS 语音合成角色
-    tts_speaker = '沈逸'  # 可选: 罗翔、马保国、沈逸、杨幂、周杰伦、马云
-
-    # 大语言模型规模
-    llm = '14B'  # '7B': 更快推理 | '14B': 更好效果
-
-    # Whisper 语音识别模型
-    whisper_model = 'medium'  # 'medium': 平衡速度和精度 | 'large': 最高精度
-```
+| 参数 | 缩写 | 可选值 | 默认值 | 描述 |
+|---|---|---|---|---|
+| `--mode` | `-m` | `cli`, `api` | `cli` | 设置运行模式 |
+| `--language`| `-l` | `zh`, `en` | `zh` | (CLI模式) 设置用户语言 |
+| `--speaker` | `-s` | (见下表) | `沈逸` | (CLI模式) 设置TTS语音角色 |
+| `--host` | | IP地址 | `0.0.0.0` | (API模式) 服务器主机 |
+| `--port` | `-p` | 端口号 | `8000` | (API模式) 服务器端口 |
+| `--reload`| | 无 | `False` | (API模式) 启用热重载 |
+
+**支持的 `speaker` 角色**: 
+- 中文角色：`罗翔`, `马保国`, `沈逸`, `杨幂`, `周杰伦`, `马云`
+- 英文角色：`Heart`, `Bella`, `Nicole`
 
 ### 高级配置
 
-#### 大语言模型参数调优
+#### 大语言模型 (LLM)
 
-```python
-# 在 main.py 中的 default_llm_params 字典
-default_llm_params = {
-    'streaming': True,        # 启用流式输出
-    'n_gpu_layers': -1,      # GPU 层数 (-1 为全部)
-    'n_batch': 512,          # 批处理大小
-    'n_ctx': 2048,           # 上下文长度
-    'f16_kv': True,          # 16位浮点数
-    'temperature': 0.8,      # 创造性参数 (0.0-1.0)
-    'top_k': 50,             # Top-K 采样
-    'top_p': 1.0,            # Top-P 采样
-}
-
-#### 路径配置
-
-系统使用 `src/VoiceDialogue/config/settings.py` 管理路径配置：
+- **模型路径和参数**: LLM 的模型和推理参数目前在代码中硬编码，方便快速启动。
+- **文件位置**: `src/VoiceDialogue/services/text/text_generator.py`
+- **自定义**: 你可以修改 `LLMResponseGenerator` 类中的 `run` 方法，更换模型路径或调整 `model_params` 字典中的参数（如 `temperature`, `top_k`, `top_p` 等）。
 
 ```python
-# 默认数据目录
-DATA_FOLDER = ~/.moyoyo_ai/
-
-# 模型存储路径
-├── llm_models/          # 大语言模型
-├── audio_models/        # TTS 语音模型  
-├── audio_output/        # 音频输出文件
-└���─ .single_instance_locker  # 单实例锁文件
+# src/VoiceDialogue/services/text/text_generator.py
+# ...
+class LLMResponseGenerator(BaseThread):
+# ...
+    def run(self):
+        # 修改这里的模型路径
+        model_path = paths.MODELS_PATH / 'llm' / 'Qwen2.5-14B-Instruct.Q4_0.gguf'
+        # 修改这里的推理参数
+        model_params = {
+            'streaming': True,
+            'n_gpu_layers': -1,
+            'n_batch': 512,
+            # ...
+        }
+# ...
 ```
 
+#### 语音识别 (ASR)
+
+- **引擎自动选择**: 系统会根据 `--language` 参数自动选择最合适的 ASR 引擎 (`FunASR` for `zh`, `Whisper` for `en`)。
+- **模型配置**: ASR 模型的具体配置位于 `src/VoiceDialogue/services/speech/asr/manager.py`。
+
+#### 系统提示词 (System Prompt)
+
+- **功能**: 定义 AI 角色的行为和说话风格。
+- **文件位置**: `src/VoiceDialogue/services/text/text_generator.py`
+- **自定义**: 你可以修改 `CHINESE_SYSTEM_PROMPT` 和 `ENGLISH_SYSTEM_PROMPT` 变量的值。
+
 ## 📁 项目结构
 
 ```text
 VoiceDialogue/
-├── src/                          # 源代码目录
-│   └── VoiceDialogue/           # 主要代码包
+├── src/
+│   └── VoiceDialogue/
+│       ├── api/                 # Web API 模块 (FastAPI)
+│       │   ├── app.py           # FastAPI 应用实例
+│       │   ├── server.py        # uvicorn 服务器
+│       │   └── ...              # 路由、依赖、模型等
 │       ├── config/              # 配置管理
-│       │   ├── __init__.py
 │       │   ├── paths.py         # 路径配置
 │       │   └── settings.py      # 系统设置
-│       ├── models/              # 模型管理模块
-│       │   ├── audio_model.py   # 音频模型管理
-│       │   ├── language_model.py # 语言模型管理
-│       │   └── voice_model.py   # 语音模型管理
+│       ├── models/              # 数据模型和任务
+│       │   ├── language_model.py # 语言模型定义
+│       │   └── voice_task.py    # 语音任务定义
 │       ├── services/            # 服务模块
 │       │   ├── audio/           # 音频处理服务
 │       │   │   ├── aec_audio_capture.py  # 回声消除捕获
 │       │   │   ├── audio_answer.py       # TTS 音频生成
-│       │   │   └── audio_player.py       # 音频播放
+│       │   │   ├── audio_player.py       # 音频播放
+│       │   │   └── audio_generator/      # TTS 管理器
 │       │   ├── speech/          # 语音识别服务
 │       │   │   ├── speech_monitor.py     # 语音状态监控
-│       │   │   └── asr_service.py        # ASR 识别服务
-│       │   ├── text/            # 文本生成服务
-│       │   │   └── text_generator.py     # LLM 文本生成
-│       │   └── core/            # 核心服务
+│       │   │   ├── asr_service.py        # ASR 识别服务
+│       │   │   └── asr/                  # ASR 管理器
+│       │   └── text/            # 文本生成服务
+│       │       ├── text_generator.py     # LLM 文本生成
+│       │       └── langchain_llm.py    # LangChain 集成
 │       ├── utils/               # 工具函数
 │       └── main.py              # 主程序入口
-├── models/                      # 预训练模型存储
-│   └── asr/                     # 语音识别模型
-├── resources/                   # 资源文件
-│   ├── audio/                   # 音频资源
-│   └── libraries/               # 动态库文件
-├── third_party/                 # 第三方库
-├── tests/                       # 测试文件
-├── docs/                        # 文档目录
+├── models/                      # 预训练模型存储 (自动下载)
 ├── requirements.txt             # Python 依赖
-├── .gitignore                   # Git 忽略文件
 └── README.md                    # 项目说明文档
 ```
 
 ## 🔧 系统架构
 
-### 数据流程图
-
+### 数据流程图 (CLI 模式)
 ```
-用户语音输入  →  回声消除  →  语音活动检测  →  语音转录  →  LLM生成回复  →  TTS合成  →  音频输出
-    ↑                                                                                 ↓
-    └───────────────────────────────── 实时语音交互循环 ─────────────────────────────────┘
+用户语音输入 → 回声消除 → 语音活动检测 → 语音转录 (ASR) → LLM生成回复 → TTS合成 → 音频输出
+↑                                                                              ↓
+└──────────��──────────────────── 实时语音交互循环 ────────────────────────────────┘
 ```
 
 
@@ -249,144 +262,46 @@ VoiceDialogue/
 |------|----------|----------|
 | **EchoCancellingAudioCapture** | 回声消除音频捕获 | 实时音频流捕获与预处理 |
 | **SpeechStateMonitor** | 语音活动检测 | VAD 算法检测用户说话状态 |
-| **WhisperWorker** | 语音识别转录 | OpenAI Whisper 模型推理 |
-| **LLMResponseGenerator** | 智能文本生成 | 大语言模型对话生成 |
-| **TTSAudioGenerator** | 语音合成 | GPT-SoVITS 文本转语音 |
+| **ASRWorker** | 语音识别转录 | FunASR / Whisper 模型推理 |
+| **LLMResponseGenerator** | 智能文本生成 | Qwen2.5 (llama.cpp) 对话生成 |
+| **TTSAudioGenerator** | 语音合成 | GPT-SoVITs / Kokoro TTS 文本转语音 |
 | **AudioStreamPlayer** | 音频流播放 | 实时音频输出播放 |
-
-### 多线程架构
-
-系统采用多线程并发处理架构，通过消息队列实现组件间通信：
-
-- `audio_frames_queue`: 原始音频帧队列
-- `user_voice_queue`: 用户语音片段队列  
-- `transcribed_text_queue`: 转录文本队列
-- `generated_answer_queue`: 生成回答队列
-- `tts_generated_audio_queue`: TTS 音频队列
-
-## 🔍 使用指南
-
-### 基本使用流程
-
-1. **启动系统**: 运行 `python src/VoiceDialogue/main.py`
-2. **等待加载**: 首次运行会下载模型，请耐心等待
-3. **开始对话**: 看到"服务启动成功"后直接开始说话
-4. **语音交互**: 系统会自动检测语音并进行对话
-5. **停止系统**: 使用 Ctrl+C 终止程序
-
-### 性能优化建议
-
-#### 硬件优化
-- **GPU 加速**: 如有 NVIDIA GPU，确保安装 CUDA 版本的 PyTorch
-- **内存管理**: 16GB RAM 可同时运行 14B 模型，8GB RAM 建议使用 7B 模型
-- **存储优化**: SSD 硬盘可显著提升模型加载速度
-
-#### 软件优化
-```python
-# 针对不同硬件配置的推荐设置
-
-# 高性能配置 (16GB+ RAM, GPU)
-llm = '14B'
-whisper_model = 'large'
-default_llm_params['n_batch'] = 1024
-default_llm_params['n_ctx'] = 4096
-
-# 平衡配置 (8-16GB RAM)
-llm = '7B'
-whisper_model = 'medium'
-default_llm_params['n_batch'] = 512
-default_llm_params['n_ctx'] = 2048
-
-# 轻量配置 (8GB RAM, CPU only)
-llm = '7B'
-whisper_model = 'medium'
-default_llm_params['n_gpu_layers'] = 0
-default_llm_params['n_batch'] = 256
-```
+| **FastAPI App** | API服务 | 提供HTTP接口，封装核心服务 |
 
 ## 🛠️ 故障排除
 
-### 常见问题及解决方案
-
-#### 1. 模型下载失败
+### 1. 模型下载失败
+- **问题**: 网络连接超时或模型下载失败。
+- **解决方案**: 设置 Hugging Face 镜像。
 ```bash
-# 问题: 网络连接超时或模型下载失败
-# 解决方案:
-export HF_ENDPOINT=https://hf-mirror.com  # 使用镜像站点
+export HF_ENDPOINT=https://hf-mirror.com
 pip install -U huggingface_hub
 ```
 
-#### 2. 音频设备问题
-```bash
-# 问题: 找不到音频设备或权限被拒绝
-# macOS 解决方案:
-# 系统偏好设置 → 安全性与隐私 → 隐私 → 麦克风 → 添加终端应用
-
-# Linux 解决方案:
-sudo usermod -a -G audio $USER
-# 重新登录生效
-```
-
-#### 3. 内存不足错误
-```python
-# 问题: CUDA out of memory 或 RAM 不足
-# 解决方案: 降低模型规模和批处理大小
-llm = '7B'  # 改为 7B 模型
-default_llm_params['n_batch'] = 256  # 减少批处理大小
-default_llm_params['n_ctx'] = 1024   # 减少上下文长度
-```
-
-#### 4. 依赖包冲突
+### 2. 音频设备问题
+- **问题**: 找不到音频设备或权限被拒绝。
+- **macOS 解决方案**: 系统设置 → 隐私与安全性 → 麦克风 → 启用你的终端应用 (如 iTerm, Terminal)。
+- **Linux 解决方案**: `sudo usermod -a -G audio $USER`，然后重新登录。
+
+### 3. 内存不足错误 (OOM)
+- **问题**: `CUDA out of memory` 或 RAM 不足。
+- **解决方案**: LLM 是主要的内存消耗者。你可以通过修改 `src/VoiceDialogue/services/text/text_generator.py` 来降低资源消耗：
+    - **更换模型**: 将 `model_path` 指向一个更小的模型（如 7B Q4 量化模型）。
+    - **减少批处理大小**: 减小 `model_params` 中的 `n_batch` 值（如 `256`）。
+    - **减少上下文长度**: 减小 `n_ctx` 的值（如 `1024`）。
+
+### 4. 依赖包冲突
+- **问题**: 包版本冲突或导入错误。
+- **解决方案**: 强烈建议在虚拟环境中安装。如果遇到问题，尝试重建虚拟环境。
 ```bash
-# 问题: 包版本冲突或导入错误
-# 解决方案: 重新创建虚拟环境
 conda deactivate
 conda env remove -n voicedialogue
-conda create -n voicedialogue python=3.9
-conda activate voicedialogue
-pip install -r requirements.txt
+# ... 重新执行安装步骤 ...
 ```
 
-### 调试模式
-
-启用详细日志输出进行问题诊断：
-
-```python
-import logging
-logging.basicConfig(level=logging.DEBUG)
-
-# 在 main.py 开头添加上述代码
-```
-
-### 性能监控
-
-```bash
-# 监控系统资源使用情况
-# macOS
-top -pid $(pgrep -f "python.*main.py")
-
-# Linux  
-htop -p $(pgrep -f "python.*main.py")
-
-# 监控 GPU 使用 (NVIDIA)
-nvidia-smi -l 1
-```
-
-## 📚 相关资源
-
-### 官方文档
-- [OpenAI Whisper](https://github.com/openai/whisper)
-- [GPT-SoVITS](https://github.com/RVC-Boss/GPT-SoVITS)
-- [Qwen2.5 模型](https://huggingface.co/Qwen)
-- [LangChain 框架](https://python.langchain.com/)
-
-### 社区支持
-- 问题反馈: [GitHub Issues](https://github.com/MoYoYoTech/VoiceDialogue/issues)
-- 功能建议: [GitHub Discussions](https://github.com/MoYoYoTech/VoiceDialogue/discussions)
-
 ## 📄 许可证
 
-本项目采用 MIT 许可证开源。详细信息请查看 [LICENSE](LICENSE) 文件。
+本项目采用 MIT 许可证开源。
 
 ## 🤝 贡献指南
 
@@ -404,6 +319,4 @@ nvidia-smi -l 1
 
 **如果这个项目对您有帮助，请给我们一个 ⭐️!**
 
-Made with ❤️ by [MoYoYo Tech](https://github.com/MoYoYoTech)
-
 </div>