safetensors/safetensors

safetensors – 用于存储 ML 张量的安全、快速格式

是什么 – safetensors 是一个小型开源库（包含 Python 绑定和 Rust 核心），定义了一种二进制文件格式，用于序列化张量（权重、激活等）而不使用 Python 的 pickle。该格式刻意保持简单：一个描述每个张量的小型 JSON 头部，以及一个连续的字节缓冲区，用于存储原始数据。由于头部不包含可执行代码，文件可以安全地共享和加载。

为何重要 – 在深度学习工作流中，模型权重通常以大型二进制块的形式分发。默认的 PyTorch 格式（.pt/pickle）在加载时可能执行任意代码，这给从互联网下载模型的用户带来安全风险。safetensors 消除了这一风险，同时仍提供以下优势：

• 零拷贝读取 – 字节缓冲区可直接内存映射到张量，避免在 CPU 上进行额外复制。
• 懒加载 – 可以检查头部并仅加载所需的张量，这对分布式或多 GPU 推理非常有用。
• 无大小限制 – 该格式适用于 GB 级别的大模型。
• 支持现代 dtype，如 bfloat16 和 fp8。

主要特性（如 README 所述）

特性	工作方式
安全性	头部为纯 JSON；加载时无代码执行。
零拷贝	张量数据连续存储；库可直接映射（torch.UntypedStorage.from_file）。
懒加载	头部列出每个张量的字节偏移，因此消费者可读取单个张量而无需扫描整个文件。
布局控制	创建者决定文件中张量的顺序，支持快速随机访问。
无文件大小限制	无类似某些基于 protobuf 的格式的 2 GiB 限制。
支持 bfloat16 / fp8	原生 dtype 代码包含在规范中。

安装

# Python 包（最常见用途）
pip install safetensors

如果要从源码构建，需要 Rust 工具链：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # 安装 Rust
git clone https://github.com/huggingface/safetensors
cd safetensors/bindings/python
pip install setuptools_rust
pip install -e .

快速入门示例（Python）

import torch
from safetensors import safe_open
from safetensors.torch import save_file

# 将两个张量写入磁盘
weights = {
    "weight1": torch.zeros((1024, 1024)),
    "weight2": torch.zeros((1024, 1024)),
}
save_file(weights, "model.safetensors")

# 懒加载读取
tensors = {}
with safe_open("model.safetensors", framework="pt", device="cpu") as f:
    for key in f.keys():
        tensors[key] = f.get_tensor(key)

safe_open 上下文返回一个轻量级句柄，可查询头部（f.keys()）并仅获取所需张量。

文件格式基础

• 前 8 字节 – 小端无符号整数 N，表示 JSON 头部的长度。
• 接下来的 N 字节 – UTF-8 编码的 JSON 对象，将张量名称映射到 {dtype, shape, data_offsets}。
• 剩余字节 – 按顺序连接的原始张量数据。
• 可选的 __metadata__ 条目可用于存储任意字符串键值对。
• 无重复键，字节缓冲区无空洞，所有内容均为小端行优先（row-major）。

在 ML 生态系统中的定位

• Hugging Face 模型库使用它来安全分发大型语言模型权重。
• 通过语言特定绑定（核心为 Rust，但 Python 是主要入口点），与 PyTorch、TensorFlow、NumPy 等兼容。
• 当需要安全性和快速随机访问时，可作为 Pickle、HDF5、ONNX protobuf、MsgPack 或 NumPy .npz 等格式的替代方案。

许可证 – Apache-2.0（宽松，适合商业使用）。

---

• 上述所有信息均直接取自仓库的 README；未推断任何额外功能。*