Format SafeTensors: przewodnik po bezpiecznej serializacji modeli ML

Format naturalnie wpisuje się w nowoczesne potoki ML, ponieważ skupia się na tym, co i tak zawiera większość checkpointów: 

• Tensory
• Kształty
• Typy danych
• Wartości wag

Zamiast działać jak ogólny system serializacji Pythona, SafeTensors pełni rolę dedykowanej warstwy przechowywania parametrów modeli.

Chociaż Hugging Face początkowo opracował SafeTensors na potrzeby swojego ekosystemu, sam format jest niezależny od frameworka. Niedawno (w kwietniu 2026 r.) dołączył do PyTorch Foundation i wspiera PyTorch, TensorFlow, JAX, Flax, NumPy oraz inne frameworki ML.

Problem z pickle: dlaczego potrzebny był nowy format

Pickle w Pythonie powstał z myślą o ogólnych aplikacjach w Pythonie, w których programiści często muszą zapisywać i odtwarzać całe obiekty wraz z ich stanem wewnętrznym, metodami i logiką rekonstrukcji.

Checkpointy uczenia maszynowego zwykle nie wymagają takiego poziomu przechowywania. Większość plików modeli to głównie tensory: macierze wag, osadzenia (embeddings), biasy i inne parametry liczbowe. W praktyce oznacza to, że checkpoint to przede wszystkim ustrukturyzowane dane liczbowe.

Ale plik .pkl robi więcej niż tylko przechowuje dane. Może też zawierać instrukcje dla Pythona, jak odbudować obiekty podczas ładowania. To znaczy, że deserializacja nie jest pasywnym odczytem; może wykonywać kod. A jeśli ten kod jest złośliwy, staje się to poważnym problemem bezpieczeństwa. 

Jak pickle umożliwia wykonywanie dowolnego kodu

Python odtwarza obiekty podczas deserializacji pickle przy użyciu specjalnych metod, takich jak __reduce__(). Klasy mogą zdefiniować tę metodę, aby wskazać pickle, jak dokładnie obiekt ma zostać odbudowany po wczytaniu do pamięci.

Na przykład __reduce__() może zwrócić wywoływalną funkcję wraz z argumentami. Podczas deserializacji Python wykonuje tę funkcję, aby zrekonstruować obiekt. Przykładowy kod:

import pickle
import os

class Demo:
    def __reduce__(self):
        return (os.system, ("echo 'Code executed during deserialization'",))

payload = pickle.dumps(Demo())

pickle.loads(payload)

Gdy uruchamia się pickle.loads(), Python wykonuje funkcję zwróconą przez __reduce__(). W tym przykładzie deserializacja wyzwala polecenie powłoki przez os.system().

Problemem nie jest samo polecenie powłoki. __reduce__() może zwrócić dowolny wywoływalny obiekt wraz z arbitralnymi argumentami zgodnie z logiką. To oznacza, że plik Pickle może wywoływać inne funkcje, pobierać pliki, modyfikować środowisko lub wykonywać złośliwy kod podczas ładowania. Dlatego dokumentacja Pythona wyraźnie ostrzega przed ładowaniem danych pickle z niezaufanych źródeł.

Ryzyko w erze współdzielenia modeli

Platformy takie jak Hugging Face Hub hostują dziś ponad milion modeli udostępnianych przez naukowców, startupy, hobbystów i anonimowych autorów. Ekosystem rozwija się szybko, bo deweloperzy mogą natychmiast pobierać i testować modele. Jednak większość przesyłanych checkpointów nie jest indywidualnie audytowana przed dystrybucją.

Wiele checkpointów PyTorch nadal polega na serializacji opartej na pickle w formatach takich jak .pt czy .bin. Gdy ktoś ładuje taki plik, Python może wykonać logikę deserializacji osadzoną w checkpointcie. Jeśli checkpoint jest złośliwy, ta logika może kraść poświadczenia, odczytywać zmienne środowiskowe, pobierać ładunki lub wykonywać zdalny kod podczas ładowania.

To dokładnie ten problem, który SafeTensors ma rozwiązać. Zamiast serializować dowolne obiekty Pythona, przechowuje tylko dane tensorów i metadane potrzebne do ich prawidłowego załadowania. Wczytanie pliku .safetensors nie wymaga wykonywania logiki rekonstrukcji w Pythonie, co znacząco zmniejsza powierzchnię ataku.

Jak działa format SafeTensors

Skoro już wiemy, czym jest SafeTensors i po co powstał, przyjrzyjmy się jego strukturze i działaniu.

Struktura nagłówek–dane

Plik SafeTensors ma dwie części: nagłówek JSON, po którym następują surowe dane tensorów.

W nagłówku przechowywane są metadane każdego tensora, w tym 

• Nazwy tensorów
• Kształty
• Typy danych
• Offsety bajtowe

Po nagłówku plik przechowuje ciągłe bajty surowych tensorów.

Nagłówek działa jak spis treści. Informuje loader, jakie tensory istnieją i gdzie są w pliku, podobnie jak indeks bazy danych wskazuje zapisane rekordy. SafeTensors ogranicza rozmiar tego nagłówka do 100 MB, aby zapobiegać nadmiernie dużym ładunkom metadanych.

Zero-copy i ładowanie z mapowaniem pamięci

SafeTensors przyspiesza ładowanie dzięki mapowaniu pamięci. Zamiast odbudowywać obiekty Pythona podczas deserializacji, frameworki mogą mapować dane tensorów bezpośrednio z dysku do pamięci. To ogranicza zbędne kopie i zmniejsza obciążenie CPU podczas ładowania.

Według benchmarków Hugging Face SafeTensors ładował wagi około 76× szybciej niż PyTorch na CPU i około 2× szybciej w zadaniach GPU. Oczywiście dokładny przyrost zależy od sprzętu i rozmiaru checkpointu, ale unikanie deserializacji Pythona konsekwentnie poprawia wydajność ładowania.

Leniwe ładowanie i częściowa deserializacja

SafeTensors ładuje konkretne tensory po nazwie zamiast czytać cały checkpoint do pamięci naraz.

To przydatne przy dużych modelach rozproszonych działających na wielu GPU. Weźmy jako przykład model BLOOM z 176 mld parametrów. Przy standardowych checkpointach PyTorch system najpierw musiał zdeserializować pełne wagi modelu, zanim rozdzielił je między urządzenia, co zajmowało około 10 minut. 

Z SafeTensors każdy GPU ładował tylko te fragmenty tensorów, których faktycznie potrzebował. To skróciło czas startu modelu do około 45 sekund na 8 GPU.

SafeTensors a inne formaty serializacji

SafeTensors świetnie sprawdza się do bezpiecznego i wydajnego przechowywania oraz ładowania wag modeli, ale nie oznacza to, że zastępuje każdy format. Wybór zależy od tego, co przechowujesz i gdzie model znajduje się w potoku.

Dużo mówiliśmy już o pickle, więc skupię się na innych formatach.

SafeTensors vs GGUF

SafeTensors i GGUF rozwiązują różne problemy. 

GGUF, czyli GGML Unified Format, powstał do zadań wnioskowania na zkwantyzowanych modelach w środowiskach uruchomieniowych takich jak llama.cpp. Format skupia się na efektywnym wdrażaniu skompresowanych modeli, zwłaszcza dla wnioskowania na CPU i urządzeniach brzegowych. 

SafeTensors znajduje się wcześniej w potoku. Większość checkpointów SafeTensors przechowuje tensory w pełnej precyzji lub gotowe do treningu, używane do treningu, dostrajania, łączenia lub rozproszonych przepływów inferencji. Format priorytetyzuje bezpieczne ładowanie, kompatybilność z frameworkami takimi jak PyTorch i wydajny dostęp do tensorów podczas treningu i serwowania.

Mogą się uzupełniać zamiast bezpośrednio konkurować. Przykładowy przepływ: 

• Trenuj lub dostrajaj model w PyTorch, zapisując checkpointy w SafeTensors
• Skonwertuj końcowy model do postaci zkwantyzowanej
• Wyeksportuj go do GGUF, aby wdrożyć w llama.cpp lub środowiskach brzegowych

SafeTensors vs ONNX

SafeTensors skupia się na bezpiecznym przechowywaniu wag modeli i ich szybkim ładowaniu w ramach takich jak PyTorch. Przechowuje tylko tensory i metadane, dzięki czemu jest lekki i szybki do udostępniania checkpointów, dostrajania i treningu.

ONNX ma szersze podejście. Przechowuje pełny graf obliczeniowy wraz z parametrami modelu. To sprawia, że ONNX jest przydatny, gdy chcesz wyeksportować model z jednego frameworka i uruchomić go zupełnie gdzie indziej.

Na przykład zespoły trenujące i dostrajające LLM-y w PyTorch zazwyczaj wybiorą checkpointy SafeTensors, bo ładują się szybko i bezpośrednio integrują z istniejącymi przepływami pracy. Ale jeśli ten sam zespół musi wdrożyć model w TensorRT, ONNX Runtime lub silniku inferencji na brzegu sieci, eksport do ONNX ma więcej sensu.

SafeTensors w praktyce

Jednym z powodów szybkiego rozprzestrzenienia SafeTensors w ekosystemie PyTorch jest znajome API. Nadal pracujesz ze słownikami stanu i tensorami tak jak zwykle.

Zapisywanie i ładowanie tensorów

Podstawowy przebieg wygląda identycznie jak przy standardowej obsłudze checkpointów w PyTorch. Oto przykład:

import torch
from safetensors.torch import save_file, load_file

tensors = {
    "weights": torch.randn(2, 2),
    "bias": torch.zeros(2)
}

save_file(tensors, "model.safetensors")

loaded_tensors = load_file("model.safetensors")

print(loaded_tensors["weights"])

save_file() zapisuje tensory w formacie .safetensors, a load_file() wczytuje je z powrotem do pamięci.

SafeTensors obsługuje też selektywne ładowanie poprzez safe_open(), co przydaje się przy dużych checkpointach, gdy potrzebujesz tylko kilku tensorów.

from safetensors import safe_open

with safe_open("model.safetensors", framework="pt") as f:
    weights = f.get_tensor("weights")

print(weights)

Zamiast ładować cały checkpoint, get_tensor() odczytuje tylko żądany tensor.

Konwertowanie istniejących modeli do safetensors

Standardowy schemat to:

1. Załaduj istniejący model
2. Wyodrębnij słownik stanu
3. Zapisz go za pomocą save_file()

from transformers import AutoModel
from safetensors.torch import save_file

model = AutoModel.from_pretrained("bert-base-uncased")

save_file(model.state_dict(), "model.safetensors")

state_dict() zwraca wagi modelu jako tensory, które SafeTensors może zapisać bezpośrednio. 

Jeśli model jest już w Hugging Face Hub, być może nie potrzebujesz lokalnej konwersji. Hugging Face zapewnia wbudowane wsparcie konwersji checkpointów dla hostowanych modeli przez interfejs Hub.

Formaty serializacji: tabela porównawcza

SafeTensors w 2026 r.: PyTorch Foundation i co dalej

W kwietniu 2026 r. Hugging Face przekazał SafeTensors do PyTorch Foundation przy Linux Foundation. Projekt znajduje się teraz obok PyTorch, vLLM, DeepSpeed i Ray pod kuratelą fundacji.

Ten ruch oznacza, że SafeTensors nie jest już tylko projektem Hugging Face. Staje się wspólną infrastrukturą ekosystemu ML. 

Ogłoszenie zarysowuje też kierunki rozwoju formatu.

Załadowanie świadome urządzenia

Jednym z głównych celów jest ładowanie świadome urządzenia. Dziś wiele przepływów nadal ładuje tensory do pamięci CPU, zanim przeniesie je na urządzenia CUDA lub ROCm. Ten dodatkowy etap zwiększa opóźnienie startu, zwłaszcza w dużych systemach rozproszonych. 

Opiekunowie SafeTensors pracują nad ścieżkami bezpośredniego ładowania na urządzenia, które ograniczają zbędne kopie przez CPU i przenoszą tensory bezpośrednio na akceleratory. 

Ładowanie rozproszone

Wsparcie dla ładowania rozproszonego także ewoluuje. Współczesne systemy inferencji rzadko uruchamiają modele na pojedynczym GPU. Równoległość tensorowa i potokowa to dziś standard przy dużych modelach, ale API ładowania checkpointów w różnych frameworkach wciąż są rozproszone. 

SafeTensors poszerza wsparcie dla ładowania świadomego shardów i rozproszonych układów tensorów, aby frameworki mogły sprawniej koordynować ładowanie checkpointów na wielu urządzeniach. 

Nowoczesne przepływy kwantyzacji

Format dostosowuje się także do nowszych przepływów kwantyzacji. Systemy inferencji coraz częściej polegają na formatach FP8, GPTQ i AWQ, aby zmniejszać zużycie pamięci i koszty serwowania. 

Zamiast zmuszać frameworki do obsługi tego przez niestandardową logikę serializacji, SafeTensors dodaje formalne wsparcie dla niskiej precyzji i blokowo kwantyzowanych formatów tensorów bezpośrednio w samym formacie. 

Obecnie deweloperzy wciąż muszą wybierać SafeTensors ręcznie, przełączając schematy zapisu i odczytu. Trwają jednak prace nad głębszą integracją z natywnym systemem serializacji PyTorch. Jeśli to dojdzie do skutku, SafeTensors może przestać być alternatywnym formatem checkpointów i stać się domyślnym sposobem zapisu modeli w PyTorch.

Na koniec

Przez lata deweloperzy udostępniali checkpointy modeli, używając systemów serializacji, które podczas ładowania mogły wykonywać dowolny kod Pythona. Gdy publiczne huby modeli zaczęły hostować miliony checkpointów, ryzyka bezpieczeństwa stały się dużo trudniejsze do zignorowania.

SafeTensors zmienił to, zawężając zakres formatu. Zamiast próbować serializować całe obiekty Pythona, skupia się tylko na przechowywaniu tensorów i metadanych potrzebnych do ich wczytania. Ta prostsza konstrukcja usuwa ryzyka deserializacji obecne w checkpointach opartych na pickle, a jednocześnie poprawia szybkość ładowania i efektywność pamięci.

Więc gdy potrzebujesz wyłącznie wag modelu, nie ma sensu wykonywać dowolnego kodu podczas deserializacji — w takich przypadkach lepiej użyć SafeTensors.

Jeśli chcesz głębiej wejść w nowoczesne narzędzia ML, formaty modeli i przepływy pracy w Hugging Face, nasze kursy Deep Learning in Python i Working with Hugging Face będą dobrym kolejnym krokiem. Obejmują praktyczne przepływy trenowania, dostrajania i wdrażania modeli narzędziami używanymi w dzisiejszym ekosystemie AI.