FaceFusion 模型下载与离线部署实战：一条命令到跑通的 5 步闭环

FaceFusion 模型下载与离线部署实战：一条命令到跑通的 5 步闭环

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

FaceFusion 是一套命令行驱动的人脸处理平台，核心能力包括人脸交换、人脸增强、表情还原等。你刚 clone 下来跑python facefusion.py run，终端却卡在模型下载上：网络抖动、下载中断、或者目标机器根本连不上外网。别急，这篇带你把 FaceFusion 模型下载这一环彻底打通：一条force-download命令拉全模型、hash 校验确认完整、离线环境用模型包一步到位，读完照着敲就能跑通第一次人脸交换。

三种场景，一张表定调

模型文件统一落在项目根目录的.assets/models/下，每个.onnx旁边都配一个同名.hash文件，下载和校验逻辑都在 模型下载模块 里：先验.hash，再拉源文件，用 CRC32 逐字节比对（见 hash 校验模块）。理解这条链路，下面所有命令你都能看懂为什么这么做。

对号入座：先判断你属于哪条路径

• ✅A. 机器能稳定上网：走主路径（下一节），一条命令下载、校验、验证，全程不用手动建目录。这是推荐路径。
• ⚠️B. 网络时好时坏，下载经常断：命令和 A 完全一样，断掉重跑即可，3.2 节给你断点续传的验证方法。
• 🚀C. 目标机完全离线（内网/隔离环境）：在任意一台联网机上先跑完 A，把.assets/models打包拷过去，3.3 节两条命令完成离线部署。

主路径：force-download 强制下载模型（推荐）

1. 准备：clone 仓库并把依赖装齐

跑命令之前，pre_check会检查 Python 版本和三个系统依赖，缺一样都进不去下载流程，所以一次性备齐。

# clone 代码（需要时改用 gitcode 镜像源） git clone https://gitcode.com/GitHub_Trending/fa/facefusion cd facefusion # 系统依赖：curl、ffmpeg、ffprobe 三者缺一不可 # Debian/Ubuntu: sudo apt install curl ffmpeg # macOS: brew install curl ffmpeg

接着准备 Python 环境。FaceFusion 要求 Python 3.10+，install.py需要 conda 环境已激活（或加--skip-conda跳过检查）：

# 进入 conda 环境后，按硬件装依赖（cpu / cuda / tensorrt 三选一） python install.py cpu

做对的话，终端不报任何依赖错误，pip list里能看到 onnxruntime 和 opencv 等包。

2. 执行：force-download 强制下载命令

force-download会遍历所有处理器模块（face_swapper、face_enhancer、lip_syncer 等）声明的模型清单，逐个下载.hash和源文件并校验，这是 命令行入口 里唯一专职下载的子命令。--download-scope full拉全量，默认值是lite，离线部署建议用 full，避免到了现场才发现缺文件：

# 联网机：全量下载所有处理器模型，带进度条 python facefusion.py force-download --download-scope full # 国内网络直连 github 困难时，指定 huggingface 源 # （代码内置了 hf-mirror 备用地址，见 facefusion/choices.py 的 download_provider_set） python facefusion.py force-download --download-scope full --download-providers huggingface

做对的话，每个文件显示一行downloading进度，最后终端安静退出，退出码为 0。

3. 验证：确认模型文件完整可用

下载结束不等于万事大吉，用两条命令确认本地模型已就绪。第一条数文件，完整全量包应包含几十个.onnx及其.hash配对：

# 数模型文件与 hash 校验文件的数量 ls .assets/models | wc -l find .assets/models -name "*.hash" | wc -l

第二条是终局验证：再次跑 force-download，如果本地文件 hash 全部通过，它不会发起任何下载直接退出；有缺件或损坏则会自动补下、删除损坏文件（deleting corrupt source日志）：

# 重跑一遍：全部校验通过则无 downloading 提示，直接退出 python facefusion.py force-download --download-scope full

再往下就是跑通第一次人脸交换，证明模型真正可用：

# 无界面模式跑一次：source 一张人脸图，target 一个视频 python facefusion.py headless-run \ --source-paths source.jpg --target-path target.mp4 \ --output-path output.mp4 --processors face_swapper

做对的话，output.mp4出现在当前目录，终端打出 processing succeeded 一类日志，说明检测、交换、编码全链路正常。

备选路径速览

• B. 断点续传：FaceFusion 底层用 curl 的--continue-at -参数，中断后重跑同一条 force-download 命令即自动续传，set_retry还带了 5 次重试。想手动验证某个文件可续传，直接curl -C - -o 目标路径 模型URL。
• C. 离线包一键部署：联网机tar -czf models.tar.gz .assets/models，传到离线机同目录解压tar -xzf models.tar.gz，离线机装好代码和 Python 依赖后跑一次force-download——hash 校验通过即跳过全部下载，全程零外网。

翻车急救：5 个高频现场

1. 首次运行直接报依赖或 Python 版本错误定位：看第一行报错，pre_check只认两类——{dependency} is not installed或python version is not supported, upgrade to 3.10 or higher。 修复：sudo apt install curl ffmpeg（或brew install）补齐依赖；python --version确认低于 3.10 的，升级 Python 或换环境后重跑。

2. 进度条卡住、反复重试定位：curl -I --connect-timeout 5 https://github.com，看当前下载源是否可达。 修复：换源重跑python facefusion.py force-download --download-scope full --download-providers huggingface；有代理就先export https_proxy=...再执行。

3. 日志刷 validating hash failed定位：这条日志说明某个模型文件与.hash内容对不上（CRC32 比对失败），常见于下载中断后留下的残文件。 修复：删掉坏文件重跑，程序会自动补下并跳过已校验的文件：

# 以报错日志里的文件名为准，删掉损坏的模型与 hash rm .assets/models/inswapper_128.onnx .assets/models/inswapper_128.onnx.hash python facefusion.py force-download --download-scope full

4. 离线机重跑 force-download 却一直报下载失败定位：离线机 ping 谁都不通，这不是故障而是前提不满足——模型包没带过来。 修复：按 3.3 节把联网机的.assets/models打包拷到离线机解压，再跑一次 force-download 做本地校验即可。

5. 磁盘空间不足定位：du -sh .assets/models看模型实际占用，df -h .看剩余空间，剩余空间小于模型包体积必挂。 修复：清理临时目录rm -rf /tmp/facefusion*（以--temp-path配置为准），或删掉用不到的大模型文件后重跑 force-download 补齐。

6. install.py 提示 conda is not activated定位：install.py检测到环境变量里没有CONDA_PREFIX就拒绝执行。 修复：conda activate 你的环境后再跑python install.py cpu；确实不用 conda 就python install.py cpu --skip-conda。

整条链路就一句话收住：联网机force-download --download-scope full下载并自校验，离线机解包模型包后靠 hash 校验免下载，headless-run跑通一次人脸交换即算闭环。接下来两个方向可以试试：用batch-run加--source-pattern批量处理整个素材目录，或者给headless-run追加--execution-providers cuda/tensorrt这类参数，按你的硬件把推理速度拉满。

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