FaceFusion 模型下载与离线部署：3 步拿到可用模型

FaceFusion 模型下载与离线部署：3 步拿到可用模型

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

FaceFusion 是一个开源的面部处理平台，核心能力是人脸交换、增强、编辑和唇形同步。它的所有功能都依赖一堆模型文件，所以"FaceFusion 模型下载"往往是安装时最卡的一步；而把模型带进内网做离线部署，则是生产环境最常见的诉求。下面按"先跑起来 → 按网络选策略 → 验证文件 → 排查问题"的顺序给你一套可操作的流程。

最快路径：让 FaceFusion 先跑起来

👇 网络正常的机器上，3 条命令就够了：

git clone https://gitcode.com/GitHub_Trending/fa/facefusion pip install -r requirements.txt python facefusion.py force-download --download-scope lite

• 第 3 条命令是专门的"强制下载"入口，默认只拉lite档位，包含 face_swapper、face_enhancer 等最常用处理器及其依赖，几分钟内完成。
• 下完直接python facefusion.py run进入图形界面，选一张人脸图作 source、一个视频作 target，点 START 就能看到效果。

按网络环境选策略

三档网络条件对应三种做法，各给一条关键命令。

稳定在线：默认流程直接下

先执行force-download，再跑业务命令，缺什么补什么，一般不用额外干预：

python facefusion.py force-download --download-scope lite

想一次拿全所有处理器的模型（含 lip_syncer、frame_enhancer 等），把--download-scope lite换成--download-scope full即可。

弱网抖动：换下载源 + 控制档位

下载请求默认走 github 源，连不上就换成 huggingface（它自带 hf-mirror 备源）：

python facefusion.py force-download --download-providers huggingface --download-scope lite

两条建议：先用lite档跑通最小集，确认源可达后再补full；大模型中断了重跑同一条命令，已下完整的文件会自动跳过。

完全离线：联网机预下载，整目录搬运

📦 离线机器自己发不出请求，标准做法是"借机下载 + 目录拷贝"：

1. 联网机执行python facefusion.py force-download --download-scope full；
2. 把项目根目录下的.assets/models/整个打包；
3. 解包到离线机同样的相对位置，.hash校验文件必须跟.onnx放在一起。

这样离线端run时本地校验通过，就不会再触发任何下载。

模型文件怎么确认没下坏

校验规则很简单：每个模型文件xxx.onnx旁边都有一个同名的xxx.onnx.hash，里面存的是内容指纹；FaceFusion 每次加载前都会自动比对，对不上就判定损坏并提示删除重下。

手动抽查单个文件，只需一行：

python -c "from facefusion.hash_helper import validate_hash; print(validate_hash('.assets/models/inswapper_1_256.onnx'))"

输出True就是好的。批量体检的话，重跑一次force-download就行——它会跳过已完整的文件，只重拉校验不过的那几个，等于一次全量体检。

踩坑速查

Q：force-download卡住不动，是什么问题？A：多半是当前源（默认 github）连不上。用curl -I https://github.com测一下连通性，不通就加--download-providers huggingface换源重试。

Q：提示Validating hash failed怎么办？A：说明文件下载不完整。FaceFusion 会自动删掉损坏文件，重跑一次force-download即可；反复失败就换源。

Q：磁盘装不下 full 档位？A：用lite档只拉核心模型，或只保留你实际启用的处理器对应的模型，其余档位按需再补。

Q：换机器后模型不生效？A：检查.assets/models/的相对路径是否和项目根目录对齐，以及每个.onnx是否都有同名.hash文件。

Q：能不能只换下载源，不改任何代码？A：可以。在facefusion.ini的[download]段写download_providers = huggingface，以后所有命令默认走这个源，无需每次带参数。

生产环境落地清单

1. 联网构建机执行force-download --download-scope full，完成预打包。
2. 用du -sh .assets/models记录体积，打包前抽查 2~3 个.onnx的哈希。
3. 用tar -czf压缩，走 U 盘/内网文件服务传入目标机，解压到项目根目录。
4. 目标机本地再跑一次force-download，确认全部通过校验、无下载行为发生。
5. 升级 FaceFusion 版本后，对照版本号（如models-3.0.0）检查是否需要重下新模型。

延伸方向

想深入看下载与校验的源码逻辑，可以读 facefusion/download.py 和 facefusion/hash_helper.py；各处理器的模型清单定义在 facefusion/processors/modules 目录下，需要自定义模型集时从这里入手即可。

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