Ubuntu部署GeneFace++环境

Ubuntu部署GeneFace++环境指南

1. 系统要求

• 操作系统：Ubuntu 18.04及以上版本（推荐20.04/22.04，兼容性更好）；
• 硬件配置：NVIDIA显卡（RTX 3090及以上已验证），显存≥8GB，存储空间≥20GB（用于存放代码、模型及数据集）；
• 依赖基础：GCC、G++、make等编译工具（通过sudo apt install build-essential安装）。

2. CUDA环境配置

GeneFace++依赖CUDA加速计算，推荐安装CUDA 11.7（与PyTorch 2.0.1版本匹配，避免兼容性问题）：

• 下载CUDA 11.7 Toolkit：从NVIDIA官网获取对应Ubuntu版本的安装包；
• 安装CUDA：运行sudo dpkg -i cuda-keyring*.deb添加官方源，执行sudo apt-get update更新软件源，再通过sudo apt-get -y install cuda=11.7.1-1安装指定版本；
• 验证安装：终端输入nvcc --version，应显示CUDA 11.7的版本信息；
• 配置环境变量：编辑~/.bashrc文件，添加export PATH=/usr/local/cuda-11.7/bin:$PATH和export LD_LIBRARY_PATH=/usr/local/cuda-11.7/lib64:$LD_LIBRARY_PATH，执行source ~/.bashrc使配置生效。

3. Python环境搭建

使用conda创建隔离环境，避免依赖冲突：

• 创建conda环境：conda create -n geneface python=3.9 -y（GeneFace++推荐Python 3.9）；
• 激活环境：conda activate geneface；
• 安装ffmpeg：conda install conda-forge::ffmpeg -y（用于视频编码，支持将图像序列转为视频）。

4. PyTorch及扩展库安装

安装与CUDA 11.7匹配的PyTorch版本，并配置3D计算机视觉库：

• 安装PyTorch：conda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 pytorch-cuda=11.7 -c pytorch -c nvidia（确保PyTorch能识别CUDA设备）；
• 安装PyTorch3D：pip install "git+https://github.com/facebookresearch/pytorch3d.git@stable"（用于3D渲染，支持NeRF技术）；
• 安装MMCV：pip install cython（编译依赖），pip install openmim==0.3.9（加速安装），mim install mmcv==2.1.0（计算机视觉基础库）。

5. 系统依赖与项目依赖

• 安装系统库：sudo apt-get install libasound2-dev portaudio19-dev（音频处理依赖，支持语音输入）；
• 安装项目依赖：进入GeneFace++项目目录（cd GeneFacePlusPlus），执行pip install -r docs/prepare_env/requirements.txt -v -i https://mirrors.aliyun.com/pypi/simple（安装Python依赖包，使用国内镜像加速下载）。

6. 自定义CUDA扩展编译

GeneFace++包含自定义CUDA内核，需编译扩展以提升性能：

• 执行编译脚本：bash docs/prepare_env/install_ext.sh（编译项目特定的CUDA扩展，如3D重建相关模块）；
• 注意：编译过程中若出现网络超时，可配置pip代理（如export http_proxy=http://your_proxy:port）解决。

7. 环境验证

• 测试3D重建模块：执行CUDA_VISIBLE_DEVICES=0 python deep_3drecon/test.py（使用GPU 0运行测试脚本），若输出“Test passed”则表示3D重建模块正常；
• 验证与GeneFace++集成：运行python deep_3drecon/generate_reconstructor_opt_for_geneface.py（生成GeneFace++所需的优化文件），无报错则集成成功。

8. 常见问题解决

• 依赖冲突：若安装过程中出现版本不兼容（如PyTorch与CUDA版本不匹配），可调整requirements.txt中的库版本，或创建新的conda环境重新安装；
• 模型路径错误：确保预训练模型（如checkpoints/audio2motion_vae、checkpoints/motion2video_nerf）放置在项目指定目录，推理脚本中的路径需与实际一致；
• 数据集格式问题：下载的数据集需为.npy格式（如trainval_dataset.npy），若格式不符可参考项目文档中的数据处理步骤转换。