FaceFusion 换脸模型怎么下载：断网与离线部署的实操路径-平芜编程栈

FaceFusion 换脸模型怎么下载：断网与离线部署的实操路径

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

FaceFusion 是面部交换、增强与编辑处理平台，ONNX 模型不随代码分发，用到时才下载到.assets/models/。本文解决两个问题：FaceFusion 模型下载失败怎么查，完全离线的内网机器怎么备齐模型。

先说结论

联网机器只需要一条命令：python facefusion.py force-download。它会遍历全部处理器，先补齐.hash校验文件，再补齐模型文件，逐项做 CRC32 校验，缺什么补什么。
内网机器不用改任何配置：在任一台能出网的机器上跑完 force-download，把整个.assets目录拷到目标机项目的同一相对位置即可，校验全部是本地哈希比对，不发起网络请求。
下载引擎内置容错：curl 5 秒连接超时、失败自动重试 5 次、--continue-at断点续传，中断后重跑同一条命令就从断点接着传。
磁盘紧张就用默认的--download-scope lite；full会额外拉取 deep_swapper 的完整角色模型包，体积差距可达数 GB。

🧭 先判断你的情况

网络正常，日常跑任务：什么都不用做。首次执行run/headless-run时，你勾选的处理器会自动拉取自己缺的模型，force-download 只是把这件事提前做完。
访问 github 慢或不通：把下载源换成 huggingface——--download-providers huggingface。该源内置两个域名，会先逐个探测可达性再选用其一。
内网 / 隔离环境：走下面第 3 节的离线搬运，没有别的捷径。
磁盘紧张：用--download-scope lite（这也是默认值）。注意 force-download 固定遍历全部处理器，不能按处理器裁剪，scope 是唯一省空间的开关。

动手操作

准备环境（只做一次）

要求：Python 3.10 及以上；系统装好curl、ffmpeg、ffprobe（启动时缺一即报错退出）。

git clone https://gitcode.com/GitHub_Trending/fa/facefusion cd facefusion conda activate <你的环境> python install.py default

install.py的第一个参数是 onnxruntime 变体：default（CPU）、cuda、openvino，Linux 另有rocm、migraphx，Windows 另有directml、qnn，按显卡选。脚本默认要求已激活 conda 环境，否则提示conda is not activated并退出，可加--skip-conda绕过。

批量预下载与体检

# 基础模型（默认值） python facefusion.py force-download --download-scope lite # 全量（deep_swapper 角色包全拉） python facefusion.py force-download --download-scope full # 换用 huggingface 源 python facefusion.py force-download --download-providers huggingface

执行流程与 facefusion/download.py 中的逻辑一一对应：按 scope 取各处理器的模型清单 → 校验缺失的.hash并补下 → 校验缺失或损坏的.onnx并补下。两个实用性质：

重跑一次 force-download 就是全量体检：校验通过的文件直接跳过，损坏的.onnx会被自动删除后重新下载，不需要手工清文件。
偏好可固化：把download_providers和download_scope两行写进facefusion.ini的[download]段，之后裸跑命令即生效。

离线搬运 .assets

模型全部平铺在.assets/models/，一个.onnx配一个同名.hash，没有更深层结构，整目录拷贝即可：

# 联网机：打包 tar czf facefusion-assets.tgz .assets # 离线机：解压到项目根目录 tar xzf facefusion-assets.tgz -C <facefusion项目目录>

注意.hash文件必须和模型一起走，缺了它离线机上校验会直接判无效。目标机仍需装好 ffmpeg / ffprobe，只是不再需要网络。

少走弯路

现象	原因	处理
进度条很久不动	增强类模型单个体积大，首次拉取本来就慢	保持等待；日志级别设为`info`或`debug`才能看到逐文件进度，`warn`/`error`下进度条被隐藏
反复提示某个文件校验失败	对应`.hash`缺失或哈希值不符	直接重跑 force-download，它会先补哈希文件再重新校验
某个`.onnx`突然消失	程序检测到损坏后主动删除源文件	属正常行为，重跑命令即自动重下
两个下载源都连不上	github、huggingface 均不可达	只能走离线搬运，或在能出网的机器上先完成下载
启动即报依赖未安装	`curl`/`ffmpeg`/`ffprobe`任一不在 PATH	装齐三个系统依赖后再运行
提示 Python 版本不受支持	需要 3.10+	换高版本解释器重建环境