现象
服务器上执行 from_pretrained 加载 7B 模型,transformers 4.44 报 SafetensorError: Error while deserializing header,换成 safetensors 直接打开单文件也是同样结果,但同目录下的 Config.json 能正常读取,说明目录本身没挂错。
原因
这个报错表示文件头部不是合法的 safetensors 结构,基本等于文件不完整。常见来源是下载中断留下半截文件、磁盘写满、把 git lfs 的指针文件当成权重、或者手工拼接分片。缓存目录里混入旧版本文件时,from_pretrained 会优先命中坏的那一份,看起来就像模型本身有问题。
解决步骤
第一步,核对文件大小。拿模型页面给出的字节数和本地对比,差得多的直接删掉重下,不要在坏文件上做断点续传。
du -sh qwen7b
ls -lh qwen7b/*.safetensors
python - <<'EOF'
from safetensors import safe_open
f = safe_open("qwen7b/model-00001-of-00004.safetensors", "pt")
print(len(f.keys()))
EOF
第二步,用官方客户端重下。snapshot_download 会校验分片并按清单补齐,比手工 wget 稳定;下载前把缓存指到大盘,留出模型体积两倍的空间。
第三步,检查索引文件。model.safetensors.index.json 里列出的分片必须一个不少,缺任何一个都会在加载时报张量找不到,而不是明确提示文件缺失。
验证
safe_open 能列出全部张量名,from_pretrained 加载后打印的参数量与模型卡片一致;跑一次前向不报形状错误,说明权重完整可用。
小结
safetensors 的头部错误几乎都是文件损坏。先比大小,再用官方客户端重下,最后核对索引,别在坏文件上反复试错。
