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 完整部署指南](#FaceLift 单图 3D 人脸重建项目 Windows 11 完整部署指南)

一、项目简介

二、最终成功的环境配置

三、部署步骤总览

四、详细步骤

[Step 0：克隆仓库 + 创建虚拟环境](#Step 0：克隆仓库 + 创建虚拟环境)

[Step 1：安装主依赖](#Step 1：安装主依赖)

[Step 2：安装 facenet-pytorch（必须 --no-deps）](#Step 2：安装 facenet-pytorch（必须 --no-deps）)

[Step 3：修复 xformers Triton 兼容性](#Step 3：修复 xformers Triton 兼容性)

[Step 4：修复 rasterizer 返回值数量](#Step 4：修复 rasterizer 返回值数量)

[Step 5：安装手动编译的 diff-gaussian-rasterization](#Step 5：安装手动编译的 diff-gaussian-rasterization)

[Step 6：下载模型权重](#Step 6：下载模型权重)

[Step 7：启动](#Step 7：启动)

[五、启动时的 Warning 说明（均无害）](#五、启动时的 Warning 说明（均无害）)

六、关键踩坑总结

[坑 1：没有 Windows 安装文档](#坑 1：没有 Windows 安装文档)

[坑 2：facenet-pytorch 的"依赖炸弹"](#坑 2：facenet-pytorch 的"依赖炸弹")

[坑 3：xformers Triton 内部 API 不兼容](#坑 3：xformers Triton 内部 API 不兼容)

[坑 4：diff-gaussian-rasterization 返回值变化](#坑 4：diff-gaussian-rasterization 返回值变化)

[坑 5：diff-gaussian-rasterization 必须手动编译](#坑 5：diff-gaussian-rasterization 必须手动编译)

[坑 6：PyTorch 版本与 CUDA Toolkit 版本的匹配](#坑 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 上几乎每个环节都有坑。

二、最终成功的环境配置

组件	版本
操作系统	Windows 11
GPU	NVIDIA RTX 3090（24GB, sm_86）
显卡驱动	595.02
Python	3.12.x（Anaconda py312 环境提供，venv 跟随项目）
PyTorch	2.4.0+cu124
CUDA Toolkit	12.6（编译 diff-gaussian-rasterization 用）
Visual Studio	2022 Professional v17.12.19
xformers	0.0.27.post2
Gradio	5.49.1

三、部署步骤总览

复制代码

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 会：

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

加了 --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，初次看到可能会紧张，但它们全部是无害的：

Warning	原因	影响
`torch.cuda.amp.custom_fwd(args...)` is deprecated	PyTorch 2.4 弃用了旧 AMP API	无影响，仅提示
`torch.library.impl_abstract` was renamed	xformers 使用了旧的 PyTorch 内部 API	无影响
`weights_only=False` FutureWarning	facenet-pytorch 加载模型时未指定 weights_only	无影响，未来版本可能需要适配
`LoRACompatibleLinear` is deprecated	diffusers 的 LoRA 实现方式更新	无影响
`allow_flagging` parameter deprecated	Gradio 接口变更	无影响
`1Torch was not compiled with flash attention`	PyTorch 2.4.0 的 cu124 预编译版未包含 flash attention	自动回退到 scaled_dot_product_attention，性能略降但功能正常

六、关键踩坑总结

坑 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

九、总结

维度	说明
部署难度	★★★★☆（主要难在依赖适配和 CUDA 编译）
总耗时	约 3-5 小时（含模型下载、编译、调试）
显存需求	RTX 3090 24GB 可流畅运行
生成速度	50 步约 11 秒（RTX 3090）
核心经验	Windows 部署 Linux-only 项目的方法论：读脚本 → 翻译依赖 → 逐个适配 → 编写修复脚本

系列文章索引：

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

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

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

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

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

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