企业官网建设流程全解析

FaceFusion 模型下载失败怎么办？force-download 命令解析与模型文件手动校验指南

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

第一次运行 FaceFusion，或者换了一台机器之后，最常见的两个症状：模型下载进度条卡在一半不动，或者程序直接报validating hash failed然后退出（退出码 1）。这两个问题的根源都在同一套"下载 + 校验"机制上。这篇文章把这套机制从源码讲清楚，然后给你三件武器：一条命令拉全所有模型、手动下载模型文件的方法、逐文件校验完整性的脚本。

模型下载是怎么工作的：30 秒建立心智模型

FaceFusion 的每个模型都自带一份.hash校验文件，下载和校验的完整流程是：

1. 各功能模块（人脸检测、换脸、增强等）声明自己需要的一组模型，每个模型对应一个.hash文件和一个模型文件（通常是.onnx）
2. 按你配置的下载源顺序，探测哪个源可达，用第一个可达的源拼装出下载地址
3. 先下载.hash文件，再下载模型文件
4. 对模型文件计算 CRC32，与.hash文件内容比对
5. 校验失败：程序自动删除损坏文件，下次运行时重新下载

所有模型统一存放在项目根目录的.assets/models/下，命名规范是<模型名>.onnx配一个<模型名>.hash。校验逻辑非常短（见 facefusion/hash_helper.py）：

def create_hash(content: bytes) -> str: return format(zlib.crc32(content), '08x') def validate_hash(validate_path: str) -> bool: # 读取同目录同名的 .hash 文件 # 比对模型文件的 CRC32 与文件内容 ...

两个容易踩的坑：

• 校验用的不是 SHA256，是 8 位十六进制的 CRC32
• .hash文件不存在时，validate_hash直接返回 False——模型文件会被判定为无效。所以模型文件和.hash文件必须成对存在，这个点后面手动下载和离线部署都要用到

一键拉取：force-download 命令怎么用

先跑这条命令，它会遍历所有处理器模块声明的模型，缺什么补什么：

python facefusion.py force-download

运行前提：Python 3.10 以上，且curl、ffmpeg、ffprobe已安装并在 PATH 里，否则会直接报dependency not installed退出。

它支持两个关键选项：

两个提醒：

• ⚠️huggingface这个提供方内部还带一个镜像源，主站不通会自动回退到下一个；如果你所在网络访问github源困难，把顺序写成--download-providers huggingface github通常就能解决
• 这两个选项也可以写进facefusion.ini持久化，不用每次敲：

[download] download_providers = huggingface download_scope = full

✅ 判断标准：命令退出码为 0 即全部成功；任何一个模型校验失败，退出码就是 1，日志里会打印validating hash failed: xxx指明是哪个文件。

下载底层是curl，带了--continue-at -（断点续传）和--retry 5（自动重试），这些细节在 facefusion/download.py 的conditional_download里能直接看到。

手动下载与放置模型文件

当force-download反复中断、或者你只想补一两个大文件时，可以手动下载。下载地址由"提供方基地址 + 模型版本号 + 文件名"自动拼装，不用你记 URL——你需要知道的只有文件名，比如人脸检测模型的scrfd_2.5g.onnx和配套的scrfd_2.5g.hash（文件名在各模块的模型声明里都有，例如facefusion/face_detector.py）。

放置规则只有三条：

/assets/models/ ├── scrfd_2.5g.onnx # 模型文件 ├── scrfd_2.5g.hash # 校验文件，内容为一串 8 位十六进制 CRC32 └── ...

• 存到项目根目录的.assets/models/
• 文件名必须与程序声明完全一致
• .onnx和.hash成对放

放好后用项目自己的校验函数验证，这比手算哈希可靠（省得你选错算法）：

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

输出True就是放对了。想全量体检一遍.assets/models/里的模型，用这个脚本：

python - <<'EOF' import glob from facefusion.hash_helper import validate_hash for path in sorted(glob.glob('.assets/models/*.onnx')): print('OK ' if validate_hash(path) else 'BAD', path) EOF

BAD的文件要么重下，要么检查.hash文件是否漏拷。

验证与排错

症状：日志报validating hash failed，退出码 1原因：模型文件下载不完整或损坏（网络抖动最常见）。 修复：直接重跑force-download即可。程序会先删掉损坏文件再重下，且下载基于断点续传，已下载的部分不用重来。

症状：下载卡住不动，或探测源时 content-length 读到 0原因：所有配置的下载源都不可达。 修复：调整提供方顺序，--download-providers huggingface github，利用镜像源回退。

症状：启动就报dependency not installed或python not supported原因：缺curl/ffmpeg/ffprobe之一，或 Python 版本低于 3.10。 修复：装齐依赖并确认在 PATH 里，再重跑。

另外说明一点：run、headless-run这类正常处理命令在启动时也会触发同样的模型自检，缺的会自动补下、坏的会删掉重下——所以force-download不是每次运行前的必选项，它更适合在部署阶段一次性把环境准备好。

离线部署的做法

给一台有网的机器跑force-download --download-scope full，然后用上面的批量校验脚本确认全部OK，把整个.assets/models/目录拷到离线机器即可。离线机器上只要本地校验通过，就完全不需要访问任何下载源。

⚠️ 拷贝时最容易犯的错误是只拷了.onnx漏了.hash——那样离线环境里所有模型都会被判为无效，而重下又必然失败，卡死循环。

• 模型统一放在.assets/models/，<名字>.onnx与<名字>.hash必须成对
• 校验算法是 CRC32（8 位十六进制），不是 SHA256；缺.hash文件直接判无效
• force-download用--download-scope full拉全量，--download-providers控制源顺序
• 损坏文件会被自动删除重下，下载支持断点续传，重跑即可恢复
• 离线部署前先用validate_hash批量脚本全量体检一遍再拷贝

下一步：在当前机器跑一次python facefusion.py force-download，配合批量校验脚本确认全部OK，再开始你的第一个处理任务。

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