2026/9/2 18:17:47
FEATURED · 精选文章 
这次来看 FaceFusion 3.8.1。FaceFusion 是目前社区活跃度非常高的开源人脸替换工具。3.8.1 这一版的核心不是简单加几个模型而是把处理器架构和视频处理底层都重写了。简单说就是同一张显卡、同一个视频素材跑到 3.8.1 上更顺卡顿和崩溃明显减少。如果你需要把一张人脸替换到照片、视频里并且在意本地部署、批量运行、API 接入这篇可以直接收藏。本文会按核心能力、版本变化、环境准备、安装部署、功能测试、API 调用、性能观察、常见问题这条线完整过一遍。先说明边界人脸替换只能用于本人或已获充分授权的素材。伪造他人肖像、制作误导性视频不仅违反公序良俗还可能触犯法律。全文只讨论技术验证和合规使用。1. FaceFusion 3.8.1 核心能力速览能力项说明项目类型开源本地人脸替换 / 人脸处理工具3.8.1 主要变化处理器Processor架构重写视频处理底层重构核心功能图片换脸、视频换脸、面部增强、帧增强运行方式源码命令行、WebUI、API 服务、社区整合包推理加速支持 CUDANVIDIA、CPU、OpenVINO、CoreML 等具体以本机环境和版本为准是否可完全本地部署支持。推理过程本地完成模型文件需提前下载或首次自动下载是否支持 API3.x 提供 API 服务接口详情以项目 README 或 Swagger 文档为准是否支持批量任务可通过命令行循环、API 队列或 WebUI 多目标处理实现推荐硬件带 NVIDIA 独立显卡的 PC 或工作站显存 6GB 及以上更合适适合场景视频素材处理、人像研究、二次创作、内容审核前的内部测试需要注意显存占用、帧率、视频处理速度都取决于模型版本、分辨率、帧数、是否启用增强器。没有统一标准数字必须本机实测。2. 3.8.1 版本重写重点处理器架构与视频底层这一节是很多人最关心的。3.8.1 的更新标题提到“重写了处理器架构 视频底层”翻译成实际使用收益可以理解为三个方向。2.1 处理器架构重写FaceFusion 内部把整个人脸处理流程拆成多个处理器人脸检测、人脸识别、人脸对齐、人脸替换、人脸增强、帧增强。老版本里这些处理器之间的数据传递和调度存在不少冗余尤其在多帧视频上每帧都要做重复初始化。3.8.1 把处理器执行管道重写后从社区反馈和作者发布说明看主要收益是减少中间数据拷贝连续帧处理更省资源。处理器调度更清晰CPU 与 GPU 任务分配更合理。多线程并发时更稳定不容易出现进程假死。这不是“功能上新”而是“内部结构变干净了”。对用户来说体感就是同参数下等待时间缩短、长时间跑批不容易失败。2.2 视频底层重构视频换脸涉及一个完整链路视频解码、抽帧、逐帧处理、音频保留、重新编码、封装。老版本在部分视频上容易出现音画不同步、输出文件变大、遇到特殊编码格式直接报错。3.8.1 对视频底层做了重构重点应该在视频读取和帧写入逻辑优化减少内存峰值。对常见编码格式H.264、H.265、MP4、MOV、MKV 等的兼容性更好。音频流保留更稳定减少替换后音画不同步问题。输出封装环节更接近原视频参数。从实际使用角度重构后处理高分辨率视频、长视频时显存占用波动会比之前更平稳。具体数据需要你在自己的机器上跑一遍基准视频才能确定。2.3 更新能带来什么一句话版本不换显卡、不调参数同一个视频素材在 3.8.1 上更容易跑完整体执行更稳定。如果你的旧版本经常跑到一半“进程消失”或显存溢出3.8.1 值得优先升级。3. 适用场景与合规使用边界3.1 适合谁视频创作者需要把授权人脸素材替换到测试片段中。短视频批量生产团队需要接口化换脸处理批量跑素材。人像算法研究者观察检测、对齐、替换、增强每一步的效果。内容安全测试人员在内部数据集上验证换脸检测效果。3.2 不适合什么未经授权替换真实人物的脸尤其是公众人物。制作误导性、虚假性视频内容。绕过身份验证、伪造证件照片等违法用途。商用场景中无法确认素材版权来源的情况。3.3 使用边界必须守住人脸替换工具天然带有滥用风险。无论个人研究还是商用素材必须满足本人授权、明确授权协议、版权清晰的公开数据集或完全由你生成的虚拟人物素材。输出内容发布前要人工复核不能直接信任自动化生成结果。4. 本地部署环境准备4.1 操作系统FaceFusion 支持 Windows、Linux、macOS。日常使用最多的是 Windows 11 NVIDIA 显卡其次是 Ubuntu 服务器 CUDA 环境。macOS 可以走 CPU 或 CoreML但处理速度不如 NVIDIA 平台。4.2 硬件要求硬件项建议显卡NVIDIA GTX 10 系以上显存越大越好显存建议 6GB 以上低显存可以启用 tolerant 显存策略内存16GB 起步32GB 更稳磁盘模型文件约 1GB 左右另需预留视频输出空间CPU影响人脸检测和视频解码越新越好如果只有 CPU功能可以跑但视频处理速度会非常慢高分辨率视频基本不可用。4.3 软件依赖通用前置条件Python 3.10 或更高版本。Git。FFmpeg并确保在系统 PATH 中。NVIDIA 驱动 CUDA显卡驱动建议保持较新版本。Visual C 运行库Windows 下常见坑。# 检查基础环境 python --version git --version ffmpeg -version nvidia-smi如果nvidia-smi能正常输出驱动信息说明 NVIDIA 环境基本可用。Python 相关加速库还需要确认 PyTorch 版本与 CUDA 版本匹配。4.4 磁盘与端口规划项目源码建议放一个剩余空间充足的目录。WebUI 默认端口通常是7860API 服务通常用8000。如果端口被占启动前先查# Windows netstat -ano | findstr :7860 # Linux / macOS lsof -i :78605. 安装部署与启动方式5.1 源码方式安装git clone https://github.com/facefusion/facefusion cd facefusion python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt如果需要 GPU 加速部分版本需要额外安装加速依赖或匹配 CUDA 的 PyTorch# 根据实际 CUDA 版本选择 PyTorch 安装命令 pip install torch --index-url https://download.pytorch.org/whl/cu121这一步和你本机的 CUDA 版本强相关。安装前先看项目 README 中关于requirements-accel.txt或对应安装说明不要盲目执行。5.2 社区整合包方式如果你不想折腾 Python 环境可以用社区发布的 FaceFusion 整合包。整合包通常已经打包好 Python、依赖、模型文件和启动脚本解压后双击启动即可。选择整合包时注意确认来源可信优先选作者发布或社区高赞版本。查杀确认后运行不明整合包可能捆绑额外脚本。确认是否内置 3.8.1 的核心改动有些整合包版本滞后。确认是否包含完整模型文件否则首次运行还是要联网下载。5.3 启动 WebUIpython facefusion.py ui launch启动成功后浏览器访问http://127.0.0.1:7860。页面会加载人脸交换相关配置面板包括源人脸、目标图片或视频、执行参数等。通过命令行也可以指定 Host 和 Portpython facefusion.py ui launch --host 127.0.0.1 --port 78605.4 命令行无界面模式适合服务器或批量处理python facefusion.py headless-run \ -s /path/to/source.png \ -t /path/to/target.mp4 \ -o /path/to/output.mp4其中-s是源人脸图片-t是目标文件-o是输出文件。不同版本参数名可能有差异建议先执行python facefusion.py headless-run --help查看当前版本支持的参数。6. 功能测试与效果验证6.1 第一次验证图片换脸建议第一个测试用单张图片不要上来就处理视频。图片测试能最快验证安装、模型下载、执行链路是否正常。测试步骤准备一张清晰的正面源人脸图片。准备一张目标图片分辨率不要太高先控制在 512 或 1024 以内。通过 WebUI 上传两张图执行换脸。观察日志是否出现success或finished关键字。检查输出图片是否保留目标图片整体构图人脸区域替换为源人脸特征。预期结果输出是一张新的图片背景和光线保留目标图风格人脸区域来自源图。如果失败先看模型是否下载完成再看显存是否溢出。6.2 视频换脸图片测试通过后再上视频。建议先用短视频测试视频时长10 到 30 秒。分辨率720p 或 1080p。画面单一人物正脸较多避免多人快速切换。音频保留原音验证声音轨道是否保留。WebUI 操作时在目标位置选择视频文件其他参数可以先保持默认。执行过程中重点观察进度条是否稳定前进。是否有frame N或百分比输出。显存占用是否稳定。处理结束后输出视频能否正常播放。验证质量时要检查换脸后的人脸轮廓是否跟随表情变化有没有明显闪烁或边缘撕裂。3.8.1 重构了视频底层后这类问题一般会少于旧版本但复杂视频仍需要人工抽帧检查。6.3 多目标批量测试FaceFusion 3.x 支持把同一张源人脸应用到多张目标图片或视频。批量测试建议这样设计input/ video1.mp4 video2.mp4 photo1.jpg photo2.jpg output/命令行批量处理可以用循环for f in input/*.mp4; do python facefusion.py headless-run \ -s /path/to/source.png \ -t $f \ -o output/$(basename $f) done批量场景下建议每条视频单独输出日志方便定位失败原因python facefusion.py headless-run \ -s source.png \ -t input/video1.mp4 \ -o output/video1.mp4 \ --log-level debug 21 | tee batch_video1.log首次批量不要开全量素材先跑 3 到 5 个样本确认稳定后再放量。6.4 低显存模式与降级测试如果你的显卡显存不大可以在参数里寻找显存策略相关配置例如--video-memory-strategy tolerant。这类策略会减少显存分配用更多时间换稳定性。测试时按这个顺序降低压力降低目标视频分辨率。关闭人脸增强器和帧增强器。降低执行线程数。使用低显存策略。改用 CPU 推理观察最慢但最稳定的下限。如果 CPU 模式能跑通、GPU 模式崩溃基本可判断是显存不足或 GPU 相关依赖问题。7. 接口 API 调用示例FaceFusion 3.x 提供 API 服务可以把它接到自己的工具链或自动化脚本中。7.1 启动 API 服务python facefusion.py api launch默认情况下 API 服务会监听一个本地端口。启动后访问http://127.0.0.1:8000/docs如果能看到 Swagger 文档说明接口列表已经可用。不同小版本的默认端口和接口路径可能会有调整以/docs文档为准。如果端口冲突可以指定python facefusion.py api launch --host 127.0.0.1 --port 80107.2 使用 curl 测试接口接口字段名需要根据实际 Swagger 文档调整下面是一个常见的 POST 请求模板curl -X POST http://127.0.0.1:8000/api/v1/face-swap \ -H Accept: application/json \ -F source_file/path/to/source.png \ -F target_file/path/to/target.mp4 \ -F output_fileoutput.mp4如果接口不是这个路径可以打开/docs找到实际的POST方法名再替换。7.3 Python 调用模板import requests api_url http://127.0.0.1:8000/api/v1/face-swap files { source_file: open(source.png, rb), target_file: open(target.mp4, rb), } data { output_file: result.mp4, } response requests.post(api_url, filesfiles, datadata, timeout300) if response.status_code 200: print(处理完成) else: print(失败, response.status_code, response.text)注意接口超时要给足。视频处理不是秒级任务timeout至少 300 秒长视频要按需继续增加。7.4 API 批量任务设计API 方式对接批量任务时不建议一个视频一个请求无限并发。更稳妥的做法是固定并发数例如同时 2 到 3 个任务。每个任务记录提交时间、状态、输出路径。失败重试 1 到 2 次。重试前检查显存是否已经被其他任务占用。import time import requests task_queue [ {target: video1.mp4, output: out1.mp4}, {target: video2.mp4, output: out2.mp4}, {target: video3.mp4, output: out3.mp4}, ] for task in task_queue: with open(task[target], rb) as f: files {target_file: f, source_file: open(source.png, rb)} data {output_file: task[output]} response requests.post( http://127.0.0.1:8000/api/v1/face-swap, filesfiles, datadata, timeout600, ) print(task[target], response.status_code) time.sleep(2)8. 资源占用与性能观察方法8.1 观察显存处理视频时建议开两个终端一个跑 FaceFusion另一个实时看显存。# NVIDIA 显卡 nvidia-smi -l 1-l 1表示每秒刷新一次。重点看Memory-Usage和Volatile GPU-Util。如果显存使用率在长时间内接近 100%说明模型和视频帧对显存压力较大可以降低分辨率或关闭增强器。8.2 CPU 与 GPU 推理差异GPU 推理的前期准备时间可能和 CPU 接近因为模型加载、视频解码在 CPU 侧完成。真正拉开差距的是逐帧推理阶段。CPU 推理适合验证流程完整性。没有独立显卡的笔记本。单张图片、小分辨率测试。GPU 推理适合视频处理。批量任务。高清图和多帧连续处理。8.3 影响性能的关键参数参数影响目标视频分辨率分辨率越高单帧耗时越大显存占用越高帧处理器数量启用 face_enhancer 后每帧都会多一次增强推理执行线程数过高可能不稳定过低会变慢视频总帧数决定总处理时间而不是帧率问题输出编码设置高码率输出会拉长编码时间8.4 如何降低显存占用先跑图片再跑视频。只启用face_swapper不启用额外增强器。用--video-memory-strategy tolerant这类低显存策略。把目标视频临时降到 720p 或更低。分段处理长视频最后再用视频剪辑工具合并。8.5 进程残留与端口清理长时间跑批后可能遇到端口被进程占用。此时需要结束残留进程# Windows找到占用 7860 的 PID 后结束 netstat -ano | findstr :7860 taskkill /PID PID /F# Linux kill $(lsof -t -i:7860)9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后页面打不开端口被占用或服务未启动查看控制台日志检查端口换端口或重启服务模型文件缺失首次运行模型下载失败查看模型目录是否为空手动下载模型并放到模型目录CUDA 相关报错PyTorch 与 CUDA 版本不匹配运行python -c import torch; print(torch.cuda.is_available())重新安装匹配 CUDA 的 PyTorch显存不足视频分辨率过高或增强器开启查看nvidia-smi占用降低分辨率、关闭增强器、启用低显存策略视频输出音画不同步视频底层封装问题查看源视频编码信息转成标准 H.264 MP4 后再处理API 调用超时视频处理时间超过请求超时时间查看 API 日志增加 timeout或改异步任务批量任务中途卡住某个视频格式异常或显存被占满单独处理该视频并看日志剔除异常样本降低并发数安装依赖时 maven 3.8.1 报“无法访问 http 仓库”部分辅助组件或整合包拉取 Java 依赖时被 Maven 拒绝访问 HTTP 仓库查看报错中repository url更换 HTTPS 仓库地址或配置阿里云 Maven 镜像输出画质偏暗或模糊未启用增强器或源人脸过小调整源人脸素材适当启用增强器但注意显存占用9.1 关于 Maven HTTP 仓库报错的说明有同学反馈过“无法访问 maven 3.8.1 http 仓库”这个问题。这里说明一下FaceFusion 核心推理链路是 Python本身不依赖 Java 的 Maven。这个报错通常出现在整合包附加组件、第三方辅助工具或某个构建脚本尝试拉取 Java 依赖时。Maven 3.8.1 默认禁止通过 HTTP 访问中央仓库只允许 HTTPS。如果你真的需要在构建中走 HTTP可以配置镜像或调整 Maven settings.xml但更推荐换 HTTPS 源mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror9.2 确认是否完全本地部署FaceFusion 可以做到完全本地部署模型文件下载好后后续推理过程不需要联网所有素材和模型都在本机处理。需要联网的环节主要是首次下载依赖和模型文件。如果你处于离线环境可以在有网的机器上下载模型然后手动复制到 FaceFusion 的模型目录。具体目录路径以项目 README 或启动日志为准常见位置是用户主目录下的.facefusion/models。9.3 社区在线镜像版社区里有人提供“FaceFusion 社区在线镜像版”这类镜像通常是提前把依赖和模型打包好界面还是本地启动。使用时要确认镜像来源可信注意不要运行来源不明的可执行文件。最安全的方式还是官方源码 自己准备模型。10. 最佳实践与使用建议10.1 先小后大第一次接触 3.8.1建议按这个顺序跑单张图片换脸。10 秒短视频换脸。30 秒以上视频。批量 5 个文件。完整生产任务。每一步都稳定通过后再放大规模避免一上来就把资源耗尽。10.2 保留一套最小可运行配置把你验证过的稳定参数记录下来形成固定命令或脚本模板。需要排查问题时先用最小参数跑通再逐步增加功能。python facefusion.py headless-run \ -s /path/to/source.png \ -t /path/to/target.mp4 \ -o /path/to/output.mp410.3 目录分管理project/ models/ # 模型文件 input/ # 源素材 output/ # 输出结果 logs/ # 每次运行的日志 temp/ # 中间文件日志命名建议带时间戳facefusion_run_$(date %Y%m%d_%H%M%S).log10.4 批量任务加日志和重试批量任务不要只打印到终端。每条任务写一行结果包含状态、耗时、输出路径。失败任务单独收集跑完后统一排查。10.5 接口服务限制访问范围API 服务启动后默认只监听本机或指定地址。如果部署在服务器不要直接暴露公网。用防火墙限制来源 IP或只允许内网访问并增加鉴权。10.6 合规红线涉及人脸、声音、视频素材时必须确认源人脸是否本人。目标素材是否有版权或授权。输出内容是否会被误解为真实记录。是否用于商业发布。凡是无法确认授权的素材一律不要输入到工具里。10.7 发布前复核自动化批量生成的视频不能直接发布。要抽帧检查确认没有明显瑕疵、不涉及他人肖像、内容符合平台规则。人脸替换类内容在部分平台会被标记或限制传播提前了解平台规范。11. 总结与下一步FaceFusion 3.8.1 这一版值得关注的点在于它没有堆砌新功能而是把处理器架构和视频底层重写了。对普通用户来说最直接的体感就是视频处理更稳定批量任务更容易跑完。如果你之前用的版本出现过跑一半崩溃、音画不同步、显存波动异常可以先升级到 3.8.1 再判断机器够不够用。建议第一次验证就做三件事单图换脸确认链路、短视频换脸确认视频底、同一视频对比新旧版本跑通率。这三个验证通过基本可以判断 3.8.1 在你的硬件上表现如何。最容易踩的坑无非三个CUDA 和 PyTorch 版本不匹配、显存拉满导致进程被杀、模型没下载完整。按本文第 9 节的排查表走基本都能定位。后续可以继续扩展的方向把 FaceFusion API 接到自己的素材处理流里做批量封装或者和视频剪辑工具配合做半自动内容生产。只要素材授权清晰、输出经过人工复核这是一个高效率的人像处理工具。建议先收藏这篇部署笔记下次拿到新显卡或新版本按流程再验证一遍。
人脸替换工具FaceFusion 3.8.1：重构底层架构，视频处理更稳定
这次来看 FaceFusion 3.8.1。FaceFusion 是目前社区活跃度非常高的开源人脸替换工具。3.8.1 这一版的核心不是简单加几个模型而是把处理器架构和视频处理底层都重写了。简单说就是同一张显卡、同一个视频素材跑到 3.8.1 上更顺卡顿和崩溃明显减少。如果你需要把一张人脸替换到照片、视频里并且在意本地部署、批量运行、API 接入这篇可以直接收藏。本文会按核心能力、版本变化、环境准备、安装部署、功能测试、API 调用、性能观察、常见问题这条线完整过一遍。先说明边界人脸替换只能用于本人或已获充分授权的素材。伪造他人肖像、制作误导性视频不仅违反公序良俗还可能触犯法律。全文只讨论技术验证和合规使用。1. FaceFusion 3.8.1 核心能力速览能力项说明项目类型开源本地人脸替换 / 人脸处理工具3.8.1 主要变化处理器Processor架构重写视频处理底层重构核心功能图片换脸、视频换脸、面部增强、帧增强运行方式源码命令行、WebUI、API 服务、社区整合包推理加速支持 CUDANVIDIA、CPU、OpenVINO、CoreML 等具体以本机环境和版本为准是否可完全本地部署支持。推理过程本地完成模型文件需提前下载或首次自动下载是否支持 API3.x 提供 API 服务接口详情以项目 README 或 Swagger 文档为准是否支持批量任务可通过命令行循环、API 队列或 WebUI 多目标处理实现推荐硬件带 NVIDIA 独立显卡的 PC 或工作站显存 6GB 及以上更合适适合场景视频素材处理、人像研究、二次创作、内容审核前的内部测试需要注意显存占用、帧率、视频处理速度都取决于模型版本、分辨率、帧数、是否启用增强器。没有统一标准数字必须本机实测。2. 3.8.1 版本重写重点处理器架构与视频底层这一节是很多人最关心的。3.8.1 的更新标题提到“重写了处理器架构 视频底层”翻译成实际使用收益可以理解为三个方向。2.1 处理器架构重写FaceFusion 内部把整个人脸处理流程拆成多个处理器人脸检测、人脸识别、人脸对齐、人脸替换、人脸增强、帧增强。老版本里这些处理器之间的数据传递和调度存在不少冗余尤其在多帧视频上每帧都要做重复初始化。3.8.1 把处理器执行管道重写后从社区反馈和作者发布说明看主要收益是减少中间数据拷贝连续帧处理更省资源。处理器调度更清晰CPU 与 GPU 任务分配更合理。多线程并发时更稳定不容易出现进程假死。这不是“功能上新”而是“内部结构变干净了”。对用户来说体感就是同参数下等待时间缩短、长时间跑批不容易失败。2.2 视频底层重构视频换脸涉及一个完整链路视频解码、抽帧、逐帧处理、音频保留、重新编码、封装。老版本在部分视频上容易出现音画不同步、输出文件变大、遇到特殊编码格式直接报错。3.8.1 对视频底层做了重构重点应该在视频读取和帧写入逻辑优化减少内存峰值。对常见编码格式H.264、H.265、MP4、MOV、MKV 等的兼容性更好。音频流保留更稳定减少替换后音画不同步问题。输出封装环节更接近原视频参数。从实际使用角度重构后处理高分辨率视频、长视频时显存占用波动会比之前更平稳。具体数据需要你在自己的机器上跑一遍基准视频才能确定。2.3 更新能带来什么一句话版本不换显卡、不调参数同一个视频素材在 3.8.1 上更容易跑完整体执行更稳定。如果你的旧版本经常跑到一半“进程消失”或显存溢出3.8.1 值得优先升级。3. 适用场景与合规使用边界3.1 适合谁视频创作者需要把授权人脸素材替换到测试片段中。短视频批量生产团队需要接口化换脸处理批量跑素材。人像算法研究者观察检测、对齐、替换、增强每一步的效果。内容安全测试人员在内部数据集上验证换脸检测效果。3.2 不适合什么未经授权替换真实人物的脸尤其是公众人物。制作误导性、虚假性视频内容。绕过身份验证、伪造证件照片等违法用途。商用场景中无法确认素材版权来源的情况。3.3 使用边界必须守住人脸替换工具天然带有滥用风险。无论个人研究还是商用素材必须满足本人授权、明确授权协议、版权清晰的公开数据集或完全由你生成的虚拟人物素材。输出内容发布前要人工复核不能直接信任自动化生成结果。4. 本地部署环境准备4.1 操作系统FaceFusion 支持 Windows、Linux、macOS。日常使用最多的是 Windows 11 NVIDIA 显卡其次是 Ubuntu 服务器 CUDA 环境。macOS 可以走 CPU 或 CoreML但处理速度不如 NVIDIA 平台。4.2 硬件要求硬件项建议显卡NVIDIA GTX 10 系以上显存越大越好显存建议 6GB 以上低显存可以启用 tolerant 显存策略内存16GB 起步32GB 更稳磁盘模型文件约 1GB 左右另需预留视频输出空间CPU影响人脸检测和视频解码越新越好如果只有 CPU功能可以跑但视频处理速度会非常慢高分辨率视频基本不可用。4.3 软件依赖通用前置条件Python 3.10 或更高版本。Git。FFmpeg并确保在系统 PATH 中。NVIDIA 驱动 CUDA显卡驱动建议保持较新版本。Visual C 运行库Windows 下常见坑。# 检查基础环境 python --version git --version ffmpeg -version nvidia-smi如果nvidia-smi能正常输出驱动信息说明 NVIDIA 环境基本可用。Python 相关加速库还需要确认 PyTorch 版本与 CUDA 版本匹配。4.4 磁盘与端口规划项目源码建议放一个剩余空间充足的目录。WebUI 默认端口通常是7860API 服务通常用8000。如果端口被占启动前先查# Windows netstat -ano | findstr :7860 # Linux / macOS lsof -i :78605. 安装部署与启动方式5.1 源码方式安装git clone https://github.com/facefusion/facefusion cd facefusion python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt如果需要 GPU 加速部分版本需要额外安装加速依赖或匹配 CUDA 的 PyTorch# 根据实际 CUDA 版本选择 PyTorch 安装命令 pip install torch --index-url https://download.pytorch.org/whl/cu121这一步和你本机的 CUDA 版本强相关。安装前先看项目 README 中关于requirements-accel.txt或对应安装说明不要盲目执行。5.2 社区整合包方式如果你不想折腾 Python 环境可以用社区发布的 FaceFusion 整合包。整合包通常已经打包好 Python、依赖、模型文件和启动脚本解压后双击启动即可。选择整合包时注意确认来源可信优先选作者发布或社区高赞版本。查杀确认后运行不明整合包可能捆绑额外脚本。确认是否内置 3.8.1 的核心改动有些整合包版本滞后。确认是否包含完整模型文件否则首次运行还是要联网下载。5.3 启动 WebUIpython facefusion.py ui launch启动成功后浏览器访问http://127.0.0.1:7860。页面会加载人脸交换相关配置面板包括源人脸、目标图片或视频、执行参数等。通过命令行也可以指定 Host 和 Portpython facefusion.py ui launch --host 127.0.0.1 --port 78605.4 命令行无界面模式适合服务器或批量处理python facefusion.py headless-run \ -s /path/to/source.png \ -t /path/to/target.mp4 \ -o /path/to/output.mp4其中-s是源人脸图片-t是目标文件-o是输出文件。不同版本参数名可能有差异建议先执行python facefusion.py headless-run --help查看当前版本支持的参数。6. 功能测试与效果验证6.1 第一次验证图片换脸建议第一个测试用单张图片不要上来就处理视频。图片测试能最快验证安装、模型下载、执行链路是否正常。测试步骤准备一张清晰的正面源人脸图片。准备一张目标图片分辨率不要太高先控制在 512 或 1024 以内。通过 WebUI 上传两张图执行换脸。观察日志是否出现success或finished关键字。检查输出图片是否保留目标图片整体构图人脸区域替换为源人脸特征。预期结果输出是一张新的图片背景和光线保留目标图风格人脸区域来自源图。如果失败先看模型是否下载完成再看显存是否溢出。6.2 视频换脸图片测试通过后再上视频。建议先用短视频测试视频时长10 到 30 秒。分辨率720p 或 1080p。画面单一人物正脸较多避免多人快速切换。音频保留原音验证声音轨道是否保留。WebUI 操作时在目标位置选择视频文件其他参数可以先保持默认。执行过程中重点观察进度条是否稳定前进。是否有frame N或百分比输出。显存占用是否稳定。处理结束后输出视频能否正常播放。验证质量时要检查换脸后的人脸轮廓是否跟随表情变化有没有明显闪烁或边缘撕裂。3.8.1 重构了视频底层后这类问题一般会少于旧版本但复杂视频仍需要人工抽帧检查。6.3 多目标批量测试FaceFusion 3.x 支持把同一张源人脸应用到多张目标图片或视频。批量测试建议这样设计input/ video1.mp4 video2.mp4 photo1.jpg photo2.jpg output/命令行批量处理可以用循环for f in input/*.mp4; do python facefusion.py headless-run \ -s /path/to/source.png \ -t $f \ -o output/$(basename $f) done批量场景下建议每条视频单独输出日志方便定位失败原因python facefusion.py headless-run \ -s source.png \ -t input/video1.mp4 \ -o output/video1.mp4 \ --log-level debug 21 | tee batch_video1.log首次批量不要开全量素材先跑 3 到 5 个样本确认稳定后再放量。6.4 低显存模式与降级测试如果你的显卡显存不大可以在参数里寻找显存策略相关配置例如--video-memory-strategy tolerant。这类策略会减少显存分配用更多时间换稳定性。测试时按这个顺序降低压力降低目标视频分辨率。关闭人脸增强器和帧增强器。降低执行线程数。使用低显存策略。改用 CPU 推理观察最慢但最稳定的下限。如果 CPU 模式能跑通、GPU 模式崩溃基本可判断是显存不足或 GPU 相关依赖问题。7. 接口 API 调用示例FaceFusion 3.x 提供 API 服务可以把它接到自己的工具链或自动化脚本中。7.1 启动 API 服务python facefusion.py api launch默认情况下 API 服务会监听一个本地端口。启动后访问http://127.0.0.1:8000/docs如果能看到 Swagger 文档说明接口列表已经可用。不同小版本的默认端口和接口路径可能会有调整以/docs文档为准。如果端口冲突可以指定python facefusion.py api launch --host 127.0.0.1 --port 80107.2 使用 curl 测试接口接口字段名需要根据实际 Swagger 文档调整下面是一个常见的 POST 请求模板curl -X POST http://127.0.0.1:8000/api/v1/face-swap \ -H Accept: application/json \ -F source_file/path/to/source.png \ -F target_file/path/to/target.mp4 \ -F output_fileoutput.mp4如果接口不是这个路径可以打开/docs找到实际的POST方法名再替换。7.3 Python 调用模板import requests api_url http://127.0.0.1:8000/api/v1/face-swap files { source_file: open(source.png, rb), target_file: open(target.mp4, rb), } data { output_file: result.mp4, } response requests.post(api_url, filesfiles, datadata, timeout300) if response.status_code 200: print(处理完成) else: print(失败, response.status_code, response.text)注意接口超时要给足。视频处理不是秒级任务timeout至少 300 秒长视频要按需继续增加。7.4 API 批量任务设计API 方式对接批量任务时不建议一个视频一个请求无限并发。更稳妥的做法是固定并发数例如同时 2 到 3 个任务。每个任务记录提交时间、状态、输出路径。失败重试 1 到 2 次。重试前检查显存是否已经被其他任务占用。import time import requests task_queue [ {target: video1.mp4, output: out1.mp4}, {target: video2.mp4, output: out2.mp4}, {target: video3.mp4, output: out3.mp4}, ] for task in task_queue: with open(task[target], rb) as f: files {target_file: f, source_file: open(source.png, rb)} data {output_file: task[output]} response requests.post( http://127.0.0.1:8000/api/v1/face-swap, filesfiles, datadata, timeout600, ) print(task[target], response.status_code) time.sleep(2)8. 资源占用与性能观察方法8.1 观察显存处理视频时建议开两个终端一个跑 FaceFusion另一个实时看显存。# NVIDIA 显卡 nvidia-smi -l 1-l 1表示每秒刷新一次。重点看Memory-Usage和Volatile GPU-Util。如果显存使用率在长时间内接近 100%说明模型和视频帧对显存压力较大可以降低分辨率或关闭增强器。8.2 CPU 与 GPU 推理差异GPU 推理的前期准备时间可能和 CPU 接近因为模型加载、视频解码在 CPU 侧完成。真正拉开差距的是逐帧推理阶段。CPU 推理适合验证流程完整性。没有独立显卡的笔记本。单张图片、小分辨率测试。GPU 推理适合视频处理。批量任务。高清图和多帧连续处理。8.3 影响性能的关键参数参数影响目标视频分辨率分辨率越高单帧耗时越大显存占用越高帧处理器数量启用 face_enhancer 后每帧都会多一次增强推理执行线程数过高可能不稳定过低会变慢视频总帧数决定总处理时间而不是帧率问题输出编码设置高码率输出会拉长编码时间8.4 如何降低显存占用先跑图片再跑视频。只启用face_swapper不启用额外增强器。用--video-memory-strategy tolerant这类低显存策略。把目标视频临时降到 720p 或更低。分段处理长视频最后再用视频剪辑工具合并。8.5 进程残留与端口清理长时间跑批后可能遇到端口被进程占用。此时需要结束残留进程# Windows找到占用 7860 的 PID 后结束 netstat -ano | findstr :7860 taskkill /PID PID /F# Linux kill $(lsof -t -i:7860)9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后页面打不开端口被占用或服务未启动查看控制台日志检查端口换端口或重启服务模型文件缺失首次运行模型下载失败查看模型目录是否为空手动下载模型并放到模型目录CUDA 相关报错PyTorch 与 CUDA 版本不匹配运行python -c import torch; print(torch.cuda.is_available())重新安装匹配 CUDA 的 PyTorch显存不足视频分辨率过高或增强器开启查看nvidia-smi占用降低分辨率、关闭增强器、启用低显存策略视频输出音画不同步视频底层封装问题查看源视频编码信息转成标准 H.264 MP4 后再处理API 调用超时视频处理时间超过请求超时时间查看 API 日志增加 timeout或改异步任务批量任务中途卡住某个视频格式异常或显存被占满单独处理该视频并看日志剔除异常样本降低并发数安装依赖时 maven 3.8.1 报“无法访问 http 仓库”部分辅助组件或整合包拉取 Java 依赖时被 Maven 拒绝访问 HTTP 仓库查看报错中repository url更换 HTTPS 仓库地址或配置阿里云 Maven 镜像输出画质偏暗或模糊未启用增强器或源人脸过小调整源人脸素材适当启用增强器但注意显存占用9.1 关于 Maven HTTP 仓库报错的说明有同学反馈过“无法访问 maven 3.8.1 http 仓库”这个问题。这里说明一下FaceFusion 核心推理链路是 Python本身不依赖 Java 的 Maven。这个报错通常出现在整合包附加组件、第三方辅助工具或某个构建脚本尝试拉取 Java 依赖时。Maven 3.8.1 默认禁止通过 HTTP 访问中央仓库只允许 HTTPS。如果你真的需要在构建中走 HTTP可以配置镜像或调整 Maven settings.xml但更推荐换 HTTPS 源mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror9.2 确认是否完全本地部署FaceFusion 可以做到完全本地部署模型文件下载好后后续推理过程不需要联网所有素材和模型都在本机处理。需要联网的环节主要是首次下载依赖和模型文件。如果你处于离线环境可以在有网的机器上下载模型然后手动复制到 FaceFusion 的模型目录。具体目录路径以项目 README 或启动日志为准常见位置是用户主目录下的.facefusion/models。9.3 社区在线镜像版社区里有人提供“FaceFusion 社区在线镜像版”这类镜像通常是提前把依赖和模型打包好界面还是本地启动。使用时要确认镜像来源可信注意不要运行来源不明的可执行文件。最安全的方式还是官方源码 自己准备模型。10. 最佳实践与使用建议10.1 先小后大第一次接触 3.8.1建议按这个顺序跑单张图片换脸。10 秒短视频换脸。30 秒以上视频。批量 5 个文件。完整生产任务。每一步都稳定通过后再放大规模避免一上来就把资源耗尽。10.2 保留一套最小可运行配置把你验证过的稳定参数记录下来形成固定命令或脚本模板。需要排查问题时先用最小参数跑通再逐步增加功能。python facefusion.py headless-run \ -s /path/to/source.png \ -t /path/to/target.mp4 \ -o /path/to/output.mp410.3 目录分管理project/ models/ # 模型文件 input/ # 源素材 output/ # 输出结果 logs/ # 每次运行的日志 temp/ # 中间文件日志命名建议带时间戳facefusion_run_$(date %Y%m%d_%H%M%S).log10.4 批量任务加日志和重试批量任务不要只打印到终端。每条任务写一行结果包含状态、耗时、输出路径。失败任务单独收集跑完后统一排查。10.5 接口服务限制访问范围API 服务启动后默认只监听本机或指定地址。如果部署在服务器不要直接暴露公网。用防火墙限制来源 IP或只允许内网访问并增加鉴权。10.6 合规红线涉及人脸、声音、视频素材时必须确认源人脸是否本人。目标素材是否有版权或授权。输出内容是否会被误解为真实记录。是否用于商业发布。凡是无法确认授权的素材一律不要输入到工具里。10.7 发布前复核自动化批量生成的视频不能直接发布。要抽帧检查确认没有明显瑕疵、不涉及他人肖像、内容符合平台规则。人脸替换类内容在部分平台会被标记或限制传播提前了解平台规范。11. 总结与下一步FaceFusion 3.8.1 这一版值得关注的点在于它没有堆砌新功能而是把处理器架构和视频底层重写了。对普通用户来说最直接的体感就是视频处理更稳定批量任务更容易跑完。如果你之前用的版本出现过跑一半崩溃、音画不同步、显存波动异常可以先升级到 3.8.1 再判断机器够不够用。建议第一次验证就做三件事单图换脸确认链路、短视频换脸确认视频底、同一视频对比新旧版本跑通率。这三个验证通过基本可以判断 3.8.1 在你的硬件上表现如何。最容易踩的坑无非三个CUDA 和 PyTorch 版本不匹配、显存拉满导致进程被杀、模型没下载完整。按本文第 9 节的排查表走基本都能定位。后续可以继续扩展的方向把 FaceFusion API 接到自己的素材处理流里做批量封装或者和视频剪辑工具配合做半自动内容生产。只要素材授权清晰、输出经过人工复核这是一个高效率的人像处理工具。建议先收藏这篇部署笔记下次拿到新显卡或新版本按流程再验证一遍。 
