FaceFusion 从0开始本地部署，RTX4060

最新推荐文章于 2025-04-16 11:10:53 发布

万山y

最新推荐文章于 2025-04-16 11:10:53 发布

阅读量3.6k

点赞数 31

文章标签： python

本文链接：https://blog.csdn.net/qq_43499921/article/details/144837392

版权

FaceFusion 从0开始本地部署指南

一、环境准备

1. 基础工具安装

1.1 Git 安装

使用管理员权限打开 PowerShell
执行安装命令：

winget install -e --id Git.Git

验证安装：

git --version

1.2 FFmpeg 安装

使用管理员权限打开 PowerShell
执行安装命令：

winget install -e --id Gyan.FFmpeg

添加环境变量：
- 打开"系统属性" -> “环境变量”
- 在"系统变量"的 Path 中添加：C:\Program Files\ffmpeg\bin

在 conda 环境中配置 FFmpeg（两种方法）：

方法一：单独添加 FFmpeg 路径

# 激活环境
conda activate py310_facefusion

# 添加 FFmpeg 路径到 conda 环境
conda env config vars set PATH="%PATH%;C:\Users\yuuu\AppData\Local\Microsoft\WinGet\Links"

# 重新激活环境使变更生效
conda deactivate
conda activate py310_facefusion

方法二：继承系统 PATH（推荐）

# 激活环境
conda activate py310_facefusion

# 将系统环境变量复制到 conda 环境
conda env config vars set PATH="%PATH%"

# 重新激活环境使变更生效
conda deactivate
conda activate py310_facefusion

验证安装：

# 确保在 conda 环境中
conda activate py310_facefusion

# 验证 FFmpeg
where ffmpeg
ffmpeg -version

1.3 K-Lite Codec Pack Basic 安装

使用管理员权限打开 PowerShell
执行安装命令：

winget install -e --id CodecGuide.K-LiteCodecPack.Basic

1.4 Anaconda 安装

下载 Anaconda：
- 访问 Anaconda官网
- 下载 Python 3.10 版本的安装包
安装步骤：
- 运行安装程序
- 选择"Install for All Users"
- 建议安装到默认路径：C:\ProgramData\Anaconda3
- 勾选"Add Anaconda to PATH"
验证安装：

conda --version
python --version

1.5 创建虚拟环境

打开 Anaconda Prompt（管理员）
创建 Python 3.10 环境：

# 创建环境时继承系统环境变量
conda create -n py310_facefusion python=3.10 --copy-system-site-packages

如果环境已经创建，可以修改现有环境：

# 激活环境
conda activate py310_facefusion

# 将系统环境变量复制到 conda 环境
conda env config vars set PATH="%PATH%"

# 或者编辑 conda 环境配置文件
# 打开 C:\Users\<用户名>\.conda\envs\py310_facefusion\etc\conda\activate.d\env_vars.bat
# 添加以下内容：
@echo off
set "PATH=%PATH%;C:\Users\yuuu\AppData\Local\Programs\Python\Python310;C:\Users\yuuu\AppData\Local\Programs\Python\Python310\Scripts"

如果只想添加 Python 路径：

conda env config vars set PATH="%PATH%;C:\Users\yuuu\AppData\Local\Programs\Python\Python310;C:\Users\yuuu\AppData\Local\Programs\Python\Python310\Scripts"

# 重新激活环境使变更生效
conda deactivate
conda activate py310_facefusion

验证 Python 是否可用：

where python
python --version

注意：

环境变量覆盖只在当前终端会话中有效
退出虚拟环境后会恢复原始环境变量
这不会永久修改系统环境变量

取消当前环境的 PATH 配置：

# 1. 查看当前环境变量配置
conda env config vars list

# 2. 取消 PATH 变量设置
conda env config vars unset PATH

# 3. 重新激活环境使更改生效
conda deactivate
conda activate py310_facefusion

# 4. 验证环境变量是否已清除
conda env config vars list

如果还有其他配置文件：

检查并删除环境变量配置文件：

# 删除 activate.d 目录下的配置文件
del C:\Users\yuuu\.conda\envs\py310_facefusion\etc\conda\activate.d\env_vars.bat
del C:\Users\yuuu\.conda\envs\py310_facefusion\etc\conda\activate.d\path.bat

如果需要特定的 PATH 配置，建议：
- 在 base 环境中配置
- 或使用 .condarc 文件进行全局配置
- 或在激活环境时临时设置

1.6 配置镜像源

添加清华源：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/
conda config --set show_channel_urls yes

配置 pip 源：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

1.7 注意事项：

所有安装命令建议使用管理员权限运行
安装完成后需要重启 PowerShell 或 CMD 使环境变量生效
如果 winget 命令不可用，需要先在 Microsoft Store 中安装 App Installer
确保网络连接稳定，特别是在配置镜像源时
如果安装过程中遇到权限问题，检查是否使用了管理员权限
建议在安装完成后重启系统，确保所有配置生效

1.8 常见问题：

FFmpeg 未找到：
- 检查环境变量是否正确配置
- 尝试重启终端或系统
Conda 命令未找到：
- 检查 Anaconda 是否已添加到 PATH
- 使用 Anaconda Prompt 而不是普通终端
pip 或 conda 下载速度慢：
- 确认镜像源配置是否正确
- 尝试更换其他镜像源

2. 显卡环境

2.1 NVIDIA 驱动安装

检查显卡型号和当前驱动：

nvidia-smi

如果未安装驱动：
- 访问 NVIDIA驱动下载
- 选择对应显卡型号下载驱动
- 运行安装程序，按默认选项安装

2.2 CUDA 环境配置

安装 PyTorch (包含 CUDA)：

conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

安装 cuDNN：

conda install -c conda-forge cudnn

安装 TensorRT：

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

安装 OpenVINO（可选）：

pip install openvino

2.3 CUDA 环境验证

创建验证脚本 验证cuda相关的安装.py：

import torch
import sys

def check_cuda():
    print(f"Python 版本: {sys.version}")
    print(f"PyTorch 版本: {torch.__version__}")
    print(f"CUDA 是否可用: {torch.cuda.is_available()}")

    if torch.cuda.is_available():
        print(f"CUDA 版本: {torch.version.cuda}")
        print(f"cuDNN 版本: {torch.backends.cudnn.version()}")
        print(f"GPU 设备名称: {torch.cuda.get_device_name(0)}")
        print(f"GPU 数量: {torch.cuda.device_count()}")

        # 测试 CUDA 计算
        x = torch.rand(5, 3)
        print("\n测试 CPU 张量:")
        print(x)

        print("\n测试 GPU 张量:")
        if torch.cuda.is_available():
            x = x.cuda()
            print(x)
    else:
        print("CUDA 不可用，请检查安装")

if __name__ == "__main__":
    check_cuda()

运行验证：

python 验证cuda相关的安装.py

2.4 注意事项：

CUDA 版本要求：
- PyTorch 2.x 推荐 CUDA 11.8 或更高版本
- 确保 NVIDIA 驱动版本支持所安装的 CUDA 版本
内存管理：
- 确保显存足够（建议 8GB 以上）
- 适当设置批处理大小避免显存溢出

2.5 常见问题：

CUDA 不可用：
- 检查 NVIDIA 驱动是否正确安装
- 确认 PyTorch 是否安装了 CUDA 版本
- 检查 CUDA 环境变量是否正确
显存不足：
- 减小批处理大小
- 使用显存优化选项
- 考虑使用显存更大的显卡
版本不匹配：
- 确保 PyTorch、CUDA、cuDNN 版本互相兼容
- 需要时可以降级或升级相应组件

二、安装步骤

1. 系统工具安装

使用管理员权限打开 PowerShell
安装 Git
安装 FFmpeg
安装编解码器
配置环境变量

2. Python 环境配置

安装 Anaconda
创建虚拟环境
激活虚拟环境
配置 pip 和 conda 镜像源

3. CUDA 环境配置

安装 NVIDIA 驱动
安装 CUDA Toolkit
安装 cuDNN
安装 PyTorch
安装 TensorRT

4. 项目配置

4.1 克隆项目

mkdir S:\AI_App
cd S:\AI_App

克隆项目：

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

4.2 安装项目依赖

确保在正确的环境中：

conda activate py310_facefusion

安装项目依赖：

# 安装 gradio 用于 UI 界面
pip install gradio gradio_rangeslider

# 运行项目的安装脚本
python install.py

4.3 下载模型文件

自动下载（推荐）：

# 自动下载所需的模型文件
python facefusion.py force-download

该命令会执行以下操作：

检查 .assets/models/ 目录是否存在，不存在则创建
下载以下必需的模型文件：
- 人脸检测模型：
  - retinaface_10g.onnx (人脸定位)
  - scrfd_2.5g.onnx (人脸检测)
  - yoloface_8n.onnx (人脸识别)
- 人脸特征模型：
  - recognition_hybrid.onnx (人脸特征提取)
  - recognition_dynamic.onnx (动态特征识别)
- 人脸处理模型：
  - inswapper_128.onnx (人脸交换)
  - GFPGANv1.4.pth (人脸增强)
  - 79999_iter.pth (表情恢复)
  - parsing_parsenet.onnx (人脸解析)
- 其他辅助模型
下载过程：
- 自动选择最快的下载源
- 显示下载进度
- 校验文件完整性
- 如果文件已存在且完整，则跳过
下载源包括：
- GitHub Release
- Hugging Face
- 项目官方 CDN
- 社区镜像
注意事项：
- 需要稳定的网络连接
- 总下载大小约 2-3GB
- 部分地区可能需要代理
- 建议使用 VPN 或镜像加速
常见问题处理：
- 如果下载中断：重新运行命令会继续下载
- 如果校验失败：删除对应文件重新下载
- 如果下载速度慢：可以尝试手动下载方式

手动下载（如果自动下载太慢）：
a. 创建目录结构：
```
mkdir -p .assets/models
```
b. 从以下地址下载模型文件：
- 主要下载源：
  - GitHub:
    - 基础URL: https://github.com
    - 路径模板: /facefusion/facefusion-assets/releases/download/{base_name}/{file_name}
    - 完整示例: https://github.com/facefusion/facefusion-assets/releases/download/models/inswapper_128.onnx
  - Hugging Face:
    - 基础URL: https://huggingface.co
    - 路径模板: /facefusion/{base_name}/resolve/main/{file_name}
    - 完整示例: https://huggingface.co/facefusion/models/resolve/main/inswapper_128.onnx
  注意：下载时需要将路径模板中的 {base_name} 替换为 “models”，{file_name} 替换为具体的模型文件名
- 需要下载的模型文件：
  - 人脸检测模型：
    - retinaface_10g.onnx (约 20MB)
    - scrfd_2.5g.onnx (约 5MB)
    - yoloface_8n.onnx (约 8MB)
  - 人脸特征模型：
    - recognition_hybrid.onnx (约 90MB)
    - recognition_dynamic.onnx (约 45MB)
  - 人脸处理模型：
    - inswapper_128.onnx (约 1.2GB)
    - GFPGANv1.4.pth (约 350MB)
    - 79999_iter.pth (约 450MB)
    - parsing_parsenet.onnx (约 100MB)
  - 其他辅助模型（根据需要下载）
c. 放置文件：
- 将下载的模型文件放入 .assets/models/ 目录
- 确保文件名与原始文件名完全一致
- 不要修改文件内容或重命名文件
- 文件结构应该如下：
```
.assets/
└── models/
    ├── retinaface_10g.onnx
    ├── scrfd_2.5g.onnx
    ├── yoloface_8n.onnx
    ├── recognition_hybrid.onnx
    ├── recognition_dynamic.onnx
    ├── inswapper_128.onnx
    ├── GFPGANv1.4.pth
    ├── 79999_iter.pth
    └── parsing_parsenet.onnx
```
d. 验证文件完整性：
```
# 运行程序会自动检查模型文件
python facefusion.py run
```
e. 常见问题：
- 如果下载链接失效，可以：
  - 使用 force-download 命令获取最新链接
  - 查看项目 Discussions 区获取镜像链接
  - 通过社区分享获取
- 如果文件校验失败：
  - 确保完整下载，没有断点续传
  - 检查文件是否被修改
  - 重新下载对应版本的文件

4.3.1 哈希验证失败的处理方法

当看到类似 “[FACEFUSION.DOWNLOAD] Validating hash for xxx failed” 的错误时：

清理已下载的文件：

# Windows
del .assets\models\alexandra_daddario_224
# 或 Linux/Mac
rm .assets/models/alexandra_daddario_224

重新下载的方法：
a. 使用命令行：
```
python facefusion.py force-download
```
b. 或手动下载：
- 访问 https://github.com/facefusion/facefusion-assets/releases
- 下载对应的文件
- 确保完整下载（不要使用断点续传）
验证步骤：
- 下载完成后运行程序会自动验证
- 如果还是失败，尝试使用其他下载源
- 确保网络稳定，最好使用代理或VPN
预防措施：
- 使用稳定的网络连接
- 避免使用下载管理器
- 确保磁盘有足够空间
- 下载时不要暂停或中断

4.4 修改配置文件

创建或编辑 facefusion.ini：

[general]
# 执行提供程序设置
execution_providers = ['cuda']          # 可选值: ['cpu', 'cuda', 'coreml', 'directml', 'openvino', 'rocm', 'tensorrt']
execution_thread_count = 8              # 范围: 1-32，控制处理线程数
execution_queue_count = 1               # 范围: 1-4，控制任务队列数

[memory]
# 显存管理策略
video_memory_strategy = 'strict'        # 可选值: ['strict', 'moderate', 'tolerant']
system_memory_limit = 0                 # 范围: 0-128，系统内存限制(GB)，0表示不限制

[face_detector]
# 人脸检测器设置
model = 'retinaface'                    # 可选值: ['many', 'retinaface', 'scrfd', 'yoloface']
size = '640x640'                        # 检测尺寸，根据模型支持的尺寸选择
score = 0.5                             # 范围: 0.0-1.0，检测置信度阈值

[face_selector]
# 人脸选择器设置
mode = 'reference'                      # 可选值: ['many', 'one', 'reference']
order = 'left-right'                    # 可选值: ['left-right', 'right-left', 'top-bottom', 'bottom-top', 'small-large', 'large-small', 'best-worst', 'worst-best']

[frame_processor]
# 帧处理器设置
blend = 0.8                            # 范围: 0.0-1.0，融合强度
quality = 80                           # 范围: 0-100，输出质量

[temp]
# 临时文件设置
format = 'jpg'                         # 可选值: ['jpg', 'png']
folder = 'temp'                        # 临时文件夹路径

配置文件说明：

general 部分：
- execution_providers: 设置运行设备，推荐使用 cuda
- execution_thread_count: 处理线程数，根据CPU核心数设置
- execution_queue_count: 任务队列数，影响并行处理能力
memory 部分：
- video_memory_strategy: 显存管理策略
  - strict: 严格模式，确保不会超出显存
  - moderate: 中等模式，允许适度使用
  - tolerant: 宽松模式，允许更多显存使用
- system_memory_limit: 系统内存限制，0表示不限制
face_detector 部分：
- model: 人脸检测模型选择
- size: 检测尺寸，越大越准确但更慢
- score: 检测置信度，越高要求越严格
face_selector 部分：
- mode: 人脸选择模式
- order: 人脸处理顺序
frame_processor 部分：
- blend: 融合强度，影响结果自然度
- quality: 输出质量，影响文件大小
temp 部分：
- format: 临时文件格式
- folder: 临时文件存储位置

4.5 启动项目

启动 UI 界面：

python facefusion.py run

如果遇到错误：

Error launching UI: expected str, bytes or os.PathLike object, not NoneType
[FACEFUSION.CORE] CURL is not installed

解决方法：

安装 CURL：

# 在 conda 环境中安装 curl
conda install curl

# 或使用 pip 安装 pycurl
pip install pycurl

修复 UI 启动错误：
a. 确保已安装 gradio：

pip install --upgrade gradio gradio_rangeslider

b. 检查项目依赖：

# 重新运行安装脚本
python install.py

# 或手动安装核心依赖
pip install -r requirements.txt

c. 清理临时文件：

# 删除临时文件夹
rm -rf temp/
mkdir temp

验证安装：

# 检查 curl 是否可用
curl --version

# 检查 Python 依赖
pip list | findstr curl
pip list | findstr gradio

或使用命令行模式：

# 处理单个文件
python facefusion.py run -s <源图片> -t <目标图片/视频> -o <输出路径>

# 批量处理
python facefusion.py batch-run -s <源目录> -t <目标目录> -o <输出目录>

4.6 注意事项：

项目目录权限：
- 确保有写入权限
- 路径不要包含中文和特殊字符
模型文件：
- 确保模型文件完整下载
- 检查文件 hash 值是否正确
运行环境：
- 确保在正确的 conda 环境中
- 确保所有依赖都已正确安装

4.7 常见问题：

模型下载失败：
- 检查网络连接
- 尝试手动下载
- 使用代理或镜像
依赖安装错误：
- 检查 Python 版本
- 检查 pip 源配置
- 查看错误日志
启动失败：
- 检查 CUDA 环境
- 验证模型文件完整性
- 查看日志输出

三、验证步骤

1. 环境验证

验证 FFmpeg 安装
验证 CUDA 环境
验证 PyTorch 环境

2. 项目验证

验证基础功能
验证 UI 界面
验证模型加载

四、常见问题

1. 环境问题

CUDA 版本不匹配解决方案
FFmpeg 未找到解决方案
临时文件路径问题

2. 运行问题

模型下载失败解决方案
UI 启动失败解决方案
CUDA 内存不足解决方案

五、优化建议

1. 性能优化

GPU 内存管理
临时文件管理
批处理优化

2. 使用建议

推荐参数设置
最佳实践流程
注意事项

六、功能说明

1. 核心功能

1.1 人脸处理

人脸检测：支持多种检测器
- RetinaFace (推荐)
- SCRFD
- YOLOFace
- Many
人脸识别与分析
- 人脸特征提取
- 人脸对比和匹配
- 表情分析
- 年龄和性别识别
人脸编辑
- 人脸交换
- 表情恢复
- 人脸增强
- 面部遮挡处理

1.2 视频处理

视频帧提取和处理
音频同步
多种输出格式支持：
- 视频编码器：
  - libx264/libx265 (CPU)
  - h264_nvenc/hevc_nvenc (NVIDIA GPU)
  - h264_amf/hevc_amf (AMD GPU)
  - h264_qsv/hevc_qsv (Intel GPU)

1.3 批处理功能

批量图片处理
批量视频处理
任务队列管理

2. 使用模式

2.1 UI 界面模式

python facefusion.py run

图形界面操作
实时预览
参数可视化调整

2.2 命令行模式

# 单文件处理
python facefusion.py run -s <源图片> -t <目标图片/视频> -o <输出路径>

# 批量处理
python facefusion.py batch-run -s <源目录> -t <目标目录> -o <输出目录>

3. 可配置选项

3.1 人脸检测配置

[face_detector]
model = 'retinaface'        # 检测模型选择
size = '640x640'           # 检测尺寸
score = 0.5                # 置信度阈值

3.2 人脸选择配置

[face_selector]
mode = 'reference'         # 选择模式
order = 'left-right'       # 处理顺序

3.3 处理器配置

[frame_processor]
blend = 0.8               # 融合强度
quality = 80              # 输出质量

4. 高级功能

4.1 性能优化

多线程处理
GPU 加速
内存管理
临时文件优化

4.2 质量控制

面部特征保持
表情同步
光照适配
边缘融合

4.3 安全特性

文件完整性校验
错误处理和恢复
进度保存和恢复
日志记录