safetensors 的加载方式
safetensors 用内存映射的方式加载权重：文件内容直接映射进地址空间，不需要反序列化整份数据，因此启动快，也避免了 pickle 反序列化带来的风险。大模型通常按大小切成多个分片文件，再用一个索引文件描述每个张量落在哪个分片里；缺了这个索引，部分框架就无法自动合并加载。
目录结构与快速校验
目录结构与快速校验
# 先看目录里的文件构成
ls models/<模型>/ # 关注 config.json、tokenizer 相关文件、分片与索引
ls models/<模型>/*.safetensors | wc -l # 分片数量
# 校验单个分片能否完整解析（能打开不等于张量齐全）
python -c "from safetensors.torch import load_file; load_file('models/<模型>/model-00001-of-00004.safetensors')"
# 与仓库里的文件清单比对大小，确认下载完整
ls -l models/<模型>/ | head文件与作用
| 文件 | 作用 | 缺失后的表现 |
|---|---|---|
| config.json | 模型结构、精度与注意力相关配置 | 加载阶段报配置缺失或按错误结构初始化 |
| tokenizer 相关文件 | 分词与词表 | 分词结果错误，输出异常 |
| 权重分片文件 | 实际权重数据 | 加载失败或张量缺失 |
| 分片索引文件 | 描述张量与分片的映射 | 多分片模型无法自动合并 |
| 对话模板文件 | 提示词渲染模板 | 对话格式错乱，回答答非所问 |
典型使用场景
- 下载后核对完整性：确认分片数量、索引与配置文件齐全
- 排查加载失败：先确认文件齐备，再怀疑框架与显存
- 离线搬迁：整个目录一起搬，只搬权重文件会缺模板与配置
- 多机分发：在共享盘下好后分发，避免每台机器重复下载
- 格式转换：作为转换到其他格式的输入，转换后要用固定用例回归
下载中断产生的半截文件有时仍能被打开，但张量不完整：加载前的文件大小核对比事后翻日志省事得多。
文件大小与仓库标注不一致通常意味着下载未完成：先补全再排查框架，否则会把时间花在错误的方向上。