SafeTensors-format: En guide till säker serialisering av ML-modeller

Formatet passar också naturligt in i moderna ML-pipelines eftersom det fokuserar på det som de flesta checkpoints redan innehåller: 

• Tensors
• Former
• Datatyper
• Viktvärden

I stället för att agera som ett allmänt Python-serialiseringssystem fungerar SafeTensors som ett dedikerat lagringslager för modellparametrar.

Även om Hugging Face ursprungligen utvecklade SafeTensors för sitt ekosystem, är formatet i sig ramverksagnostiskt. Det anslöt sig nyligen till PyTorch Foundation (i april 2026) och stöder PyTorch, TensorFlow, JAX, Flax, NumPy och andra ML-ramverk.

Pickle-problemet: Varför ett nytt format behövdes

Pythons Pickle-format byggdes för allmänna Python-applikationer, där utvecklare ofta behöver spara och återställa hela Python-objekt tillsammans med deras interna tillstånd, metoder och återuppbyggnadslogik.

Maskininlärnings-checkpoints behöver vanligtvis inte den nivån av lagring. De flesta modellfiler lagrar främst tensorkomponenter: viktmatriser, inbäddningar, bias och andra numeriska parametrar. I praktiken betyder det att checkpointen mestadels bara är strukturerad numerisk data.

Men en .pkl-fil gör mer än att bara lagra data. Den kan också innehålla instruktioner för Python om hur objekt ska återskapas vid inläsning. Det betyder att deserialisering inte är en passiv läsoperation; den kan köra kod. Och om koden är skadlig blir det ett allvarligt säkerhetsproblem. 

Hur pickle möjliggör godtycklig kodkörning

Python återskapar objekt under pickle-deserialisering med hjälp av specialmetoder som __reduce__(). Klasser kan definiera denna metod för att tala om för pickle exakt hur objektet ska byggas upp igen när någon läser in det i minnet.

Till exempel kan __reduce__() returnera en anropsbar funktion tillsammans med argument för den funktionen. Under deserialisering kör Python den funktionen för att återskapa objektet. Exempelkod:

import pickle
import os

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

payload = pickle.dumps(Demo())

pickle.loads(payload)

När pickle.loads() körs, exekverar Python funktionen som returneras av __reduce__(). I det här exemplet triggar deserialiseringen ett skal-kommando via os.system().

Problemet är inte själva skal-kommandot. __reduce__() kan returnera vilken anropsbar funktion som helst tillsammans med godtyckliga argument baserat på logiken. Det betyder att en Pickle-fil kan anropa andra funktioner, ladda ner filer, ändra miljön eller köra skadlig kod vid inläsning. Därför varnar Pythons dokumentation uttryckligen för att läsa in pickle-data från källor man inte litar på.

Risken i modell-delningens era

Plattformar som Hugging Face Hub är nu värd för mer än en miljon modeller som delas av forskare, startups, hobbyister och anonyma bidragsgivare. Ekosystemet rör sig snabbt eftersom utvecklare kan ladda ner och testa modeller direkt. Men de flesta uppladdade checkpoints granskas inte individuellt före distribution.

Många PyTorch-checkpoints förlitar sig fortfarande på pickle-baserad serialisering via format som .pt eller .bin. När någon läser in en sådan fil kan Python köra deserialiseringslogik inbäddad i checkpointen. Om checkpointen är skadlig kan den logiken stjäla inloggningsuppgifter, läsa miljövariabler, ladda ner payloads eller köra fjärrkod vid inläsning.

Detta är det exakta problemet som SafeTensors byggdes för att lösa. I stället för att serialisera godtyckliga Python-objekt lagrar det endast tensordata och metadata som behövs för att läsa in dessa tensorer korrekt. Att läsa in en .safetensors-fil kräver inte att man kör Pythons återuppbyggnadslogik, vilket avsevärt minskar angreppsytan.

Hur SafeTensors-formatet fungerar

Nu när vi vet vad SafeTensors är och varför de finns, ska vi titta på deras struktur och hur de fungerar.

Header–data-strukturen

En SafeTensors-fil har två delar: ett JSON-huvud följt av den råa tensordatan.

I huvudet lagras metadata för varje tensor, inklusive 

• Tensornamn
• Former
• Datatyper
• Byte-offsetar

Efter huvudet lagrar filen de råa tensorbytena i följd.

Huvudet fungerar som en innehållsförteckning. Det talar om för inläsaren vilka tensorer som finns och var de finns i filen, ungefär som hur ett databasindex pekar på lagrade poster. SafeTensors begränsar denna huvudstorlek till 100 MB för att förhindra överstora metadata-payloads.

Nollkopiering och minnesmappad inläsning

SafeTensors förbättrar inläsningshastigheten genom minnesmappad inläsning. I stället för att återskapa Python-objekt under deserialisering kan ramverk mappa tensordata direkt från disk till minnet. Det minskar onödiga minneskopior och sänker CPU-belastningen vid inläsning.

Enligt Hugging Faces benchmarktester läste SafeTensors in vikter cirka 76x snabbare än PyTorch på CPU och cirka 2x snabbare på GPU-arbetslaster. Självklart beror den exakta hastighetsökningen fortfarande på hårdvaran och checkpointens storlek, men att undvika Python-deserialisering förbättrar konsekvent inläsningsprestandan.

Lat inläsning och partiell deserialisering

SafeTensors läser in specifika tensorer efter namn i stället för att läsa in hela checkpointen i minnet på en gång.

Det är användbart vid stora distribuerade modeller som körs över flera GPU:er. Ta till exempel BLOOMs modell med 176 miljarder parametrar. Med standard-PyTorch-checkpoints behövde systemet först deserialisera hela modellvikterna innan de delades upp över enheter, vilket tog runt 10 minuter. 

Med SafeTensors läste varje GPU bara in de tensorfragment den faktiskt behövde. Det minskade modellens uppstartstid till cirka 45 sekunder över 8 GPU:er.

SafeTensors vs andra serialiseringsformat

SafeTensors fungerar bra för att lagra och läsa in modellvikter säkert och effektivt, men det gör det inte till en universell ersättare för varje format. Rätt val beror på vad du lagrar och var modellen befinner sig i pipelinen.

Vi har pratat mycket om pickle redan, så jag fokuserar på andra format.

SafeTensors vs GGUF

SafeTensors och GGUF löser olika problem. 

GGUF, som står för GGML Unified Format, byggdes för kvantiserade inferensarbetslaster i runtime-miljöer som llama.cpp. Formatet fokuserar på effektiv distrib ution av komprimerade modeller, särskilt för CPU-inferens och edge-enheter. 

SafeTensors ligger tidigare i pipelinen. De flesta SafeTensors-checkpoints lagrar tensorer i full precision eller redo för träning som används för träning, finjustering, sammanslagning eller distribuerade inferensarbetsflöden. Formatet prioriterar säker inläsning, kompatibilitet med ramverk som PyTorch och effektiv åtkomst till tensorer under träning och drift.

De kan komplettera varandra i stället för att konkurrera direkt. Exempel på arbetsflöde: 

• Träna eller finjustera modellen med PyTorch och SafeTensors-checkpoints
• Kvantifiera slutmodellen
• Exportera den till GGUF för driftsättning i llama.cpp eller edge-inferensmiljöer

SafeTensors vs ONNX

SafeTensors fokuserar på att lagra modellvikter säkert och läsa in dem effektivt i ramverk som PyTorch. Det lagrar endast tensorer och metadata, vilket gör det lättviktigt och snabbt för delning av checkpoints, finjustering och träningsarbetsflöden.

ONNX tar ett bredare grepp. Det lagrar hela beräkningsgrafen tillsammans med modellparametrarna. Det gör ONNX användbart när du vill exportera en modell från ett ramverk och köra den någon helt annanstans.

Till exempel kommer team som tränar och finjusterar LLM:er med PyTorch vanligtvis att föredra SafeTensors-checkpoints eftersom de läses in snabbt och integreras direkt i befintliga arbetsflöden. Men om samma team behöver driftsätta modellen i TensorRT, ONNX Runtime eller en edge-inferensmotor, är det mer logiskt att exportera modellen till ONNX.

Att använda SafeTensors i praktiken

En anledning till att SafeTensors spreds snabbt i PyTorch-ekosystemet är att API:et känns bekant. Du arbetar fortfarande med state dictionaries och tensorer på samma sätt som du brukar.

Spara och läsa in tensorer

Det grundläggande arbetsflödet ser identiskt ut med standardhantering av PyTorch-checkpoints. Här är ett exempel:

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() skriver tensorerna till .safetensors-formatet, medan load_file() läser in dem tillbaka i minnet.

SafeTensors stöder också selektiv inläsning via safe_open(), vilket blir användbart med stora checkpoints där du bara behöver några få tensorer.

from safetensors import safe_open

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

print(weights)

I stället för att läsa in hela checkpointen läser get_tensor() bara den tensor du begär.

Konvertera befintliga modeller till safetensors

Standardmönstret är:

1. Läs in den befintliga modellen
2. Extrahera state dictionary
3. Spara den med 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() returnerar modellvikterna som tensorer, vilket SafeTensors kan lagra direkt. 

Om modellen redan finns på Hugging Face Hub kanske du inte ens behöver lokal konverteringskod. Hugging Face erbjuder inbyggt stöd för konvertering av checkpoints för modeller som hostas via Hub-gränssnittet.

Serialiseringsformat: jämförelsetabell

SafeTensors 2026: PyTorch Foundation och vad som väntar

I april 2026 bidrog Hugging Face med SafeTensors till PyTorch Foundation under Linux Foundation. Projektet ligger nu sida vid PyTorch, vLLM, DeepSpeed och Ray under stiftelsens styrning.

Det steget signalerar att SafeTensors inte längre bara är ett Hugging Face-projekt. Det håller på att bli delad infrastruktur för ML-ekosystemet. 

Tillkännagivandet berör också vart formatet är på väg härnäst.

Enhetsmedveten inläsning

Ett huvudfokus är enhetsmedveten inläsning. I dag läser många arbetsflöden fortfarande in tensorer i CPU-minne innan de flyttas till CUDA- eller ROCm-enheter. Det extra mellansteget ökar uppstartslatensen, särskilt för stora distribuerade system. 

Underhållarna av SafeTensors arbetar med direkta inläsningsvägar till enheter som minskar onödiga CPU-kopior och flyttar tensorer direkt till acceleratorer. 

Distribuerad inläsning

Stödet för distribuerad inläsning utvecklas också. Moderna inferenssystem kör sällan modeller på en enda GPU längre. Tensor-parallellism och pipeline-parallellism är nu standardmönster för stora modeller, men API:er för inläsning av checkpoints över ramverk är fortfarande fragmenterade. 

SafeTensors utökar stödet för shard-medveten inläsning och distribuerade tensorlayouter, så att ramverk kan samordna inläsningen av checkpoints mer effektivt över enheter. 

Moderna kvantiseringsarbetsflöden

Formatet anpassas också till nyare kvantiseringsarbetsflöden. Inferenssystem förlitar sig i allt högre grad på FP8, GPTQ och AWQ-format för att minska minnesanvändningen och sänka driftkostnaderna. 

I stället för att tvinga ramverk att hantera detta via anpassad serialiseringslogik, lägger SafeTensors till formellt stöd för lägre precision och blockkvantiserade tensorformat direkt i formatet. 

Just nu måste utvecklare fortfarande välja SafeTensors manuellt genom att växla mellan spar- och inläsningsarbetsflöden. Men det pågår arbete med en djupare integration med PyTorchs inbyggda serialiseringssystem. Om det så småningom landar kan SafeTensors sluta vara ett alternativt checkpointformat och bli det sätt PyTorch lagrar modeller på som standard.

Avslutande tankar

I flera år delade utvecklare modell-checkpoints med serialiseringssystem som kunde köra godtycklig Python-kod vid inläsning. När offentliga modellhubbar började hysa miljontals checkpoints blev säkerhetsriskerna mycket svårare att ignorera.

SafeTensors förändrade detta genom att begränsa formatets omfång. I stället för att försöka serialisera hela Python-objekt fokuserar det endast på att lagra tensorer och den metadata som behövs för att läsa in dem. Den enklare designen tar bort deserialiseringsriskerna som följde med pickle-baserade checkpoints och förbättrar samtidigt inläsningshastighet och minneseffektivitet.

Så när du bara behöver modellvikter finns det ingen poäng med att köra godtycklig kod under deserialisering, och det är bättre att använda SafeTensors i de fallen.

Om du vill arbeta djupare med moderna ML-verktyg, modellformat och arbetsflöden i Hugging Face, är våra kurser Deep Learning in Python och Working with Hugging Face ett bra nästa steg. De täcker praktiska arbetsflöden för att träna, finjustera och driftsätta modeller med verktygen som används i dagens AI-ekosystem.