FaceFusion 换脸部署指南：3 种网络场景搞定模型下载与离线部署
【免费下载链接】facefusionIndustry leading face manipulation platform项目地址: https://gitcode.com/GitHub_Trending/fa/facefusion
首次运行python facefusion.py run时，FaceFusion 这款换脸与面部处理平台的终端卡在模型文件下载上，或者你要把它部署到完全不能联外网的内网机器上——问题其实都出在同一处：模型下载与离线部署。本文基于 FaceFusion 3.8.0 的真实命令行，带你走一遍完整流程：先判断自己属于哪种网络场景，再执行对应的下载方法，最后用一张症状速查表和一份部署前检查清单收尾。
先判断你的网络场景，再动手
结论：别急着反复重下，先判定你处于哪种场景。模型源有两个 provider：github与huggingface，其中 huggingface 源在官方不可达时会自动回退到 hf-mirror 镜像，定义见 facefusion/choices.py。
| 场景 | 判断标准 | 走哪条路 |
|---|---|---|
| 外网稳定 | force-download 首个文件速度平稳 | 直接 run 自动下载，或提前 force-download |
| 时断时续、速度差 | 下载经常超时、进度条长时间不动 | 依赖断点续传 + 切换 provider + 走代理 |
| 完全离线 | 机器访问不了任何外网 | 联网机预下载，整包拷走.assets/ |
判断最快的方式是直接跑一次最小范围下载：
# 用 lite 范围（体量最小）试下载，看首个文件的速度判断网络是否可用 python facefusion.py force-download --download-scope lite所有模型都落在.assets/models/目录，每个.onnx模型配一个同名.hash校验文件；facefusion/hash_helper.py 会对文件内容计算 CRC32 并与 hash 文件比对，这是后文一切校验动作的依据。
网络稳定时：自动下载或提前预下载
结论：网络稳就不用折腾，程序在运行前会自动检查并补齐缺失文件。
第一次部署时先装依赖，然后直接跑：
# 获取源码 git clone https://gitcode.com/GitHub_Trending/fa/facefusion # 安装 Python 依赖（conda 环境已激活时可去掉 --skip-conda） python install.py default --skip-conda # 首次运行：自动下载缺失的模型并打开 web 界面 python facefusion.py run我的建议是网络好的时候仍提前跑一次force-download，把"下载 + 校验"在任务开始前做完，避免跑到一半才暴露网络问题：
# 预下载全部模型（full 为全集；默认值是 lite 子集） python facefusion.py force-download --download-scope full # 查看模型目录的实际占用与文件列表 du -sh .assets/models && ls .assets/models/ | head也可以把这两项写进 facefusion.ini，之后所有命令都会沿用，不用每次传参：
[download] download_providers = github huggingface download_scope = full下载反复失败时：换源、续传，别从头来
结论：反复失败的下载，大多数靠切换 provider 加上内置续传就能收尾，不需要推倒重来。
先记住三件事：
- 续传是内置的。底层下载命令带
--continue-at - --retry 5（见 facefusion/curl_builder.py），中断的半成品会自动从断点继续，不用手动删。 - 损坏文件会被自动清理。哈希校验失败时程序会打印
deleting_corrupt_source并直接删掉坏文件，下次运行自动重新下载，别急着整体重下。 - provider 可以显式指定。默认顺序是先 github 后 huggingface，第一个不可达时手动切换：
# 指定走 huggingface 源下载（官方不可达时会自动回退到 hf-mirror） python facefusion.py force-download --download-providers huggingface --download-scope full # 或者启用代理 export https_proxy=http://127.0.0.1:7890 # 代理生效后重新执行强制下载 python facefusion.py force-download下载完成后抽查单个文件，确认校验通过：
# 校验单个模型文件，True 正常、False 损坏（文件名按实际替换） python -c "from facefusion.hash_helper import validate_hash; print(validate_hash('.assets/models/yoloface_8n.onnx'))"机器完全不能联网时：手动部署模型文件
结论：离线机唯一稳妥的办法是把完整的.assets/目录搬过去——程序只在"文件缺失或哈希不匹配"时才尝试联网下载，文件齐了就不碰网络。
三步走：
# 第 1 步：在联网机上下载全集 python facefusion.py force-download --download-scope full # 第 2 步：把模型目录打包 tar -czf facefusion-assets.tar.gz .assets/ # 第 3 步：传到离线机后，解压到 facefusion.py 同级目录 tar -xzf facefusion-assets.tar.gz之后在离线机直接python facefusion.py run即可。如果只需要少数模型（比如只用 face_swapper），源机上不必下 full，用 lite 即可，但要人工挑文件时记住一条原则：
⚠️.onnx和它对应的.hash必须成对、文件名严格一致。校验逻辑按模型文件名去找 hash 文件，缺一个就会被判为"无效"，程序会尝试联网补下——这在离线机上就是直接失败。
症状速查表
| 症状 | 可能原因 | 该做什么 |
|---|---|---|
| downloading 进度条卡住、速度极低 | 源站连通性差或限速 | 换--download-providers huggingface，或配代理后重跑 |
日志出现validating_hash_failed | 下载中途文件损坏 | 不用手动处理，程序已自动删坏文件，重跑 force-download |
| 同一文件被反复下载 | 对应.hash缺失或文件名对不上 | 检查.assets/models/中 onnx 与 hash 是否成对，再重跑 |
| 磁盘写满 | full 范围模型合计数 GB | 改用--download-scope lite，用du -sh .assets查看实际占用 |
| 这台机器不行、另一台正常 | 网络策略或代理差异 | 先用force-download --download-scope lite单文件验证连通性 |
| 运行时报 onnxruntime 相关错误 | 依赖未安装 | python install.py default --skip-conda |
部署前检查清单
交给生产环境或内网部署前，按顺序过完这 5 项：
- 依赖已装：
python install.py default --skip-conda（conda 环境可去掉--skip-conda） force-download --download-scope full完整跑完、退出码为 0.assets/models/下模型文件与.hash校验文件一一对应，无落单文件du -sh .assets确认目标机磁盘剩余空间足够（全集模型合计数 GB）- 用最小任务试跑一次：
python facefusion.py run -s source.jpg -t target.mp4 -o output.mp4
清单全绿，这套部署就可以放心带到任何网络环境了。
【免费下载链接】facefusionIndustry leading face manipulation platform项目地址: https://gitcode.com/GitHub_Trending/fa/facefusion
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考