Safetensors：格式规范Format Spec

可视化演示

演示Safetensors文件头与数据区的组织方式：文件头以JSON存储张量元信息，数据区按偏移量连续排列二进制张量数据。

文件整体布局

把 Safetensors 文件想象成一艘集装箱货轮。船最前端钉着一块小小的电子牌，写着“本船舱单共有多长”；紧接着是驾驶舱里的纸质舱单，记录每个集装箱的名字、尺寸和货位；最后才是真正的货舱，里面整整齐齐地码着所有集装箱。Safetensors 的格式规范，就是这一整套“造船标准”：三块区域按顺序出现，任何解析器只要按标准施工，就能读懂这艘船。

在技术层面，一个 Safetensors 文件是连续的一段字节流。文件前 8 个字节保存一个整数，它表示 JSON 头部的字节长度；接下来是 JSON 格式的头部，记录张量的元信息；再往后就是二进制数据区，所有张量的原始数据一个接一个排列。解析器不需要“猜”，因为长度前缀把头部边界画得清清楚楚。

这个设计的精妙之处在于可读性与效率的平衡：JSON 头部是人类和工具都能读的“说明书”，而数据区是机器最喜欢的高密度二进制。两者之间不需要复杂的容器包装，也没有层层嵌套的对象结构。于是，文件既能被快速校验，也能被内存映射到进程地址空间，按需访问。

只要记住“长度牌 + 舱单 + 货物”的三段式布局，Safetensors 就不再是黑盒。你拿到任意一个文件，都可以像熟练的港口调度员一样，先量长度，再看舱单，最后精准卸货。

头部长度字段

一艘船停进港口，起重机操作员第一件事是看船头那块电子牌。电子牌不写货物内容，只写“舱单有多长”。没有它，操作员就不知道从哪里开始读舱单，也不知道舱单在哪里结束。Safetensors 文件的前 8 个字节，就是这块电子牌。

这 8 个字节按小端序保存一个无符号 64 位整数。小端序可以理解为“低位放在前面”：就像我们读数字时从个位开始。解析器用统一的规则把这 8 个字节还原成整数，这个整数就是 JSON 头部的字节数。头部在写入时还会做 8 字节对齐：如果 JSON 文本长度不是 8 的倍数，就在末尾补空格，让整个头部长度凑成 8 的倍数。这样数据区就能对齐到 8 字节边界，更适合底层硬件读取。

有了这个字段，读取器可以算出数据区起点：8 + 头部长度。它不需要扫描整个文件，也不需要尝试解析“可能很长”的头部，而是读一个整数、跳转一次、直接进入舱单。这个简单的 8 字节前缀，是整份格式规范最不起眼却最关键的“门把手”。

这块电子牌虽然只有巴掌大，却决定了整船货物能否高效卸运。一个 AI 工程师在加载模型时，可能不会直接看见这 8 个字节，但它就是所有快速加载魔法开始的地方。

JSON 元信息

现在，操作员走进驾驶舱，翻开舱单。舱单不是天书，而是白纸黑字的 JSON：每个集装箱的编号就是张量名，旁边标注着“货种”“尺寸”和“货位”。JSON 是互联网世界最通用的“白纸黑字”，人眼能读，程序能解析，几乎不需要专门定制复杂的二进制解释器。

Safetensors 的 JSON 头部正是这样一个对象。它支持一个保留字段 __metadata__ 存放文件级说明；其余每个键都是一个张量名，对应的值描述这个张量：dtype 表示数据类型，比如 F32、BF16、I64；shape 表示张量形状，比如 [4, 8]；data_offsets 表示这个张量的数据在数据区中的起止位置。头部可能还会带有少量空格填充，目的就是让头部长度对齐到 8 字节。

由于头部是 JSON，任何框架都可以用现成的 JSON 解析器打开它，而不必为“私有二进制元数据”单独写一套工具。这也让恶意文件更容易被人工检查：平台可以在加载数据前先审计头部，看看是否有可疑字段。用一个比喻说，舱单越透明，海关越放心。

JSON 元信息让 Safetensors 文件“透明可见”。即使你从未加载过某个模型，只要打开头部，就可以像读货运舱单一样，知道船上有哪些张量、各自多大、放在哪。这种透明性，是传统 pickle 格式给不了的。

张量数据区

舱单看完，真正的重头戏是货舱。货舱里没有包装盒，没有绳子，只有集装箱按顺序一个接一个紧密排列。Safetensors 的数据区也是这样：所有张量的原始二进制字节，按它们在头部出现的顺序连续拼接，中间没有分隔符、没有索引表、没有压缩流。

为什么要把数据区做得这么“朴素”？因为机器最喜欢的格式就是连续字节。连续可以内存映射：加载器把文件映射到内存后，数据区变成一段连续地址，张量可以直接复用这些字节，不需要额外拷贝。连续也可以随机定位：给定偏移区间，seek 到目标位置后一次性读出。它不存字符串、不存对象图，更不存可执行代码，因此反序列化时无需运行任何业务逻辑。

与常见的 Zip 或 pickle 不同，Safetensors 不做主动压缩。它追求的是“零拷贝”和“极速加载”，而不是把文件压到最小。对大型模型来说，推理时的加载时间往往比磁盘节省的那几 MB 更重要。数据区保持原始二进制，等于货舱里的集装箱本身已经是最适合搬运的状态。

这种“货物一个挨一个”的设计，可能让文件看起来不够花哨，但恰恰是效率的核心。真正专业的码头，往往不需要华丽的分拣系统，只需要一条笔直的传送带。

偏移量索引

舱单上每个条目都写着“第几排第几列”，吊机司机一眼就能定位。如果舱单只写“货物在船上”，司机就得翻遍全船。Safetensors 的 data_offsets 就是这种精确坐标：它给每个张量写清“从数据区起点算起，从第几个字节开始，到第几个字节结束”。

需要特别注意的是，data_offsets 不是相对文件开头的绝对地址，而是相对数据区起点的偏移。因此，要定位某个张量在文件中的真实位置，必须先算 8 + header_length 作为数据区起点，再加上这个相对偏移。这个设计让头部与数据区解耦：无论头部以后如何改动，数据区内部的坐标体系不会变。

有了偏移索引，读取器就能实现“随机读取”。比如一个文件里有 100 个张量，推理时只需要其中 2 个，加载器就不必读完整份文件。它可以计算目标张量的文件位置，精确地 seek 过去，只读取需要的字节。这就是大模型快速冷启动的基础之一。

有了这套索引，加载器就像拥有 GPS 的吊机，不需要绕路。AI 从业者在写高性能推理代码时，最惦记的往往就是这组坐标：它决定了一个权重文件能否被“按需读取”。

安全加载机制

传统 pickle 格式像一只“会自动爆炸的快递箱”：你只要 load 它，它就可能执行一段隐藏代码，可能是正常对象，也可能是恶意指令。这正是 AI 社区长期担心的供应链风险。Safetensors 的回应很朴素：我们只运集装箱，不接受“会自己动的箱子”。

Safetensors 的加载过程本质上只做三件事：读头部长度、解析 JSON、按偏移读取二进制。这三步都不需要执行文件里的代码。头部如果被篡改，解析器会在构建张量前发现异常；数据区里的字节无论是什么，都只是被当作普通数字处理。因此恶意代码没有“被触发”的机会。它不加密，不校验文件来源，而是从根上移除了“执行任意代码”这个危险入口。

这种设计也让平台可以做更细的防护。现代推理框架常使用 safe_open 结合内存映射打开文件，先查头部，再按需读取具体张量。无论是 Hugging Face Hub 的下载校验，还是企业内部模型仓库的扫描，都可以在加载前检查 JSON 舱单，而不用信任数据区的任何“行为”。

没有公式能描述“安全”，但你可以这样理解：pickle 是一封会自动朗读的信，Safetensors 是一箱沉默的货物。它不朗读，不执行，不表态；它只是安静地等待程序用明确的方式读取。这艘船最值钱的不是导航系统，而是它从不搭载“自动执行器”。

跨框架生态

当同一套集装箱标准被全世界港口接受，船就能在任意码头靠岸。Safetensors 从诞生起就绑定开源生态，而不是某一个深度学习框架的私有密码。它由 Hugging Face 推动，迅速被 PyTorch、JAX、Flax 等主流工具支持，成为模型仓库中最常见的权重格式之一。

在 AI 工程链路上，Safetensors 常常扮演“通用语言”：PyTorch 训练出的权重，导出成 Safetensors 后，可以被 JAX 推理服务读取；Hugging Face Hub 上的开源模型，也大量使用 Safetensors 作为默认权重格式。这种互操作能力，让模型不再被“框架锁死”，也让部署系统只需要实现一份格式解析器，就能服务来自不同训练框架的模型。

跨框架的背后，是格式规范本身的克制。它不保存特定框架的对象结构，不依赖 Python 运行时，不绑定 GPU 厂商，只保存最底层的“张量名 + 类型 + 形状 + 偏移 + 原始字节”。这种最小化设计，恰恰换来了最大化兼容。就像集装箱不关心里面装的是玩具还是机床，只关心尺寸合规，于是全世界港口都愿意为它改造设备。

对 AI 从业者来说，理解 Safetensors 格式规范，不只是读懂一个文件头，更是看懂现代模型交付的通用底座。当你把模型从训练环境搬到推理集群，或者在 Hub 上发布开源权重时，Safetensors 就是那张让所有港口都认的通行证。它用最简单的三段式布局，把安全、速度与开放同时装进了同一艘船。

AI 应用场景

Python 演示

import jsonimport struct  def write_safetensors_like(path, tensors):    header = {}    data = bytearray()     for name, (dtype, shape, raw) in tensors.items():        begin = len(data)        data.extend(raw)        end = len(data)        header[name] = {            "dtype": dtype,            "shape": shape,            "data_offsets": [begin, end],        }     header_bytes = json.dumps(header, separators=(",", ":")).encode("utf-8")    while len(header_bytes) % 8 != 0:        header_bytes += b" "     with open(path, "wb") as f:        f.write(struct.pack("<Q", len(header_bytes)))        f.write(header_bytes)        f.write(data)  def read_safetensors_like(path, tensor_name):    with open(path, "rb") as f:        header_len = struct.unpack("<Q", f.read(8))[0]        header_bytes = f.read(header_len)     header = json.loads(header_bytes)    begin, end = header[tensor_name]["data_offsets"]     with open(path, "rb") as f:        f.seek(8 + header_len + begin)        return f.read(end - begin)  if __name__ == "__main__":    fake_tensors = {        "embedding": ("F32", [4, 8], bytes(range(128))),        "weight": ("F16", [2, 3], bytes(range(12))),    }    path = "demo.safetensors"    write_safetensors_like(path, fake_tensors)    blob = read_safetensors_like(path, "embedding")    print("tensor bytes:", len(blob), "prefix:", list(blob[:4]))

1. header[name] = {...}为每个张量记录 dtype、shape 和数据区起止偏移，相当于写舱单。
2. json.dumps(header, separators=(",", ":"))把头部压缩成紧凑 JSON，节省空间且保持可读。
3. while len(header_bytes) % 8 != 0给 JSON 头部补空格，使其长度对齐到 8 字节。
4. struct.pack("<Q", len(header_bytes))用 8 字节小端整数写出头部长度，这是文件的第一块“长度牌”。
5. f.seek(8 + header_len + begin)从数据区起点再加相对偏移，精确跳转到目标张量。
6. return f.read(end - begin)只读取该张量的字节区间，而不是读完整份文件。

常见误区

面试题