如何搞定 FaceFusion 模型下载失败：三条路径的离线部署完整指南-平芜编程栈

如何搞定 FaceFusion 模型下载失败：三条路径的离线部署完整指南

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

FaceFusion 是一个 AI 人脸操作平台，提供人脸交换、人脸增强、唇形同步等能力。这篇指南围绕 FaceFusion 模型下载展开：网络顺畅时，一条 force-download 命令即可搞定；纯离线环境则走三步——联网机预下载、打包传输、放到目标机对应目录，全程无需外网。

前提确认：项目已拉取并安装好 Python 依赖，facefusion.py能正常启动。

核心命令（在项目根目录执行）：

python facefusion.py force-download

这条命令会依次下载每个处理器需要的.onnx模型和同名.hash校验文件，默认走 github 和 huggingface 两个源，并自动完成校验。

验收标准（满足以下两条算成功）：

模型统一存放在项目根目录下的.assets/models/中，记住这个位置，后面离线部署全靠它。

FaceFusion 内部用 curl 下载，自带--continue-at断点续传、5 次重试和 5 秒超时，所以下载中断后直接重跑同一条命令即可，它会从断点继续，不用手动处理：

python facefusion.py force-download

如果重试后速度依然不理想，说明你所在网络对 github 源不友好，切换到 huggingface 源（代码里会自动回落到 hf-mirror 镜像站）：

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

验证方式：跑完后同样检查.assets/models/里.onnx与.hash是否成对齐全；缺哪个，就重跑一次命令，程序只会补下缺失的文件，已校验通过的会跳过。

内网环境按"联网机准备 → 传输 → 目标机部署 → 验证"四步走。

拉取项目并下载全量模型：

git clone https://gitcode.com/GitHub_Trending/fa/facefusion

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

--download-scope只有两个取值：lite下载精简模型集（也是默认值），full下载全部模型。离线部署建议直接选full，避免以后又缺模型。

成功标志：.assets/models/下模型文件齐全且全部通过校验。

把整个.assets目录打成压缩包（注意 hash 文件必须跟着模型一起走）：

tar -czf facefusion-assets.tar.gz .assets

用 U 盘、内网文件服务器等方式传到目标机。

在目标机上解压，关键是让.assets/models/与facefusion.py处于同一层目录，代码是按相对路径定位模型的，放错位置等于没部署：

tar -xzf facefusion-assets.tar.gz -C /path/to/facefusion

对任一模型文件做哈希校验，返回True即完整可用：

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

下表列出.assets/models/里常见的核心文件，均出自仓库源码中的静态模型配置（文件大小以实际下载日志为准）：

文件名	用途	所属模块
`inswapper_128.onnx`、`inswapper_128_fp16.onnx`	默认人脸交换模型	face_swapper
`blendswap_256.onnx`、`simswap_256.onnx`、`uniface_256.onnx`	备选人脸交换模型	face_swapper
`gfpgan_1.4.onnx`、`codeformer.onnx`、`restoreformer_plus_plus.onnx`	人脸增强	face_enhancer
`retinaface_10g.onnx`、`scrfd_2.5g.onnx`、`yoloface_8n.onnx`	人脸检测	face_detector
`2dfan4.onnx`、`fan_68_5.onnx`	人脸关键点定位	face_landmarker
`arcface_w600k_r50.onnx`	人脸识别	face_recognizer
`xseg_1.onnx`、`bisenet_resnet_18.onnx`	人脸遮罩	face_masker
`ben_2.onnx`、`ormbg.onnx`、`rmbg_1.4.onnx`	背景移除	background_remover

现象	可能原因	一行修复
进度条反复中断	弱网导致连接断开	直接重跑`force-download`，curl 自带断点续传
下载极慢或超时	github 源不可达	换源：`--download-providers huggingface`
日志提示哈希校验失败，文件被自动删除	下载中断导致文件损坏	删掉该目录下的`.onnx`和`.hash`，重跑`force-download`
目标机运行却提示找不到模型	`.assets`没放在项目根目录，或`.hash`缺失	把`.assets`移到与`facefusion.py`同级，确认`.onnx`/`.hash`成对同目录

走代理下载：有代理时先导出环境变量再跑命令，curl 会自动生效：export https_proxy=http://127.0.0.1:7890
按需选范围省空间：磁盘紧张时保持默认的--download-scope lite，只下载精简模型集；确认要跑全部功能再升full
固化默认下载源：在facefusion.ini的download段写download_providers = huggingface，以后不用每次带参数
单文件快速验伤：怀疑某个模型损坏时，用上面的validate_hash单点验证，返回False就删掉重下