模型权重不带可执行代码,不代表每个检查器都在检查同一份模型含义。一个只有 118 字节的 Safetensors 文件,足以让审计逻辑写下“4 个 U8”,让真实加载器拿到“1 个 F32”。问题不在数据区被替换,数据区从头到尾只有四个字节;被替换的是 JSON 对象成员进入映射表时的解释权。

Safetensors 的文件头保存张量名、dtype、shape 与 data_offsets。格式说明禁止重复键,并明确提示并非每个解析器都会遵守这一限制。

对象

固定值

用途

解释器

CPython 3.13.12

生成文件、解析头部、调用 Python 绑定

Safetensors

0.5.2

目标加载器

源码归档

safetensors-0.5.2.tar.gz

SHA-256:cb4a8d98ba12fa016f4241932b1fc5e702e5143f5374bba0bbcf7ddc1c4cf2b8

数据区

00 00 80 3f

一个 little-endian F32 的 1.0,也可被描述成四个 U8

同一段四字节,审核器和加载器读出了两种张量

Safetensors 起始的 8 字节是无符号 little-endian 整数 N。其后恰好 N 字节是 UTF-8 JSON 头,剩余内容才是 data buffer。[1] 构造文件中,N=106,所以文件布局是 8 + 106 + 4。两个同名 w 都引用 [0,4],但首项将它定义为 U8/[4],末项将它定义为 F32/[1]。

先建立独立环境。Kali 的全局 Python 受 PEP 668 约束并不影响 venv,依赖安装发生在 .venv 内。

创建工作目录。

mkdir -p ~/safetensors-duplicate-key-lab
cd ~/safetensors-duplicate-key-lab
python3.13 -m venv .venv

固定 pip 的版本。这样能让安装日志与后续复查使用同一套 pip 行为。

.venv/bin/python -m pip install --disable-pip-version-check pip==24.3.1

安装目标 wheel。

.venv/bin/python -m pip install --disable-pip-version-check safetensors==0.5.2

枚举 venv 中真正参与实验的第三方依赖。

.venv/bin/python -m pip freeze

若用普通 Python dict 再调用 JSON 序列化,第一份 w 就会在写盘前被覆盖,测试对象不存在。

# make_samples.py
"""构造一个正常文件、一个重复名文件和一个偏移失败控制文件。"""

from __future__ import annotations

import hashlib
import struct
from pathlib import Path

OUTPUT_DIR = Path("samples")
DATA_BUFFER = bytes.fromhex("0000803f")

# 三个头部都没有尾部空白。重复名文件的两个 w 都指向同一段数据区。
HEADERS: dict[str, bytes] = {
    "normal.safetensors": (
        b'{"w":{"dtype":"F32","shape":[1],"data_offsets":[0,4]}}'
    ),
    "duplicate-last-wins.safetensors": (
        b'{"w":{"dtype":"U8","shape":[4],"data_offsets":[0,4]},'
        b'"w":{"dtype":"F32","shape":[1],"data_offsets":[0,4]}}'
    ),
    "duplicate-invalid-offset.safetensors": (
        b'{"w":{"dtype":"U8","shape":[4],"data_offsets":[0,4]},'
        b'"w":{"dtype":"F32","shape":[1],"data_offsets":[4,8]}}'
    ),
}


def write_safetensors(name: str, header: bytes) -> None:
    """写入 little-endian 头长度、JSON 头和固定 data buffer。"""
    blob = struct.pack("<Q", len(header)) + header + DATA_BUFFER
    path = OUTPUT_DIR / name
    path.write_bytes(blob)
    digest = hashlib.sha256(blob).hexdigest()
    print(f"{name}: header_len={len(header)} total_len={len(blob)} sha256={digest}")


def main() -> None:
    OUTPUT_DIR.mkdir(exist_ok=True)
    for name, header in HEADERS.items():
        write_safetensors(name, header)


if __name__ == "__main__":
    main()

运行构造器,写出三份固定样本,并打印文件长度与 SHA-256。三个哈希用于确认脚本或文件没有在截图前被误改。

.venv/bin/python make_samples.py

正常文件为 79704046079abf4a598ac667f78c51c2adcf0b1f08a718c3468a07b9941cb658,重复名通过文件为 383c2614f725abe65aaa20ca6a53d919d3dfc0be0ea259f968d690e15ec5601e,偏移失败文件为 cbcff3d9eb287bc07b86bab99a835e9d035478b9c4bc39a4dee38e86d11b527e。

只读取重复名通过样本的前 32 字节。这个范围覆盖 8 字节长度字段和 JSON 起始字节,尚未触及 data buffer。

od -An -tx1 -N 32 samples/duplicate-last-wins.safetensors

十六进制开头是:

前 8 字节 6a 00 00 00 00 00 00 00 按 little-endian 解为十进制 106,JSON 头由文件偏移 0x08 延伸到 0x71;data buffer 因而只能从 0x72 开始。7b 22 77 22 是 ASCII 的 {"w",与构造器里第一份张量名一致。这个字节序列排除了“第二份 w 位于头长度之外”或“读取区间误把 data buffer 当 JSON”两种解释:两个同名成员都被长度字段包含,00 00 80 3f 仍只出现一次。

文件偏移        原始字节或语义
0x00—0x07      6a 00 00 00 00 00 00 00    JSON头长度:106
0x08—0x71      { "w": {无符号8位,4个元素,偏移0至4},
                 "w": {单精度浮点,1个元素,偏移0至4} }
0x72—0x75      00 00 80 3f                唯一的 data buffer

首项和末项都引用偏移0至4;差别只在 dtype 与 shape。

HashMap 接到头部时,原始成员序列已经消失

源码需要从与 wheel 同版本的 PyPI 归档读取。GitHub 访问失败不会影响这一步;归档本身经 SHA-256 固定后再解包。

清理旧归档和旧源码目录,避免把不同版本的文件混在一起。

rm -rf safetensors-0.5.2 safetensors-0.5.2.tar.gz

下载 PyPI 发布的 0.5.2 源码归档。--fail 让 HTTP 错误返回非零,--proto 限制为 HTTPS。

curl --fail --location --proto '=https' -o safetensors-0.5.2.tar.gz https://files.pythonhosted.org/packages/f4/4f/2ef9ef1766f8c194b01b67a63a444d2e557c8fe1d82faf3ebd85f370a917/safetensors-0.5.2.tar.gz

校验发布归档的 SHA-256。只有摘要完全一致时才应继续读取源码。

echo 'cb4a8d98ba12fa016f4241932b1fc5e702e5143f5374bba0bbcf7ddc1c4cf2b8  safetensors-0.5.2.tar.gz' | sha256sum --check --strict

展开已经通过校验的归档。

tar -xzf safetensors-0.5.2.tar.gz

​

打印 Rust 核心中读取长度、解析 JSON、建立映射和调用校验的相邻行。

nl -ba safetensors-0.5.2/safetensors/src/tensor.rs | sed -n '290,319p;431,454p'

第 313 行把 JSON 头转进 Metadata,第 315 行才校验偏移。第 437–438 行将顶层张量描述展平到 HashMap<String, TensorInfo>,第 446 行取回映射结果。

打印 Python 绑定进入 Rust 核心的调用行。

nl -ba safetensors-0.5.2/bindings/python/src/lib.rs | sed -n '166,188p'

293 let n: usize = u64::from_le_bytes(arr);
307 core::str::from_utf8(&buffer[8..stop]);
313 let metadata: Metadata = serde_json::from_str(string)
315 let buffer_end = metadata.validate()?;
437 #[serde(flatten)]
438 tensors: HashMap<String, TensorInfo>,
446 let hashdata: HashMetadata = HashMetadata::deserialize(deserializer)?;
169 let safetensor = SafeTensors::deserialize(bytes)

Python 绑定第 169 行直接调用 Rust 的 SafeTensors::deserialize。这里的顺序意味着 Safetensors 的偏移检查面对的是已经映射化的描述,不是保留全部重复成员的原始 JSON 序列。至于映射最终采用末项,由运行记录而不是类型名证明。

首见审计拿到 U8,加载器拿到 F32

同一段头部交给三种规则:标准 JSON 映射采用末项,首见审计器保留第一次出现的成员,严格解析器拒绝重复成员。代码需要保留 object_pairs_hook 传入的成员序列;对 json.loads() 的返回字典再做检查已经晚了。

# inspect_header.py
"""并排显示标准映射、首见映射与严格拒绝对同一文件头的处理。"""

from __future__ import annotations

import json
import struct
import sys
from pathlib import Path
from typing import Any, Callable


class DuplicateName(ValueError):
    """JSON 对象中出现第二个同名成员时抛出。"""


def split_safetensors(blob: bytes) -> tuple[int, bytes, bytes]:
    """按 Safetensors 头长度切出 JSON 头和 data buffer。"""
    if len(blob) < 8:
        raise ValueError("文件不足 8 字节")

    header_len = struct.unpack("<Q", blob[:8])[0]
    header_end = 8 + header_len
    if header_end > len(blob):
        raise ValueError("头长度超过文件长度")

    return header_len, blob[8:header_end], blob[header_end:]


def first_wins(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
    """保留同名成员的第一次出现,模拟错误的首见式审计逻辑。"""
    result: dict[str, Any] = {}
    for name, value in pairs:
        if name not in result:
            result[name] = value
    return result


def reject_duplicate(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
    """拒绝任何层级的重复对象成员。"""
    result: dict[str, Any] = {}
    for name, value in pairs:
        if name in result:
            raise DuplicateName(f"重复对象成员: {name}")
        result[name] = value
    return result


def show_tensor(label: str, mapping: dict[str, Any]) -> None:
    """打印 w 的 dtype、shape 和 data_offsets,便于横向比较。"""
    info = mapping["w"]
    print(
        f"{label}: w -> dtype={info['dtype']} shape={info['shape']} "
        f"offsets={info['data_offsets']}"
    )


def parse_with(
    label: str,
    header: bytes,
    hook: Callable[[list[tuple[str, Any]]], dict[str, Any]],
) -> None:
    """用指定的对象成员处理规则解析同一段原始 JSON。"""
    mapping = json.loads(header.decode("utf-8"), object_pairs_hook=hook)
    show_tensor(label, mapping)


def main() -> None:
    if len(sys.argv) != 2:
        raise SystemExit(f"用法: {Path(sys.argv[0]).name} 样本文件")

    path = Path(sys.argv[1])
    header_len, header, data = split_safetensors(path.read_bytes())
    print(f"文件: {path.name}")
    print(f"头长度: {header_len}")
    print(f"原始头: {header.decode('utf-8')}")
    print(f"数据区: {data.hex()}")

    parse_with("标准解析", header, dict)
    parse_with("首见审计", header, first_wins)
    try:
        parse_with("严格拒绝", header, reject_duplicate)
    except DuplicateName as error:
        print(f"严格拒绝: {error}")


if __name__ == "__main__":
    main()

脚本只读取指定文件,并依次在同一段 header 上执行三次 JSON 解析;它不调用 Safetensors。这里刻意把“审计规则造成的解释”与“目标加载器造成的解释”拆开,避免将两者混成一个输出。

.venv/bin/python inspect_header.py samples/duplicate-last-wins.safetensors

首项和末项都指向 [0,4],没有第二段 data buffer。首见逻辑把字节解释成 4 个 U8,标准逻辑把同一字节解释成 1 个 F32。严格规则不参与取舍,直接把文件挡在解析入口。Safetensors 加载器与标准 dict 在此文件上同为末项语义;检查—加载不一致只会出现在首见扫描、手写流式提取或其他未拒绝重复名的实现中。

metadata.validate() 只校验留下的记录

要证明“重复成员不是凭空绕过偏移校验”,必须保留失败控制。通过文件的末项为 [0,4];失败文件只把末项改成 [4,8]。首项没有变化,仍是 [0,4],但它已经不在映射中。

# load_with_safetensors.py
"""经 Safetensors 0.5.2 Python 绑定加载文件,并打印绑定返回的张量描述。"""

from __future__ import annotations

import platform
import struct
import sys
from pathlib import Path

import safetensors
from safetensors import SafetensorError, deserialize


def main() -> None:
    if len(sys.argv) != 2:
        raise SystemExit(f"用法: {Path(sys.argv[0]).name} 样本文件")

    path = Path(sys.argv[1])
    print(f"CPython: {platform.python_version()}")
    print(f"safetensors: {safetensors.__version__}")

    try:
        tensors = deserialize(path.read_bytes())
    except SafetensorError as error:
        print(f"加载失败: {error}")
        raise SystemExit(2)

    for name, info in tensors:
        payload = bytes(info["data"])
        print(
            f"加载结果: {name} -> dtype={info['dtype']} "
            f"shape={list(info['shape'])} data={payload.hex()}"
        )
        if info["dtype"] == "F32" and len(payload) == 4:
            print(f"按 F32 小端解释: {struct.unpack('<f', payload)[0]}")


if __name__ == "__main__":
    main()

先加载末项为 [0,4] 的通过文件。这里看的是 Safetensors 绑定最终交给调用方的 dtype、shape 和 data:

.venv/bin/python load_with_safetensors.py samples/duplicate-last-wins.safetensors

再加载只把末项偏移改为 [4,8] 的失败文件。首项仍为 [0,4],因此报错只可能来自映射中保留的末项。

.venv/bin/python load_with_safetensors.py samples/duplicate-invalid-offset.safetensors

单独打印刚才失败命令的退出码。

printf '失败控制退出码: %s\n' "$?"

通过文件的末项完整覆盖 4 字节 data buffer,绑定返回 F32/[1]。失败文件的末项从 4 开始,metadata.validate() 返回 InvalidOffset("w")。首项没有机会替末项补位,因为它已被映射规则覆盖。这里不是偏移校验失效,而是校验器只校验存活的描述。

[图 3:同一个张量名在三种规则下的终态]

重序列化不能把被覆盖的 w 找回来

普通 JSON 解析先建立映射,再序列化。重复名在第一步已经不存在,第二步当然无法恢复它。将同一头部交给标准库得到的文本只保留末项:

先从文件头取出 N,再把原始 JSON 交给默认 dict,最后重序列化结果。它不改写样本文件;输出中若只剩一个 w,说明信息是在映射构建时而不是写回磁盘时消失的。

.venv/bin/python -c 'import json,struct,pathlib; b=pathlib.Path("samples/duplicate-last-wins.safetensors").read_bytes(); n=struct.unpack("<Q", b[:8])[0]; print(json.dumps(json.loads(b[8:8+n]), separators=(",", ":")))'

这个结果与一个天生只含 F32 的正常头完全相同。依赖“JSON 解析后再检查键是否重复”的审计流程没有补救空间,检测点必须位于原始头字节被转成普通映射之前。

拒绝器放在 deserialize 之前

修补无需改动 Safetensors 0.5.2 的二进制扩展。上传服务、模型分发平台代理或离线检查器读取文件后,先按头长度截取 JSON,再以 object_pairs_hook 拒绝重复成员;只有通过后才把同一份 bytes 交给 deserialize。同一缓冲区还避免了“校验路径 A、加载时路径 A 已换成另一文件”的时间窗口。

# strict_header.py
"""在调用 Safetensors 前拒绝头部 JSON 中的重复对象成员。"""

from __future__ import annotations

import json
import struct
import sys
from pathlib import Path
from typing import Any

MAX_HEADER_SIZE = 100_000_000


class DuplicateName(ValueError):
    """头部 JSON 的任意对象层级出现重名成员时抛出。"""


def reject_duplicate(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
    """构建映射前检测重复名,避免标准 dict 覆盖证据。"""
    result: dict[str, Any] = {}
    for name, value in pairs:
        if name in result:
            raise DuplicateName(f"重复对象成员: {name}")
        result[name] = value
    return result


def validate_header(blob: bytes) -> dict[str, Any]:
    """提取并严格解析 Safetensors JSON 头,不读取或解释 data buffer。"""
    if len(blob) < 8:
        raise ValueError("文件不足 8 字节")

    header_len = struct.unpack("<Q", blob[:8])[0]
    if header_len > MAX_HEADER_SIZE:
        raise ValueError(f"头长度超限: {header_len}")

    header_end = 8 + header_len
    if header_end > len(blob):
        raise ValueError("头长度超过文件长度")

    header = blob[8:header_end]
    return json.loads(header.decode("utf-8"), object_pairs_hook=reject_duplicate)


def main() -> None:
    if len(sys.argv) != 2:
        raise SystemExit(f"用法: {Path(sys.argv[0]).name} 模型文件")

    path = Path(sys.argv[1])
    try:
        validate_header(path.read_bytes())
    except (DuplicateName, UnicodeDecodeError, json.JSONDecodeError, ValueError) as error:
        print(f"拒绝加载: {error}")
        raise SystemExit(2)

    print(f"允许加载: {path.name}")


if __name__ == "__main__":
    main()

先检查正常文件。通过结果表明严格规则不是对所有 Safetensors 的粗暴封禁。

.venv/bin/python strict_header.py samples/normal.safetensors

再检查重复名文件。此脚本在调用 deserialize 前结束,因此输出的拒绝来自头部成员检查,而不是 Safetensors 的偏移校验。

.venv/bin/python strict_header.py samples/duplicate-last-wins.safetensors

单独保留拒绝路径的退出码,便于接入 CI 或批量检查任务。

printf '重复名退出码: %s\n' "$?"

接入点可以保持很短:

--- a/model_loader.py
+++ b/model_loader.py
@@
 from safetensors import deserialize
+from strict_header import validate_header
 
 def load_weights(path):
-    return deserialize(path.read_bytes())
+    blob = path.read_bytes()
+    validate_header(blob)
+    return deserialize(blob)

模型仓库的检查器不能先建 dict 再谈安全

风险不在“带重复键的文件一定能改变模型行为”。本次文件只证明同一段字节可以在两个保留规则下获得两种 dtype/shape 描述。危险点在检查器和加载器规则不一致:一个首见式检查器可以据 U8/[4] 做统计、拦截或准入,末项加载器却按 F32/[1] 切出真实张量。两端都没有读错字节,却没有在描述同一份张量。

检测方应从文件头原始字节入手,而不是从解析后的 JSON 文本入手。数据流中出现 json.loads、JSON.parse、Go 的 map[string]T、Rust 的 HashMap 或 Java 的 Map 并不自动构成问题;问题出现在它们之前没有拒绝重复成员,而之后又把结果用于模型准入、张量统计、格式允许集或内容签名。签名信息也必须覆盖原始文件哈希,而不是仅覆盖被重序列化后的头部。

一个成熟的检查器应该把“重复对象成员”当作格式违规直接拒绝,并记录文件哈希、成员名和获取位置。这样做没有猜测加载器会选择首项还是末项,也不用依赖语言运行时的默认映射规则。模型文件的安全判断从这一步开始才有稳定对象:检查的头,和加载的头,是同一段字节、同一个成员序列、同一种解释。

引用资料

[1] Safetensors v0.5.2 README:文件布局、重复键限制与头部大小限制

[2] Safetensors v0.5.2 tensor.rs:头部读取、JSON 反序列化与 HashMetadata

[3] Safetensors v0.5.2 Python 绑定:deserialize 到 Rust 核心的调用

[4] Safetensors 文档:以 HTTP Range 读取元数据

[5] RFC 8259 第 4 节:JSON 对象名称唯一性与重复名互操作性

[6] PyPI:safetensors 0.5.2 的 CPython ABI3 Linux wheel