Ubuntu部署GeneFace++教程

Ubuntu部署 GeneFace++ 教程
一 环境准备与版本选择

• 系统建议：Ubuntu 18.04/20.04/22.04。
• GPU与驱动：NVIDIA 显卡（如 V100/A100/RTX 3090 等），驱动版本需与 CUDA 匹配。
• CUDA 与 PyTorch：GeneFace++ 已在 CUDA 11.7 + PyTorch 2.0.1 的组合下验证；当前分支对 CUDA 12+ 支持不佳，建议优先使用 11.7。若你参考的是 GeneFace 系列旧教程，可能使用 CUDA 11.3 + PyTorch 1.11，与 GeneFace++ 不完全一致，请注意区分。
• Python：建议使用 Python 3.9。
• 存储与显存：至少 20GB 可用空间；显存建议 ≥8GB（更高更稳，如 24GB/48GB 在大模型或高分辨率下更从容）。

二 本地环境安装步骤

1. 安装 CUDA 11.7（示例为 Ubuntu 22.04）

• 下载并安装密钥环与工具包：
• wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.0-1_all.deb
• sudo dpkg -i cuda-keyring*.deb
• sudo apt-get update
• sudo apt-get -y install cuda=11.7.1-1
• 配置环境变量（写入 ~/.bashrc 或 ~/.zshrc）：
• export 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}}
• 验证：nvcc --version 应显示 11.7。

1. 创建 Conda 环境

• conda create -n geneface python=3.9 -y
• conda activate geneface

1. 安装 PyTorch 2.0.1 + cu117

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

1. 安装系统依赖与多媒体工具

• sudo apt-get update && sudo apt-get install -y build-essential libasound2-dev portaudio19-dev
• conda install -c conda-forge ffmpeg -y

1. 安装 PyTorch3D（源码）

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

1. 安装 MMCV（推荐 mim）

• 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

1. 安装项目依赖

• pip install -r docs/prepare_env/requirements.txt -i https://mirrors.aliyun.com/pypi/simple

1. 构建自定义 CUDA 扩展

• bash docs/prepare_env/install_ext.sh

1. 验证环境

• python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

三 数据与模型准备

• 克隆代码
• git clone https://github.com/yerfor/GeneFacePlusPlus
• cd GeneFacePlusPlus
• 数据预处理
• 参考 docs/process_data/guide-zh.md，使用你的个性化视频生成预处理数据与二进制 .npy 文件。
• 3DMM 相关模型（用于 3D 重建，路径与文件名以项目要求为准）
• BFM2009：01_MorphableModel.mat → deep_3drecon/BFM/
• Exp_Pca.bin → deep_3drecon/BFM/
• BFM_model_front.mat → deep_3drecon/BFM/
• FaceRecon 预训练权重：epoch_20.pth → deep_3drecon/checkpoints/facerecon/
• 生成跟踪文件：
• cd data_util/face_tracking
• python convert_BFM.py
• 训练与推理
• 训练流程与一键脚本：参考 docs/train_and_infer/guide-zh.md。首次建议逐步执行以排查问题，后续可用同目录的 bash run.sh ${VIDEO_ID} 一键运行。

四 Docker 部署（可选）

• 运行容器（示例）
• sudo docker run -p 8000:8000 -it --name ubuntu_conda117 --privileged=true ubuntu:latest /bin/bash
• 拷贝 CUDA 11.7 到容器
• sudo docker cp /usr/local/cuda-11.7/ ubuntu_conda117:/usr/local/
• 在容器内配置环境变量（同第二节步骤 3）
• 拷贝项目代码与已调试好的依赖/模型
• sudo docker cp /data/code/GeneFacePlusPlus/ ubuntu_conda117:/data/code/
• 进入容器后按第二节步骤 2–9 完成环境安装与验证。

五 常见问题与排错要点

• 版本不兼容
• 已知 PyTorch 2.1 + cu121 会导致 torch-ngp 错误；请使用 PyTorch 2.0.1 + cu117。
• 当前分支对 CUDA 12+ 支持不佳，优先使用 CUDA 11.7。
• 构建与依赖
• 自定义 CUDA 扩展编译失败多与 gcc/g++/CUDA 版本不匹配或 PATH/LD_LIBRARY_PATH 未正确设置有关；请确认 gcc/g++ 版本与 CUDA 兼容，并核对环境变量。
• 多媒体依赖缺失会导致视频/音频处理报错，确保已安装 ffmpeg（含 x264）、libasound2-dev、portaudio19-dev。
• 资源与性能
• 显存不足可先降低分辨率/批量大小；训练/推理前关闭占用显存较大的进程。
• 权限与路径
• 安装与拷贝文件时注意 sudo 与目录权限；容器内外路径映射需一致，避免找不到 CUDA 或模型文件。