Safetensors：格式规范

可视化演示

围绕格式规范展开深入探讨，从基本概念出发逐步深入到高级应用。内容涵盖AI编译器与系统软件、模型格式与序列化中的... 切换模式查看不同维度。

格式与安全背景

想象你收到一个写着“模型文件”的快递箱。撕开胶带，箱子里除了一堆参数，还有一张纸条：“请先执行下面的代码：删除所有数据。”正常快递不会这么做，但 PyTorch 默认的 .pt 文件基于 pickle 序列化，它在加载时会按“说明书”重建 Python 对象，说明书里可以藏着一行 __reduce__ 魔术代码，相当于让快递柜替你执行了纸条。

这就是所谓的任意代码执行（RCE）风险。黑客把恶意 pickle 文件发布到开源社区，任何人 torch.load 都会中招。Safetensors 正是为了终结这种局面：它统一采用“清单 + 货物”结构，清单是 JSON，货物是纯二进制张量，加载过程没有“执行纸条”这一步。

Safetensors（Safe Tensors）由 Hugging Face 主导设计，核心规格包含：8 字节长度前缀、UTF-8 编码的 JSON 头、按 offset 排列的数据区。它不像 pickle 保存 Python 对象图，而是保存跨框架可读的张量元数据与字节。所谓 safe，不是加密，而是从机制上移除了代码执行通道。

于是，新的集装箱从此只装货、不装人。码头工人不用读纸条，只需要对着清单取货，危险被扼杀在格式层面。

文件结构

集装箱侧壁会有一张货物清单，写明每件货在哪个位置、有多重。Safetensors 文件也有一张固定位置的清单：最开头 8 个字节记录 JSON 头的长度，紧接着是 JSON 元数据，再往后才是整整齐齐的数据区。

8 字节长度前缀是小端无符号整数，值为 N。程序先读这 8 字节，知道有多少 JSON 要解析；然后读取 JSON 头，里面为每个张量记录 dtype、shape、data_offsets。data_offsets 是 [begin, end]，表示该张量在数据区中的字节范围。

例如 {"weight": {"dtype": "F32", "shape": [4, 4], "data_offsets": [0, 64]}}。实际文件中的字节位置还要加上头部占用长度，因此计算方式如下。

码头工人看一眼清单，就知道“W 在数据区第 0 到 64 字节”，全程不需要拆开别的货物。

序列化写入

装箱员的工作分三步：先清点货物，再写清单，最后按清单把货一件件码进箱内。Safetensors 的写入流程与此完全一致。

第一步收集所有张量的 dtype、shape 和字节数；第二步将这些元数据编码成 JSON 头，并预留 8 字节长度字段；第三步把张量数据按顺序拼接。重点是共享去重：如果多个键引用同一个底层 Tensor 对象，Safetensors 只写入一份字节，多个键在 JSON 头中指向同一段 data_offsets。

为了后续读取高效，数据区起点还要做 8 字节对齐。JSON 头长度不一，需要在头部末尾填充空白字节，使数据区从 8 的倍数位置开始。计算公式如下。

像集装箱要求四角对齐，张量数据也对齐码放，叉车才能一下插中重心。

反序列化读取

过去卸货要把整艘船的集装箱都搬进仓库，再拆包找货。Safetensors 的加载方式更像“把集装箱挂在仓库门口”，需要哪件取哪件。

核心实现是 mmap（内存映射）。safe_open 调用 mmap 将整个文件映射到进程虚拟地址空间，返回一个 SafeTensors 句柄；get_tensor(key) 时，解析 JSON 头里的 data_offsets，直接在映射区域切片，得到内存视图。

这意味着惰性加载：打开文件时并不把全部数据读进物理内存，只有真正访问某个张量的页面，操作系统才会按页调入。对 70B 大模型，可以只加载推理需要的部分权重，避免 OOM。张量字节长度计算如下。

按需卸货让 70B 模型的加载不再“一把梭”，这也是大模型推理服务能秒级启动的秘密之一。

对齐与优化

集装箱码放讲究边角对齐，歪歪扭扭会让叉车反复调整。Safetensors 在格式层面同样强调对齐与连续。

头部之后的填充字节使数据区起始地址按 8 字节对齐；所有张量数据连续存放，不夹杂多余描述信息；读取时配合 mmap 和零拷贝，可以直接把文件里的字节当作内存中的张量，不需要逐块复制。

对齐的意义在底层：x86/ARM 对非对齐访问可能需要多次载入指令，对齐后单次访存即可；SSD 顺序读取大块连续数据也比随机小 IO 快得多。需要填充的字节数公式如下。

就像叉车插入托盘的位置被标准化，Safetensors 通过对齐让每一次取货都快、稳、省。

工程应用

如今全球大多数开源大模型的“码头”都已换装这种标准集装箱。Hugging Face Hub 上的模型仓库，普遍同时提供 .safetensors 文件。

transformers 的 from_pretrained 会自动优先加载仓库中的 safetensors 版本；若只有 .bin，才会回退到 pickle。官方还提供 convert.py 等脚本，把老式 .bin / .pt 一键转换成 .safetensors。

生态上，safetensors 库提供了 save_file、load_file、safe_open 三组核心 API，并支持 PyTorch、TensorFlow、Flax、NumPy 多种框架绑定。工程最佳实践包括：发布模型时一律附带 safetensors；加载时用 safe_open + mmap 按需获取权重；训练 checkpoint 用共享去重节省磁盘。

集装箱标准一旦统一，全球码头都能无缝对接——AI 工程化也因此更安全、更高效。

AI 应用场景

Python 演示

import jsonimport numpy as npfrom safetensors import safe_openfrom safetensors.numpy import save_file  def main():    shared = np.random.randn(2, 3).astype(np.float32)    tensors = {        "w": shared,        "b": np.zeros(3, dtype=np.float32),        "w_copy": shared,    }    save_file(tensors, "demo.safetensors")     with open("demo.safetensors", "rb") as fh:        header_len = int.from_bytes(fh.read(8), "little")        header = json.loads(fh.read(header_len))        print(json.dumps(header, indent=2))     with safe_open("demo.safetensors", framework="numpy") as f:        print(f.keys())        print(f.get_tensor("w").shape)  if __name__ == "__main__":    main()

1. header_len = int.from_bytes(fh.read(8), "little")读取文件前 8 字节，按小端解析出 JSON 头长度。
2. header = json.loads(fh.read(header_len))按长度读取并解析 JSON 头，得到每张量的元数据。
3. save_file(tensors, "demo.safetensors")把张量字典写入一个 safetensors 文件。
4. "w_copy": shared让两个 key 引用同一个底层数组，验证只写一份数据的去重机制。
5. safe_open("demo.safetensors", framework="numpy")用 mmap 惰性打开文件，不立即读入全部字节。
6. f.get_tensor("w")按 key 定位 data_offsets，只取出这一个张量。

常见误区

面试题