FaceFusion Windows 本地 .venv 部署实战教程

# 确认当前 Python 版本
python -V

# 切换到指定 Python 版本环境（conda）
conda activate py312

# 创建项目本地虚拟环境（--copies 禁用符号链接，用于可能移动/拷贝的项目）
python -m venv --copies .venv

# 激活本地虚拟环境（Windows PowerShell）
.\.venv\Scripts\Activate.ps1

# 退出父级 conda 环境，避免包冲突
conda deactivate

# 升级 pip 到最新版，保证依赖安装稳定
python.exe -m pip install --upgrade pip

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

二、创建项目内 `.venv`

# 克隆项目
git clone https://github.com/facefusion/facefusion.git

进入项目根目录后，创建虚拟环境：

python -m venv --copies .venv

这里使用 --copies，目的是避免虚拟环境大量使用符号链接。对于可能被移动、拷贝或打包迁移的项目，这个参数更稳。

创建完成后激活环境：

.\.venv\Scripts\Activate.ps1

升级 pip：

python.exe -m pip install --upgrade pip

建议顺手确认当前解释器确实来自项目内 .venv：

python -c "import sys; print(sys.executable)"

输出路径应类似：

K:\PythonProjects5\facefusion\.venv\Scripts\python.exe

三、安装 PyTorch CUDA 版本

这一步建议优先单独安装 PyTorch GPU 版，用它来验证显卡、CUDA 和 cuDNN 是否正常。

安装命令：

pip install torch==2.10.0 torchvision==0.25.0 torchaudio==2.10.0 --index-url https://download.pytorch.org/whl/cu130

实际验证通过的版本如下：

torch 2.10.0+cu130
torchvision 0.25.0
torchaudio 2.10.0

四、验证 PyTorch 是否成功启用 GPU

进入 Python：

python

执行下面这段代码：

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

# 验证
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 的内容

如果输出中满足这些条件，说明 PyTorch GPU 路线已经通了：

设备： cuda:0
CUDA 可用： True
cuDNN 已启用： True

五、安装 FaceFusion 基础依赖

FaceFusion 自带了安装脚本。由于本文走的是本地 .venv，不是 Conda，所以使用：

python install.py --onnxruntime cuda --skip-conda

这一步会安装项目的大部分 Python 依赖。

需要注意的是：项目默认安装的 onnxruntime-gpu 版本不一定是最适合当前 CUDA 路线的版本，所以后面还要手动覆盖一次。

六、强制安装 CUDA 13 线路的 ONNX Runtime

如果你的环境和本文一样，是实际跑通了 PyTorch cu130，那么建议把 onnxruntime-gpu 强制切到 CUDA 13 对应源：

pip install --force-reinstall --no-cache-dir onnxruntime-gpu --extra-index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-13/pypi/simple/

安装完成后验证：

python -c "import onnxruntime as ort; print(ort.__version__); print(ort.get_available_providers())"

本次验证通过的输出是：

1.25.1
['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider']

如果你至少看到了：

CUDAExecutionProvider

就说明 ONNX Runtime 已经可以使用 CUDA。

七、安装 TensorRT

为了让 FaceFusion 支持更高优先级的推理后端，可以继续安装 TensorRT：

pip install tensorrt --extra-index-url https://pypi.nvidia.com

安装完成后再验证一次：

python -c "from facefusion.execution import get_available_execution_providers; print(get_available_execution_providers())"

本次环境中的输出为：

['cuda', 'tensorrt', 'cpu']

这说明 FaceFusion 这一层已经能识别：

cuda
tensorrt
cpu

到这里，核心 GPU 加速链路就已经通了。

八、模型共享，减少磁盘占用

基于 EPGF 架构的环境迁移复现部署及基于符号链接的模型共享解决方案——FaceFusion 3.3.2与3.4.1 模型共享方案：100GB 空间节省实践

如果你在别的盘里已经有一份 FaceFusion 模型目录，可以通过目录符号链接复用，避免重复下载和占用空间。

例如，把：

F:\PythonProjects1\facefusion\.assets\models

共享给当前项目：

New-Item -ItemType SymbolicLink -Path ".assets\models" -Target "F:\PythonProjects1\facefusion\.assets\models"

如果 .assets 目录还不存在，可以先创建：

New-Item -ItemType Directory -Path ".assets"

验证方式：

Get-Item ".assets\models" | Format-List FullName,LinkType,Target

如果看到 LinkType : SymbolicLink，说明链接创建成功。

九、配置默认输出目录

建议在项目根目录下创建一个 outputs 文件夹，用于统一保存导出结果。

先创建目录：

New-Item -ItemType Directory -Path "outputs"

然后编辑项目根目录下的 facefusion.ini，把：

[paths]
output_path =

改成：

[paths]
output_path = outputs

这样后续默认输出会落到项目内的 outputs 目录，便于管理。

十、启动 FaceFusion

浏览器模式启动：

python facefusion.py run --open-browser

启动后，上传源图和目标图，执行一次实际处理，能得到正常结果就说明部署成功。

十一、命令行测试示例

如果你想先用命令行验证，而不是直接打开 UI，需要注意 face_swapper 默认必须同时提供源图和目标图。

示例：

python facefusion.py headless-run --execution-providers tensorrt cuda -s source.jpg -t target.jpg -o outputs\result.jpg

说明：

tensorrt 放前面，表示优先尝试 TensorRT
cuda 放后面，表示 TensorRT 不适用时回退到 CUDA

十二、常见坑

1. 没有激活 `.venv`

如果你没有激活项目内 .venv，可能会误用系统或其他环境里的 Python，导致：

numpy 导入失败
onnxruntime 版本不一致
torch 和 onnxruntime 不在同一个环境里

每次操作前建议先确认：

python -c "import sys; print(sys.executable)"

2. `install.py` 可能覆盖你手动安装的 ONNX Runtime

本文为了适配 CUDA 13，执行过一次：

pip install --force-reinstall --no-cache-dir onnxruntime-gpu --extra-index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-13/pypi/simple/

如果后面再次运行项目原始安装脚本，有可能把它换回默认版本。遇到这种情况，重新执行上面的强制安装命令即可。

3. FaceFusion 报 `choose an image for the source!`

这通常不是 CUDA 问题，而是你运行 headless-run 时只传了目标图，没有传源图。

正确示例：

python facefusion.py headless-run --execution-providers cuda -s source.jpg -t target.jpg -o outputs\result.jpg

4. 看到 `CUDAExecutionProvider` 不代表 TensorRT 一定已启用

要确认 FaceFusion 是否识别到 TensorRT，请执行：

python -c "from facefusion.execution import get_available_execution_providers; print(get_available_execution_providers())"

如果输出中有 tensorrt，才表示 FaceFusion 这一层也看到了 TensorRT。

十三、最终验证清单

部署完成后，至少确认以下几点：

.venv 已激活
python -c "import torch; print(torch.cuda.is_available())" 输出 True
python -c "import onnxruntime as ort; print(ort.get_available_providers())" 中有 CUDAExecutionProvider
python -c "from facefusion.execution import get_available_execution_providers; print(get_available_execution_providers())" 中有 cuda
如需 TensorRT，加上确认输出里有 tensorrt
python facefusion.py run --open-browser 可以正常打开页面并完成一次处理