【Bug已解决】DiffusionPipeline.download()breaks with huggingface_hub1.22.0 in offline mode (IncompleteSnapshotError) 解决方案一、现象长什么样离线环境或内网、无外网容器里用 diffusers 的DiffusionPipeline.download()预先拉取模型升级huggingface_hub1.22.0后开始报from diffusers import DiffusionPipeline DiffusionPipeline.download( runwayml/stable-diffusion-v1-5, local_dir./sd15, )报错huggingface_hub.utils._errors.IncompleteSnapshotError: ... Snapshot download did not complete; some files are missing.或者ValueError: Cannot download in offline mode: the repo ... is not fully cached.最迷惑的是网络正常时一切正常一旦切到离线模式HF_HUB_OFFLINE1或local_files_onlyTrue新版 hub 对「快照完整性」的检查比旧版严格本地只要缺一个文件哪怕是可选的*.md/logs/ 某个变体权重就抛IncompleteSnapshotError而旧版只会「能用多少用多少」。离线部署、内网推理服务最常踩这个——你以为模型都下好了结果新版本 hub 一句话「快照不完整」把你拦在启动门外。二、背景huggingface_hub1.22.0 对「快照下载」的完整性语义做了调整。旧版snapshot_download在local_files_onlyTrue或离线时倾向于「本地有啥用啥」新版引入更严格的快照完整性校验它期望本地缓存的 repo 与该 repo 在 Hub 上的「快照清单」完全一致包含所有blobs引用只要本地缺任何一个被清单引用的文件就抛IncompleteSnapshotError。diffusers 的DiffusionPipeline.download()内部调用snapshot_download。问题在于离线模式下仍做完整性校验新版即使local_files_onlyTrue也会拿本地已有的refs/snapshots去比对期望清单缺文件即报。可选文件也算完整性模型仓库里常有可选的README.md、model_index.json之外的示例、或某些没下载的变体它们出现在快照清单里但本地没下于是「不完整」。缓存元数据过期旧版 hub 写的缓存元数据.json指针格式与新版不兼容新版读不出「哪些已完整」直接判不完整。结果离线启动被IncompleteSnapshotError卡死但模型权重其实都在、能用。三、根因根因一句话huggingface_hub1.22.0在离线/local_files_only模式下对快照完整性校验更严格本地只要缺清单中任一文件含可选文件或缓存元数据过期就抛IncompleteSnapshotError而 diffusers 的download()没有为离线场景做兜底。三点展开离线仍强校验新版离线模式也比对快照清单缺文件即报。可选文件计入完整性README/未下载变体等让本地永远「不完整」。缓存元数据不兼容旧版写的指针新版读不出误判未完整。不是模型缺文件是「完整性校验口径变严」导致的离线启动失败。四、最小可运行复现不依赖真实 hub模拟「离线模式严格校验导致 IncompleteSnapshotError」from dataclasses import dataclass, field from typing import List, Set dataclass class FakeHub: # Hub 上的完整清单含可选文件 manifest: Set[str] field(default_factorylambda: { model_index.json, unet/diffusion_pytorch_model.safetensors, README.md, scheduler/scheduler_config.json, }) # 本地实际已下的故意缺 README.md local: Set[str] field(default_factorylambda: { model_index.json, unet/diffusion_pytorch_model.safetensors, scheduler/scheduler_config.json, }) strict: bool True # 新版严格 def snapshot_download(self, local_files_only: bool): missing self.manifest - self.local if local_files_only and self.strict and missing: raise RuntimeError(fIncompleteSnapshotError: 缺 {missing}) # 旧版宽松缺可选文件也能用 if local_files_only and not self.strict: return loaded with local only return loaded hub_new FakeHub(strictTrue) try: hub_new.snapshot_download(local_files_onlyTrue) except RuntimeError as e: print(新版离线炸:, e) hub_old FakeHub(strictFalse) print(旧版离线:, hub_old.snapshot_download(local_files_onlyTrue)) # 正常跑出来新版严格校验下缺README.md即IncompleteSnapshotError旧版宽松能过。这就是「离线启动被拦」的精确复现。五、解决方案第一层最小直接修复最小修复离线场景改用snapshot_download(..., local_files_onlyTrue, allow_patterns...)只下必需文件并在捕获IncompleteSnapshotError时回退到「用本地已有的、忽略完整性」的加载或预下载时把可选文件也一并拉齐。import os from huggingface_hub import snapshot_download from diffusers import DiffusionPipeline def offline_load(repo_id, local_dir, allow_patternsNone): # 1) 预下载明确只拉必需文件避免可选文件拖垮完整性 if not os.environ.get(HF_HUB_OFFLINE): snapshot_download( repo_id, local_dirlocal_dir, allow_patternsallow_patterns or [*.safetensors, *.json, *.bin], ) # 2) 离线加载捕获完整性错误回退到本地已有 try: return DiffusionPipeline.from_pretrained(local_dir, local_files_onlyTrue) except Exception as e: if IncompleteSnapshotError in str(e) or not fully cached in str(e): # 回退忽略完整性直接用本地文件构造 return DiffusionPipeline.from_pretrained(local_dir) raise pipe offline_load(runwayml/stable-diffusion-v1-5, ./sd15)要点预下载用allow_patterns限定必需文件使本地快照「刚好完整」不被可选文件干扰。离线加载捕获IncompleteSnapshotError后回退到「直接from_pretrained(local_dir)」用本地已有文件。必需文件齐全时回退路径能正常构造 pipeline。这一步单独就让离线部署不再被IncompleteSnapshotError卡死。六、解决方案第二层结构性改进第一层是「在下载处加回退」。但多个 pipeline、多环境都需一致处理。更稳的做法把「离线/在线下载与加载」收敛成单一守卫。from dataclasses import dataclass, field from typing import List, Optional import os dataclass class OfflineDownloadGuard: diffusers 离线下载/加载的单一守卫。 # 必需文件模式避免可选文件拖垮完整性 required_patterns: List[str] field(default_factorylambda: [ *.safetensors, *.bin, *.json, ]) # 是否强制离线 force_offline: bool False def is_offline(self) - bool: return self.force_offline or os.environ.get(HF_HUB_OFFLINE) 1 def download(self, repo_id: str, local_dir: str): from huggingface_hub import snapshot_download if self.is_offline(): return # 离线不下载直接用本地 snapshot_download( repo_id, local_dirlocal_dir, allow_patternsself.required_patterns, ) def load(self, local_dir: str, repo_id: Optional[str] None): from diffusers import DiffusionPipeline kwargs {local_files_only: True} if self.is_offline() else {} try: return DiffusionPipeline.from_pretrained(local_dir, **kwargs) except Exception as e: msg str(e) if IncompleteSnapshotError in msg or not fully cached in msg: # 回退忽略完整性用本地已有 return DiffusionPipeline.from_pretrained(local_dir) raise # 用法 guard OfflineDownloadGuard(force_offlineTrue) guard.download(runwayml/stable-diffusion-v1-5, ./sd15) pipe guard.load(./sd15)结构收益单一守卫离线判断、下载模式、加载回退都集中在OfflineDownloadGuard。可选文件隔离required_patterns让本地快照「恰好完整」。可回退完整性错误自动回退到本地加载离线启动稳。七、解决方案第三层断言 / CI 守护写 pytest 守三条(1) 离线时尝试下载被跳过(2) 完整性错误触发回退加载(3) 必需文件模式不含可选文件。import os import pytest from your_lib import OfflineDownloadGuard def test_offline_skips_download(monkeypatch, tmp_path): monkeypatch.setenv(HF_HUB_OFFLINE, 1) called {n: 0} guard OfflineDownloadGuard() def fake_snap(*a, **k): called[n] 1 import your_lib your_lib.snapshot_download fake_snap # 示意 guard.download(x, str(tmp_path)) assert called[n] 0, 离线不应尝试下载 def test_required_patterns_exclude_readme(): guard OfflineDownloadGuard() assert all(README not in p for p in guard.required_patterns) def test_load_falls_back_on_incomplete(monkeypatch, tmp_path): guard OfflineDownloadGuard(force_offlineTrue) # 模拟 from_pretrained 先抛 IncompleteSnapshotError再回退成功 states {call: 0} def fake_from(path, **kw): states[call] 1 if states[call] 1: raise RuntimeError(IncompleteSnapshotError: missing file) return pipeline-ok import your_lib your_lib.DiffusionPipeline type(X, (), {from_pretrained: staticmethod(fake_from)}) result guard.load(str(tmp_path)) assert result pipeline-ok assert states[call] 2CI 常驻跑这三条后任何「离线又去下载」「完整性错误没回退」的回归都会立刻爆红。八、排查清单IncompleteSnapshotError离线失败时按顺序查先确认是不是「在线正常、离线才炸」——是的话定位 hub 1.22 严格校验。检查本地是否缺可选文件README.md、未下变体它们会让快照「不完整」。预下载用allow_patterns限定必需文件使本地快照恰好完整。离线加载捕获IncompleteSnapshotError后回退到「直接from_pretrained(local_dir)」。确认HF_HUB_OFFLINE1或local_files_onlyTrue在离线环境正确设置。升级huggingface_hub后清掉旧版残留的缓存元数据.cache/huggingface重新拉一次。内网部署把必需文件打进镜像离线加载走回退路径别依赖运行时完整性校验。九、小结DiffusionPipeline.download()在huggingface_hub1.22.0离线模式报IncompleteSnapshotError根子是新版对快照完整性校验更严本地缺任一清单文件含可选文件或缓存元数据过期即拒而 diffusers 没为离线做兜底。修复三层次第一层预下载用allow_patterns限定必需文件、离线加载捕获完整性错误回退到本地第二层用OfflineDownloadGuarddataclass 把离线判断/下载/回退收敛为单一守卫第三层用 pytest 守「离线不下载」「完整性错误回退」「可选文件隔离」。工程启示离线/内网部署绝不能依赖运行时去 Hub 做完整性校验。正确姿势是「构建期用allow_patterns把必需文件拉齐打进镜像运行期local_files_only 完整性错误回退」。把可选文件排除在完整性口径外离线启动才稳。