模型文件下载不完整怎么查？Safetensors 分片、索引与完整性校验

模型文件已经下载到本地，启动时却提示找不到分片；换一份文件之后又遇到 Safetensors 解析错误。遇到这种情况，先不要反复调整显存参数。应该先回答三个问题：索引引用的文件是否齐全，文件结构是否能被解析，文件字节是否与可信来源一致。

本文给出一个可运行的 Python 检查脚本，并用两个很小的模拟权重文件演示缺失、截断和同大小内容变化。检查过程不启动推理、不需要 GPU，也不需要模型 API Key。范围限定为带有 model.safetensors.index.json 的分片权重，不重复讲 HF CLI 安装或模型格式转换。

Table of Contents

一、先区分四种“检查通过”

检查层次	能发现什么	不能证明什么
文件存在	分片缺失、空文件、失效链接	文件内容正确
结构与索引	部分截断、头部解析失败、张量名与索引不符	所有数值都与原版本一致
可信基准校验	受检文件的大小或 SHA-256 与基准不一致	基准本身可信、模型行为安全
实际加载与任务验证	模型结构、配置、运行环境或任务结果的问题	完整的供应链安全保证

最容易漏掉的是第三层：一个合法的浮点数被改成另一个浮点数后，文件大小可能不变，Safetensors 结构也仍然合法。只有与独立保留的可信基准比较，才有机会发现这种内容变化。反过来，文件一致也不代表模型没有后门或不可信代码。

二、分片索引怎么读？不要只数文件数量

Transformers 的分片检查点通过索引中的 weight_map 记录“张量名对应哪个权重文件”。应检查索引实际引用的文件集合，不能只凭文件名里的 of-00002 判断下载是否完整。官方说明见 Transformers 分片检查点文档。


1
2
3
4
demo-model/

├── model.safetensors.index.json

├── model-00001-of-00002.safetensors

└── model-00002-of-00002.safetensors

下面是本文模拟数据的索引。它只有两个张量，不能作为真正的预训练模型加载：


1
2
3
4
5
6
7
{

  "metadata": {"total_size": 16},

  "weight_map": {

    "layer_a.weight": "model-00001-of-00002.safetensors",

    "layer_b.weight": "model-00002-of-00002.safetensors"

  }

}

metadata.total_size 是张量数据大小的元信息，不应直接拿它与所有分片的磁盘文件大小总和作相等判断；分片还含有头部等格式开销。本文脚本不依赖这个数值，而是逐个检查索引引用、张量名集合与文件校验值。

三、下载脚本并准备环境

下载完整示例：Safetensors 分片检查工具 ZIP。压缩包包含 check_model.py、make_demo.py 和使用说明，不包含真实模型权重。下载解压后，在该目录中打开终端。文章示例针对 Python 3.11；本次实际验证环境为 Windows、Python 3.11.7、safetensors 0.7.0、numpy 1.24.4。


1
2
3
4
5
6
7
python -m venv .venv

# Linux / macOS:

source .venv/bin/activate

# Windows PowerShell 使用下面这一行替代上面的激活命令：

# .\.venv\Scripts\Activate.ps1

python -m pip install safetensors==0.7.0 numpy==1.24.4

python make_demo.py

numpy 只用于生成演示权重；检查脚本本身使用 Python 标准库和 safetensors。如果终端中的 python 指向 Python 2 或其他环境，请改用本机 Python 3.11 的可执行文件。生成器拒绝覆盖已有的 demo-model 目录；重复演示请使用新的解压目录。

四、检查脚本具体做什么？

完整实现以压缩包中的文件为准。它读取指定索引，拒绝重复 JSON 键与明显越界的相对路径，然后检查每个分片，并把实际张量名集合与索引分配逐项对照。下面是关键逻辑节选，不是单独可运行的完整程序：


1
2
3
4
5
6
7
8
9
10
11
12
13
14
from safetensors import safe_open



# expected[name] 是索引分配给这个分片的张量名集合。

with safe_open(str(path), framework="np") as handle:

    actual = set(handle.keys())

if actual != expected[name]:

    raise ValueError("tensor keys mismatch")



# 逐块读文件计算摘要，避免一次把全部权重读入内存。

digest = hashlib.sha256()

with path.open("rb") as handle:

    for block in iter(lambda: handle.read(1024 * 1024), b""):

        digest.update(block)

sha256 = digest.hexdigest()

使用官方 Safetensors 解析器读取键集合，不会实例化模型，也不会调用 get_tensor() 把整份权重变成 NumPy 数组。计算 SHA-256 仍需读完整个文件，因此大模型检查主要消耗存储读取时间；进行检查前应停止下载、同步和其他写入。解析器的使用方式可参考 Safetensors 官方文档。

脚本按索引选择分片，目录中其他 *.safetensors 文件会产生 WARN，不会被悄悄加入模型。额外文件可能是旧版本或另一套权重，应人工确认用途。脚本允许跟随符号链接，以兼容常见本地缓存结构；只在自己控制且可信的目录中使用，它不是文件系统隔离工具。

五、先建立可信基准，再检查目标副本

演示文件由我们刚刚生成，可以用来学习建立基准的过程：


1
2
python check_model.py demo-model --write-manifest reference.json

python check_model.py demo-model --manifest reference.json

正常情况下，每个文件输出 OK，最后显示：


1
PASS: structure + indexed tensor keys + reference hashes

reference.json 是本文工具的自定义基准格式，并非 Hugging Face 通用清单。它记录索引文件及其引用分片的大小和 SHA-256，不包含其他配置或 tokenizer 文件。示意如下，省略号仅用于展示，不能直接作为有效校验值使用：


1
2
3
4
5
6
7
8
{

  "schema": 1,

  "files": {

    "model.safetensors.index.json": {"size": 245, "sha256": "..."},

    "model-00001-of-00002.safetensors": {"size": 88, "sha256": "..."},

    "model-00002-of-00002.safetensors": {"size": 88, "sha256": "..."}

  }

}

真实使用时，应在已经核验来源和版本的原始副本上生成基准，独立保存后再验证目标副本，并记录仓库、完整 commit、获取日期与基准来源。如果是怀疑首次下载已经损坏，不能先对这份可疑文件生成基准，再说“自己和自己一致”。需要从可信发布者取得对应校验信息，或重新获取同一版本的已知可信副本。

脚本使用独占创建方式写基准，不覆盖已有 reference.json，避免排错过程中把错误状态覆盖成新基准。也不要将“SHA-256 算出来了”理解为“已经验证”：没有可信预期值时，摘要只是这份文件当前状态的指纹。

六、动手演示：少一个分片会怎样？

以下操作只针对刚生成的 demo-model，不操作真实缓存。使用 Python 移走第二个模拟分片：


1
2
python -c "from pathlib import Path; p=Path('demo-model/model-00002-of-00002.safetensors'); p.rename(str(p)+'.hold')"

python check_model.py demo-model --manifest reference.json

检查结果会包含以下提示，并以退出码 1 结束：


1
2
FAIL model-00002-of-00002.safetensors: missing, empty or broken symlink

FAILED: 1 file(s)

恢复原文件后再次执行同一条检查命令，应重新通过：


1
2
python -c "from pathlib import Path; p=Path('demo-model/model-00002-of-00002.safetensors.hold'); p.rename(p.with_suffix(''))"

python check_model.py demo-model --manifest reference.json

七、为什么文件大小一样，也可能有问题？

在同一个模拟分片的最后一个字节上翻转一位，可以演示“大小不变、结构仍合法、内容已经变化”。先确认上一节已经恢复文件，再执行：


1
2
3
python -c "from pathlib import Path; p=Path('demo-model/model-00002-of-00002.safetensors'); b=bytearray(p.read_bytes()); b[-1]^=1; p.write_bytes(b)"

python check_model.py demo-model

python check_model.py demo-model --manifest reference.json

第一条检查没有提供基准，仍可能显示：


1
PARTIAL: structure checked; no trusted reference hashes

第二条会报告 size or SHA-256 mismatch。这就是不能仅凭“同样大、能解析”判断内容未变的原因。在这个特定模拟文件上，再执行一次相同的翻转命令会恢复原字节，随后带基准校验应通过。真实文件不能靠猜测字节进行修复，应重新取得同一可信版本的文件。

八、本次验证结果与脚本边界

以下是对本文小型合成分片执行的验证，不是对真实大模型做过完整加载或推理测试：

场景	本次观察到的结果
正常分片与已知基准	检查通过
移走一个被引用分片	报告缺失，退出码 1
分片截断一个字节	解析失败，退出码 1
等长修改张量数据	无基准时结构检查通过；带基准时发现摘要不一致
索引与分片的张量名不匹配	报告张量名不符，退出码 1
额外放入未引用权重	发出 WARN；已引用文件的校验仍可通过
索引含上级路径或重复 JSON 键	拒绝输入，退出码 2
试图覆盖已有基准	拒绝覆盖，退出码 2
恢复模拟分片后复查	再次通过

退出码 0 只代表所请求的检查完成且未发现失败。未提供基准时，退出码 0 仍然只是结构检查通过；额外文件的 WARN 也不会使它变成非零。自动化流水线应明确要求 --manifest，并按自己的目录策略处理 WARN，不能只看绿色提示。

九、排错时优先检查这些情况

现象	下一步
没有默认索引	确认是否为单文件模型、适配器、其他格式或另一套索引；可用 `--index` 指定索引，不要臆造 weight_map
分片存在但解析失败	检查是否是 Git LFS 指针文本、下载错误页面、空文件或截断文件，再核验来源与版本
文件集合与基准不同	先核对版本与索引是否成套，不能直接重建基准绕过问题
摘要不一致	停止使用目标副本；检查传输、磁盘和版本混用，重新获取对应文件
权重检查通过但仍加载失败	继续核对 config、tokenizer、适配器、框架版本、算子与内存；这些不在本工具覆盖范围内

混入另一版本的分片时，如果张量名相同，结构检查未必能发现；只有与正确版本的可信校验值对照，才能检查字节是否一致。索引本身也必须进入基准，否则只校验部分权重容易漏掉索引变化。大型仓库还可能同时包含多个模型组件，本工具默认只检查你指定的那一套索引。

需要重新下载时，使用同一仓库的固定完整 commit，而不是混用不同时间的 main。Hugging Face 官方支持通过 revision 指定版本，见文件下载文档。不要直接修改缓存指向的文件做实验；本文故障演示只对独立生成的数据进行。