Ubuntu部署GeneFace++注意

Ubuntu部署 GeneFace++ 关键注意事项
一 版本与驱动匹配

• 操作系统建议使用Ubuntu 18.04/20.04/22.04；显卡建议NVIDIA且显存≥8GB（如RTX 3090已验证）。存储建议预留≥20GB可用空间。
• CUDA 与 PyTorch 的版本组合要一致，常见稳定组合如下（择一使用，不要混装）：
• 组合A：CUDA 11.7 + PyTorch 2.0.1（对应 torchvision 0.15.2、torchaudio 2.0.2），已验证可跑通；不建议使用CUDA 12.x。
• 组合B：CUDA 11.3 + PyTorch 1.11.0（对应 torchvision 0.12.0、torchaudio 0.11.0）。
• 驱动与工具链：确保 NVIDIA 驱动与所选 CUDA 兼容；用nvidia-smi查看驱动与 CUDA Runtime，用nvcc --version查看 Toolkit 版本，二者需与 PyTorch 的 CUDA 版本匹配。
• 常见坑：使用PyTorch 2.1 + CUDA 12.1会导致torch-ngp报错；若遇到扩展编译或运行异常，优先回退到上述稳定组合。

二 环境与依赖安装

• 建议使用conda创建隔离环境，Python 版本3.9.x（如3.9.16）。
• 音视频与系统依赖：
• conda install -c conda-forge ffmpeg（需包含libx264编码器，用于图像转视频）。
• sudo apt-get install libasound2-dev portaudio19-dev（音频依赖）。
• Python 包与扩展：
• 按项目文档执行：pip install -r docs/prepare_env/requirements.txt。
• PyTorch3D建议从源码安装：pip install "git+https://github.com/facebookresearch/pytorch3d.git@stable"。
• MMCV建议用 mim 安装：pip install openmim==0.3.9 && mim install mmcv==2.1.0。
• 构建自定义 CUDA 扩展：运行bash docs/prepare_env/install_ext.sh，确保编译日志无报错。

三 数据模型与目录准备

• 3DMM 模型文件需按目录放置（示例路径为项目根相对路径）：
• 01_MorphableModel.mat → ./deep_3drecon/BFM/
• Exp_Pca.bin → ./deep_3drecon/BFM/
• BFM_model_front.mat → ./deep_3drecon/BFM/
• 人脸重建权重：epoch_20.pth → ./deep_3drecon/checkpoints/facerecon/
• 生成跟踪信息：在项目根目录执行
• export PYTHONPATH=.
• CUDA_VISIBLE_DEVICES=0 python deep_3drecon/test.py（验证 3D 重建）
• python deep_3drecon/generate_reconstructor_opt_for_geneface.py（为 GeneFace 生成配置）
• 数据与模型获取：按docs/process_data/guide-zh.md准备个性化视频与预处理数据（会生成二进制.npy等）；首次建议逐步执行，跑通后再用同目录的run.sh一键化。

四 运行与性能优化

• 推理/训练前确认：
• 环境变量正确：export PYTHONPATH=.；CUDA_VISIBLE_DEVICES设置可见 GPU。
• 使用项目提供的run.sh脚本可简化流程；若报错，回退到逐步命令定位问题。
• Docker 场景：
• 先在本地打通环境再迁移到容器；容器内可通过--privileged运行，并将本机CUDA 11.7目录拷贝进容器（如/usr/local/cuda-11.7）。
• 在容器内设置环境变量：CUDA_PATH_11=/usr/local/cuda-11.7，并将$CUDA_PATH_11/bin加入PATH、$CUDA_PATH_11/lib64加入LD_LIBRARY_PATH。
• 性能与稳定性：
• 显存8GB可运行但更建议≥24GB（如RTX 3090）以提升稳定性与速度。
• 若遇到扩展编译或运行异常，优先检查：CUDA 与 PyTorch 版本匹配、驱动版本、ffmpeg 是否含libx264、以及自定义扩展是否成功编译。

五 常见报错与快速排查

• 版本不兼容：出现与torch-ngp相关的错误，优先回退到PyTorch 2.0.1 + CUDA 11.7或PyTorch 1.11.0 + CUDA 11.3的稳定组合。
• 找不到 CUDA：检查/usr/local/cuda符号链接是否指向实际安装目录（如cuda-11.7或cuda-11.3），并确认PATH与LD_LIBRARY_PATH包含bin与lib64。
• 扩展编译失败：确认已安装GCC/G++/make等编译工具，清理后重跑install_ext.sh。
• 音频/视频问题：安装libasound2-dev、portaudio19-dev与含libx264的ffmpeg。
• 权限问题：避免用 root 直接跑训练；必要时用sudo仅安装系统包，数据与环境保持在用户目录。
• 资源不足：显存或磁盘不足会导致 OOM 或预处理失败，建议≥24GB 显存与≥20GB可用空间。