3 步在本地跑通视频换脸：FaceFusion 部署、调参与排障完整指南

3 步在本地跑通视频换脸：FaceFusion 部署、调参与排障完整指南

【免费下载链接】facefusionIndustry leading face manipulation platform项目地址: https://gitcode.com/GitHub_Trending/fa/facefusion

想把照片里的人"搬进"一段视频？FaceFusion 是一个完全本地运行的开源视频换脸平台：你只提供一张源脸照片和一段目标视频，它逐帧检测人脸、完成替换，再把结果编码成新视频返回。除了换脸，它还能顺手修复糊掉的人脸、调整面部年龄，甚至做口型同步。本文带你从零基础环境配置，一路走到调参排障。

它按什么顺序处理每一帧

在敲命令之前，先建立一个大致的心理模型，后面所有参数都能对号入座。FaceFusion 对视频的每一帧依次做三件事：

1. 定位：用人脸检测模型框出画面里的每张脸（facefusion/face_detector.py）
2. 加工：按你指定的顺序，把脸送进各个处理模块
3. 落盘：由 ffmpeg 把处理完的帧合成输出视频（facefusion/ffmpeg_builder.py）

第 2 步的"处理模块"就是玩法所在。每个模块都是 facefusion/processors/modules/ 下的一个独立文件夹，文件夹名就是模块 ID，常用几个：

当前版本为 3.8.0，见 facefusion/metadata.py。

部署前的环境自检

先说结论：Python 3.10 及以上 + 系统里装好 ffmpeg，两条满足就能装。NVIDIA 显卡有最好，没有也能用 CPU 跑，只是慢。

打开终端确认一下：

python --version ffmpeg -version

两行命令都能正常打印版本号，说明环境没问题。如果缺 ffmpeg，用系统包管理器（apt / brew / winget）装一个即可。

从零跑通第一次换脸：3 步部署

以下 3 步在仓库根目录执行，每步都有明确的成功标志。

第 1 步：拿到代码

git clone https://gitcode.com/GitHub_Trending/fa/facefusion cd facefusion

第 2 步：装依赖并下载全部模型

python -m pip install -r requirements.txt python install.py

install.py 会一次性把换脸、增强等模块所需的模型权重全部拉下来。成功标志：install.py跑完后没有任何中断报错。这里容易翻车——如果网络中断，模型缓存会不完整，后面运行时才暴露，所以这步一定要看到完整结束。

第 3 步：跑第一条换脸命令

python facefusion.py run \ --source-path 照片.jpg \ --target-path 视频.mp4 \ --output-path 输出.mp4

参数含义一句话版本：--source-path是你要"搬进"视频的源脸照片，--target-path是被替换脸的视频，--output-path是结果存放路径。

成功标志：终端打印出输出文件路径、输出.mp4真实生成，且打开后第一帧的人脸已经变成源脸。到这里，部署就算跑通了 ✅

组合玩法：一条 --processors 串起整条流水线

单个命令可以同时启用多个模块，用--processors逗号分隔即可，顺序就是执行顺序：

python facefusion.py run \ --processors face_swapper,face_enhancer,age_modifier \ --face-swapper-model inswapper_128 \ --face-enhancer-model gfpgan_1.4 \ --age-modifier-direction 30

这条命令的效果链：先换脸 → 再把换完的脸修清晰 → 最后往幼态方向偏移 30 个单位。

换脸模型怎么选。完整清单在 face_swapper 的 choices.py，规律很直白：

• inswapper_128：默认款，速度快、占用小，第一次跑通先用它
• blendswap_256、ghost_1_256、hyperswap_1a_256：更大的模型，面部细节更足，代价是显存和耗时都明显上升
• simswap_256、uniface_256等第三方权重也已内置，装好即可选

增强模型怎么选。可选gfpgan_1.2 / 1.3 / 1.4、codeformer、gpen_bfr_512、restoreformer_plus_plus等，face_enhancer 的类型定义里都有。gfpgan_1.4是"修得清、不容易过曝"的稳妥起点。

年龄偏移的边界。--age-modifier-direction正数偏年轻、负数偏年长。它是整脸平移，不重排五官，所以幅度超过 50 之后观感开始崩，建议从小值试起。

调参：4 个最值得动的旋钮

调之前先记住一件事：所有 ini 键都和命令行参数一一对应，全部键名见 facefusion.ini。下面是 4 个性价比最高的旋钮，附推荐值与副作用：

另外两个输出端参数常被误伤：output_video_preset提供 ultrafast 到 veryslow 共 9 档，交付成品用medium、快速预览用fast；face_enhancer_blend建议从 70 起步，低于 40 基本只去噪、高于 90 容易塑料感。

一段能直接落地的最小 ini 配置：

[execution] execution_providers = cuda [memory] video_memory_strategy = strict

CPU 机器把execution_providers改成cpu，线程数设到物理核心数附近即可，别盲目开满。

翻车现场对照表（排障问答）

问：一运行就提示模型文件缺失？大概率是install.py没跑完或中途断了，模型缓存不全。重跑一次python install.py，或者用python facefusion.py force-download强制补齐，再回来跑run。

问：换完的脸边缘像贴纸，或者整段视频脸在"飘"？贴纸感说明检测框太紧、羽化不足：face_detector_margin从 0 提到 20 给框留余量，同时face_mask_blur提到 0.3。脸在飘则是跟踪阈值太松导致中途锁定到别的脸，把face_tracker_score从 0.5 降到 0.3。

问：显存直接爆掉，长视频跑到一半卡死？这是"分辨率 × pixel_boost × tolerant 策略"三项乘积超了预算。先切回strict、pixel_boost退回256x256；处理长视频时，先用--target-frame-amount只跑部分帧验证流程，通了再全量执行。

问：输出视频比原片还糊？查输出端而不是处理端：output_video_quality保持 90 以上、output_video_scale用 1.0，然后再确认源视频本身的分辨率够不够。

想继续深入？三个入口

• 🧩写一个自定义处理器：照 face_swapper 模块 的四件套复制一份——core.py写逻辑、choices.py定义选项、locales.py放文案、types.py声明类型——就是一个新模块的完整骨架
• 🧪改完参数先跑测试：tests/ 目录下每个模块都有test_cli_*.py用例，改动后跑对应文件，回归问题当场就能暴露
• 📖查所有可配置项：facefusion.ini 是全量键名清单，遇到不认识的命令行参数，先来这里查对应的 ini 键

回顾一下这条动作链：自检 Python 与 ffmpeg → clone 仓库并跑install.py拉模型 → 一条run命令验证首帧换脸成功 → 用pixel_boost、face_mask_blur、video_memory_strategy三个旋钮在速度、画质、显存之间找平衡 → 出问题回到排障问答对号入座。走顺这条链之后，下一步值得尝试的，是换更大的换脸模型、把lip_syncer等模块拼进更长的流水线，或者按模块四件套动手写一个属于自己的处理器。

【免费下载链接】facefusionIndustry leading face manipulation platform项目地址: https://gitcode.com/GitHub_Trending/fa/facefusion