GGUF, safetensors: capire i formati di modelli

#Perché esistono questi formati

Un LLM, una volta addestrato, non è altro che un enorme sacco di numeri: i pesi (weights), cioè i miliardi di parametri che codificano ciò che il modello «sa». Il formato del file è semplicemente il modo in cui questi numeri sono organizzati sul disco. Bisogna decidere come memorizzarli, come rileggerli velocemente e quali informazioni aggiuntive (il vocabolario, l'architettura, le impostazioni) includere insieme ai pesi.

Storicamente, questi pesi erano salvati nel formato .bin di PyTorch (pickle Python), pratico ma lento da caricare e soprattutto pericoloso: un file pickle può eseguire codice arbitrario all'apertura. Due formati si sono affermati per risolvere problemi diversi. safetensors risponde alle esigenze dei ricercatori e delle piattaforme: un'archiviazione sicura e veloce, fedele alla precisione di partenza. GGUF risponde alle esigenze dell'inferenza locale: un file unico, compatto, quantizzato, pronto per essere eseguito su una CPU o una GPU di fascia consumer.

#safetensors : il formato Hugging Face

safetensors è il formato predefinito dell'ecosistema Hugging Face. Creato per sostituire il pickle di PyTorch, il suo principale punto di forza è nel nome: la sicurezza. Il file contiene solo dati (i tensori dei pesi) e una piccola intestazione JSON che ne descrive la forma e il tipo. Nessun codice eseguibile, quindi nessun rischio di aprire un file malevolo. Bonus: il caricamento è più veloce grazie al memory-mapping, che permette di leggere i pesi direttamente dal disco senza prima copiarli tutti in RAM.

Sicuro fin dalla progettazione

Nessun codice eseguibile, a differenza dei vecchi .bin/.pt in pickle. È possibile scaricare un safetensors senza temere l'esecuzione di codice.

Piena precisione

I pesi sono generalmente salvati in FP16 o BF16 (16 bit), o addirittura FP32. È la precisione di addestramento, quella che serve da riferimento.

Fatto per essere trasformato

È il formato di partenza per il fine-tuning, la fusione dei modelli (merge), la quantizzazione o la conversione in altri formati.

Spesso suddiviso

Un modello di grandi dimensioni è suddiviso in più file (shard) accompagnati da un indice JSON, perché un singolo file di decine di GB sarebbe ingestibile.

Il rovescio della medaglia: un file safetensors in FP16 è voluminoso. Un modello 7B pesa circa 14 GB (2 byte per parametro), un 70B intorno a 140 GB. Per l'addestramento e la ricerca su GPU per server, è la scelta giusta. Per eseguire un modello sulla tua macchina, spesso è troppo pesante — da qui l'interesse per la quantizzazione e il GGUF.

#GGUF: il formato di inferenza locale

GGUF (GPT-Generated Unified Format) è il formato nato dal progetto llama.cpp, il motore di inferenza che esegue gli LLM in modo efficiente sia su CPU sia su GPU. Ha sostituito il vecchio formato GGML nel 2023. La sua idea centrale: mettere tutto in un unico file. I pesi, il vocabolario del tokenizer, i metadati dell'architettura (numero di livelli, dimensione del contesto), il template della chat — tutto è racchiuso nello stesso file. Scarichi un file, lo avvii e funziona.

File unico e autonomo

Pesi + tokenizer + metadati in un solo .gguf. Nessuna cartella di configurazione da assemblare, nessuna dipendenza Python da installare.

Quantizzato

Progettato per contenere pesi compressi (4, 5, 6, 8 bit). È questo che rende i grandi modelli accessibili su hardware di largo consumo.

CPU + GPU + offload

llama.cpp può distribuire i layer tra GPU e RAM di sistema. Si può eseguire un modello che supera la capacità della propria VRAM, sacrificando un po' di velocità.

Portatile

Lo stesso file .gguf funziona su Windows, macOS (Metal) e Linux, con Ollama, LM Studio, Jan oppure direttamente con llama.cpp.

La quantizzazione è al centro del tema. Consiste nel memorizzare ogni peso su meno bit (4 invece di 16, ad esempio), il che riduce la dimensione di un fattore da 3 a 4 con una perdita di qualità minima se si sceglie bene. È proprio questo che permette a un modello 7B di stare in circa 5 GB di VRAM invece che in 14. I livelli più comuni che si incontrano: Q4_K_M (il migliore compromesso, consigliato per impostazione predefinita), Q5_K_M (un livello superiore in qualità), Q8_0 (quasi senza perdita, più pesante) e FP16 (non quantizzato, di riferimento).

#Perché Ollama e LM Studio vogliono il GGUF

Ollama e LM Studio sono costruiti su llama.cpp (o su un motore equivalente) e llama.cpp supporta nativamente GGUF. Non è un capriccio: è ciò che rende questi strumenti così semplici. Poiché il GGUF contiene già il tokenizer, l'architettura e il template di chat, lo strumento non ha nulla da indovinare. Legge il file, alloca la memoria e ti risponde. Nessun ambiente Python, nessuna dipendenza da risolvere, nessuna configurazione da scrivere.

Quando esegui `ollama pull llama3.2`, Ollama scarica in realtà un GGUF dal suo registry e lo archivia nel proprio archivio di modelli. Non vedi mai il file, ma dietro le quinte si tratta proprio di GGUF. LM Studio, invece, ti mostra esplicitamente i file GGUF disponibili e le loro quantizzazioni al momento del download.

# Ollama récupère un GGUF depuis sa registry et le sert sur localhost:11434
ollama pull llama3.2
ollama run llama3.2

# Vérifier que le daemon répond
curl http://localhost:11434/api/tags

#Leggere il nome di un file senza sbagliare

Su Hugging Face, i nomi dei file GGUF seguono una convenzione leggibile una volta che si conosce il codice. Prendi un esempio tipico: `Qwen2.5-7B-Instruct-Q4_K_M.gguf`. Ogni pezzo contiene un'informazione.

Qwen2.5

Famiglia e versione del modello.

7B

Il numero di parametri: 7 miliardi. È il primo indicatore della VRAM necessaria.

Instruct

La variante addestrata per seguire istruzioni e dialogare (a differenza di -base, il modello grezzo, non allineato per la chat).

Q4_K_M

La quantizzazione: 4 bit, variante K_M (medium). Il compromesso qualità/dimensione raccomandato per impostazione predefinita.

.gguf

Il formato. Sai che funzionerà su Ollama, LM Studio o llama.cpp senza conversione.

Il suffisso di quantizzazione è la parte più utile da decifrare. Il numero indica il numero di bit per peso; le lettere K_S / K_M / K_L indicano varianti (Small, Medium, Large) che proteggono in misura maggiore o minore gli strati sensibili. Più il numero è alto, più il file è grande e fedele.

Q4_K_M

~4 bit, medium. La scelta predefinita: la migliore qualità in rapporto alle dimensioni nella stragrande maggioranza dei casi.

Q5_K_M

~5 bit. Qualità leggermente superiore, file un po' più pesante. Una buona scelta se la VRAM lo permette.

Q8_0

8 bit. Quasi indistinguibile dal non quantizzato, ma due volte più pesante di Q4. Per i puristi o per compiti impegnativi.

Q2_K / Q3_K

2-3 bit. Molto compatto, ma con un peggioramento evidente della qualità. Da riservare ai casi in cui la memoria è davvero critica.

FP16 / F16

Non quantizzato, precisione completa su 16 bit. La versione di riferimento, ma pesante — meglio restare su safetensors in questo caso.

#Quale scaricare in base allo strumento utilizzato

La domanda pratica si riduce a: quale strumento userò? Il formato deriva dalla risposta, non l'inverso.

Ollama, LM Studio, Jan, llama.cpp

→ GGUF. Questi strumenti sono fatti per questo. Scegli la quantizzazione in base alla tua VRAM (Q4_K_M per impostazione predefinita).

vLLM, TGI, Transformers (Python)

→ safetensors. Questi motori server caricano il formato nativo di Hugging Face, spesso in FP16 o con la loro propria quantizzazione (AWQ, GPTQ).

Fine-tuning, fusione, quantizzazione in casa

→ safetensors. È il formato di lavoro: si parte dalla piena precisione per trasformare il modello.

Non lo sai ancora

→ GGUF quantizzato se è per un uso locale sulla tua macchina. È la soluzione più semplice e più parsimoniosa nell'uso delle risorse.

Per scegliere la quantizzazione giusta, basati sulla VRAM disponibile. Valori di riferimento in Q4: un modello 3B rientra in ~2 GB, un 7B in ~5 GB, un 14B in ~9 GB, un 32B in ~19 GB, un 70B in ~40 GB. Una RTX 3060 da 12 GB fa girare comodamente modelli da 7B a 14B in Q4; una RTX 4090 da 24 GB punta ai modelli 32B; per i modelli 70B, bisogna puntare a una scheda con molta VRAM o a un Mac con memoria unificata (M4 Pro da 24-48 GB).

#Convertire safetensors in GGUF

A volte un modello viene pubblicato solo in safetensors (cosa frequente il giorno del rilascio) e vuoi eseguirlo in Ollama. In tal caso bisogna convertirlo in GGUF e poi, eventualmente, quantizzarlo. Lo strumento di riferimento è lo script `convert_hf_to_gguf.py` fornito da llama.cpp. Il processo si svolge in due fasi: prima convertire in GGUF a piena precisione, poi quantizzare con lo strumento `llama-quantize`.

1. 01
   Recuperare llama.cpp e le sue dipendenze

   Clona il repository llama.cpp e installa le dipendenze Python dello script di conversione. È il repository a contenere convert_hf_to_gguf.py.
2. 02
   Scaricare il modello safetensors

   Recupera l'intera cartella del modello da Hugging Face (pesi .safetensors + config.json + file del tokenizer). Tutto deve essere presente, non solo i pesi.
3. 03
   Convertire in GGUF FP16

   Esegui convert_hf_to_gguf.py sulla cartella del modello. Ottieni un file .gguf a piena precisione (16 bit), voluminoso ma fedele.
4. 04
   Quantizzare in Q4_K_M

   Passa il GGUF FP16 a llama-quantize scegliendo il livello desiderato (Q4_K_M per impostazione predefinita). Il file finale è da 3 a 4 volte più leggero.
5. 05
   Importare in Ollama

   Scrivi un Modelfile che punti al .gguf quantizzato e crea il modello con ollama create. È così utilizzabile come qualsiasi altro modello Ollama.

# 1. Cloner llama.cpp et installer les dépendances de conversion
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

# 2. Convertir le dossier safetensors en GGUF pleine précision
python convert_hf_to_gguf.py ./mon-modele-hf --outfile mon-modele-f16.gguf --outtype f16

# 3. Quantifier en Q4_K_M (compromis recommandé)
./llama-quantize mon-modele-f16.gguf mon-modele-Q4_K_M.gguf Q4_K_M

# Créer un Modelfile minimal
printf 'FROM ./mon-modele-Q4_K_M.gguf\n' > Modelfile

# Enregistrer le modèle dans Ollama
ollama create mon-modele -f Modelfile
ollama run mon-modele

#Gli altri formati che si incontrano

GGUF e safetensors coprono l'essenziale, ma durante i download si incontrano anche altri nomi. Conoscerli evita brutte sorprese.

.bin / .pt (pickle)

Il formato precedente PyTorch. Funzionale ma non sicuro (può eseguire del codice). Progressivamente sostituito da safetensors — da evitare se esiste un'alternativa.

GPTQ / AWQ

Quantizzazioni lato GPU per vLLM e Transformers, memorizzate in safetensors. Veloci sulle GPU NVIDIA, ma non leggibili da Ollama/llama.cpp.

MLX

Il formato di Apple per il suo framework MLX, ottimizzato per il chip Apple Silicon. Usato da alcune app native per Mac, distinto dal GGUF.

ONNX

Un formato di scambio tra più framework, soprattutto per il deployment industriale e all'edge. Poco comune nell'uso degli LLM locali da parte del grande pubblico.

GGML

L'antenato di GGUF (stesso progetto). Obsoleto: se incontri un .ggml, cerca la versione .gguf equivalente.

#Domande frequenti

GGUF o safetensors, quale è meglio?

Nessuno dei due in assoluto: servono a scopi diversi. GGUF per eseguire un modello in locale (Ollama, LM Studio), safetensors per l'ecosistema Hugging Face, il fine-tuning e i motori di inferenza lato server. Il «migliore» dipende dal tuo strumento.

Un GGUF è peggio di un safetensors?

Un GGUF quantizzato perde un po' di precisione rispetto al safetensors FP16 di partenza. In Q4_K_M o Q5_K_M, la differenza è trascurabile e raramente percepibile nell'uso. In Q2/Q3, diventa visibile.

Posso usare un safetensors direttamente in Ollama?

Nella maggior parte dei casi, non direttamente: Ollama richiede il formato GGUF. Occorre prima convertire il file safetensors in GGUF con llama.cpp. Alcune versioni recenti accettano l'importazione di safetensors, ma il GGUF rimane la strada affidabile.

Perché tanti file su una pagina Hugging Face?

Un modello è spesso suddiviso in diversi shard (safetensors o GGUF), a cui si aggiungono i file di configurazione e del tokenizer. Per il GGUF, generalmente ti serve un solo file per quantizzazione (o tutte le parti di una serie suddivisa).

#Per approfondire

Ora che i formati non hanno più segreti, queste guide approfondiscono naturalmente l'argomento.

Scegliere la quantizzazione (Q4, Q5, Q8, FP16)

Guida dettagliata per scegliere il livello di quantizzazione di un GGUF in base alla tua VRAM e alle tue esigenze di qualità.

Cos'è Ollama e come funziona

Capire lo strumento che scarica e serve i GGUF in locale, con i comandi di base.

Comprendere la finestra di contesto

L'altro parametro che influisce sulla memoria: i token e il contesto, da combinare con la scelta di quantizzazione.