AI 模型权重怎么检查？用 Safetensors 核对格式、张量形状与类型

检查 AI 模型权重时，可以先用 Safetensors 核对文件是否可解析、有哪些张量、形状和数据类型是否符合预期，再比较来源和文件哈希。这个过程能发现格式损坏或结构契约不一致，不能证明模型回答可靠，也不是对整个模型仓库的恶意代码扫描。

本例在 Windows、Python 3.11.15、PyTorch 2.6.0 CPU、Safetensors 0.8.0 下运行，自己构造三个小张量作为教学数据，并另做一个截断副本检验失败路径；没有打开未知第三方权重或评估真实模型行为。官方资料核对日期为 2026 年 10 月 1 日。

为什么先查格式和张量契约

Safetensors 官方介绍说明它是面向张量存储的格式，并提供 safe_open 的读取示例。相比 pickle 反序列化，采用这种格式可以避免把张量加载本身当作任意 Python 对象反序列化；但文件解析、依赖库和后续运行仍有各自边界。

• 格式能读取：解析器认可文件头和张量数据范围，不能仅凭 .safetensors 后缀推断。
• 契约一致：键名、形状、dtype 与目标模型定义相符；它们应来自已知模型配置或作者资料。
• 字节一致：和可信来源提供的哈希比对；自己算出一个哈希只是在建立记录。
• 行为可信：需要另外做任务测试、数据和风险评估；上述文件检查不能代替它。

创建并检查一个已知的演示文件

新建空练习目录并进入它，以下 Windows PowerShell 命令需要 Python 3.11 和首次安装网络：

py -3.11 -m venv .venv-weights
.\.venv-weights\Scripts\python.exe -m pip install "torch==2.6.0" --index-url https://download.pytorch.org/whl/cpu
.\.venv-weights\Scripts\python.exe -m pip install "safetensors==0.8.0"

保存完整代码为 inspect_weights.py，运行 .\.venv-weights\Scripts\python.exe -X utf8 inspect_weights.py。脚本在当前练习目录写入并可能覆盖两个专用演示文件：demo-weights.safetensors 和 demo-broken.safetensors，不读取你的现有权重。

官方 Torch API提供 save_file；0.8.0 官方绑定源码明确实现 get_slice、get_shape 和 get_dtype。这里通过切片对象读取形状和类型，不需要把每个完整大张量都复制到 GPU。

from pathlib import Path
import hashlib
import torch
from safetensors import safe_open, SafetensorError
from safetensors.torch import save_file

path = Path('demo-weights.safetensors')
demo = {'linear.weight': torch.arange(6, dtype=torch.float32).reshape(2, 3),
        'linear.bias': torch.zeros(2, dtype=torch.float32),
        'counter': torch.tensor([7], dtype=torch.int64)}
save_file(demo, path, metadata={'purpose': 'format-demo'})
expected = {'linear.weight': ([2, 3], 'F32'),
            'linear.bias': ([2], 'F32'), 'counter': ([1], 'I64')}
with safe_open(path, framework='pt', device='cpu') as f:
    assert set(f.keys()) == set(expected)
    print('metadata:', f.metadata())
    for key in sorted(f.keys()):
        view = f.get_slice(key)
        shape, dtype = view.get_shape(), view.get_dtype()
        assert (shape, dtype) == expected[key]
        print(key, shape, dtype)
print('sha256:', hashlib.sha256(path.read_bytes()).hexdigest())
print('tensor_contract: OK')

broken = Path('demo-broken.safetensors')
broken.write_bytes(path.read_bytes()[:10])
try:
    with safe_open(broken, framework='pt', device='cpu'):
        pass
except SafetensorError:
    print('truncated_copy: rejected')
else:
    raise AssertionError('损坏副本未被拒绝')

读懂输出，并找到三类差异

metadata: {'purpose': 'format-demo'}
counter [1] I64
linear.bias [2] F32
linear.weight [2, 3] F32
tensor_contract: OK
truncated_copy: rejected

这是实际运行输出的主要部分。I64 表示 64 位整数，F32 表示 32 位浮点数；linear.weight 为 2×3，符合演示定义。tensor_contract: OK 表示键集合、每个形状和类型都与 expected 一致；truncated_copy: rejected 表示专用截断副本被解析器拒绝，不是“所有损坏或攻击都已被检测”的结论。

实际文件的 SHA-256 也会输出。Safetensors 允许元数据键的序列化次序不同，重新生成演示文件时哈希可能变化；应把哈希用于已取得文件的前后字节比较，而不是强行要求读者生成的文件与本文同一个哈希。

把检查用于真实模型时

先保留下载地址、提交版本和发布者提供的校验值。读取指定文件后，把 expected 换成从真实模型结构和配置得到的契约；大型分片模型还要按其索引确认所有分片以及整体键集合，不把单个文件通过当成完整模型通过。

metadata 是文件内自行声明的信息，不是签名或来源证明。能够解析 Safetensors 也不意味着同目录的 Python 代码、配置及后续自动执行步骤可信；不要为了查看键名随意启用未知仓库的自定义运行代码。

张量形状正确，就能直接加载到模型吗？

还要匹配键名、模型定义、预处理和实际输入输出。需要验证 PyTorch 权重重载后输出一致，可以继续阅读state_dict 本地保存与重载教程；想查看算子与连线，则是Netron 模型结构查看的任务。本篇的下一步是用可信契约定位具体差异，再进行对应框架的加载验证。