Update README for enhanced installation and usage guidance.

README.md

@@ -5,54 +5,64 @@
 ![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.0.0-orange.svg)
 
 一个集成了语音识别(ASR)、大语言模型(LLM)和文本转语音(TTS)的实时语音对话系统
 
+[快速开始](#-快速开始) • [功能特性](#-主要特性) • [配置说明](#-配置选项) • [系统架构](#-系统架构) • [故障排除](#-故障排除)
+
 </div>
 
 ## 🎯 项目简介
 
-VoiceDialogue 是一个完整的语音对话系统，支持：
-- 🎤 **实时语音识别** - 基于 Whisper 的高精度语音转文本
-- 🤖 **智能对话生成** - 支持多种大语言模型（Qwen、Llama、Mistral等）
+VoiceDialogue 是一个基于 Python 的完整语音对话系统，实现了端到端的语音交互体验。系统采用模块化设计，支持：
+
+- 🎤 **实时语音识别** - 基于 Whisper 的高精度语音转文本，支持中英文识别
+- 🤖 **智能对话生成** - 集成多种大语言模型（Qwen2.5、Llama3、Mistral等）
 - 🔊 **高质量语音合成** - 基于 GPT-SoVITS 的多角色语音生成
-- 🔇 **回声消除** - 内置音频处理，支持实时语音交互
+- 🔇 **回声消除** - 内置音频处理技术，支持实时语音交互
 - 🌍 **多语言支持** - 支持中文和英文语音识别与合成
+- ⚡ **低延迟处理** - 优化的音频流处理管道，实现流畅对话体验
 
 ## ✨ 主要特性
 
 ### 🎵 音频处理
-- **回声消除音频捕获** - 消除回声干扰，提升语音质量
-- **语音活动检测** - 自动检测用户说话状态
-- **实时音频流处理** - 低延迟音频播放
+- **回声消除音频捕获** - 自动消除回声干扰，提升语音质量
+- **语音活动检测(VAD)** - 智能检测用户说话状态，自动开始/停止录制
+- **实时音频流处理** - 低延迟音频播放和处理
+- **多格式音频支持** - 支持多种音频格式的输入输出
 
 ### 🗣️ 语音识别
-- **Whisper 模型支持** - Medium/Large 模型可选
-- **多语言识别** - 支持中文/英文自动识别
-- **实时转录** - 流式语音转文本处理
+- **Whisper 模型支持** - 支持 Medium/Large 模型，可根据精度需求选择
+- **多语言识别** - 自动识别中文/英文语音内容
+- **实时转录** - 流式语音转文本处理，降低响应延迟
+- **高精度识别** - 基于 OpenAI Whisper 的领先语音识别技术
 
 ### 🧠 语言模型
-支持多种预训练模型：
-- **Qwen2.5** (7B/14B) - 中文优化模型
-- **Llama3** (8B) - 通用对话模型  
-- **Mistral** (7B) - 高效推理模型
-- **Phi-3** (mini) - 轻量级模型
+支持多种预训练大语言模型：
+- **Qwen2.5** (7B/14B) - 阿里巴巴开源的中文优化模型
+- **Llama3** (8B) - Meta 开源的通用对话模型  
+- **Mistral** (7B) - 高效推理的欧洲开源模型
+- **自定义系统提示词** - 可配置 AI 助手的行为风格
 
 ### 🎭 语音合成
-内置多种音色选择：
-- 罗翔 - 法学教授风格
-- 马保国 - 网络名人风格
-- 沈逸 - 学者风格
-- 杨幂 - 明星风格
-- 周杰伦 - 歌手风格
-- 马云 - 企业家风格
+内置丰富的音色选择，基于 GPT-SoVITS 技术：
+- **罗翔** - 法学教授风格，适合严肃话题
+- **马保国** - 网络名人风格，轻松幽默
+- **沈逸** - 学者风格，理性分析
+- **杨幂** - 明星风格，亲和力强
+- **周杰伦** - 歌手风格，个性鲜明
+- **马云** - 企业家风格，商务感强
 
 ## 🚀 快速开始
 
-### 环境要求
+### 系统要求
+
+- **操作系统**: macOS 14+ (推荐)
+- **Python 版本**: 3.9 或更高版本
+- **内存要求**: 至少 16GB RAM (推荐 32GB 用于大模型)
+- **存储空间**: 至少 20GB 可用空间 (用于模型文件)
 
-- Python 3.9+
-- macOS 14+
 
 ### 安装步骤
 
@@ -62,103 +72,167 @@ git clone https://huggingface.co/MoYoYoTech/VoiceDialogue
 cd VoiceDialogue
 ```
 
-2. **创建虚拟环境**
+2. **创建并激活虚拟环境**
 ```bash
+# 使用 conda (推荐)
 conda create -n voicedialogue python=3.9
 conda activate voicedialogue
+
+# 或使用 virtualenv
+python -m venv voicedialogue
+source voicedialogue/bin/activate  # Linux/macOS
+# voicedialogue\Scripts\activate  # Windows
 ```
 
-3. **安装依赖**
+3. **安装 whisper.cpp**
 ```bash
-# 基础依赖
-pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118
-pip install -r requirements.txt
-
-# 音频处理
-conda install ffmpeg
-
-# macOS 额外依赖
-brew install ffmpeg  # macOS only
+WHISPER_COREML=1 pip install git+https://github.com/absadiki/pywhispercpp
+```
+4. **安装 llama.cpp**
+```bash
+CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python
 ```
 
-4. **下载模型文件**
-
-模型会在首次运行时自动下载，或手动下载：
+5**安装项目依赖**
+```bash
+pip install -r requirements.txt
+```
 
+6**安装音频处理工具**
 ```bash
-# ASR 模型 (Whisper)
-mkdir -p models/asr
-# 下载 whisper 模型到 models/asr/
+# macOS
+brew install ffmpeg
 
-# LLM 模型
-mkdir -p models/llm  
-# 模型将从 HuggingFace 自动下载
+# Ubuntu/Debian
+sudo apt update
+sudo apt install ffmpeg
 
-# TTS 模型
-mkdir -p models/tts
-# GPT-SoVITS 模型将自动下载
+# CentOS/RHEL
+sudo yum install ffmpeg
+
+# 或使用 conda
+conda install ffmpeg
 ```
 
-### 🎮 运行程序
+### 🎮 首次运行
 
 ```bash
 # 启动语音对话系统
-python -m src.VoiceDialogue.main
+python src/VoiceDialogue/main.py
 ```
 
-### ⚙️ 配置选项
+**首次运行说明**：
+- 系统会自动下载所需的模型文件 (约 5-10GB)
+- 下载时间取决于网络速度，请耐心等待
+- 模型文件会保存在 `~/.moyoyo_ai/` 目录下
+- 看到 "服务启动成功" 提示后即可开始语音对话
 
-在 `src/VoiceDialogue/main.py` 中可以自定义：
+
+## ⚙️ 配置选项
+
+### 基础配置
+
+在 `src/VoiceDialogue/main.py` 的 `main()` 函数中可以自定义以下选项：
 
 ```python
 def main():
     # 语言设置
-    user_language = 'zh'  # 'zh' 中文 | 'en' 英文
+    user_language = 'zh'  # 'zh': 中文 | 'en': 英文
 
-    # 系统提示词
-    SYSTEM_PROMPT = "你是善于模拟真实思考过程的AI助手..."
+    # 系统提示词 - 定义 AI 助手的行为风格
+    SYSTEM_PROMPT = (
+        "你是善于模拟真实的思考过程的AI助手。"
+        "回答时，必须首先生成一个不超过5个字的简短句子，"
+        "比如：\"让我想一下\"、\"在我看来\"、\"稍等我理一理\"等，"
+        "然后再进行正式回答，保持中文口语化表达。"
+    )
 
-    # TTS 音色选择
+    # TTS 语音合成角色
     tts_speaker = '沈逸'  # 可选: 罗翔、马保国、沈逸、杨幂、周杰伦、马云
 
-    # LLM 模型大小
-    llm = '14B'  # '7B' | '14B'
+    # 大语言模型规模
+    llm = '14B'  # '7B': 更快推理 | '14B': 更好效果
+
+    # Whisper 语音识别模型
+    whisper_model = 'medium'  # 'medium': 平衡速度和精度 | 'large': 最高精度
+```
+
+### 高级配置
+
+#### 大语言模型参数调优
+
+```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` 管理路径配置：
 
-    # Whisper 模型
-    whisper_model = 'medium'  # 'medium' | 'large'
+```python
+# 默认数据目录
+DATA_FOLDER = ~/.moyoyo_ai/
+
+# 模型存储路径
+├── llm_models/          # 大语言模型
+├── audio_models/        # TTS 语音模型  
+├── audio_output/        # 音频输出文件
+└── .single_instance_locker  # 单实例锁文件
 ```
 
 ## 📁 项目结构
+
 ```text
 VoiceDialogue/
-├── src/ # 源代码
-│ └── VoiceDialogue/ # 主要代码包
-│   ├── config/ # 配置文件
-│   │ └── settings.py # 系统设置
-│   ├── models/ # 模型相关代码
-│   │ ├── audio_model.py # 音频模型管理
-│   │ ├── llm_model.py # 语言模型管理
-│   │ └── ...
-│   ├── services/ # 服务模块
-│   │ ├── audio/ # 音频处理服务
-│   │ ├── speech/ # 语音识别服务
-│   │ ├── text/ # 文本生成服务
-│   │ └── core/ # 核心服务
-│   ├── utils/ # 工具函数
-│   └── main.py # 主程序入口
-├── models/ # 预训练模型
-│ ├── asr/ # 语音识别模型
-│ └── tts/ # 语音合成模型
-├── resources/ # 资源文件
-│ ├── audio/ # 音频资源
-│ ├── libraries/ # 动态库
-│ └── models/ # 模型配置
-├── third_party/ # 第三方库
-├── tests/ # 测试文件
-└── docs/ # 文档
+├── src/                          # 源代码目录
+│   └── VoiceDialogue/           # 主要代码包
+│       ├── config/              # 配置管理
+│       │   ├── __init__.py
+│       │   ├── paths.py         # 路径配置
+│       │   └── settings.py      # 系统设置
+│       ├── models/              # 模型管理模块
+│       │   ├── audio_model.py   # 音频模型管理
+│       │   ├── language_model.py # 语言模型管理
+│       │   └── voice_model.py   # 语音模型管理
+│       ├── services/            # 服务模块
+│       │   ├── audio/           # 音频处理服务
+│       │   │   ├── aec_audio_capture.py  # 回声消除捕获
+│       │   │   ├── audio_answer.py       # TTS 音频生成
+│       │   │   └── audio_player.py       # 音频播放
+│       │   ├── speech/          # 语音识别服务
+│       │   │   ├── speech_monitor.py     # 语音状态监控
+│       │   │   └── whisper_service.py    # Whisper 识别服务
+│       │   ├── text/            # 文本生成服务
+│       │   │   └── text_generator.py     # LLM 文本生成
+│       │   └── core/            # 核心服务
+│       ├── utils/               # 工具函数
+│       └── main.py              # 主程序入口
+├── models/                      # 预训练模型存储
+│   └── asr/                     # 语音识别模型
+├── resources/                   # 资源文件
+│   ├── audio/                   # 音频资源
+│   └── libraries/               # 动态库文件
+├── third_party/                 # 第三方库
+├── tests/                       # 测试文件
+├── docs/                        # 文档目录
+├── requirements.txt             # Python 依赖
+├── .gitignore                   # Git 忽略文件
+└── README.md                    # 项目说明文档
 ```
 
 ## 🔧 系统架构
+
+### 数据流程图
+
 ```
 用户语音输入  →  回声消除  →  语音活动检测  →  Whisper转录  →  LLM生成回复  →  TTS合成  →  音频输出
     ↑                                                                                 ↓
@@ -166,12 +240,167 @@ VoiceDialogue/
 ```
 
 
-### 核心组件
+### 核心组件说明
+
+| 组件 | 功能描述 | 技术实现 |
+|------|----------|----------|
+| **EchoCancellingAudioCapture** | 回声消除音频捕获 | 实时音频流捕获与预处理 |
+| **SpeechStateMonitor** | 语音活动检测 | VAD 算法检测用户说话状态 |
+| **WhisperWorker** | 语音识别转录 | OpenAI Whisper 模型推理 |
+| **LLMResponseGenerator** | 智能文本生成 | 大语言模型对话生成 |
+| **TTSAudioGenerator** | 语音合成 | GPT-SoVITS 文本转语音 |
+| **AudioStreamPlayer** | 音频流播放 | 实时音频输出播放 |
+
+### 多线程架构
+
+系统采用多线程并发处理架构，通过消息队列实现组件间通信：
+
+- `audio_frames_queue`: 原始音频帧队列
+- `user_voice_queue`: 用户语音片段队列  
+- `transcribed_text_queue`: 转录文本队列
+- `generated_answer_queue`: 生成回答队列
+- `tts_generated_audio_queue`: TTS 音频队列
+
+## 🔍 使用指南
+
+### 基本使用流程
+
+1. **启动系统**: 运行 `python -m src.VoiceDialogue.main`
+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
+```
+
+## 🛠️ 故障排除
+
+### 常见问题及解决方案
+
+#### 1. 模型下载失败
+```bash
+# 问题: 网络连接超时或模型下载失败
+# 解决方案:
+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. 依赖包冲突
+```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) 文件。
+
+## 🤝 贡献指南
+
+欢迎提交 Pull Request 和 Issue！
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+---
+
+<div align="center">
+
+**如果这个项目对您有帮助，请给我们一个 ⭐️!**
 
-1. **EchoCancellingAudioCapture** - 回声消除音频捕获
-2. **SpeechStateMonitor** - 语音状态监控
-3. **WhisperWorker** - Whisper语音识别
-4. **LLMResponseGenerator** - LLM文本生成
-5. **TTSAudioGenerator** - TTS语音合成
-6. **AudioStreamPlayer** - 音频流播放
+Made with ❤️ by [MoYoYo Tech](https://github.com/MoYoYoTech)
 
+</div>

requirements.txt

@@ -9,7 +9,7 @@ torch==2.3.1
 transformers==4.41.2
 accelerate
 setuptools==70.0.0
-llama_cpp_python
+llama_cpp_python==0.3.9
 langchain==0.2.17
 langchain-community==0.2.17