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表示不限制
- video_memory_strategy: 显存管理策略
-
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 安全特性
- 文件完整性校验
- 错误处理和恢复
- 进度保存和恢复
- 日志记录