FaceFusion 从0开始本地部署，RTX4060

FaceFusion 从0开始本地部署指南

一、环境准备

1. 基础工具安装

1.1 Git 安装

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

winget install -e --id Git.Git

3. 验证安装：

git --version

1.2 FFmpeg 安装

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

winget install -e --id Gyan.FFmpeg

3. 添加环境变量：

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

4. 在 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
   

5. 验证安装：

# 确保在 conda 环境中
conda activate py310_facefusion# 验证 FFmpeg
where ffmpeg
ffmpeg -version

1.3 K-Lite Codec Pack Basic 安装

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

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

1.4 Anaconda 安装

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

conda --version
python --version

1.5 创建虚拟环境

1. 打开 Anaconda Prompt（管理员）
2. 创建 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

注意：

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

取消当前环境的 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

如果还有其他配置文件：

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

# 删除 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

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

1.6 配置镜像源

1. 添加清华源：

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

2. 配置 pip 源：

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

1.7 注意事项：

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

1.8 常见问题：

1. FFmpeg 未找到：

   • 检查环境变量是否正确配置
   • 尝试重启终端或系统

2. Conda 命令未找到：

   • 检查 Anaconda 是否已添加到 PATH
   • 使用 Anaconda Prompt 而不是普通终端

3. pip 或 conda 下载速度慢：

   • 确认镜像源配置是否正确
   • 尝试更换其他镜像源

2. 显卡环境

2.1 NVIDIA 驱动安装

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

nvidia-smi

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

2.2 CUDA 环境配置

1. 安装 PyTorch (包含 CUDA)：

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

2. 安装 cuDNN：

conda install -c conda-forge cudnn

3. 安装 TensorRT：

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

4. 安装 OpenVINO（可选）：

pip install openvino

2.3 CUDA 环境验证

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

import torch
import sysdef 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()

2. 运行验证：

python 验证cuda相关的安装.py

2.4 注意事项：

1. CUDA 版本要求：

   • PyTorch 2.x 推荐 CUDA 11.8 或更高版本
   • 确保 NVIDIA 驱动版本支持所安装的 CUDA 版本

2. 内存管理：

   • 确保显存足够（建议 8GB 以上）
   • 适当设置批处理大小避免显存溢出

2.5 常见问题：

1. CUDA 不可用：

   • 检查 NVIDIA 驱动是否正确安装
   • 确认 PyTorch 是否安装了 CUDA 版本
   • 检查 CUDA 环境变量是否正确

2. 显存不足：

   • 减小批处理大小
   • 使用显存优化选项
   • 考虑使用显存更大的显卡

3. 版本不匹配：

   • 确保 PyTorch、CUDA、cuDNN 版本互相兼容
   • 需要时可以降级或升级相应组件

二、安装步骤

1. 系统工具安装

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

2. Python 环境配置

1. 安装 Anaconda
2. 创建虚拟环境
3. 激活虚拟环境
4. 配置 pip 和 conda 镜像源

3. CUDA 环境配置

1. 安装 NVIDIA 驱动
2. 安装 CUDA Toolkit
3. 安装 cuDNN
4. 安装 PyTorch
5. 安装 TensorRT

4. 项目配置

4.1 克隆项目

1. 创建项目目录：

mkdir S:\AI_App
cd S:\AI_App

2. 克隆项目：

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

4.2 安装项目依赖

1. 确保在正确的环境中：

conda activate py310_facefusion

2. 安装项目依赖：

# 安装 gradio 用于 UI 界面
pip install gradio gradio_rangeslider# 运行项目的安装脚本
python install.py

4.3 下载模型文件

1. 自动下载（推荐）：

# 自动下载所需的模型文件
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 或镜像加速

• 常见问题处理：

  • 如果下载中断：重新运行命令会继续下载
  • 如果校验失败：删除对应文件重新下载
  • 如果下载速度慢：可以尝试手动下载方式

2. 手动下载（如果自动下载太慢）：
   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” 的错误时：

1. 清理已下载的文件：

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

2. 重新下载的方法：
   a. 使用命令行：

   python facefusion.py force-download
   

   b. 或手动下载：

   • 访问 https://github.com/facefusion/facefusion-assets/releases
   • 下载对应的文件
   • 确保完整下载（不要使用断点续传）

3. 验证步骤：

   • 下载完成后运行程序会自动验证
   • 如果还是失败，尝试使用其他下载源
   • 确保网络稳定，最好使用代理或VPN

4. 预防措施：

   • 使用稳定的网络连接
   • 避免使用下载管理器
   • 确保磁盘有足够空间
   • 下载时不要暂停或中断

4.4 修改配置文件

1. 创建或编辑 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'                        # 临时文件夹路径

配置文件说明：

1. general 部分：

   • execution_providers: 设置运行设备，推荐使用 cuda
   • execution_thread_count: 处理线程数，根据CPU核心数设置
   • execution_queue_count: 任务队列数，影响并行处理能力

2. memory 部分：

   • video_memory_strategy: 显存管理策略
     • strict: 严格模式，确保不会超出显存
     • moderate: 中等模式，允许适度使用
     • tolerant: 宽松模式，允许更多显存使用
   • system_memory_limit: 系统内存限制，0表示不限制

3. face_detector 部分：

   • model: 人脸检测模型选择
   • size: 检测尺寸，越大越准确但更慢
   • score: 检测置信度，越高要求越严格

4. face_selector 部分：

   • mode: 人脸选择模式
   • order: 人脸处理顺序

5. frame_processor 部分：

   • blend: 融合强度，影响结果自然度
   • quality: 输出质量，影响文件大小

6. temp 部分：

   • format: 临时文件格式
   • folder: 临时文件存储位置

4.5 启动项目

1. 启动 UI 界面：

python facefusion.py run

如果遇到错误：

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

解决方法：

1. 安装 CURL：

# 在 conda 环境中安装 curl
conda install curl# 或使用 pip 安装 pycurl
pip install pycurl

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

   pip install --upgrade gradio gradio_rangeslider
   

   b. 检查项目依赖：

   # 重新运行安装脚本
   python install.py# 或手动安装核心依赖
   pip install -r requirements.txt
   

   c. 清理临时文件：

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

3. 验证安装：

# 检查 curl 是否可用
curl --version# 检查 Python 依赖
pip list | findstr curl
pip list | findstr gradio

2. 或使用命令行模式：

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

4.6 注意事项：

1. 项目目录权限：

   • 确保有写入权限
   • 路径不要包含中文和特殊字符

2. 模型文件：

   • 确保模型文件完整下载
   • 检查文件 hash 值是否正确

3. 运行环境：

   • 确保在正确的 conda 环境中
   • 确保所有依赖都已正确安装

4.7 常见问题：

1. 模型下载失败：

   • 检查网络连接
   • 尝试手动下载
   • 使用代理或镜像

2. 依赖安装错误：

   • 检查 Python 版本
   • 检查 pip 源配置
   • 查看错误日志

3. 启动失败：

   • 检查 CUDA 环境
   • 验证模型文件完整性
   • 查看日志输出

三、验证步骤

1. 环境验证

1. 验证 FFmpeg 安装
2. 验证 CUDA 环境
3. 验证 PyTorch 环境

2. 项目验证

1. 验证基础功能
2. 验证 UI 界面
3. 验证模型加载

四、常见问题

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 安全特性

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