FaceFusion Windows 本地.venv部署实战教程目录FaceFusion Windows 本地 .venv 部署实战教程前言一、准备条件二、创建项目内 .venv三、安装 PyTorch CUDA 版本四、验证 PyTorch 是否成功启用 GPU五、安装 FaceFusion 基础依赖​编辑六、强制安装 CUDA 13 线路的 ONNX Runtime七、安装 TensorRT八、模型共享减少磁盘占用九、配置默认输出目录十、启动 FaceFusion十一、命令行测试示例十二、常见坑1. 没有激活 .venv2. install.py 可能覆盖你手动安装的 ONNX Runtime3. FaceFusion 报 choose an image for the source!4. 看到 CUDAExecutionProvider 不代表 TensorRT 一定已启用十三、最终验证清单结论参考资料前言https://github.com/facefusion/facefusion这篇文章记录一次可复现的 FaceFusion 本地部署过程特点是系统Windows 11Python 环境项目内.venv不使用 Conda 环境管理GPU 加速CUDA ONNX Runtime TensorRT适合希望本地长期使用、并且不想依赖 Conda 的场景本文基于一次实际跑通的环境整理相关信息如下FaceFusion 版本3.6.1Python 版本3.12.11显卡NVIDIA GeForce RTX 3090显卡驱动591.86ONNX Runtime1.25.1PyTorch2.10.0cu130系统 CUDA13.1cuDNN9.12.0一、准备条件部署前建议先确认以下条件Windows 机器上已经安装 NVIDIA 显卡驱动nvidia-smi可以正常执行已安装 Python3.12 推荐 EPGF 架构已安装 Git可先执行一次nvidia-smi如果这里就报错先解决显卡驱动问题再继续后面的步骤。EPGF 架构的使用提示EPGF 架构 环境配置规范注释 代码格式# 确认当前 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升级pippython.exe -m pip install --upgrade pip建议顺手确认当前解释器确实来自项目内.venvpython -c import sys; print(sys.executable)输出路径应类似K:\PythonProjects5\facefusion\.venv\Scripts\python.exe三、安装 PyTorch CUDA 版本这一步建议优先单独安装 PyTorch GPU 版用它来验证显卡、CUDA 和 cuDNN 是否正常。安装命令pip install torch2.10.0 torchvision0.25.0 torchaudio2.10.0 --index-url https://download.pytorch.org/whl/cu130实际验证通过的版本如下torch 2.10.0cu130torchvision 0.25.0torchaudio 2.10.0四、验证 PyTorch 是否成功启用 GPU进入 Pythonpython执行下面这段代码验证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:0CUDA 可用 TruecuDNN 已启用 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 支持更高优先级的推理后端可以继续安装 TensorRTpip 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 这一层已经能识别cudatensorrtcpu到这里核心 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放前面表示优先尝试 TensorRTcuda放后面表示 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.jpg4. 看到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())输出Truepython -c import onnxruntime as ort; print(ort.get_available_providers())中有CUDAExecutionProviderpython -c from facefusion.execution import get_available_execution_providers; print(get_available_execution_providers())中有cuda如需 TensorRT加上确认输出里有tensorrtpython facefusion.py run --open-browser可以正常打开页面并完成一次处理结论如果你的目标是在 Windows 上以本地.venv的方式部署 FaceFusion而不是依赖 Conda那么这套流程是可以跑通的用python -m venv --copies .venv创建独立环境先验证PyTorch CUDA再安装 FaceFusion手动切换到可用的onnxruntime-gpu CUDA 13源补装 TensorRT最后通过 UI 或命令行做一次实测部署成功后这套环境已经具备PyTorch GPU 加速ONNX Runtime CUDA 加速TensorRT 可选加速模型目录跨项目共享项目内统一输出目录对于需要长期维护、希望项目目录结构清晰、并且不想引入 Conda 的用户这是一条比较稳的 Windows 本地部署路线。参考资料https://docs.facefusion.io/基于 EPGF 架构的环境迁移复现部署 及 基于符号链接的模型共享解决方案——FaceFusion 3.3.2与3.4.1 模型共享方案100GB 空间节省实践FaceFusion 3.4.1 版本[FACEFUSION.CORE] Copying image failed 大分辨率图像处理失败的解决方案与 Bug 探究基于 EPGF 架构理念的 FaceFusion 3.4.1 本地 .venv 部署教程非 Conda 环境部署优化版【笔记】Facefusion3.3.2 之 NSFW 检测屏蔽测试【笔记】FaceFusion 3.3.0 CUDA GPU 环境 Docker 构建与运行全流程记录怎么使用嵌套虚拟环境实现项目部署之virtualenv嵌套conda绕开安装环境检测实现.venv部署facefusion