Formato SafeTensors: una guida alla serializzazione sicura dei modelli ML

Il formato si integra anche in modo naturale nelle pipeline ML moderne perché si concentra su ciò che la maggior parte dei checkpoint già contiene: 

• Tensori
• Shape
• Tipi di dato
• Valori dei pesi

Invece di comportarsi come un sistema di serializzazione Python generico, SafeTensors si comporta come un livello di archiviazione dedicato ai parametri del modello.

Anche se Hugging Face ha sviluppato originariamente SafeTensors per il proprio ecosistema, il formato in sé è agnostico rispetto al framework. È entrato di recente nella PyTorch Foundation (nell'aprile 2026) e supporta PyTorch, TensorFlow, JAX, Flax, NumPy e altri framework ML.

Il problema di Pickle: perché serviva un nuovo formato

Il formato Pickle di Python è stato creato per applicazioni Python generiche, in cui gli sviluppatori spesso devono salvare e ripristinare interi oggetti Python insieme al loro stato interno, ai metodi e alla logica di ricostruzione.

I checkpoint di machine learning di solito non necessitano di quel livello di archiviazione. La maggior parte dei file di modello contiene principalmente tensori: matrici di pesi, embedding, bias e altri parametri numerici. In pratica, ciò significa che il checkpoint è per lo più solo dati numerici strutturati.

Ma un file .pkl fa più che archiviare dati. Può anche contenere istruzioni per Python su come ricostruire gli oggetti durante il caricamento. Ciò significa che la deserializzazione non è un'operazione di lettura passiva; può eseguire codice. E se il codice è dannoso, diventa un serio problema di sicurezza. 

Come pickle abilita l'esecuzione di codice arbitrario

Python ricostruisce gli oggetti durante la deserializzazione con pickle usando metodi speciali come __reduce__(). Le classi possono definire questo metodo per dire a pickle esattamente come l'oggetto deve essere ricostruito quando viene ricaricato in memoria.

Per esempio, __reduce__() può restituire una funzione richiamabile insieme agli argomenti per quella funzione. Durante la deserializzazione, Python esegue quella callable per ricostruire l'oggetto. Esempio di codice:

import pickle
import os

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

payload = pickle.dumps(Demo())

pickle.loads(payload)

Quando pickle.loads() viene eseguito, Python esegue la funzione restituita da __reduce__(). In questo esempio, la deserializzazione attiva un comando shell tramite os.system().

Il problema non è il comando shell in sé. __reduce__() può restituire qualsiasi callable insieme ad argomenti arbitrari in base alla logica. Ciò significa che un file Pickle può chiamare altre funzioni, scaricare file, modificare l'ambiente o eseguire codice dannoso durante il caricamento. Ecco perché la documentazione di Python avverte esplicitamente di non caricare dati pickle da fonti non attendibili.

Il rischio nell'era della condivisione dei modelli

Piattaforme come Hugging Face Hub oggi ospitano più di un milione di modelli condivisi da ricercatori, startup, hobbisti e contributor anonimi. L'ecosistema si muove rapidamente perché gli sviluppatori possono scaricare e testare i modelli all'istante. Ma la maggior parte dei checkpoint caricati non viene verificata singolarmente prima della distribuzione.

Molti checkpoint PyTorch si basano ancora sulla serializzazione con pickle tramite formati come .pt o .bin. Quando qualcuno carica uno di questi file, Python può eseguire la logica di deserializzazione incorporata nel checkpoint. Se il checkpoint è dannoso, tale logica può rubare credenziali, leggere variabili d'ambiente, scaricare payload o eseguire codice remoto durante il caricamento.

Questo è esattamente il problema che SafeTensors è stato progettato per risolvere. Invece di serializzare oggetti Python arbitrari, archivia solo i dati tensoriali e i metadati necessari per caricarli correttamente. Il caricamento di un file .safetensors non richiede l'esecuzione della logica di ricostruzione di Python, riducendo significativamente la superficie d'attacco.

Come funziona il formato SafeTensors

Ora che sappiamo cosa sono i SafeTensors e perché esistono, diamo un'occhiata alla loro struttura e al loro funzionamento.

La struttura header-dati

Un file SafeTensors ha due parti: un header JSON seguito dai dati tensoriali grezzi.

L'header archivia i metadati per ogni tensore, tra cui 

• Nomi dei tensori
• Shape
• Tipi di dato
• Offset in byte

Dopo l'header, il file archivia in modo contiguo i byte grezzi dei tensori.

L'header funziona come un indice. Indica al loader quali tensori esistono e dove si trovano nel file, in modo simile a come un indice di database punta ai record archiviati. SafeTensors limita la dimensione di questo header a 100 MB per evitare payload di metadati sovradimensionati.

Caricamento zero-copy e memory-mapped

SafeTensors migliora la velocità di caricamento tramite il caricamento memory-mapped. Invece di ricostruire oggetti Python durante la deserializzazione, i framework possono mappare i dati dei tensori direttamente dal disco in memoria. Questo riduce le copie di memoria non necessarie e abbassa il carico sulla CPU durante il caricamento.

Secondo i benchmark di Hugging Face, SafeTensors ha caricato i pesi circa 76 volte più velocemente di PyTorch su CPU e circa 2 volte più velocemente su carichi GPU. Ovviamente, l'esatto speedup dipende dall'hardware e dalla dimensione del checkpoint, ma evitare la deserializzazione Python migliora costantemente le prestazioni di caricamento.

Lazy loading e deserializzazione parziale

SafeTensors carica tensori specifici per nome invece di leggere l'intero checkpoint in memoria in una volta.

Questo è utile con modelli di grandi dimensioni distribuiti su più GPU. Prendi ad esempio il modello BLOOM da 176 miliardi di parametri. Con i checkpoint PyTorch standard, il sistema doveva prima deserializzare l'intero set di pesi del modello prima di suddividerli tra i dispositivi, operazione che richiedeva circa 10 minuti. 

Con SafeTensors, ogni GPU ha caricato solo le shard di tensori effettivamente necessarie. Questo ha ridotto il tempo di avvio del modello a circa 45 secondi su 8 GPU.

SafeTensors vs altri formati di serializzazione

SafeTensors funziona bene per archiviare e caricare i pesi dei modelli in modo sicuro ed efficiente, ma ciò non lo rende un sostituto universale per ogni formato. La scelta giusta dipende da cosa stai archiviando e da dove il modello si trova nella pipeline.

Abbiamo già parlato molto di pickle, quindi mi concentrerò su formati diversi.

SafeTensors vs GGUF

SafeTensors e GGUF risolvono problemi diversi. 

GGUF, acronimo di GGML Unified Format, è stato creato per carichi di lavoro di inferenza quantizzata in runtime come llama.cpp. Il formato si concentra sulla distribuzione efficiente di modelli compressi, soprattutto per inferenza su CPU e dispositivi edge. 

SafeTensors si colloca prima nella pipeline. La maggior parte dei checkpoint SafeTensors archivia tensori a precisione piena o pronti per l'addestramento, utilizzati per training, fine-tuning, merge o workflow di inferenza distribuita. Il formato dà priorità al caricamento sicuro, alla compatibilità con framework come PyTorch e all'accesso efficiente ai tensori durante training e serving.

Possono completarsi a vicenda invece di competere direttamente. Esempio di workflow: 

• Allena o fai fine-tuning del modello usando PyTorch e checkpoint SafeTensors
• Quantizza il modello finale
• Esportalo in GGUF per il deployment in llama.cpp o in runtime di inferenza edge

SafeTensors vs ONNX

SafeTensors si concentra sull'archiviazione sicura dei pesi del modello e sul loro caricamento efficiente all'interno di framework come PyTorch. Archivia solo tensori e metadati, il che lo rende leggero e veloce per la condivisione dei checkpoint, il fine-tuning e i workflow di training.

ONNX adotta un approccio più ampio. Archivia l'intero grafo di calcolo insieme ai parametri del modello. Questo rende ONNX utile quando vuoi esportare un modello da un framework ed eseguirlo altrove.

Per esempio, i team che addestrano e fanno fine-tuning di LLM con PyTorch di solito preferiranno i checkpoint SafeTensors perché si caricano rapidamente e si integrano direttamente nei workflow esistenti. Ma se lo stesso team deve distribuire il modello in TensorRT, ONNX Runtime o un motore di inferenza edge, ha più senso esportarlo in ONNX.

Uso pratico di SafeTensors

Uno dei motivi per cui SafeTensors si è diffuso rapidamente nell'ecosistema PyTorch è che le API risultano familiari. Continui a lavorare con gli state dictionary e i tensori come faresti normalmente.

Salvataggio e caricamento dei tensori

Il flusso di base è identico alla gestione dei checkpoint standard in PyTorch. Ecco l'esempio:

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() scrive i tensori nel formato .safetensors, mentre load_file() li ricarica in memoria.

SafeTensors supporta anche il caricamento selettivo tramite safe_open(), utile con checkpoint di grandi dimensioni quando ti servono solo pochi tensori.

from safetensors import safe_open

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

print(weights)

Invece di caricare l'intero checkpoint, get_tensor() legge solo il tensore richiesto.

Conversione di modelli esistenti in safetensors

Lo schema standard è:

1. Carica il modello esistente
2. Estrai lo state dictionary
3. Salvalo con 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() restituisce i pesi del modello come tensori, che SafeTensors può archiviare direttamente. 

Se il modello è già su Hugging Face Hub, potresti non aver nemmeno bisogno di codice di conversione locale. Hugging Face fornisce il supporto integrato per la conversione dei checkpoint dei modelli ospitati tramite l'interfaccia dell'Hub.

Formati di serializzazione: tabella di confronto

SafeTensors nel 2026: la PyTorch Foundation e cosa ci aspetta

Nell'aprile 2026, Hugging Face ha contribuito SafeTensors alla PyTorch Foundation sotto la Linux Foundation. Il progetto ora si trova a fianco di PyTorch, vLLM, DeepSpeed e Ray sotto la governance della fondazione.

Questa mossa segnala che SafeTensors non è più solo un progetto di Hugging Face. Sta diventando un'infrastruttura condivisa per l'ecosistema ML. 

L'annuncio tocca anche la direzione futura del formato.

Caricamento consapevole del dispositivo

Un'area chiave è il caricamento consapevole del dispositivo. Oggi, molti workflow caricano ancora i tensori nella memoria della CPU prima di trasferirli su dispositivi CUDA o ROCm. Questo passaggio di staging extra aumenta la latenza di avvio, soprattutto per grandi sistemi distribuiti. 

I maintainer di SafeTensors stanno lavorando a percorsi di caricamento diretto sul dispositivo che riducono le copie inutili sulla CPU e spostano i tensori direttamente sugli acceleratori. 

Caricamento distribuito

Anche il supporto al caricamento distribuito sta evolvendo. I sistemi di inferenza moderni raramente eseguono i modelli su una singola GPU. Il parallelismo dei tensori e il parallelismo a pipeline sono ormai schemi standard per i modelli di grandi dimensioni, ma le API di caricamento dei checkpoint tra i framework sono ancora frammentate. 

SafeTensors sta ampliando il supporto per il caricamento consapevole delle shard e i layout tensoriali distribuiti, così i framework possono coordinare il caricamento dei checkpoint in modo più efficiente tra i dispositivi. 

Workflow di quantizzazione moderni

Il formato si sta inoltre adattando ai workflow di quantizzazione più recenti. I sistemi di inferenza si affidano sempre più a formati come FP8, GPTQ e AWQ per ridurre l'uso di memoria e i costi di serving. 

Invece di costringere i framework a gestirli tramite logiche di serializzazione personalizzate, SafeTensors sta aggiungendo un supporto formale per formati tensoriali a precisione più bassa e quantizzati a blocchi direttamente nel formato stesso. 

Al momento, gli sviluppatori devono ancora scegliere esplicitamente SafeTensors passando tra workflow di salvataggio e caricamento. Ma è in corso un lavoro per un'integrazione più profonda con il sistema di serializzazione nativo di PyTorch. Se e quando ciò arriverà, SafeTensors potrebbe smettere di essere un formato alternativo per i checkpoint e diventare il modo predefinito con cui PyTorch archivia i modelli.

Considerazioni finali

Per anni, gli sviluppatori hanno condiviso checkpoint di modelli usando sistemi di serializzazione che potevano eseguire codice Python arbitrario durante il caricamento. Una volta che gli hub pubblici di modelli hanno iniziato a ospitare milioni di checkpoint, i rischi per la sicurezza sono diventati molto più difficili da ignorare.

SafeTensors ha cambiato le cose restringendo l'ambito del formato. Invece di provare a serializzare interi oggetti Python, si concentra solo sull'archiviazione dei tensori e dei metadati necessari per caricarli. Questo design più semplice rimuove i rischi di deserializzazione presenti nei checkpoint basati su pickle e, allo stesso tempo, migliora la velocità di caricamento e l'efficienza della memoria.

Quindi, quando ti servono solo i pesi del modello, non ha senso eseguire codice arbitrario durante la deserializzazione: in quei casi è meglio usare SafeTensors.

Se vuoi lavorare più a fondo con gli strumenti ML moderni, i formati dei modelli e i workflow Hugging Face, i nostri corsi Deep Learning in Python e Working with Hugging Face sono un buon passo successivo. Coprono workflow pratici per addestrare, fare fine-tuning e distribuire modelli con gli strumenti usati nell'ecosistema AI di oggi.