Ubuntu部署GeneFace++方法

Ubuntu部署GeneFace++实操指南
一 环境准备与版本选择

• 操作系统与硬件：建议使用 Ubuntu 18.04/20.04/22.04，NVIDIA GPU（如 RTX 3090/V100/A100 已验证），显存建议 ≥8GB，可用存储 ≥20GB。
• CUDA 与驱动：优先选择 CUDA 11.7（项目已在 A100/V100 上验证），当前不支持 CUDA 12+；安装后在容器内或系统中确认 /usr/local/cuda-11.7 路径与驱动正常。
• Python 与工具：使用 conda 创建隔离环境，推荐 Python 3.9；安装 ffmpeg（含 libx264）、GCC/G++/make 等基础工具。
• 项目地址：https://github.com/yerfor/GeneFacePlusPlus

二 本机或容器部署步骤

• 获取代码与创建环境
• 克隆仓库：git clone https://github.com/yerfor/GeneFacePlusPlus.git && cd GeneFacePlusPlus
• 创建环境：conda create -n geneface python=3.9 -y && conda activate geneface
• 多媒体与系统依赖：conda install -c conda-forge ffmpeg -y；sudo apt-get install -y libasound2-dev portaudio19-dev build-essential
• 安装 PyTorch（两种已验证组合，二选一）
• 组合A（适配 CUDA 11.7）：

conda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 pytorch-cuda=11.7 -c pytorch -c nvidia -y

• 组合B（适配 CUDA 11.3）：

conda install pytorch==1.11.0 torchvision==0.12.0 torchaudio==0.11.0 cudatoolkit=11.3 -c pytorch -c nvidia -y

• 安装 PyTorch3D
• 推荐源码安装：pip install "git+https://github.com/facebookresearch/pytorch3d.git@stable"
• 安装 MMCV（若项目脚本用到）
• pip install cython -i https://mirrors.aliyun.com/pypi/simple
• pip install openmim==0.3.9 -i https://mirrors.aliyun.com/pypi/simple
• mim install mmcv==2.1.0
• 安装其他 Python 依赖
• pip install -r docs/prepare_env/requirements.txt -i https://mirrors.aliyun.com/pypi/simple
• 编译自定义 CUDA 扩展
• bash docs/prepare_env/install_ext.sh
• 验证环境（可选）
• 运行 3D 重建模块测试：export PYTHONPATH=./ && CUDA_VISIBLE_DEVICES=0 python deep_3drecon/test.py
• 生成重建器配置：python deep_3drecon/generate_reconstructor_opt_for_geneface.py

三 Docker 部署步骤

• 运行容器并映射端口（示例映射 8000）：
• sudo docker run -p 8000:8000 -it --name ubuntu_conda117 --gpus all --privileged=true ubuntu:latest /bin/bash
• 拷贝 CUDA 到容器并配置环境变量：
• sudo docker cp /usr/local/cuda-11.7/ ubuntu_conda117:/usr/local/
• 在容器内 ~/.bashrc 追加：
• CUDA_PATH_11=/usr/local/cuda-11.7
• export PATH=${CUDA_PATH_11}/bin${PATH:+:${PATH}}
• export LD_LIBRARY_PATH=${CUDA_PATH_11}/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
• 执行 source ~/.bashrc
• 拷贝项目代码并进入目录：
• sudo docker cp /data/code/GeneFacePlusPlus/ ubuntu_conda117:/data/code/
• cd /data/code/GeneFacePlusPlus
• 在容器内按“本机部署步骤”安装 Python 依赖、PyTorch、PyTorch3D、MMCV 并运行 bash docs/prepare_env/install_ext.sh

四 数据准备与训练推理

• 数据预处理：按 docs/process_data/guide-zh.md 准备个性化视频，生成二进制 .npy 数据文件。
• 训练与推理：按 docs/train_and_infer/guide-zh.md 执行；首次可逐步运行命令排查问题，跑通后可使用同目录的 bash run.sh ${VIDEO_ID} 一键化执行。
• 合成测试：按说明配置后，进行音频驱动的视频与口型同步合成测试。

五 常见问题与排查

• 版本不兼容
• 已发现 torch==2.1 + cuda12.1 会导致 torch-ngp 错误；建议优先使用 CUDA 11.7 + torch 2.0.1 或 CUDA 11.3 + torch 1.11.0 的组合。
• 自定义扩展冲突
• 若与 ER-NeRF 等项目的 gridencoder 冲突，建议为 GeneFace++ 单独创建 conda 环境，避免同名模块覆盖。
• 环境与权限问题
• 依赖多、版本需严格匹配；安装过程可能需要 sudo；注意 CUDA 路径与 LD_LIBRARY_PATH 配置，容器内需映射 /usr/local/cuda-11.7 并正确设置环境变量。
• 硬件与性能
• 显存 <8GB 可能影响训练/推理或无法运行；建议使用 ≥8GB 显存 GPU。