当前位置：首页 > news >正文

基于 EPGF 架构理念的 FaceFusion 3.4.1 本地 .venv 部署教程（非 Conda 环境部署优化版）

news 2025/9/16 5:54:57

基于 EPGF 架构理念的 FaceFusion 3.4.1 本地 .venv 部署教程（非 Conda 环境部署优化版）

什么是 EPGF 架构？

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

EPGF（Engineering Python Governance Framework） 是一套 工程化 Python 治理体系，通过 三维治理 → 四级隔离 → 五项自治 构建完整闭环，实现路径可控、结构可迁移、状态可复现。
本教程借助 EPGF 的治理理念，在 Windows 环境中采用“版本隔离 + 虚拟环境隔离 + 工具链隔离”的策略，为 FaceFusion 提供纯净、可复现的本地部署方案，并实现 GPU 加速。

📚 参考：

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

更进一步的路径精简方案：D:\A\envs —— 构建极简可控的 Anaconda 环境路径

初代版本的非 Conda 环境部署方案

virtualenv嵌套conda绕开安装环境检测实现.venv部署facefusion

前置条件

【收藏级】Windows AI 本地开发「完全体」环境搭建清单

操作系统：Windows 10/11（64 位）
Python 环境：建议已具备 Python 3.12 运行环境（可通过 Conda、pyenv 或官方安装包安装，本教程不依赖 Conda 管理依赖，只按 EPGF 架构，从 Conda 获得 Python 源）
硬件要求：支持 CUDA 的 NVIDIA 显卡（需预装匹配驱动及 CUDA Toolkit ≥11.6，建议 CUDA 13.0 以获得最新 TensorRT 支持）
工具依赖：git、ffmpeg 已安装并配置到系统环境变量

💡 提示：如果没有 Python 3.12，可先用 Conda 创建环境或使用官方安装包安装；本教程重点是环境隔离，而非强制依赖 Conda。

部署步骤（按顺序执行）

1. 克隆仓库并进入项目目录

拉取 FaceFusion 核心代码，准备项目基础文件：

git clone https://github.com/facefusion/facefusion.git
cd facefusion

2. 切换到 Python 3.12 环境（EPGF：版本隔离）

确保当前激活的 Python 版本为 3.12：

# Conda 示例（如使用 pyenv 或系统 Python，可跳过此步）
conda activate py312
python -V
# 预期输出：Python 3.12.x

3. 创建项目本地虚拟环境（EPGF：依赖隔离）

在项目目录中创建独立虚拟环境 .venv，确保依赖与系统/全局环境完全隔离：

python -m venv .venv# 激活虚拟环境（Windows CMD）
.venv\Scripts\activate.bat# PowerShell 需执行以下两步
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
.\.venv\Scripts\Activate.ps1# 退出 Conda 环境，彻底脱离对 Conda 的依赖
conda deactivate py312

💡 激活成功后，终端提示符应显示 (.venv)，此后所有操作均在此虚拟环境中完成。

4. 升级基础打包工具（EPGF：工具链隔离）

升级 .vevn 中的 pip、setuptools、wheel，避免因版本过旧导致部署安装失败：

python -m pip install --upgrade pip setuptools wheel

5. 安装 PyTorch（GPU 版本）

PyTorch 的 CUDA GPU 支持 · 安装五条铁律（最新版 2025 修订）（适用于所有用户）

“100% 成功的 PyTorch CUDA GPU 支持” 安装攻略

FaceFusion 依赖 PyTorch，建议先安装最新支持 CUDA 的版本：

pip3 install --pre torch torchvision --index-url https://download.pytorch.org/whl/nightly/cu129

⚠️ 如果你的 CUDA 版本不同，请前往 PyTorch 官网查询对应的 --index-url 并替换。

6. 安装 TensorRT（可选优化）

为了提升推理性能，可安装匹配 CUDA 13.0 的 TensorRT（需提前下载对应的 .whl 文件）：

python -m pip install tensorrt-10.13.3.9-cp312-none-win_amd64.whl

详细步骤和跨版本维护方案可参考：Windows 安装 TensorRT 10.13.3.9（适配 CUDA 13.0）

7. 安装部署（ CUDA GPU 加速支持）

使用官方安装脚本部署 CUDA 版 ONNX Runtime，确保依赖安装到当前虚拟环境：

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

参数说明

--onnxruntime cuda：安装支持 CUDA 的 ONNX Runtime（FaceFusion 推理核心）
--skip-conda：跳过 Conda 检查，强制安装到当前 .venv
--python install.py ：自动安装 requirements.txt 及相关依赖

安装过程可能耗时 5–20 分钟，提示 Successfully installed 表示成功。

8. 启动 FaceFusion

完成依赖安装后，启动程序：

python facefusion.py run --open-browser

默认打开浏览器访问 http://127.0.0.1:7860
如不想自动打开浏览器，可用 python facefusion.py run

上传图片测试：

【笔记】Facefusion3.3.2 之 NSFW 检测屏蔽测试

部署验证

环境隔离验证
在激活的虚拟环境中执行，再运行 where python\where torch 等关键依赖项，.venv 中的路径应位于首行位置，证明依赖调用于本地 .venv。
GPU 加速验证
执行一次人脸融合任务，打开“任务管理器 → 性能 → GPU”，观察 GPU 利用率是否上升。
功能验证
确认输出文件是否正常生成（默认路径：facefusion/output）。

常见问题与解决方案

问题现象	可能原因	解决方法
克隆仓库失败	网络不稳定或未配置 git	使用镜像仓库：`git clone https://gitee.com/mirrors/facefusion.git`
激活虚拟环境报权限不足	PowerShell 脚本权限受限	执行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`，输入 `Y` 确认
安装依赖超时	官方 PyPI 源访问慢	使用镜像源：`pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple`
CUDA 不可用	CUDA Toolkit 版本不匹配	确认 CUDA Toolkit ≥11.6，并配置 `CUDA_PATH` 环境变量
TensorRT 安装失败	CUDA / Python 版本不匹配	参考官方兼容表下载对应版本