FaceFusion force-download 完整指南：3 步搞定模型下载与哈希校验-平芜编程栈

FaceFusion force-download 完整指南：3 步搞定模型下载与哈希校验

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

把 FaceFusion 搬上内网机器，模型下载进度条一小时不动，下完还发现文件损坏、推理直接报错——这是新手部署最常踩的坑。解法就一条主线：用 force-download 命令统一管下载，用 CRC32 哈希校验兜底，一次备齐、离线跑通。

30 秒速览：照做能拿到什么

照下面步骤做完，你会得到一个校验全部通过的.assets/models/目录（模型文件与同名.hash校验文件成对存放），FaceFusion 可以直接断网运行换脸、人脸增强等完整功能。最小可执行命令只有一条：

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

force-download 机制一图流：下载流程怎么走

force-download的实现在 facefusion/core.py 的force_download()里，整体只有五个动作：

白话解读：它像一个"模型仓库管理员"，先盘点哪些文件缺了、哪些坏了，再挨个补齐，最后报个总账。范围选lite只拉人脸检测、关键点、识别这些公共基础模型；选full则连换脸、超分、背景移除等处理器专用模型一起拉。

force-download 分步实操：从装环境到跑通

Step 1：准备环境并克隆项目

前置要求：Python 3.10+，以及系统里的 curl、ffmpeg、ffprobe 三个命令行工具（facefusion/core.py 的pre_check()会逐个检查，缺一个都拒绝启动）。

git clone https://gitcode.com/GitHub_Trending/fa/facefusion cd facefusion pip install -r requirements.txt

做完你该看到：pip输出Successfully installed ...，且ffmpeg -version能正常打印版本信息。

Step 2：执行 force-download 拉取全量模型

离线部署建议直接拉full，一次备齐后续不用再来回折腾：

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

下载由内置 curl 完成，固定带--continue-at -（断点续传）和--retry 5，实现见 facefusion/curl_builder.py。做完你该看到：日志逐文件输出validating source succeeded，命令以退出码 0 结束，.assets/models/下出现成对的.onnx与.onnx.hash文件。

Step 3：手动复算 CRC32，独立复核文件没坏

注意一个反直觉的点：FaceFusion 的.hash文件里存的是CRC32而不是 SHA256，见 facefusion/hash_helper.py。网上说"用 sha256 验文件"的资料在这里都不成立。你可以用同一算法手动复算：

python -c "import zlib; print(format(zlib.crc32(open('.assets/models/scrfd_2.5g.onnx','rb').read()), '08x'))" cat .assets/models/scrfd_2.5g.onnx.hash

做完你该看到：两行输出的 8 位 16 进制字符串完全一致。不一致就说明文件传坏或.hash与.onnx版本不匹配，把两个文件一起删掉重下即可。

force-download 配置速查：范围与下载源

下载源在 facefusion/download.py 的resolve_download_url()里按顺序逐个试连通，命中的第一个生效；内置源为github与huggingface（后者会依次尝试主域名和镜像域名）。默认值可在 facefusion.ini 的[download]段固定下来：

[download] download_providers = github huggingface download_scope = lite

配置项	默认值	何时改
`--download-scope`	`lite`	要换脸、超分等完整功能时改成`full`
`--download-providers`	`github huggingface`	某个源被墙或太慢时，把更稳的放前面
`ini: download_scope`	`lite`	想让 full 成为长期默认，少敲参数
`ini: download_providers`	两个源依次尝试	内网镜像环境里固定顺序

校验失败与下载报错怎么办

现象	原因	一键修复命令
日志报`validating source failed`	文件传输损坏或`.hash`版本不匹配	删除损坏文件后重跑`python facefusion.py force-download --download-scope full`（内置流程会自动删掉坏文件）
进度条龟速或卡死	网络高峰或下载源不稳	中断后直接重跑同一条命令，curl 断点续传会接着下
连接超时、curl 返回非 0	目标源不通或防火墙拦 443	`curl -I <下载源地址>`测连通性，再`--download-providers`换源顺序
启动即报依赖缺失	curl / ffmpeg / ffprobe 未装	用系统包管理器安装，如`sudo apt install ffmpeg`

进阶玩法：离线打包与批量校验

离线搬运：把校验通过的.assets/models/整包tar czf models.tar.gz .assets/models，离线机解压即用，省得在慢网上一件件下
批量校验：到位后跑一遍全目录复核，全部"通过"再断网

import os from facefusion.hash_helper import validate_hash for name in sorted(os.listdir('.assets/models')): if name.endswith('.onnx'): path = os.path.join('.assets/models', name) print('通过' if validate_hash(path) else '失败', name)