CentOS服务器上GeneFace Plus Plus安装教程

CentOS服务器上部署 GeneFace++ 的完整教程
一 环境准备与驱动检查

• 确认 GPU 与驱动：执行 nvidia-smi，确保驱动正常；如需安装或升级，请先安装与 CUDA 版本匹配的 NVIDIA 驱动。
• 安装 CUDA Toolkit：GeneFace++ 社区常用 CUDA 11.7（亦有 11.3 的教程分支）。安装后在 shell 配置中导出环境变量，例如：

export PATH="/usr/local/cuda-11.7/bin:$PATH"
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda-11.7/lib64
export CUDA_HOME=/usr/local/cuda
执行 nvcc --version 验证版本。

• 基础工具：安装 gcc/g++、make、cmake 等编译工具（yum 或 dnf）。
• 音频依赖（后续 Python 依赖会用到）：yum install -y alsa-lib-devel portaudio-devel。
• 说明：GeneFace++ 官方更常见于 Ubuntu，但在 CentOS 上通过 Conda 与源码编译同样可行；关键是 CUDA、驱动与 PyTorch 版本匹配。

二 创建 Conda 环境并安装 PyTorch 与多媒体依赖

• 创建隔离环境：conda create -n geneface python=3.9；conda activate geneface。
• 安装多媒体工具：conda install -c conda-forge ffmpeg。
• 安装 PyTorch（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
注：有经验帖指出 torch 2.1 + CUDA 12.1 在部分子模块（如 torch-ngp）会报错，优先选用 2.0.1+cu117。

• 安装 PyTorch3D（源码方式，编译耗时较长）：

pip install "git+https://github.com/facebookresearch/pytorch3d.git@stable"

• 安装 MMCV（推荐用 MIM）：

pip install cython
pip install openmim==0.3.9
mim install mmcv==2.1.0

• 安装项目 Python 依赖：

pip install -r docs/prepare_env/requirements.txt
以上版本组合与安装命令为 GeneFace++ 社区常见做法，适用于 CentOS 服务器场景。
三 编译 CUDA 扩展与验证安装

• 编译自定义算子/扩展：在项目根目录执行

bash docs/prepare_env/install_ext.sh
该脚本通常会构建如 gridencoder 等 CUDA 扩展，确保与当前 CUDA、PyTorch 版本匹配。

• 快速自检（示例）：
• 验证 3D 重建模块：

export PYTHONPATH=.
CUDA_VISIBLE_DEVICES=0 python deep_3drecon/test.py

• 生成/检查跟踪所需文件：

cd data_util/face_tracking
python convert_BFM.py
若脚本或模块缺失，请确认已安装 requirements.txt 并执行了 install_ext.sh。
四 数据集与 3DMM 模型准备

• 获取并放置 BFM2009 模型文件：将 01_MorphableModel.mat 放到 deep_3drecon/BFM/。
• 放置 PCA 基向量：将 Exp_Pca.bin 放到 deep_3drecon/BFM/。
• 可选前脸模型：将 BFM_model_front.mat 放到 deep_3drecon/BFM/。
• 人脸重建权重：下载 epoch_20.pth 到 deep_3drecon/checkpoints/facerecon/。
• 生成跟踪文件：在 data_util/face_tracking 下执行 python convert_BFM.py，生成 3DMM_info.npy。
• 以上资源与目录结构为 GeneFace/ER-NeRF 系列常见约定，缺失会导致 3D 重建或跟踪阶段报错。

五 常见问题与排错要点

• 版本不匹配：确保 PyTorch 的 CUDA 版本 与系统 CUDA Toolkit 一致；经验上 torch 2.1 + cu121 与部分子模块不兼容，优先使用 2.0.1 + cu117。
• 构建失败：install_ext.sh 阶段若报 CUDA 编译错误，检查 gcc 版本、CUDA 路径与 PyTorch 头文件匹配；必要时清理缓存后重跑。
• 依赖冲突：建议使用全新 Conda 环境，避免与 ER-NeRF 等项目的同名扩展（如 gridencoder）冲突。
• 音频报错：若运行训练/推理报与音频设备相关错误，确认已安装 alsa-lib-devel、portaudio-devel 并重新安装对应 Python 音频依赖。
• 资源缺失：缺失 01_MorphableModel.mat / Exp_Pca.bin / BFM_model_front.mat / epoch_20.pth 等文件会直接导致 3D 重建或跟踪失败，请按第四节补齐。