SpeechRecognition/INSTALL.md

项目依赖安装指南

📋 环境要求

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

🚀 快速安装

1. 创建虚拟环境

python -m venv funasr_env

2. 激活虚拟环境

Windows:

funasr_env\Scripts\activate

Linux/macOS:

source funasr_env/bin/activate

3. 安装 PyTorch (带 CUDA 支持)

CUDA 11.8:

pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118

CPU 版本:

pip install torch torchaudio

4. 安装 3D-Speaker

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

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

5. 安装其他依赖

# 返回项目目录
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	需要持久化存储时

🔧 验证安装

运行测试脚本验证安装：

# 测试模型加载
python test_model_load.py

# 运行主程序
python main.py

⚠️ 常见问题

1. CUDA 版本不匹配

错误信息:

RuntimeError: CUDA error: no kernel image is available for execution

解决方案:

# 卸载当前 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'

解决方案:

# 确保 3D-Speaker 在项目父目录
# 结构应为:
#   project/
#     ├── audio2/
#     └── 3D-Speaker/

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

3. 模型下载失败

错误信息:

ConnectionError: Failed to download model from ModelScope

解决方案:

# 使用阿里云镜像
export MODELSCOPE_CACHE="./models"

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

4. 内存不足

错误信息:

RuntimeError: CUDA out of memory

解决方案:

• 减少并发数：修改 main.py 中的 max_workers=1
• 使用 CPU 模式：device='cpu'
• 关闭其他占用 GPU 的程序

📝 依赖版本锁定

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

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

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

🎯 最小化安装

如果只需要基础功能：

# 最小依赖集
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 以上可用空间。