FaceLift 单图 3D 人脸重建项目 Windows 11 完整部署指南

FaceLift 单图 3D 人脸重建项目 Windows 11 完整部署指南

FaceLift 是一个基于单张肖像照片生成完整 3D 头部模型的开源项目，来自 CMU（卡内基梅隆大学）。官方仅提供了 Linux 环境的setup_env.sh安装脚本，没有任何 Windows 部署文档。本文完整记录了在 Windows 11 + RTX 3090 上从零部署该项目的全过程，包含依赖适配、源码修复、CUDA 编译等所有踩坑细节。

项目地址：https://github.com/weijielyu/FaceLift

目录

FaceLift 单图 3D 人脸重建项目 Windows 11 完整部署指南

一、项目简介

二、最终成功的环境配置

三、部署步骤总览

四、详细步骤

Step 0：克隆仓库 + 创建虚拟环境

Step 1：安装主依赖

Step 2：安装 facenet-pytorch（必须 --no-deps）

Step 3：修复 xformers Triton 兼容性

Step 4：修复 rasterizer 返回值数量

Step 5：安装手动编译的 diff-gaussian-rasterization

Step 6：下载模型权重

Step 7：启动

五、启动时的 Warning 说明（均无害）

六、关键踩坑总结

坑 1：没有 Windows 安装文档

坑 2：facenet-pytorch 的"依赖炸弹"

坑 3：xformers Triton 内部 API 不兼容

坑 4：diff-gaussian-rasterization 返回值变化

坑 5：diff-gaussian-rasterization 必须手动编译

坑 6：PyTorch 版本与 CUDA Toolkit 版本的匹配

七、文件清单

八、一键部署脚本参考

九、总结

一、项目简介

https://github.com/weijielyu/FaceLift

FaceLift（OpenFaceLift）能从一张正面/侧面人脸照片，生成多视角一致的 3D 头部模型，并输出旋转动画视频。其技术栈涉及：

• Stable Diffusion：多视角一致性图像生成
• 3D Gaussian Splatting：高效 3D 重建（依赖 diff-gaussian-rasterization）
• xformers + Triton：注意力加速
• facenet-pytorch：人脸检测与对齐

这套技术栈在 Linux 上可以一键安装，但在 Windows 上几乎每个环节都有坑。

二、最终成功的环境配置

三、部署步骤总览

Step 0: 克隆仓库 + 创建虚拟环境 Step 1: pip install -r requirements.txt ← 核心依赖（Windows 适配版） Step 2: pip install facenet-pytorch==2.5.3 --no-deps ← 必须 --no-deps Step 3: python fix_xformers_triton.py ← 修复 xformers Triton 兼容性 Step 4: python fix_rasterizer.py ← 修复 rasterizer 返回值数量 Step 5: pip install diff_gaussian_rasterization-xxx.whl ← 手动编译的 wheel Step 6: huggingface-cli download 模型权重 ← ~10GB+ Step 7: python gradio_app.py ← 启动！

四、详细步骤

Step 0：克隆仓库 + 创建虚拟环境

git clone https://github.com/weijielyu/FaceLift.git cd FaceLift

虚拟环境创建采用 EPGF 架构（Anaconda 负责提供多版本 Python，venv 跟随项目目录独立管理依赖）：

【EPGF 白皮书】路径治理驱动的多版本 Python 架构—— Windows 环境治理与 AI 教学开发体系

conda activate py312 python -V :: Python 3.12.x :: 使用 --copies 避免符号链接问题（推荐） python -m venv --copies .venv .venv\Scripts\activate python.exe -m pip install --upgrade pip

关于 EPGF 架构：这是一种路径治理驱动的多版本 Python 管理方法论——Anaconda 只负责稳定提供各版本 Python 解释器（py308~py314），几乎不参与具体项目开发；所有项目依赖通过项目目录下的.venv管理，做到环境隔离和可移植。详见：

【EPGF 白皮书】路径治理驱动的多版本 Python 架构

Step 1：安装主依赖

FaceLift 官方只提供setup_env.sh（Linux 脚本），没有requirements.txt。我根据该脚本的内容逐行翻译并结合实际调试，整理出了 Windows 适配版requirements.txt：

# ============================================== # Windows 环境适配的依赖文件 # 安装命令：pip install -r requirements.txt # 注意：diff-gaussian-rasterization 需要手动编译，无法自动安装 # ============================================== # PyTorch CUDA专属源，确保安装带CUDA支持的版本 --extra-index-url https://download.pytorch.org/whl/cu124 # ------------------------------ # 核心基础依赖 # ------------------------------ packaging==24.2 typing-extensions==4.14.0 # ------------------------------ # PyTorch 深度学习框架 # ------------------------------ torch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 # ------------------------------ # AI/ML 通用库 # ------------------------------ transformers==4.44.2 diffusers[torch]==0.30.3 huggingface-hub==0.35.3 xformers==0.0.27.post2 accelerate==0.33.0 # ------------------------------ # 计算机视觉/图像处理 # ------------------------------ Pillow==10.4.0 opencv-python==4.10.0.84 scikit-image>=0.21.0 lpips==0.1.4 # 需手动装2.5.3版本（pip install facenet-pytorch==2.5.3 --no-deps）手动安装facenet-pytorch时用 --no-deps 参数忽略依赖，避免版本冲突 # facenet-pytorch==2.5.3 --no-deps # 背景移除工具 rembg # ------------------------------ # 科学计算 # ------------------------------ numpy==1.26.4 matplotlib==3.7.5 scikit-learn==1.3.2 einops==0.8.0 jaxtyping==0.2.19 pytorch-msssim==1.0.0 # ------------------------------ # 工具与配置 # ------------------------------ easydict==1.13 pyyaml==6.0.2 wandb==0.19.1 termcolor==2.4.0 plyfile==1.0.3 tqdm gradio==5.49.1 # ------------------------------ # 视频处理 # ------------------------------ videoio==0.3.0 ffmpeg-python==0.2.0 # ------------------------------ # 其他依赖 # ------------------------------ triton-windows==3.5.0.post21 opencv-python==4.10.0.84 onnxruntime-gpu==1.25.0 ninja==1.13.0 build==1.4.4 # ------------------------------ # ⚠️ 【核心提醒】diff-gaussian-rasterization # Windows下CUDA编译器不支持中文路径，无法直接自动安装！ # 请先将整个项目移到纯英文路径，再按之前的编译指南手动编译 # ------------------------------ # git+https://github.com/graphdeco-inria/diff-gaussian-rasterization # git+https://github.com/ashawkey/diff-gaussian-rasterization

pip install -r requirements.txt

PyTorch 离线安装技巧：如果网络超时导致 torch wheel 下载失败，可以先从pip install -v的日志中获取 wheel 下载地址，用 IDM 等下载工具下载到本地，再本地安装：

pip install 本地路径\torch-2.4.0+cu124-cp312-cp312-win_amd64.whl ^ torchvision==0.19.0 torchaudio==2.4.0 ^ --index-url https://download.pytorch.org/whl/cu124

验证PyTorch深度学习环境Torch和CUDA还有cuDNN是否正确配置的命令

验证 torch+cuda：

import torch # 导入 PyTorch 库 print("PyTorch 版本：", torch.__version__) # 打印 PyTorch 的版本号 # 检查 CUDA 是否可用，并设置设备（"cuda:0" 或 "cpu"） device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu") print("设备：", device) # 打印当前使用的设备 print("CUDA 可用：", torch.cuda.is_available()) # 打印 CUDA 是否可用 print("cuDNN 已启用：", torch.backends.cudnn.enabled) # 打印 cuDNN 是否已启用 # 打印 PyTorch 支持的 CUDA 和 cuDNN 版本 print("支持的 CUDA 版本：", torch.version.cuda) print("cuDNN 版本：", torch.backends.cudnn.version()) # 创建两个随机张量（默认在 CPU 上） x = torch.rand(5, 3) y = torch.rand(5, 3) # 将张量移动到指定设备（CPU 或 GPU） x = x.to(device) y = y.to(device) # 对张量进行逐元素相加 z = x + y # 打印结果 print("张量 z 的值：") print(z) # 输出张量 z 的内容

Step 2：安装 facenet-pytorch（必须 --no-deps）

pip install facenet-pytorch==2.5.3 --no-deps

为什么必须--no-deps？这是整个部署过程中最隐蔽的陷阱之一。facenet-pytorch 的依赖声明非常"霸道"——它会尝试拉取自己指定版本的 torch、torchvision、numpy、Pillow 等几乎所有核心包。如果不加--no-deps，pip 会：

1. 降级 PyTorch 到 CPU 版本（丢失 CUDA 支持）
2. 回退 numpy、Pillow 等到旧版本（与其他依赖冲突）
3. 破坏你刚装好的整个环境

加了--no-deps后，facenet-pytorch 只安装自己的代码文件，使用环境中已有的 torch 和其他依赖——这完全没问题，因为 Step 1 已经装好了所有必要的包。

Step 3：修复 xformers Triton 兼容性

python fix_xformers_triton.py

注意：请修改成自己项目虚拟环境的路径！

import os import glob # 目标文件路径 file_path = r"J:\PythonProjects4\FaceLift\.venv\Lib\site-packages\xformers\triton\vararg_kernel.py" if not os.path.exists(file_path): print(f"❌ 文件不存在: {file_path}") exit(1) # 读取文件内容 with open(file_path, 'r', encoding='utf-8') as f: content = f.read() # 统计替换前的出现次数 count_before = content.count("jitted_fn.src = new_src") print(f"🔍 找到 {count_before} 处 'jitted_fn.src = new_src'") if count_before == 0: print("⚠️ 未找到需要替换的内容，可能已经被修改过") else: # 执行替换 new_content = content.replace("jitted_fn.src = new_src", "jitted_fn._unsafe_update_src(new_src)") # 写回文件 with open(file_path, 'w', encoding='utf-8') as f: f.write(new_content) # 验证替换结果 count_after = new_content.count("jitted_fn.src = new_src") count_new = new_content.count("jitted_fn._unsafe_update_src(new_src)") print(f"✅ 替换完成！剩余旧代码: {count_after} 处，新代码: {count_new} 处") # 清理所有 __pycache__ 目录 cache_dirs = glob.glob(r"J:\PythonProjects4\FaceLift\.venv\Lib\site-packages\xformers\**\__pycache__", recursive=True) if cache_dirs: for d in cache_dirs: import shutil shutil.rmtree(d, ignore_errors=True) print(f"🗑️ 已清理缓存: {d}") else: print("ℹ️ 未发现 __pycache__ 缓存目录") print("\n🎉 完成！请重新运行 gradio_app.py")

问题根因：xformers 0.0.27.post2 的triton/vararg_kernel.py中使用了jitted_fn.src = new_src这个属性赋值方式，但在 Windows 上搭配triton-windows包时，Triton JIT 编译器不支持直接设置.src属性，需要改用._unsafe_update_src()方法。

修复内容：

# 替换前 jitted_fn.src = new_src # 替换后 jitted_fn._unsafe_update_src(new_src)

脚本同时会清理 xformers 的__pycache__缓存，确保修改生效。

注意：每次重新安装或升级 xformers 后，需要重新运行此修复脚本。

Step 4：修复 rasterizer 返回值数量

python fix_rasterizer.py

注意：请修改成自己项目虚拟环境的路径！

import os file_path = r"J:\PythonProjects4\FaceLift\gslrm\model\gaussians_renderer.py" with open(file_path, 'r', encoding='utf-8') as f: content = f.read() # 查找并替换 old_code = "rendered_image, radii = rasterizer(" new_code = "rendered_image, radii, _, _ = rasterizer(" if old_code in content: content = content.replace(old_code, new_code) with open(file_path, 'w', encoding='utf-8') as f: f.write(content) print("✅ 修改成功：rendered_image, radii = rasterizer( → rendered_image, radii, _, _ = rasterizer(") else: print("⚠️ 未找到需要修改的代码，可能已经被修改过或文件路径不同") # 清理缓存 import glob, shutil cache_dirs = glob.glob(r"J:\PythonProjects4\FaceLift\gslrm\**\__pycache__", recursive=True) for d in cache_dirs: shutil.rmtree(d, ignore_errors=True) print(f"🗑️ 已清理缓存: {d}")

问题根因：FaceLift 的gslrm/model/gaussians_renderer.py中调用 rasterizer 时，代码只接收了 2 个返回值：

rendered_image, radii = rasterizer(...)

但 diff-gaussian-rasterization 最新版的rasterizer()返回 4 个值（增加了深度和 alpha 通道输出），导致ValueError: too many values to unpack。

修复内容：

# 替换前 rendered_image, radii = rasterizer( # 替换后 rendered_image, radii, _, _ = rasterizer(

用_丢弃多余的返回值即可。

Step 5：安装手动编译的 diff-gaussian-rasterization

这个 CUDA 扩展在 Windows 上无法自动安装，必须手动编译。完整编译过程请参见系列文章。编译好之后：

pip install diff_gaussian_rasterization-0.0.0-cp312-cp312-win_amd64.whl

编译指南：

• 首次编译：Windows 11 下编译 diff-gaussian-rasterization 完整踩坑记录
• 二次复现：diff-gaussian-rasterization 二次编译复现记录
• CUDA 环境准备：Windows 多版本 CUDA + cuDNN 环境配置完全指南
• CMD 下切换 CUDA：Windows CMD 多版本 CUDA & cuDNN 一键切换管理方案

验证

python -c "import diff_gaussian_rasterization; print('✅ 安装成功')"

Step 6：下载模型权重

huggingface-cli download wlyu/OpenFaceLift --local-dir J:\PythonProjects4\FaceLift\checkpoints

模型权重约10GB+，下载时间视网络状况而定（通常数小时）。如果使用 HuggingFace 镜像：

set HF_ENDPOINT=https://hf-mirror.com hf download wlyu/OpenFaceLift --local-dir 你的路径\FaceLift\checkpoints

Step 7：启动

python gradio_app.py

启动后终端会输出大量 Warning（均无害，详见下文第五节），最终看到：

Models loaded successfully! * Running on local URL: http://0.0.0.0:7860

在浏览器中打开http://localhost:7860，点击页面上的示例图片，点击 Submit，等待 50 步生成（约 11 秒/RTX 3090），即可看到：

• Processed Input：预处理后的人脸
• Multi-view Generation：6 个角度的一致性视图
• 3D Reconstruction：3D 高斯重建结果
• Turntable Animation：旋转动画视频

五、启动时的 Warning 说明（均无害）

python gradio_app.py启动时会输出大量黄色/红色 Warning，初次看到可能会紧张，但它们全部是无害的：

六、关键踩坑总结

坑 1：没有 Windows 安装文档

FaceLift 只提供setup_env.sh，里面的依赖安装命令全是 Linux 的（conda、pip 混合，还有 git+https 直接编译安装）。需要逐行阅读脚本，理解每个依赖的作用，然后翻译成 Windows 可执行的requirements.txt。

坑 2：facenet-pytorch 的"依赖拉踩"

不加--no-deps会摧毁整个环境。这个包的依赖声明会把 PyTorch 拉回 CPU 版本，是本次部署中最难定位的问题——因为pip install看起来成功了，但之后运行时 CUDA 不可用，往回查才发现 torch 版本被偷换了。

教训：安装任何不确定的包之前，先pip install xxx --dry-run看看它要装什么、要改什么。

坑 3：xformers Triton 内部 API 不兼容

Windows 下triton-windows和 xformers 之间存在 API 差异。.src属性赋值方式在triton-windows中不可用，必须改用._unsafe_update_src()方法。这个错误只在运行时才暴露，且报错信息不直观。

坑 4：diff-gaussian-rasterization 返回值变化

FaceLift 的代码是基于较旧版本的 diff-gaussian-rasterization 写的，只接收 2 个返回值。但当前版本返回 4 个值，导致解包失败。修改一行代码即可解决。

坑 5：diff-gaussian-rasterization 必须手动编译

这是 Windows 部署 3DGS 相关项目的经典难题。CUDA 扩展需要 VS 2022 编译器 + 匹配的 CUDA Toolkit 版本 + 正确的环境变量设置。详细方案已在系列文章中记录。

坑 6：PyTorch 版本与 CUDA Toolkit 版本的匹配

本项目使用 PyTorch 2.4.0+cu124，编译 CUDA 扩展时的 nvcc 必须是 CUDA 12.x（主版本号匹配）。系统默认的 CUDA 13.1 会导致致命错误，需要通过switch-cuda 12.6切换。

Windows CMD 多版本 CUDA & cuDNN 一键切换管理方案

七、文件清单

完成部署后，项目目录下应有以下关键文件：

FaceLift/ ├── .venv/ ← Python 虚拟环境 ├── checkpoints/ ← 模型权重（~10GB+） ├── diff-gaussian-rasterization/ ← 编译目录（可选保留） │ ├── third_party/glm/ ← GLM 数学库 │ └── dist/ ← 编译产出的 .whl ├── gslrm/ ← 项目核心代码 │ └── model/ │ └── gaussians_renderer.py ← Step 4 修改的文件 ├── requirements.txt ← Windows 适配版依赖 ├── fix_xformers_triton.py ← Step 3 修复脚本 ├── fix_rasterizer.py ← Step 4 修复脚本 ├── gradio_app.py ← Gradio 启动入口 └── setup_env.sh ← 官方 Linux 脚本（参考用）

八、一键部署脚本参考

将所有步骤整合为 batch 脚本（假设虚拟环境已创建并激活）：

Compilation.bat 示例

@echo off chcp 65001 >nul 2>&1 echo ===== FaceLift Windows Deployment ===== echo [1/7] Installing main dependencies... pip install -r requirements.txt echo [2/7] Installing facenet-pytorch (--no-deps)... pip install facenet-pytorch==2.5.3 --no-deps echo [3/7] Fixing xformers Triton compatibility... python fix_xformers_triton.py echo [4/7] Fixing rasterizer return values... python fix_rasterizer.py echo [5/7] Installing diff-gaussian-rasterization wheel... pip install diff_gaussian_rasterization-0.0.0-cp312-cp312-win_amd64.whl echo [6/7] Downloading model weights (this will take a while)... huggingface-cli download wlyu/OpenFaceLift --local-dir checkpoints echo [7/7] Done! Launch with: echo python gradio_app.py pause

九、总结

系列文章索引：

• 1. 【EPGF 白皮书】路径治理驱动的多版本 Python 架构

• 2. Windows 多版本 CUDA + cuDNN 环境配置完全指南

• 3. Windows CMD 多版本 CUDA & cuDNN 一键切换管理方案

• 4. Windows 11 下编译 diff-gaussian-rasterization 完整踩坑记录（首次编译）

• 5. diff-gaussian-rasterization 二次编译复现记录（FaceLift 环境）

• 6. 本文：FaceLift 单图 3D 人脸重建项目 Windows 11 完整部署指南