1. 为什么我选择把FaceFusion搬到本地来跑第一次接触FaceFusion是在一个做短视频的朋友那里他当时用在线版处理一段两分钟的人脸替换素材排队等了四十多分钟导出还带了水印。我当时就琢磨这东西能不能放到自己机器上跑。后来花了一个周末把本地环境搭起来实测下来一段两分钟的视频在本地RTX 3060上跑完只要三分钟左右而且没有任何次数限制素材也不用来回上传下载。这就是我写这份部署指南的直接动机。FaceFusion本质上是一个基于深度学习的人脸替换与增强工具它把人脸检测、特征提取、人脸交换、后期融合这几个环节串成了一条完整的处理流水线。它解决的核心问题是让普通用户在不依赖云端服务的前提下用自己的显卡完成高质量的人脸替换。适合谁来参考这份指南我认为有三类人一是做短视频、影视二创的内容创作者需要批量处理素材二是对AI视觉方向感兴趣、想动手跑通一个完整项目的开发者三是单纯想折腾本地AI环境、积累部署经验的技术爱好者。不管你之前有没有接触过Python和Docker只要跟着步骤走都能把环境搭起来。需要提前说明的是本地部署FaceFusion对硬件有一定门槛尤其是显卡。如果你用的是纯CPU模式速度会慢到让人怀疑人生所以下面我会重点讲GPU环境的配置。另外这份指南里涉及的所有操作都是基于我自己的实际部署经验整理的参数和版本会随时间变化遇到不一致的地方以官方仓库的最新说明为准。2. 部署前的整体思路与环境选型2.1 为什么优先推荐Docker而不是裸装Python很多人一上来就想直接pip install我一开始也是这么干的结果在依赖冲突上卡了整整一个下午。FaceFusion依赖的库比较多onnxruntime、insightface、opencv这些对版本都很敏感裸装很容易出现某个包版本不匹配导致整个流程跑不起来的情况。Docker的好处在于它把运行环境连同依赖一起打包好了你拉下来的镜像里该有的都有不用自己去逐个解决版本问题。当然Docker也不是没有代价。它需要你先装好Docker DesktopWindows或者Docker EngineLinux还要配置好GPU直通这一步对新手来说反而是最容易出问题的地方。我的建议是如果你只是想快速跑起来看效果走Docker路线如果你想深入改代码、加自定义模型那裸装Python环境更灵活。下面两条路线我都会讲你可以根据自己的需求选。2.2 硬件与驱动的前置检查清单在动手之前先花五分钟确认一下自己的机器能不能跑。这一步很多人会跳过结果装到一半才发现显卡不支持白折腾。检查项最低要求推荐配置检查方法操作系统Windows 10 64位 / Ubuntu 20.04Windows 11 / Ubuntu 22.04系统设置里查看显卡NVIDIA GTX 1060 6GRTX 3060 12G及以上任务管理器或nvidia-smi显卡驱动支持CUDA 11.8以上最新版驱动nvidia-smi查看内存16GB32GB系统信息硬盘空间20GB可用50GB以上磁盘管理Python裸装路线3.103.10或3.11python --version这里要特别提醒一点FaceFusion目前对Python 3.12的支持还不完善我实测3.12下有几个依赖装不上所以裸装路线强烈建议用3.10。另外显卡显存低于6G的话处理高分辨率视频会爆显存只能降分辨率或者用CPU模式硬扛。2.3 CUDA、cuDNN与显卡驱动的三角关系这三个东西的关系经常把人绕晕我用一个生活化的类比来解释。显卡驱动是地基它让操作系统能认识你的显卡CUDA是盖在地基上的楼层它提供了一套让程序调用显卡算力的接口cuDNN则是楼层里的专业设备专门加速深度学习相关的运算。三者版本必须匹配否则就会出现“地基打好了但楼层盖不上”的情况。具体到版本对应关系我整理了一个常用组合表显卡驱动版本支持的CUDA版本推荐cuDNN适用场景525.x以上CUDA 11.8cuDNN 8.6稳定首选535.x以上CUDA 12.1cuDNN 8.9新卡推荐550.x以上CUDA 12.4cuDNN 9.x最新特性如果你走Docker路线其实不需要在宿主机上单独装CUDA和cuDNN只需要装好显卡驱动然后在Docker里配置nvidia-container-toolkit就行。这一点是Docker路线最大的省心之处也是我推荐新手优先选它的原因。3. Docker路线从零到跑通第一条视频3.1 Docker Desktop的安装与GPU直通配置Windows用户直接去Docker官网下载Docker Desktop安装包双击一路下一步就行。安装完成后打开Docker Desktop进入Settings找到General确认“Use WSL 2 based engine”是勾选状态。这一步很关键因为只有WSL 2后端才支持GPU直通。接下来是GPU配置。在Settings里找到Resources再找到WSL Integration确认你的WSL发行版已经启用。然后在宿主机上装好NVIDIA显卡驱动注意WSL里不需要单独装驱动装宿主机的就行。装完后在PowerShell里执行nvidia-smi如果能看到显卡信息表格说明驱动没问题。接着在WSL终端里再执行一次同样的命令如果也能看到说明GPU直通已经打通。这一步我踩过坑有一次WSL里死活看不到显卡最后发现是WSL内核版本太旧执行wsl --update更新后就好了。Linux用户相对简单装好Docker Engine后安装nvidia-container-toolkitsudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker然后用docker run --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi测试一下能输出显卡信息就说明配置成功。3.2 拉取镜像与目录挂载的实操细节FaceFusion官方提供了Docker镜像直接拉取即可docker pull facefusion/facefusion:latest拉取完成后不要急着run先规划好目录结构。我习惯在宿主机上建三个文件夹input放待处理的源视频和源人脸图片output放处理结果models放模型文件。这样做的目的是把数据持久化到宿主机容器删了数据还在。启动命令我一般这么写docker run --gpus all -it --rm \ -v /home/user/facefusion/input:/app/input \ -v /home/user/facefusion/output:/app/output \ -v /home/user/facefusion/models:/app/models \ facefusion/facefusion:latestWindows下路径写法不同比如-v D:\facefusion\input:/app/input。这里有个细节Windows路径里的反斜杠在Docker命令里要写成正斜杠或者用双反斜杠转义否则会报路径错误。我第一次就因为这个卡了十分钟。3.3 第一次运行FaceFusion的完整命令拆解进入容器后FaceFusion的命令行工具就可以用了。一个最基础的换脸命令长这样python facefusion.py run \ --source-path /app/input/source.jpg \ --target-path /app/input/target.mp4 \ --output-path /app/output/result.mp4 \ --processors face_swapper face_enhancer \ --execution-providers cuda逐个参数解释一下。--source-path是提供人脸的那张图--target-path是被替换的视频--output-path是输出路径。--processors指定要启用的处理模块face_swapper负责换脸face_enhancer负责画质增强后者可选但强烈建议加上不然换完的脸会有点糊。--execution-providers cuda指定用GPU加速如果写成cpu就是纯CPU模式速度差十倍以上。跑起来之后终端会显示进度条处理完成后去output目录找结果就行。我第一次跑的时候用了张侧脸照片当源图结果换出来效果很差后来换成正面清晰照就好了。所以源图的选择很关键后面我会专门讲。4. 裸装Python路线更灵活但更折腾4.1 Python环境与虚拟环境的正确姿势如果你决定走裸装路线第一步是装Python 3.10。去官网下载安装包安装时务必勾选“Add Python to PATH”否则后面命令行里调不到python命令。装完后验证python --version pip --version接下来强烈建议用conda或者venv建一个独立虚拟环境不要直接在系统Python里装依赖。我用conda比较多conda create -n facefusion python3.10 conda activate facefusion虚拟环境的好处是隔离万一装崩了直接删掉重建不影响系统里其他项目。这一点在我反复测试不同版本依赖的时候帮了大忙。4.2 CUDA与cuDNN的手动安装流程裸装路线需要在系统里装CUDA Toolkit和cuDNN。去NVIDIA官网下载CUDA 11.8的安装包Windows下是个exeLinux下是个run文件。安装时选择“自定义”把Visual Studio Integration之类的用不上的组件取消勾选只保留CUDA核心组件。cuDNN需要注册NVIDIA开发者账号才能下载下载下来是个压缩包解压后把里面的bin、include、lib文件夹里的内容分别复制到CUDA安装目录对应的文件夹里。这一步在Windows下就是手动复制粘贴Linux下用cp命令。装完后验证nvcc --version能输出版本号就说明CUDA装好了。这里有个常见坑如果你之前装过其他版本的CUDA环境变量PATH里可能指向了旧版本需要手动调整顺序把新版本的路径放到前面。4.3 依赖安装与onnxruntime-gpu的版本匹配克隆FaceFusion仓库后安装依赖git clone https://github.com/facefusion/facefusion.git cd facefusion pip install -r requirements.txt这里最容易出问题的是onnxruntime-gpu。requirements里默认装的可能是CPU版本你需要手动换成GPU版本pip uninstall onnxruntime pip install onnxruntime-gpu1.16.3版本号要和你的CUDA版本匹配CUDA 11.8对应onnxruntime-gpu 1.16.xCUDA 12.x对应1.17.x以上。装完后可以跑一段测试代码验证GPU是否可用import onnxruntime as ort print(ort.get_available_providers())如果输出里有CUDAExecutionProvider说明GPU加速已经就绪。如果只有CPUExecutionProvider那就是版本没匹配上需要重新检查。5. 模型文件与素材准备的实操经验5.1 模型下载与存放位置FaceFusion运行时会自动下载所需的模型文件但国内网络环境下自动下载经常失败。我的做法是手动下载好模型放到指定目录。模型默认存放在.assets/models目录下不同处理模块对应不同的模型文件比如face_swapper用的是inswapper_128face_enhancer用的是GFPGAN或CodeFormer。手动下载的话去FaceFusion的官方文档里找到模型下载链接下载后按目录结构放好。如果自动下载卡住可以在命令里加--download-providers参数指定下载源或者干脆用离线模式--skip-download跳过下载前提是你已经手动放好了模型。5.2 源图与目标视频的选择技巧源图的质量直接决定换脸效果。我总结了几条经验第一源图必须是正面清晰照侧脸、遮挡、模糊的都不行第二光照要均匀避免强烈的阴影第三分辨率不用太高512x512以上就够太高反而增加处理时间第四如果源图里有多张脸FaceFusion会默认选最大的一张你也可以用--source-face-index参数指定。目标视频方面分辨率建议控制在1080p以内4K视频处理起来非常慢。如果视频里人脸角度变化很大换脸效果会打折扣这是目前所有换脸工具的通病。另外视频帧率越高处理时间越长30fps是比較平衡的选择。5.3 输出参数与画质平衡的取舍输出参数里最影响画质的是--output-video-quality默认是80范围0到100。我实测下来85左右是画质和文件大小的平衡点再高文件会大很多但肉眼几乎看不出差别。还有一个--execution-thread-count参数控制线程数默认是4显卡好的话可以调到8能快一些。如果你追求极致画质可以启用face_enhancer并选择CodeFormer模型它比GFPGAN细节保留更好但速度慢一些。我一般处理重要素材时用CodeFormer批量处理时用GFPGAN。6. 常见报错与排查速查表6.1 环境类报错报错信息原因解决方法CUDA out of memory显存不足降低分辨率或换小模型No module named onnxruntime依赖没装pip install onnxruntime-gpuCould not load library cudnncuDNN版本不匹配重新下载对应版本cuDNNnvcc not foundCUDA环境变量没配手动添加CUDA bin目录到PATHDocker GPU not availablenvidia-container-toolkit没装安装并重启Docker6.2 运行类报错有一类报错是处理到一半突然中断终端显示stdin: invalid compressed data这通常是模型文件下载不完整导致的。解决办法是删掉.assets/models目录下对应的模型文件重新下载。我遇到过一次反复重下了三次才成功后来发现是网络波动换了个时间段就好了。另一类常见问题是换脸后人脸边缘有明显接缝这通常是face_enhancer没启用或者融合参数没调好。可以尝试加上--face-enhancer-blend参数值设成80到100之间让融合更自然。6.3 性能优化与提速技巧如果你觉得处理速度慢可以从几个方面优化。第一确认--execution-providers确实是cuda而不是cpu第二把--execution-thread-count调高第三降低输出分辨率第四如果视频很长可以先用剪辑软件切成小段并行处理最后再拼接。还有一个技巧是用--face-detector-score参数调整人脸检测的阈值默认0.5调高到0.7可以减少误检加快处理速度但可能会漏掉一些模糊的人脸。这个参数需要根据素材具体情况来调。7. 我在实际部署中踩过的坑和总结的经验说几个文档里不会写但实际很要命的细节。第一个是Windows下路径长度限制FaceFusion的模型路径比较深有时候会超过260字符导致文件读写失败。解决办法是开启Windows的长路径支持在组策略里改一下就行。第二个是Docker Desktop的内存分配默认可能只给了2G跑FaceFusion会卡死需要在Settings里调到8G以上。第三个是关于显卡驱动的我有一次更新驱动后FaceFusion突然跑不了了排查半天发现是新驱动默认启用了某个省电模式导致CUDA调用被限制。回滚驱动或者手动关闭省电模式就好了。所以我的建议是环境跑通之后不要轻易更新驱动除非有明确的需求。最后分享一个批量处理的思路。FaceFusion本身是命令行工具你可以写个简单的shell脚本或者Python脚本遍历input目录下的所有视频逐个调用FaceFusion命令。我写了个二十行的Python脚本把整个目录的视频批量处理完省了大量手动操作的时间。这个脚本的核心就是subprocess调用命令行加上进度打印和错误捕获有编程基础的话半小时就能写出来。