首页/AI/大模型部署与运维速查/safetensors 加载与常见问题
部署形态与选型43 条

safetensors 加载与常见问题

safetensors 以内存映射方式加载权重,启动快且避免 pickle 反序列化风险;多分片模型依赖 .index.json 描述分片与张量映射关系。

目录结构与快速校验

目录结构与快速校验
ls models/<模型>/*.safetensors
head models/<模型>/model.safetensors.index.json
# 校验单个分片能否完整解析
python -c "from safetensors.torch import load_file; load_file('models/<模型>/model-00001-of-00004.safetensors')"
优点内存映射加载、无 pickle 反序列化风险
多分片由 model.safetensors.index.json 描述
兼容vLLM/TGI/Transformers 原生支持
下载中断产生的半截文件有时仍能打开但张量缺失,加载前核对文件大小与清单更省事。

易错点

  • 文件大小与仓库标注不一致通常是下载未完成,先补全再排查框架

数据来源与参考

  • Hugging Face safetensors 文档(huggingface.co/docs/safetensors)
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌