模型加载报 header / deserializing 错：改配置全白搭，先比对文件大小

报 Error while deserializing header 或 unexpected end of file，很多人第一反应是去调参数、换插件 —— 但这类报错改任何配置都没用，因为文件本身就是坏的。大模型动辄几 G 到几十 G，HTTP 下载中断很常见，而且中断的文件会留在原地，看起来「文件在」，其实只有一半。判据是最简单的一条：文件字节数和发布页标称大小对不上，就是没下完。

这条适用于

• 模型文件下载过程曾中断 / 断点续传
• 报的是 header / deserializing / unpickling 类错误

版本指纹

Windows 11 + ComfyUI；模型放英文路径；HF 镜像 hf-mirror.com（可用性随时间变）

具体做法

# ① 先比对大小：这是最快的判据
$ ls -l /path/to/model.safetensors
$ du -h /path/to/model.safetensors
# 与 HuggingFace / 发布页标的 Size 对照；差一截 = 没下完

# ② 清掉残留的不完整文件（不要在原文件上续传：头已坏）
$ rm -f /path/to/model.safetensors
$ rm -f /path/to/*.part /path/to/*.tmp

# ③ 用支持断点续传的方式重下（推荐 huggingface-cli）
$ huggingface-cli download <repo_id> <filename> --local-dir /path/to
$ huggingface-cli download <repo_id> <filename> \
    --resume-download --local-dir /path/to

# ④ 国内加速（HF 直连慢/易断时）
$ export HF_ENDPOINT=https://hf-mirror.com
$ export HF_HUB_ENABLE_HF_TRANSFER=1     # 需先 pip install hf_transfer

# ⑤ 校验哈希（发布页一般给 sha256）
$ sha256sum model.safetensors
# Windows: certutil -hashfile model.safetensors SHA256

← 返回全部排错方案