197 lines
3.5 KiB
Markdown
197 lines
3.5 KiB
Markdown
# 项目依赖安装指南
|
|
|
|
## 📋 环境要求
|
|
|
|
- **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 torchaudio --index-url https://download.pytorch.org/whl/cu118
|
|
```
|
|
|
|
**CPU 版本:**
|
|
```bash
|
|
pip install torch 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** 以上可用空间。
|