Safetensors
定义
Safetensors 是一种专门用来保存张量(tensor)的文件格式，同时也是一个提供读写接口的程序库。它面向机器学习模型的权重存储与分发，把纯数值数据与可执行代码彻底分开，文件里除了张量本身只保留类型、形状和位置信息[3]。
这一格式的设计目标有两个：一是消除旧格式在反序列化阶段可能触发代码执行的问题，二是让文件的读取速度足够快[2]。官方将其定位为取代 pickle 的简易替代方案，文件通常以 .safetensors 作为扩展名[1]。
该库最初由 Hugging Face 为其生态开发，但格式本身不依赖特定框架，可配合 PyTorch、TensorFlow、JAX、Flax、PaddlePaddle 与 NumPy 使用[3]。
原理
一个 Safetensors 文件由三部分按顺序连接而成：开头是 8 字节的无符号小端 64 位整数，记录头部长度 N；随后是 N 字节的 UTF-8 JSON 头部；最后是原始张量字节缓冲区[4]。头部是一个以张量名为键的映射，每个条目给出数据类型、形状和该张量数据在缓冲区中的起止偏移，偏移量相对于数据段起点而非文件起点[4]。
头部允许一个保留键 metadata，用于存放自由形式的字符串到字符串映射，其他任意 JSON 结构不被接受[4]。由于字节缓冲区必须被完整索引、不能出现空洞，这一约束也可防止文件被构造成同时符合多种格式的多语言文件[4]。
加载过程只需解析 JSON 头部并按偏移映射数据，因此可以跳过对全部内容的遍历[1]。为了防范解析阶段的资源耗尽，头部被限定在 100 MB 以内，读取时还保证各地址区间互不重叠，使内存占用不超过文件本身[1][4]。库以 Rust 实现并提供 Python 绑定，语言层面的内存安全也构成额外的保护。
发展历程
该库的早期提交可追溯到 2022 年，同年 9 月陆续出现发布相关的构建配置与许可证文件[5]。其动因在于 PyTorch 默认使用 pickle，而 pickle 在反序列化时可以执行任意指令，这在模型被随意上传、下载的环境中构成风险。
2023 年 5 月 23 日，Hugging Face 与 EleutherAI、Stability AI 合作完成了一次外部安全审计并公开报告，结论是未发现可导致任意代码执行的关键缺陷，同时修正了规范中的若干不精确之处。在这一结果之后，transformers 库将 safetensors 设为默认依赖，并计划把该格式作为默认的模型保存格式。
此后 Hugging Face Hub 上的模型逐步改以该格式分发，该格式成为开放权重模型的事实标准之一。2026 年 4 月，PyTorch 基金会宣布接收 Hugging Face 贡献的 Safetensors 项目，使其与 PyTorch、vLLM、DeepSpeed、Ray 等项目并列[6][1]。
应用
该格式主要用于保存和分发模型检查点。在 Hugging Face 的生态中，装好该库后 transformers 会优先使用对应的模型权重文件，transformers 与 diffusers 等库也以其作为默认的保存格式[3]。
配合分片索引文件，单个模型可以拆成多个文件分发，加载时按参数名定位到相应分片，这一方式适用于参数规模较大的模型[7]。按需读取单个张量的能力则让分布式与多卡场景可以只加载所需部分，例如推理服务在张量并行时按分片读取权重。
围绕原始格式还出现了扩展实现。压缩张量库在 Safetensors 的基础上加入量化与稀疏编码，用于存放量化或稀疏化后的权重[8]；另有方案在其之上增加加密、签名和访问策略，以应对模型分发中的保密需求[9]。
局限
该格式只面向张量数据，不保存模型结构、层间连接关系或自定义代码，因此单独一个权重文件无法还原完整模型，仍需框架代码与配置来描述网络结构[10][3]。用官方对比表里的说法，其在灵活性一项上的评价为不足，原因正是无法把定制代码随文件一并保存[10]。
零拷贝也不是普遍成立的。数据仍需从磁盘进入内存或显存，在 CPU 上只有文件已被缓存时才可能真正不复制，在 GPU 上则必须复制一次；头部本身同样不是零拷贝的[4][10]。格式要求所有张量在序列化前打包为连续内存，非连续张量与稀疏张量默认不被接受，需先转为密集连续形式，这可能显著增大文件体积[11]。
安全保证的范围也有边界。格式只保证加载时不会执行代码，但张量中的 NaN 或正负无穷等数值不会被校验，文件内容本身是否可靠仍需另行判断[4]。格式不含压缩功能，压缩需借助外部算法或扩展格式实现，量化表达的能力也不如某些专用格式灵活[12]。此外，读取元数据依赖 JSON 解析器，在缺少内置 JSON 支持的低层语言中会增加接入成本[12]。
参见
-
Pickle —— Python 的通用序列化模块，其反序列化可执行代码，是 Safetensors 试图替代的对象。
-
Hugging Face —— 开发并维护 Safetensors 的公司及其模型托管平台。
-
PyTorch —— 深度学习框架，其检查点默认使用 pickle，Safetensors 提供了更安全的替代。
-
PyTorch 基金会 —— 2026 年接收 Safetensors 项目的开源基金会。
-
零拷贝 —— 指数据在读取时不经额外复制的技术，是该格式宣称的性能特性之一。
-
模型量化 —— 降低权重数值精度以压缩模型体积的技术，可借助 Safetensors 的扩展格式存储。
参考资料
- Safetensors [引用日期2026-10-29]
- Safetensors · Hugging Face [引用日期2026-10-29]
- SafeTensors 格式：安全机器学习模型序列化指南 [引用日期2026-10-29]
- safetensors 0.4.1 [引用日期2026-10-29]
- safetensors/safetensors at python-v0.0.1 · GitHub [引用日期2026-10-29]
- pytorch-foundation-adds-safetensors-for-safer-ai-models [引用日期2026-10-29]
- core/nn/safetensors library [引用日期2026-10-29]
- compressed_tensors [引用日期2026-10-29]
- cryptotensors - CryptoTensors Python Package [引用日期2026-10-29]
- GitHub - huggingface/safetensors at faster_gpu_load2 [引用日期2026-10-29]
- github.com 上的网页 [引用日期2026-10-29]
- 常见的 AI 模型格式 [引用日期2026-10-29]