What is SafeTensors?

Definition

SafeTensors 是由 Hugging Face 開發的用於序列化和反序列化神經網路張量（模型權重）的檔案格式。它被建立以解決 PyTorch 預設基於 pickle 的序列化（.bin 檔案）的安全和效能限制。與 pickle 在反序列化期間可以執行任意 Python 程式碼（使其成為惡意軟體的潛在載體）不同，SafeTensors 使用帶有 JSON 標頭的簡單二進位格式，可以證明載入是安全的——不可能執行程式碼。

該格式以記憶體映射的二進位佈局儲存張量，帶有描述張量名稱、形狀、資料類型和位元組偏移的小型 JSON 標頭。這種設計實現了零複製載入：檔案可以直接記憶體映射到程序的地址空間而無需解析或複製，大幅減少大型模型的載入時間。一個從 PyTorch pickle 載入需要 30 秒的 14 GB 模型檔案，從 SafeTensors 載入可以在 5 秒以內完成。

SafeTensors 已被迅速採用為 Hugging Face Hub 上模型分發的標準格式。大多數新發佈的模型現在都包含 SafeTensors 檔案，而 Hugging Face 的模型載入庫在可用時預設使用 SafeTensors。該格式也受到 vLLM、TGI 和 llama.cpp 等主要推論框架的支援，使其成為模型權重儲存的事實標準。

Why It Matters

安全是 SafeTensors 的主要動機。PyTorch pickle 檔案已被用於分發偽裝為 ML 模型的惡意軟體——載入惡意的 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 上模型分發的事實標準。