SpeechRecognition/INSTALL.md

# 项目依赖安装指南

## 📋 环境要求

- **Python**: 3.10+
- **CUDA**: 11.8+ (可选，用于 GPU 加速)
- **系统**: Windows 10/11, Linux, macOS

## 🚀 快速安装

### 1. 创建虚拟环境

```bash
python -m venv funasr_env
```

### 2. 激活虚拟环境

**Windows:**
```bash
funasr_env\Scripts\activate
```

**Linux/macOS:**
```bash
source funasr_env/bin/activate
```

### 3. 安装 PyTorch (带 CUDA 支持)

**CUDA 11.8:**
```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```

**CPU 版本:**
```bash
pip install torch torchvision torchaudio
```

### 4. 安装 3D-Speaker

```bash
# 克隆 3D-Speaker 项目到父目录
cd ..
git clone https://github.com/alibaba-damo-academy/3D-Speaker.git

# 安装 3D-Speaker 依赖
cd 3D-Speaker
pip install -e .
```

### 5. 安装其他依赖

```bash
# 返回项目目录
cd ../audio2

# 安装 requirements.txt
pip install -r requirements.txt
```

## 📦 依赖说明

### 核心依赖

| 包名 | 用途 | 必需 |
|------|------|------|
| torch | 深度学习框架 | ✅ |
| funasr | 语音识别引擎 | ✅ |
| modelscope | 模型下载与管理 | ✅ |
| speakerlab | 3D-Speaker 说话人分离 | ✅ |
| soundfile | 音频文件读写 | ✅ |
| librosa | 音频分析 | ✅ |

### 可选依赖

| 包名 | 用途 | 何时需要 |
|------|------|----------|
| onnxruntime-gpu | ONNX 推理加速 | 需要更高性能时 |
| Flask | Web API 服务 | 需要部署 Web 服务时 |
| SQLAlchemy | 数据库 ORM | 需要持久化存储时 |

## 🔧 验证安装

运行测试脚本验证安装：

```bash
# 测试模型加载
python test_model_load.py

# 运行主程序
python main.py
```

## ⚠️ 常见问题

### 1. CUDA 版本不匹配

**错误信息:**
```
RuntimeError: CUDA error: no kernel image is available for execution
```

**解决方案:**
```bash
# 卸载当前 PyTorch
pip uninstall torch torchvision torchaudio

# 根据 CUDA 版本重新安装
# CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
```

### 2. 3D-Speaker 导入失败

**错误信息:**
```
ModuleNotFoundError: No module named 'speakerlab'
```

**解决方案:**
```bash
# 确保 3D-Speaker 在项目父目录
# 结构应为:
#   project/
#     ├── audio2/
#     └── 3D-Speaker/

# 重新安装 3D-Speaker
cd 3D-Speaker
pip install -e .
```

### 3. 模型下载失败

**错误信息:**
```
ConnectionError: Failed to download model from ModelScope
```

**解决方案:**
```bash
# 使用阿里云镜像
export MODELSCOPE_CACHE="./models"

# 或手动下载模型后放入缓存目录
```

### 4. 内存不足

**错误信息:**
```
RuntimeError: CUDA out of memory
```

**解决方案:**
- 减少并发数：修改 `main.py` 中的 `max_workers=1`
- 使用 CPU 模式：`device='cpu'`
- 关闭其他占用 GPU 的程序

## 📝 依赖版本锁定

如需精确控制版本，使用：

```bash
# 生成当前环境的依赖快照
pip freeze > requirements.lock.txt

# 使用锁定的版本安装
pip install -r requirements.lock.txt
```

## 🎯 最小化安装

如果只需要基础功能：

```bash
# 最小依赖集
pip install torch funasr modelscope soundfile scipy numpy tqdm pyyaml
```

## 📊 磁盘空间需求

| 组件 | 空间需求 |
|------|----------|
| 基础依赖 | ~2 GB |
| PyTorch (CUDA) | ~3 GB |
| FunASR 模型 | ~2 GB |
| 3D-Speaker 模型 | ~1 GB |
| **总计** | **~8 GB** |

建议预留 **10 GB** 以上可用空间。