FaceSwap 深度学习换脸工具技术指南：从安装到 Extract / Train / Convert 完整工作流

FaceSwap 是一个利用深度学习在图片与视频中识别并替换人脸的开源工具（Deepfakes Software For All）。本文以仓库根目录 README.md 为主线，完整覆盖环境要求、安装方式、Extract → Train → Convert 三段式核心工作流、GUI 与辅助工具的使用，并结合 faceswap.py、plugins 与 tools 等源码，说明每个命令背后的插件化实现结构，帮助读者从零跑通一次完整的人脸替换并理解其底层调用链。

一、项目定位与使用边界

FaceSwap 的核心定义在 README 中一句话概括：

FaceSwap is a tool that utilizes deep learning to recognize and swap faces in pictures and videos.

它的工作对象是人脸——模型学习的是"如何把 A 的脸变换成 B 的脸"，因此非人脸对象不一定能正确处理。README 同时以 Manifesto 章节明确了项目的伦理立场，这是理解该项目设计意图的重要背景：

• FaceSwap 不用于制作不当内容；
• 不用于未经同意、或带有隐瞒意图的人脸替换；
• 不用于任何非法、不道德或存疑的目的；
• 它的存在是为了实验与探索 AI 技术、社会或政治评论、影视制作等合法合理的用途。

开发团队强调将"滥用潜力最小化、学习与实验价值最大化"作为演进方向，对不道德用途采取零容忍态度。作为技术研究或学习深度学习的工具时，应把这一边界作为前提。

二、运行环境与安装

2.1 硬件与操作系统要求

README 指出 FaceSwap 是一个 Python 程序，可在 Windows、Linux、macOS 多平台运行，并给出关键前提：

• 最佳性能需要 支持 CUDA 的现代 GPU；
• 许多 AMD GPU 可通过 ROCm（Linux）获得支持。

INSTALL.md 给出了更完整的硬件结论：训练本质上是"让程序尝试数百万种参数设置"的试错过程，在 CPU 上训练可能需要数周，而在 GPU 上只需数小时，因此桌面级/服务器级 GPU 几乎是训练的必要条件。Nvidia GPU 需至少支持 CUDA Compute Capability 3.5，桌面端 7xx 系列之后的显卡大多可用。支持的操作系统为 Windows 10/11、主流 Linux 发行版（Ubuntu/Debian/CentOS 系）、以及 macOS（Apple Silicon M 系列通过 Metal 获得实验性 GPU 加速，Intel Mac 需走手动安装路径），所有系统必须为 64 位。

2.2 安装路径：安装器、setup.py 与 requirements

从 INSTALL.md 可以梳理出三条安装路线：

1. 官方安装器：Windows / Linux / macOS 均有打包好的安装器，一键完成环境配置；
2. 手动安装：安装 Anaconda 与 Git 后，创建 Python 3.13 的虚拟环境（conda create --name faceswap python=3.13），克隆仓库并执行 python setup.py 走 Easy install；
3. 按 GPU 类型选择 requirements 文件手动安装依赖，这是排查问题时最重要的参考：

# Nvidia GPU
pip install -r ./requirements/requirements_nvidia_13.txt   # RTX 20xx 及以后
pip install -r ./requirements/requirements_nvidia_12.txt   # GTX 9xx - 10xx
pip install -r ./requirements/requirements_nvidia_11.txt   # GTX 7xx - 8xx
# AMD GPU（仅 Linux，需先装好兼容的 ROCm）
pip install -r ./requirements/requirements_rocm64.txt
# CPU 用户
pip install -r ./requirements/requirements_cpu.txt
# Apple Silicon（M 系列）
pip install -r ./requirements/requirements_apple-silicon.txt

仓库中 requirements 目录下按 GPU 平台分文件存放依赖清单，这正是 INSTALL.md 中各命令对应的真实文件来源。需要注意的约束包括：GTX 8xx/9xx 对应的旧版 Torch 对 Python 版本上限为 3.13；ROCm 6.0 要求 Python ≤ 3.12。

2.3 入口程序如何工作

安装完成后，运行入口是根目录的 faceswap.py。从源码看，其 _main() 函数（faceswap.py#L37-L57）做了三件事：

1. system.validate_python() 校验 Python 版本（tools.py#L16-L18 中则硬性要求至少 Python 3.11）；
2. generate_configs() 在首次运行时自动生成配置文件——这就是后文 config/ 下各 ini 文件的来源，仓库中 config 目录初始为空，配置文件是运行后才出现的；
3. 用 FullHelpArgumentParser 注册四个子命令：extract、train、convert、gui，分别由 ExtractArgs、TrainArgs、ConvertArgs、GuiArgs（定义于 lib/cli）构建。参数非法时打印全局帮助并退出。

README 中"所有脚本都有 -h/--help 选项"这一说明，对应的就是这里的 FullHelpArgumentParser 实现。

更新方面，GUI 内可在 Help 菜单执行 "Check for Updates..." / "Update Faceswap"；命令行用户则 git pull --all 后运行仓库根目录的 update_deps.py 刷新依赖。

三、核心工作流：Extract → Train → Convert

README 的 Overview 部分给出了三段式流程：收集原始素材 → Extract 从照片中提取人脸 → Train 用两张人脸集合训练模型 → Convert 用模型转换源素材。下面逐环节展开，命令行细节同时参考 USAGE.md。

3.1 Extract：从原始图片/视频中提取人脸

README 的基本命令（在 setup 目录下执行）：

python faceswap.py extract

约定素材放在 src 文件夹、提取结果进入 extract 文件夹。实际 CLI 使用 -i 指定输入、-o 指定输出，例如：

# 从图片文件夹提取
python faceswap.py extract -i ~/faceswap/src/trump -o ~/faceswap/faces/trump
# 从视频文件提取
python faceswap.py extract -i ~/faceswap/src/trump.mp4 -o ~/faceswap/faces/trump

执行后脚本会：识别人脸关键点（landmarks）→ 把图像裁剪为统一尺寸 → 保存人脸到输出文件夹，同时在输入目录生成一个 alignments.json 文件，记录每张人脸的位置信息，供后续 Train/Convert 使用。

从源码结构看，extract 命令的能力由 plugins/extract 下的插件提供：detect/（人脸检测，即 README 致谢中提到的 MTCNN 检测器所在的环节）、align/（对齐，含 FAN aligner）、identity/（识别哪张脸属于目标人物）、mask/（蒙版生成）。README 中"开发者把 MTCNN 检测器、FAN 对齐器移植进 FaceSwap"的表述与这些插件目录一一对应。

实践要点（来自 USAGE.md 与 README 的 General notes）：

• 训练素材建议为每个目标人物收集 500～5000 张高质量人脸，覆盖多角度、多表情、多光照；
• 不要把视频的每一帧都拿来训练——相邻帧高度重复；
• 提取脚本并非完美：可能误检多张脸、也可能把非目标人物的脸混入，训练前务必人工检查训练数据；
• 完整参数用 python faceswap.py extract -h 查看，插件级配置项在首次运行后生成于 <faceswap_folder>/config/extract.ini。

3.2 Train：训练 A/B 两个人脸之间的变换模型

README 的基本命令：

python faceswap.py train

约定读取两个人脸文件夹、把模型保存到 models 文件夹。带完整参数的形式为：

python faceswap.py train -A ~/faceswap/faces/trump -B ~/faceswap/faces/cage -m ~/faceswap/trump_cage_model/
# -p 开启预览窗口
python faceswap.py train -A ~/faceswap/faces/trump -B ~/faceswap/faces/cage -m ~/faceswap/trump_cage_model/ -p

训练过程的直观表现（USAGE.md 描述）：开启预览后先看到一堆"斑块"，随着迭代逐步浮现出两张脸的轮廓，直到预览效果满意为止。关键行为特性：

• 时长：GPU 上 ballpark 12–48 小时，CPU 上以周计；
• 保存与恢复：模型大约每 100 次迭代自动保存一次；整体 loss 下降的保存点会自动备份，模型损坏时可移除备份文件的 .bk 后缀恢复；训练可随时中断并从同一组文件夹继续；
• 停止方式：命令行在预览窗口或控制台按 Enter，GUI 点 Terminate 按钮。

模型选择是训练中最关键的决策。README 的视频示例中点名了两个模型：Emma Stone/Scarlett Johansson 换脸使用 Phaze-A 模型，Jennifer Lawrence/Steve Buscemi 换脸使用 Villain 模型。当前仓库 plugins/train/model 目录实际内置了十余个生成模型可选，包括：

模型	源码文件
DFaker	plugins/train/model/dfaker.py
DFL-H128	plugins/train/model/dfl_h128.py
DFL-SAE	plugins/train/model/dfl_sae.py
DLIGHT	plugins/train/model/dlight.py
IAE	plugins/train/model/iae.py
Lightweight	plugins/train/model/lightweight.py
Original	plugins/train/model/original.py
Phaze-A	plugins/train/model/phaze_a.py
RealFace	plugins/train/model/realface.py
Unbalanced	plugins/train/model/unbalanced.py
Villain	plugins/train/model/villain.py

这些与 README 致谢中提到的移植/创作记录一致（torzdf 移植了 Villain、DFL-H128、DFaker；andenixa 创作了 Unbalanced 与 OHR 模型）。完整的训练参数用 python faceswap.py train -h 查看，插件级配置在 <faceswap_folder>/config/train.ini（首次运行后生成）。若使用 mask 或 Warp to Landmarks 训练，还需为每套人脸传入对应的 alignments.json。

3.3 Convert：用训练好的模型替换人脸

README 的基本命令：

python faceswap.py convert

约定读取 original 文件夹、把替换结果写入 modified 文件夹。完整参数形式：

python faceswap.py convert -i ~/faceswap/src/trump/ -o ~/faceswap/converted/ -m ~/faceswap/trump_cage_model/

关键前置步骤：Convert 需要一份针对源素材的 alignments.json，做法是对源视频/图片再跑一次 extract（即"给换脸目标做提取"），然后清理其中的误检、对齐不良的条目——这些脏数据会直接拉低成片质量，仓库 tools/alignments 目录提供了专门的 alignments 清理工具。

从源码结构看，convert 的可调环节对应 plugins/convert 下的四组插件：color/（颜色转移/融合）、mask/（蒙版策略）、scaling/（缩放处理）、writer/（输出写入）。参数同样用 python faceswap.py convert -h 查看，插件配置位于 <faceswap_folder>/config/convert.ini。

3.4 视频处理：effmpeg 与 ffmpeg

README 的 General notes 指出两条视频处理路径：

1. 内置 effmpeg 工具：python tools.py effmpeg -h。tools.py 的 _get_cli_opts()（tools.py#L27-L38）会扫描 tools 目录下每个含 cli.py 的子模块并自动注册为子命令，因此 tools.py 目前还内置了 alignments、manual、mask、model、preview、sort 等辅助工具，均可用 python tools.py <name> -h 发现；
2. 系统 ffmpeg：拆帧与合帧的示例命令（来自 USAGE.md）：

# 拆帧
ffmpeg -i /path/to/my/video.mp4 /path/to/output/video-frame-%d.png
# 合帧（25fps）
ffmpeg -i video-frame-%0d.png -c:v libx264 -vf "fps=25,format=yuv420p" out.mp4

视频在流程中只是"以帧为单位的图片序列"：拆成帧后走 extract/train/convert 的图片流水线，再把结果帧合成回视频。

四、GUI 模式

除命令行外，README 提供了等价的图形界面入口：

python faceswap.py gui

GUI 对应 faceswap.py 注册的第四个子命令，前端实现位于 lib/gui。GUI 覆盖 extract / train / convert 的全部选项并带悬停提示，还额外提供：更新检查（Help → Check for Updates...）、训练预览与 Terminate 按钮、以及桌面快捷方式支持（Windows 下可将 %USERPROFILE%\Anaconda3\envs\faceswap\python.exe %USERPROFILE%/faceswap/faceswap.py gui 保存为 faceswap.bat）。对不熟悉 CLI 的选项，"在 GUI 中悬停查看选项说明"是 USAGE.md 推荐的探索方式。

五、实战技巧（General notes）

README 与 USAGE.md 沉淀了两条最实用的经验：

1. 复用已有模型可大幅加速训练，比从零开始快得多；
2. 训练数据不足时，可以先用一个长相相似的人物开始训练，再切换数据继续——让模型先"热机"到相近分布，再逐步收敛到目标人脸。

配合前文，一条完整的落地路径是：收集 ≥500 张/人的高质量照片或视频 → extract 并人工清洗数据 → 用目标模型 train（开预览、可断点续训）→ 对目标视频 extract + 清理 alignments → convert 出图/出帧 → 必要时合成视频。

六、支持渠道与贡献入口

• 支持：一般性问题应发到 FaceSwap 官方论坛（faceswap.dev/forum）或 FaceSwap Discord 服务器，而不是本仓库的 issue（仓库内提的使用类 issue 会被直接删除/关闭）；
• 贡献（README 的 How to contribute 章节按角色分层）：
  • 关注生成模型算法的人：可到 "faceswap-model" 仓库讨论/建议/提交算法替代方案；
  • 开发者：通读 README → Fork → 试用 → 处理带 dev 标签的 issue；偏 computer vision/OpenCV 方向可关注 advuser/opencv 标签；
  • 非开发者进阶用户：处理带 advuser 标签的 issue 并参与论坛互助；
  • 终端用户：能跑就跑，同时到论坛获取帮助——"对运行代码的问题一律去论坛开帖"是 README 的硬性约定。

仓库根目录另有 CODE_OF_CONDUCT.md、LICENSE 与 .github 下的持续集成配置（含 pytest 工作流），测试代码位于 tests 目录，可作为验证各插件行为的入口。

七、原理速览：机器学习如何"认识"人脸

README 最后用 "About machine learning" 章节回答了一个基础问题：计算机如何识别人脸、什么是神经网络？官方给出的 tl;dr 是：training data + trial and error（训练数据 + 试错）。

用本仓库的工作流来翻译这句话：Extract 阶段生产的裁剪对齐人脸是"训练数据"；Train 阶段模型在 A/B 两张脸之间反复预测、比较、修正参数（预览窗口中从斑块到人脸的变化就是试错的可视化），直到 loss 收敛；Convert 阶段则是拿训练好的映射去处理新素材。README 建议配合 3Blue1Brown 等神经网络入门视频理解全貌，而对 FaceSwap 而言，把 Extract/Train/Convert 三步跑通一遍，就是对这套"数据 + 试错"范式最直接的亲手验证。

小结

本文以 README.md 为骨架完整继承并扩充了 FaceSwap 的核心内容：伦理边界与适用前提、跨平台安装与 GPU/ROCm/CPU 依赖选择、extract/train/convert/gui 四个入口的完整命令与参数、alignments.json 这一贯穿全流程的数据契约、内置模型清单与插件化源码结构，以及模型复用等实战技巧。读者按此路径可以独立完成一次从原始素材到成片的人脸替换，并能沿 INSTALL.md、USAGE.md 与 plugins 源码继续深入任意一个环节。