FaceSwap 使用工作流详解：从 Extract 到 Train 再到 Convert 的完整换脸流程

FaceSwap（Deepfakes Software For All）的核心使用路径是一条三阶段流水线：先用 extract 从图片/视频中检测并对齐人脸生成训练数据，再用 train 训练一个能互相转换 A、B 两张脸的模型，最后用 convert 将源素材中的脸替换为目标脸。本文基于仓库根目录的 USAGE.md 完整展开该工作流，并结合 faceswap.py、scripts/extract.py、scripts/train.py 以及 lib/cli/ 下的参数定义源码，补齐每个命令的完整参数、默认值与底层实现细节，帮助读者从零跑通一次完整的换脸项目并理解每一步在代码里实际发生了什么。

一、开始之前：理解 FaceSwap 的工作方式

USAGE.md 开篇就给出了一份重要声明：它提供的是 faceswap 流程的高层概览，不会覆盖每一个可选项；所有未列出的选项都可以通过给命令行加 -h 标志查看（例如 python faceswap.py extract -h），或在 GUI 中将鼠标悬停在选项上查看说明。

换脸应用的基本原理用一句话概括：训练一个机器学习模型，使其基于图片学会识别并转换两张脸。模型就是被我们"教会"执行实际替换的"机器人"，图片则是用来训练它的"训练数据"。需要特别注意的是，该模型主要处理人脸，其他对象可能无法正常工作。

USAGE.md 以一个经典示例贯穿全文：假设我们想让某位政治人物的就职视频变成由另一位演员"主演"，即把视频中的人脸 A 替换成人脸 B。后文所有命令都围绕这一示例展开。在动手之前，请先确保已完成 INSTALL.md 中的安装步骤；遇到问题应优先去官方论坛或社区讨论，而不是在主仓库提 issue。

从源码结构看，入口脚本 faceswap.py 在 _main() 中先调用 generate_configs() 生成配置文件（这正是后文 config/ 目录下 extract.ini / train.ini / convert.ini 的来源），然后注册四个子命令：

subparser = _PARSER.add_subparsers()
ExtractArgs(subparser, "extract", _("Extract the faces from pictures or a video"))
TrainArgs(subparser, "train", _("Train a model for the two faces A and B"))
ConvertArgs(subparser, "convert", _("Convert source pictures or video to a new one with the face swapped"))
cli_args.GuiArgs(subparser, "gui", _("Launch the Faceswap Graphical User Interface"))

也就是说 extract、train、convert、gui 四个子命令一一对应本文的四个核心章节。

二、Extract：采集原始数据并提取人脸

2.1 采集原始数据

模型需要"认识"脸 A（原始脸）和脸 B（目标脸）。默认情况下模型对这两张脸一无所知，我们必须展示大量图片让它自己判断哪张是哪张。图片来源上，USAGE.md 建议优先使用视频（访谈、公开演讲、电影片段），因为视频能捕捉到更多自然姿态和表情；其次是 Google、DuckDuckGo、Bing 等图片搜索（配合批量下载脚本）。FaceSwap 本身支持从静态图片和视频文件两种来源提取人脸。

按示例约定，将素材分两个文件夹存放，例如：

~/faceswap/src/trump   # 脸 A 的图片/视频
~/faceswap/src/cage    # 脸 B 的图片/视频

2.2 提取人脸

原始素材是个"混乱"的集合：人物全身、多人同框、各种环境背景。只有数据一致且聚焦于目标人脸时才能用来训练。FaceSwap 的 extract 命令负责识别人脸关键点、把图片裁剪到统一尺寸，并把人脸保存到输出目录。

命令行（沿用 USAGE.md 的示例命令）：

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

GUI： 在 GUI 的 Extract 页面中，用"文件夹"图标按钮选择图片目录或视频文件作为输入，再指定提取人脸的保存目录即可。

输入可以是图片目录或视频文件，输出是指定人脸保存位置的目录。脚本会尽力识别人脸关键点、裁剪图片到一致尺寸，并把人脸保存到输出目录。同时会在输入目录中生成并保存一个 alignments.json 文件，其中包含每张人脸的信息，供 FaceSwap 后续流程（尤其 convert）使用。

注意：提取过程会让获取测试数据变得容易，但它并不完美——它可能在某些照片上错误地检测到多张脸，也无法识别某张脸是否属于我们要换的目标人物。因此 USAGE.md 特别强调：开始训练前务必检查你的训练数据。训练数据的质量直接决定模型换脸效果的上限。

2.3 extract 的完整参数（来自源码）

USAGE.md 建议通过 python faceswap.py extract -h 查看完整参数列表。这些参数的完整定义位于 lib/cli/args_extract_convert.py 的 ExtractArgs 类中，其中 ExtractConvertArgs 基类定义了 extract 与 convert 共享的 -i（输入目录/视频）和 -p（自定义 alignments 文件路径）参数。核心参数如下表（默认值均取自源码）：

参数	短选项	说明	默认值
--input-dir	-i	输入目录（图片）或视频文件。注意：必须是源素材，而不是训练用的脸	必填
--output-dir	-o	提取人脸的保存目录；不提供则不保存人脸，只生成 alignments 文件	无
--batch-mode	-b	批量模式：输入目录是包含多个视频和/或图片子目录的父目录，人脸会分别输出到 output_dir 下的各子文件夹	False
--detector	-D	人脸检测器：cv2-dnn（仅 CPU，资源占用最低）、mtcnn（CPU/GPU 均较快但误检偏多）、retinaface（比 s3fd 更快更轻，提供 ResNet/MobileNet 变体）、s3fd（检出更多人脸、误报更少但资源占用高）、file（从 alignments 文件导入）	GPU 环境 retinaface，CPU 环境 mtcnn
--aligner	-A	关键点/对齐器：cv2-dnn（仅 CPU）、fan（GPU 快/CPU 慢）、hrnet（比 FAN 更快更优，针对旋转人脸训练）、file	GPU 环境 hrnet，CPU 环境 cv2-dnn
--masker	-M	附加分割掩码（可多选）：bisenet-fp、custom、vgg-clear、vgg-obstructed、unet-dfl；另外 components 与 extended 两个基于关键点的掩码会在提取时自动生成	无
--identity	-I	保存人脸身份编码（如 t-face、vggface2），"按脸排序"和人脸过滤功能必需	无
--min-size / --max-size	-m / -x	按"帧短边百分比 × 检测框最长边"过滤过小/过大的人脸，0 表示关闭	0 / 0
--rotate-images	-r	未找到人脸时旋转图片重试；传单个数字表示按该步长递增到 360 度，也可传角度列表	None
--normalization	-O	归一化手段帮助 aligner 处理困难光照（none/clahe/hist/mean），只影响送入 aligner 的图像，不影响输出	none
--re-feed	-R	将检测到的人脸反复送进 aligner 并平均关键点，消除"微抖动"，代价是变慢	0
--re-align	-a	把初次对齐结果再次送进 aligner，对旋转超 45° 或极端角度的脸有帮助	False
--align-filters	-g	启用 aligner 过滤器，可按统计特征过滤人脸（在 extract 设置中可配）	False
--nfilter / --filter	-n / -f	传入"不想提取的人"/"想提取的人"的参考图片（文件夹或多张图）做身份过滤	None
--ref_threshold	-l	配合 filter/nfilter 的识别阈值，越大越严格	0.60
--size	-z	输出人脸尺寸，需确保后续要训练的模型支持该尺寸	512（256–1024）
--extract-every-n	-N	每第 N 帧提取一次（视频降采样的关键参数）	1
--min-scale	-u	只输出放大到目标尺寸所需比例 ≥ 该百分比的人脸，用于从训练集中剔除低分辨率图；不影响 alignments 文件	0
--save-interval	-v	每处理 N 帧自动保存一次 alignments 文件，0 关闭（默认仅在结束时保存）	0
--debug-landmarks	-B	在输出脸上绘制关键点等调试标注	False
--compile	-c	编译 PyTorch 模型：启动变慢、处理变快，适合大批量数据	False
--benchmark	-k	对选定 extract 插件组合做批大小性能基准测试	False
--skip-existing / --skip-existing-faces	-s / -e	跳过 alignments 文件中已存在的帧 / 已有检测结果的帧	False

几个值得留意的实现细节（来自 scripts/extract.py）：

• 参数兼容性校验：_validate_compatible_args() 会自动修正冲突组合，例如 --aligner file（从文件导入关键点）时强制把 detector 设为 file、并禁用 skip_existing；启用了 --filter/--nfilter 但没选 identity 插件时会自动选择 t-face。
• 抽取流水线：_load_pipeline() 按 Detect → Align → Mask → Identity 的顺序串联各插件（见 plugins/extract/ 下的 detect/align/mask/identity 四个插件目录），最后统一输出。
• 批量模式：_get_input_locations() 会扫描输入父目录下的图片子目录与视频文件，分别处理并输出到各自的子文件夹。

2.4 提取阶段的通用技巧

USAGE.md 给出的训练数据采集建议（与源码中的硬校验一致）：

• 每个训练对象大约采集 500 到 5000 张脸，质量要高，覆盖多样的角度、表情和光照条件。这一点在 scripts/train.py 的 _validate_image_counts() 中得到印证：单侧少于 25 张直接报错退出，少于 250 张会警告"结果可能较差"，提示语即"Aim for between 500 - 5000 images per side"。
• 不要从视频中提取每一帧用于训练——相邻帧的人脸高度相似，会造成数据冗余。实践中可配合 --extract-every-n（如 -N 10）抽帧。
• 完整参数用 -h 查看；部分插件有可配置选项，配置位于 <faceswap_folder>/config/extract.ini，需要先运行过一次 Extract 或 GUI 该文件才会生成（入口 faceswap.py 的 generate_configs() 在每次启动时都会确保配置存在）。

三、Train：训练换脸模型

现在你有了两文件夹训练脸（trump 与 cage），可以训练"机器人"了。训练会创建一个"模型"，其中包含"什么是 cage 的脸、什么是 trump 的脸，以及如何在两者之间转换"的信息。

训练是整个流程中最耗时的环节，时长取决于所用模型、图片数量、GPU 等，粗略估计 GPU 上 12–48 小时，纯 CPU 训练则以周计（lib/cli/args_train.py 中的命令描述同样给出 24 小时到一周以上的预期）。

命令行：

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

GUI： 在 GUI 的 Train 页面分别指定 A、B 两个脸文件夹与模型保存目录即可。

命令执行后会开始"猛攻"训练数据。如果开着预览窗口，会看到一堆模糊的斑块——那是模型正在学习的脸，初期几乎看不出什么，随着训练推进会越来越像 trump 和 cage。在预览图像让你满意之前应让模型持续学习。停止训练的方式：

• 命令行：在预览窗口或控制台中按回车；
• GUI：点击 Terminate 按钮。

停止时模型会保存并退出，这一步可能要花一点时间，请耐心等待。模型大约每 100 次迭代也会自动保存一次（默认保存间隔见下表 --save-interval 默认 250）。训练可以随时停止和恢复——只要让 FaceSwap 指向相同的文件夹继续训练即可。

3.1 train 的完整参数（来自源码）

完整定义见 lib/cli/args_train.py 的 TrainArgs 类：

参数	短选项	说明	默认值
--input-A	-A	脸 A（原始脸，要被移除并替换）的训练图片目录	必填
--input-B	-B	脸 B（目标脸，要贴到 A 头上）的训练图片目录	必填
--model-dir	-m	模型保存目录；新模型选空/不存在的文件夹，续训则指向现有模型	必填
--load-weights	-l	从已有模型加载权重到新模型的对应层（仅新建模型时生效，且必须同为同插件模型）	无
--trainer	-t	模型/训练器插件：original、dfaker、dfl-h128、dfl-sae、dlight、iae、lightweight（低显存卡可用，batch size 8 时约 1.6GB）、realface、unbalanced、villain（高显存、细节好但对色差敏感）等	见 plugins/train/model/
--summary	-u	仅输出模型摘要后退出	False
--freeze-weights	-f	冻结部分权重（多数模型冻结 encoder）	False
--batch-size	-b	每次迭代每侧处理的图片数（模型内实际为两倍），越大越吃显存	16（1–256）
--iterations	-i	训练总迭代数，主要用于自动化，没有"正确值"，应以预览效果为准	1000000
--warmup	-a	学习率从 0 线性升到目标值所用的迭代数，0 关闭	0
--distributed	-d	多 GPU 分布式训练（不足 2 卡时自动回退，见 scripts/train.py）	False
--no-logs	-n	禁用 TensorBoard 日志（同时失去 GUI 的曲线/分析功能）	False
--use-lr-finder	-r	用 Learning Rate Finder 自动发现最优学习率	False
--save-interval	-s	每隔多少次迭代保存一次模型	250（10–1000）
--snapshot-interval	-I	每隔多少次迭代做一次模型备份快照，0 关闭	25000
--timelapse-input-A/-B / --timelapse-output	-x / -y / -z	三个参数齐全时启用 timelapse：每次保存迭代时把选定人脸快照存入输出目录	None
--preview	-p	在独立窗口显示训练预览	False
--write-image	-w	把训练预览写入 FaceSwap 根目录的 training_preview.png	False
--warp-to-landmarks	-M	按对面数据集中匹配度最高的关键点做 warping（dfaker 式训练）	False
--no-flip	-P	关闭随机水平翻转增强（一般仅在 fit training 时开启）	False
--no-augment-color	-c	关闭颜色增强（默认开启，可降低 A/B 两侧色差敏感度）	False
--no-warp	-W	关闭 warping 增强。warping 是训练神经网络的关键，只应在训练末尾作为"精调"开启，从开头启用很可能毁掉模型	False

3.2 训练入口的校验逻辑

scripts/train.py 的 Train._get_images() 除了数量校验外，还会调用 _validate_faceswap_image() 读取第一张图的 PNG 元数据：只有 FaceSwap extract 过程生成的、带 alignments 元数据（PNG itxt 块）的人脸图才能用于训练，混入普通照片会直接报错退出。这解释了为什么训练数据目录必须来自 extract 输出。

训练主循环 _run_training_cycle() 中：save_iteration = iteration % save_interval == 0 or iteration == 1，即首次迭代与每隔 save-interval 次各保存一次；控制台按 S 键可立即触发一次保存（_check_keypress()），按回车保存并退出（_end_thread() 会提示退出保存可能耗时数分钟）。

3.3 训练阶段的通用技巧

• alignments 前置要求：如果使用 mask 训练或开启 Warp to Landmarks，需要为每个脸文件夹传入对应的 alignments.json 文件（见 lib/cli/args_train.py 中 --warp-to-landmarks 的帮助说明）。
• 自动备份与恢复：每次保存迭代时，若整体 loss 下降（即模型在进步），模型会自动备份；如果模型损坏，可进入模型文件夹把备份文件的 .bk 扩展名去掉来恢复。这一机制由 lib/model/backup_restore.py 实现（backup_model() 生成 原文件名.bk，restore_files() 从 .bk 恢复），备份触发条件在 plugins/train/model/_base/io.py 的 _should_backup() 中判定（本次保存的 average loss 低于历史值才备份）。
• 完整参数用 python faceswap.py train -h 查看；插件可配置选项位于 <faceswap_folder>/config/train.ini，需先运行过一次 Train 或 GUI 才会生成。

四、Convert：转换视频/图片

模型训练满意后就可以转换视频了。原理是：先为目标素材生成 alignments.json。做法与 Extract 一节完全相同——对源视频中的每一张脸都跑一遍 extract。该文件告诉 convert 流程每帧上人脸的位置。

通常需要清理 alignments 文件：删除误检、对齐很差的人脸等，否则最终转换效果会打折扣。仓库内专门提供了清理 alignments 的工具（见 tools/alignments/ 模块，支持对帧与人脸的批量重命名、移动、删除、绘制关键点等操作）。

和 extract 一样，convert 既支持图片序列也支持视频文件。回到示例：用最初那批 trump 图片做换脸，指定输入目录、新建输出目录，并告诉它用哪个模型：

命令行：

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

GUI： 在 GUI 的 Convert 页面填入输入、输出与模型目录即可。

执行后即开始替换所有这些图片中的脸。

4.1 convert 的完整参数（来自源码）

完整定义见 lib/cli/args_extract_convert.py 的 ConvertArgs 类（与 extract 共享 -i/-p 参数）：

参数	短选项	说明	默认值
--output-dir	-o	转换结果的保存目录	必填
--reference-video	-r	从图片转视频时才需要：提供源帧拆分自的原始视频（用于提取 fps 与音频）	无
--model-dir	-m	训练好的模型目录	必填
--color-adjustment	-c	换脸后的颜色调整：avg-color（均值对齐）、color-transfer（Lab 空间分布迁移）、manual-balance（多色彩空间手动调，配合 Preview 工具最佳）、match-hist（直方图匹配）、seamless-clone（OpenCV 无缝克隆，效果通常一般）、none	avg-color
--mask-type	-M	使用哪种掩码（该掩码必须已存在于 alignments 文件中，可用 Mask 工具追加）：extended、components、bisenet-fp_face/_head、custom_face/_head、vgg-clear、vgg-obstructed、unet-dfl、predicted（训练时开启 Learn Mask 后使用）	extended
--writer	-w	输出写入器：opencv（图片，最快）、pillow（图片，更多格式）、patch（输出裸脸 patch + 变换矩阵，供外部工具二次合成）、ffmpeg（直接写视频；图片输入时必须配合 -r）、gif（动图）	opencv
--output-scale	-O	输出帧缩放百分比，100 为源尺寸	100（25–400）
--frame-ranges	-R	只对指定帧范围做转换，如 --frame-ranges 10-50 90-100；范围外帧默认丢弃（-k 可保留）	无
--face-scale	-S	缩放换出的脸，正值放大、负值缩小	0.0（±10）
--input-aligned-dir	-a	未清理 alignments 文件时的兜底：指定一个已提取人脸的目录，只转换同时存在于 alignments 与该目录中的人脸	None
--nfilter / --filter / --ref_threshold	-n / -f / -l	按参考人脸图片过滤"不处理"/"只处理"的人，阈值默认 0.4（越小越严格）；注意会显著降低速度	None
--jobs	-j	并行进程数，0 为自动用满可用核数；图片转换吃内存，进程过多可能 OOM	0
--on-the-fly	-T	在线提取 alignments（不推荐：使用较弱的提取流水线，效果差；若已存在 alignments 文件则被忽略）	False
--keep-unchanged	-k	配合 --frame-ranges 输出未处理帧而非丢弃	False
--swap-model	-s	反向使用模型：把 A→B 变成 B→A	False
--singleprocess	-P	禁用多进程，更慢但更省资源	False

颜色调整与写入器均为插件化实现，可配置项位于 config/convert.ini（对应插件源码在 plugins/convert/color/ 与 plugins/convert/writer/）。

4.2 convert 阶段的通用技巧

• 完整参数用 python faceswap.py convert -h 查看，或在 GUI 中悬停选项查看；
• 插件可配置选项位于 <faceswap_folder>/config/convert.ini，需先运行过一次 Convert 或 GUI 才会生成。

五、GUI：图形界面

上述所有命令与选项都可以在 GUI 中执行，启动方式：

python faceswap.py gui

GUI 提供了比命令行更友好的界面，并带有一些扩展功能；将鼠标悬停在任一选项上即可查看该选项的详细说明（对应入口注册于 faceswap.py 的 GuiArgs，界面实现位于 lib/gui/）。

六、视频相关操作

**视频的本质只是一系列以帧形式存在的小图片。**因此你可以从视频中采集原始图片作为数据集，也可以把结果帧重新合成视频。

6.1 内置 EFFMPEG 工具

FaceSwap 内置了 effmpeg 工具，可完成各类视频处理（如拆分帧、合帧等），完整参数列表：

python tools.py effmpeg -h

工具实现位于 tools/effmpeg/。

6.2 用 FFMPEG 拆分视频帧

也可以用 ffmpeg 等外部工具把视频拆分为独立帧，示例命令：

ffmpeg -i /path/to/my/video.mp4 /path/to/output/video-frame-%d.png

6.3 重新合成视频

如果先用 ffmpeg 把视频拆帧、作为换脸目标处理，之后可以再把 png 帧拼接回一个视频。以下命令将 png 帧重新合成为单个视频：

ffmpeg -i video-frame-%0d.png -c:v libx264 -vf "fps=25,format=yuv420p" out.mp4

注意 convert 的 ffmpeg 写入器也可以直接输出视频（配合 --reference-video 提取 fps 与音频），见 plugins/convert/writer/ffmpeg.py。

七、补充说明与延伸阅读

USAGE.md 末尾说明：这份指南远非完备，功能会随时间变化，依赖也会随时间增删；遇到问题请到官方论坛或社区讨论，仓库中的使用类提问大概率会被直接关闭。

结合仓库源码，以下路径可作为继续深入学习的入口：

• 命令入口与子命令注册：faceswap.py；
• 三大流程的实现：scripts/extract.py、scripts/train.py、scripts/convert.py；
• 命令行参数定义：lib/cli/args_extract_convert.py、lib/cli/args_train.py；
• 提取插件（检测/对齐/掩码/身份）：plugins/extract/detect/、plugins/extract/align/、plugins/extract/mask/、plugins/extract/identity/；
• 训练模型与训练器：plugins/train/model/、plugins/train/trainer/；
• 模型保存与 .bk 备份恢复：plugins/train/model/_base/io.py、lib/model/backup_restore.py；
• 辅助工具（alignments 清理、effmpeg、模型管理、人工标注等）：tools/；
• 插件选项配置模板（首次运行后生成于 config/ 目录）：extract.ini、train.ini、convert.ini。

再次强调 USAGE.md 的核心提醒：训练前务必人工检查训练数据，500–5000 张高质量、角度/表情/光照多样的脸是获得可用模型的基本前提。