What is SafeTensors?

Definition

SafeTensors 是由 Hugging Face 开发的一种文件格式，用于序列化和反序列化神经网络张量（模型权重）。它的创建目的是解决 PyTorch 默认基于 pickle 的序列化（.bin 文件）在安全性和性能方面的局限性。与 pickle 不同——pickle 在反序列化过程中可以执行任意 Python 代码（使其成为潜在的恶意软件传播途径），SafeTensors 使用一种简单的二进制格式，带有一个 JSON 头部，加载时可以证明是安全的——不可能执行任何代码。

该格式将张量存储在可内存映射的二进制布局中，配有一个小型 JSON 头部，描述张量名称、形状、数据类型和字节偏移量。这种设计实现了零拷贝加载：文件可以直接内存映射到进程的地址空间中，无需解析或复制，从而显著减少大型模型的加载时间。一个 14 GB 的模型文件从 PyTorch pickle 加载需要 30 秒，而从 SafeTensors 加载可以在 5 秒以内完成。

SafeTensors 已经被迅速采纳为 Hugging Face Hub 上模型分发的标准格式。大多数新发布的模型现在都包含 SafeTensors 文件，Hugging Face 的模型加载库在可用时默认使用 SafeTensors。该格式也被主要推理框架支持，包括 vLLM、TGI 和 llama.cpp，使其成为模型权重存储的事实标准。

Why It Matters

安全性是 SafeTensors 的首要动机。PyTorch pickle 文件已被用于分发伪装成机器学习模型的恶意软件——加载恶意 pickle 文件可以以用户权限执行任意代码，可能危及整个系统。对于从公共仓库下载模型的组织来说，这是一个严重的供应链风险。SafeTensors 通过设计完全消除了这一攻击面。

性能是次要优势。更快的模型加载减少了推理服务的启动时间，加速了开发过程中的实验迭代，并减少了生产环境中模型切换的时间。对于大型模型（70B 以上），pickle 和 SafeTensors 加载之间的差异可以是几分钟与几秒钟的区别，这对于有严格可用性要求的服务来说至关重要。

How It Works

SafeTensors 文件由一个头部和原始张量数据组成。头部是一个 JSON 对象，列出每个张量的名称、数据类型（float16、bfloat16、float32、int8 等）、形状以及在文件中的字节偏移量。头部本身以其长度作为 8 字节整数的前缀，便于高效解析。

张量数据以扁平的二进制布局存储，在内存中连续排列，对齐以实现高效访问。这种布局支持内存映射——操作系统将文件直接映射到虚拟内存中，张量数据在访问页面时按需从磁盘读取。无需反序列化、解析或数据转换。这种零拷贝方式意味着加载 SafeTensors 模型不需要超出模型权重本身之外的额外内存，不像 pickle 那样需要临时内存用于反序列化缓冲区。

Example Use Case

一家注重安全的金融机构从 Hugging Face Hub 下载开源模型进行评估。他们的安全策略禁止加载 pickle 文件，因为存在任意代码执行风险。通过筛选提供 SafeTensors 格式的模型，他们可以安全地评估模型而无需运行不受信任的代码。SafeTensors 格式还可以与他们基于校验和的完整性验证流程集成，确保模型权重在传输过程中未被篡改。

Key Takeaways

• SafeTensors 是一种安全的模型权重格式，可防止加载过程中的任意代码执行。
• 它使用内存映射的二进制存储实现快速零拷贝模型加载。
• 它由 Hugging Face 创建，作为基于 pickle 的 PyTorch 模型文件的安全替代方案。
• 大型模型的加载速度比 pickle 快 3-10 倍。
• SafeTensors 是 Hugging Face Hub 上模型分发的事实标准。