CentOS容器GeneFace++安装指南

CentOS 容器化部署 GeneFace++ 指南
一 环境规划与准备

• 主机建议选择 CentOS 7/8，已安装 Docker Engine（可参考官方安装文档，配置国内镜像加速以提升拉取速度）。容器建议使用 Ubuntu 20.04/22.04 基础镜像以便更好兼容 Python 与多媒体工具链。GPU 场景需准备 NVIDIA Container Toolkit 并启用 nvidia-docker2，确保宿主机驱动与容器内 CUDA 版本匹配。项目与权重体积较大，建议挂载大容量数据卷用于存放 3DMM 文件、预处理数据与预训练模型。

二 构建镜像 Dockerfile

• 选择组合：CPU-only 或 GPU（CUDA 11.7）+ Python 3.9 + ffmpeg（含 libx264）。以下为可直接使用的多阶段 Dockerfile（按需选择阶段）。

# 阶段一：CPU 版本
FROM ubuntu:22.04 AS geneface-cpu
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential cmake git wget ca-certificates \
python3 python3-dev python3-pip ffmpeg libsm6 libxext6 && \
rm -rf /var/lib/apt/lists/*
RUN ln -s /usr/bin/python3 /usr/bin/python
# 建议先 conda 安装以锁定版本
RUN wget -O /tmp/miniconda.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh \
&& bash /tmp/miniconda.sh -b -p /opt/conda \
&& rm /tmp/miniconda.sh
ENV PATH=/opt/conda/bin:$PATH
RUN conda create -n geneface python=3.9 -y && \
conda install -n geneface -c conda-forge ffmpeg -y
WORKDIR /opt/GeneFacePlusPlus
# 可选：提前克隆（也可在运行时挂载代码）
# RUN git clone https://github.com/yerfor/GeneFacePlusPlus.git .
# 阶段二：GPU 版本（CUDA 11.7）
FROM nvidia/cuda:11.7.1-devel-ubuntu20.04 AS geneface-gpu
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential cmake git wget ca-certificates \
python3 python3-dev python3-pip ffmpeg libsm6 libxext6 && \
rm -rf /var/lib/apt/lists/*
RUN ln -s /usr/bin/python3 /usr/bin/python
RUN wget -O /tmp/miniconda.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh \
&& bash /tmp/miniconda.sh -b -p /opt/conda \
&& rm /tmp/miniconda.sh
ENV PATH=/opt/conda/bin:$PATH
RUN conda create -n geneface python=3.9 -y && \
conda install -n geneface -c conda-forge ffmpeg -y
WORKDIR /opt/GeneFacePlusPlus
# 可选：提前克隆
# RUN git clone https://github.com/yerfor/GeneFacePlusPlus.git .

• 构建命令示例：
• CPU：docker build -f Dockerfile -t geneface-plusplus:cpu .
• GPU：docker build -f Dockerfile -t geneface-plusplus:gpu --target geneface-gpu .

三 运行容器与数据准备

• 运行命令模板（GPU 示例，挂载代码、数据与权重，端口可按需映射）：

docker run --gpus all -it --rm \
--name geneface-pp \
-p 8000:8000 \
-v /host/data:/data \
-v /host/GeneFacePlusPlus:/opt/GeneFacePlusPlus \
geneface-plusplus:gpu bash

• 进入容器后创建并激活环境，安装 Python 依赖（请使用项目根目录下的 requirements.txt）：

conda activate geneface
cd /opt/GeneFacePlusPlus
pip install -r requirements.txt
# 如项目文档另有说明，优先遵循其版本建议（例如部分教程推荐 torch==2.0.1+cu117）

• 数据准备要点：
• 按项目说明下载并放置 3DMM 文件、预处理数据集、预训练模型 到容器挂载目录（如 /data），目录结构需与代码默认路径一致或在配置中显式指定。
• 确保 ffmpeg 包含 libx264 编码器，用于图像序列到视频的导出。

四 推理验证与常见问题

• 推理验证（示例命令，路径与参数请按实际调整）：

conda activate geneface
cd /opt/GeneFacePlusPlus
export PYTHONPATH=$(pwd):$PYTHONPATH
python inference/genefacepp_infer.py \
--a2m_ckpt checkpoints/audio2motion_vae \
--head_ckpt checkpoints/motion2video_nerf/may_head \
--torso_ckpt checkpoints/motion2video_nerf/may_torso \
--drv_aud /data/raw/val_wavs/example.wav \
--out_name /data/output/demo_output.mp4

• 常见问题与排查要点：
• 版本匹配：确保 CUDA 版本 与深度学习框架（如 PyTorch）一致；GPU 镜像与宿主机驱动匹配；CPU 镜像请勿启用 --gpus。
• 编码器缺失：若导出 MP4 失败，检查容器内 ffmpeg 是否包含 libx264（conda-forge 版本通常已包含）。
• 路径错误：确认 3DMM、数据、权重 路径与代码中默认路径一致，或通过命令行参数显式指定。
• 权限与挂载：挂载目录权限不足会导致读取/写入失败，建议使用相同 UID/GID 或在宿主机设置合适权限。
• 资源不足：显存/内存不足时，可降低分辨率、批量大小或改用 CPU 镜像进行功能验证。