FaceFusion 离线部署一次讲透：3步搞定模型拉取与哈希校验

FaceFusion 离线部署一次讲透：3步搞定模型拉取与哈希校验

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

当你在内网机器上敲下python facefusion.py run，等了几十秒进度条却卡着不动——FaceFusion 的模型下载自带「提供商自动切换 + crc32 哈希校验」，多数时候只需要把force-download一条命令用对。本文以换脸（face_swapper）场景为例，把离线部署的路径一次走完。

快速跑通

如果还没拿到代码，先执行git clone https://gitcode.com/GitHub_Trending/fa/facefusion，然后进入项目根目录（需要 Python 3.10+，且curl、ffmpeg、ffprobe在 PATH 里）：

pip install -r requirements.txt python facefusion.py force-download --download-scope lite python facefusion.py run -s source.jpg -t target.mp4 -o result.mp4

三步结束。force-download预拉 lite 模型集；run时若当前参数还需要其他模型，会走同一套下载流程自动补齐，输出写到result.mp4。判定标准：.assets/models/下出现.onnx且每个都带.hash文件、输出视频能正常播放，就算跑通了。

分场景实操

下载源在代码里叫 provider，内置两个，拉取路径和兜底方式不一样：

默认顺序是github→huggingface，代码逐个 ping 通哪个用哪个，普通网络不用手动干预。

外网可用但不稳：force-download 一次拉全

1. 完整拉取：python facefusion.py force-download --download-scope full
2. 环境里 github 完全不通时，把提供商钉死，省掉无效的 ping：python facefusion.py force-download --download-providers huggingface --download-scope full
3. 下载底层是 curl，带了 5 次重试和断点续传，中途中断后重跑同一条命令接着传即可。
4. 验证是否成功：日志结尾一串 validating source succeeded，且.assets/models/里每个.onnx旁边都有.hash。

拉全之后，要搬去完全无网络的环境，用的就是下面这条路。

内网无外网时：整搬 .assets/models 并校验哈希

1. 在联网机器先跑完python facefusion.py force-download --download-scope full。

2. 打包项目时连隐藏目录.assets一起带过去——它是最容易漏的东西。

3. 目标机器上用项目自带的校验函数验完整性：

   python -c "from pathlib import Path; from facefusion.hash_helper import validate_hash; bad=[str(p) for p in Path('.assets/models').glob('*.onnx') if not validate_hash(str(p))]; print(bad or '全部通过')"

4. 判定标准：输出全部通过，且之后run不再发起任何网络请求。

要是只想先快速验证一次换脸效果，不想等全部文件，还有更轻的路径。

磁盘紧张时：用 lite 快速起步、事后补 full

1. --download-scope默认就是lite，只拉最常用的模型子集，换脸开箱即用（具体包含哪些以实际版本为准）。
2. 之后想启用其他模型时，把 scope 切成full重跑即可：校验通过的文件直接跳过，只补缺失的。
3. 别试all、common之类的写法——这个版本的 scope 只认lite/full，传别的直接 invalid choice。
4. 判定标准：force-download 快速退出，.assets/models/里的文件正好是当前参数需要的子集。

原理 60 秒

每个用模型的模块（face_detector、face_recognizer、face_swapper 等处理器）都会注册一份模型清单，每个模型带两条信息：远程 URL 和本地路径.assets/models/<模型名>.onnx。force-download运行时先拉全部.hash文件，再逐个处理模型：本地文件大小和远端 Content-Length 对不上，就用 curl 断点续传补全；下完后按 facefusion/hash_helper.py 做 crc32 比对（注意不是 sha256），不一致就自动删掉重下。运行时 onnxruntime 只加载当前参数真正用到的那一个 onnx，盘上放多少都不影响内存。设计意图就是把下载做成「幂等 + 可续传」：无论中断多少次，重跑都能收敛到正确状态。

落盘结构很简单，唯一的坑是.assets是隐藏目录：

项目根目录/ ├── facefusion.py # 入口 ├── facefusion.ini # 配置，含 [download] 段 ├── facefusion/ # 核心源码包 └── .assets/models/ # 模型存放处（隐藏目录，搬迁必须带上） ├── inswapper_128.onnx ├── inswapper_128.onnx.hash # crc32 校验值 └── ...

踩坑与绕过 ⚠️

force-download 卡在第一个提供商上很久原因：provider 按列表顺序挑选，第一个不通会耗掉连接超时。修复：python facefusion.py force-download --download-providers huggingface

日志出现 validating source failed原因：上次下载中断导致文件不完整，crc32 对不上。修复：重跑python facefusion.py force-download，程序会自动删除损坏文件重新拉取。

--download-scope all报 invalid choice原因：scope 只支持lite/full，不少旧博客的参数写法在这版本里已经失效。修复：改用--download-scope full，别照抄。

搬完目录后模型被重新下载原因：.assets是隐藏目录，cp、git默认容易漏；模型路径是相对源码包位置解析的，目录不在就回源下载。修复：rsync -a src/ dst/整目录同步。

生产环境加固 💡

• 定时哈希巡检：挂到 cron，月度跑一次，输出 OK 或列出坏文件。

  python -c "from pathlib import Path; from facefusion.hash_helper import validate_hash; bad=[str(p) for p in Path('.assets/models').glob('*.onnx') if not validate_hash(str(p))]; print(bad or 'OK')"

• 把下载策略钉进 facefusion.ini：避免命令行参数临时性漂移。

  [download] download_providers = huggingface download_scope = full

• 离线部署包：.assets和代码一起打包，目标机器零网络依赖，交付前先du -sh .assets/models估好体积。

在线还是离线，FaceFusion 模型下载的关键就是「提供商兜底 + 哈希校验」。参数细节可继续翻 facefusion/download.py 的源码。

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