Safetensors:新一代安全高效的模型权重存储格式详解
在日常 AI 模型训练与部署过程中,模型权重的存储格式至关重要。目前最流行的深度学习框架 PyTorch 默认使用 pickle 格式存储模型权重文件(.pth)。然而,PyTorch 官方文档明确指出:使用 torch.load() 保存模型时,除非将 weights_only 参数设置为 True,否则隐式使用 pickle 模块。pickle 是不安全的,可以构造恶意的 pickle 数据,在反序列化期间执行任意代码。
为了规避此类安全风险,Hugging Face 推出了新的权重存储格式 Safetensors。本文将深入解析 Safetensors 的内部机制、安全性优势、零拷贝技术原理以及在 PyTorch 中的实践应用。
一、Safetensors 简介
Safetensors 是一种用于安全地存储张量的新格式。它的设计目标是在保持简单性的同时实现高性能(支持零拷贝读取)。作为 pickle 格式的替代品,Safetensors 从根本上解决了反序列化漏洞问题,因为它不包含可执行的 Python 代码对象,仅存储纯数值数据。
1.1 核心特性
- 安全性:无法执行恶意代码,加载过程仅涉及内存映射和数据解析。
- 速度:支持零拷贝(Zero-Copy)读取,减少 CPU 和内存带宽消耗。
- 惰性加载:允许在不加载整个文件的情况下检查元数据或读取特定张量。
- 跨语言支持:基于 C++ 实现,提供 Python、Rust、C# 等多种语言的绑定。
二、Safetensors 内部文件格式
Safetensors 文件结构非常清晰,主要由两部分组成:头部信息(Header)和数据部分(Data)。假设有一个名为 model.safetensors 的文件,其内部结构如下:
- 文件头长度:前 8 个字节是一个无符号的 64 位整数(Little-endian),表示 JSON 头部信息的字节数。
- JSON 头部:紧接着的 N 个字节是 UTF-8 编码的 JSON 字符串,包含所有张量的元数据(如数据类型、形状、数据偏移量)以及可选的全局元数据(如
__metadata__)。 - 原始数据:文件的剩余部分直接存储模型权重 tensor 的二进制值,按照头部中定义的顺序排列。
2.1 头部元数据结构示例
以 GPT2 模型的 Safetensors 文件为例,其头部 JSON 内容通常包含以下字段:
{
"__metadata__": { "format": "pt" },
"h.10.ln_1.weight": {
"dtype": "F32",
"shape"


