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；未推斷任何額外功能。*