Cos'è GGUF? Il formato di file per LLM alla base di Ollama e llama.cpp, spiegato

GGUF (generalmente espanso come GPT-Generated Unified Format) è un formato di file binario per memorizzare modelli linguistici di grandi dimensioni: i pesi, il tokenizer e tutti i metadati di configurazione in un unico file autosufficiente. È il formato nativo di llama.cpp, ed è ciò che Ollama, LM Studio, KoboldCpp, gennaio e la maggior parte delle altre applicazioni locali LLM in realtà vengono eseguite. Se hai mai scaricato un file con estensione .gguf, oppure scaricato un modello con ollama run, stavi utilizzando questo formato.

Cosa contiene effettivamente un file GGUF

Un file GGUF inizia con quattro byte ASCII GGUF, seguiti da un numero di versione, da una sezione di metadati chiave-valore e quindi dai tensori stessi. I metadati rappresentano la decisione progettuale fondamentale: memorizzano l'architettura del modello, la lunghezza massima del contesto, il vocabolario del tokenizer, il template per le conversazioni e i dettagli della quantizzazione sotto forma di chiavi denominate, in modo che un runtime possa caricare qualsiasi file GGUF senza aver bisogno di un file separato config.json o i file del tokenizer accanto ad esso.

Da questa progettazione derivano tre conseguenze pratiche:

• Un singolo file rappresenta l’intero modello. È possibile copiare un file .gguf tra macchine diverse e funzionerà immediatamente. (I modelli molto grandi vengono talvolta suddivisi in parti numerate, ad esempio -00001-of-00002.gguf, ma si tratta comunque di un unico modello logico.)
• Il file è mappabile in memoria. I runtime possono utilizzare la funzione mmap per caricare il file e caricare i pesi su richiesta (on demand), rendendo così il caricamento rapido e consentendo l’avvio di modelli più grandi della RAM disponibile.
• La quantizzazione è integrata nel formato. Un file GGUF memorizza già i pesi compressi con una precisione compresa tra 2 e 8 bit per peso, motivo per cui un modello da 8 miliardi di parametri può occupare solo 4,9 GB invece che 16 GB.

Perché GGUF ha sostituito GGML

Prima di agosto 2023, llama.cpp utilizzava un formato chiamato GGML (dal nome della libreria tensoriale sottostante). GGML funzionava, ma presentava un difetto strutturale: la disposizione dei dati nel file era rigida e non prevedeva alcuna gestione delle versioni. Ogni volta che llama.cpp introduceva una nuova funzionalità — nuove architetture, metodi di quantizzazione migliorati, parametri per la scalatura RoPE — il formato doveva essere modificato, e ogni file di modello esistente su ogni disco rigido diventava inutilizzabile. Gli utenti erano costretti a riscaricare o riconvertire intere collezioni di modelli più volte nell’arco di pochi mesi.

GGUF, introdotto dal progetto llama.cpp ad agosto 2023, ha risolto questo problema con due modifiche:

• Gestione delle versioni. Il file dichiara esplicitamente la propria versione del formato, permettendo ai lettori di sapere esattamente come analizzarlo.
• Metadati chiave-valore estensibili. Nuove informazioni (ad esempio un nuovo campo per l’architettura, un template per le conversazioni, un iperparametro aggiuntivo) corrispondono semplicemente a nuove chiavi. I vecchi file privi di tali chiavi continuano a caricarsi regolarmente; i nuovi file che le contengono funzionano correttamente nei runtime aggiornati. Nulla viene invalidato retroattivamente.

llama.cpp ha abbandonato il supporto per GGML poco dopo, e l’intero ecosistema lo ha seguito. Oggi GGML sopravvive unicamente come nome della libreria tensoriale sottostante; se trovate un file di modello .ggml o .bin del 2023, non verrà caricato da nessuno strumento attuale e dovrete invece scaricare una versione in formato GGUF.

Come interpretare i suffissi della quantizzazione

Ogni nome di file GGUF include un suffisso come Q4_K_M che indica il grado di compressione applicato ai pesi. Il criterio è il seguente:

• Il numero che segue la lettera Q rappresenta approssimativamente il numero di bit per peso: Q4 ≈ 4 bit, Q8 ≈ 8 bit. Minori bit equivalgono a un file più piccolo e a una qualità inferiore.
• _K indica i più recenti metodi di "k-quant" (quantizzazione k), che allocano bit aggiuntivi ai tensori più influenti sulla qualità dell’output. A parità di dimensione, una quantizzazione K offre prestazioni migliori rispetto allo stile precedente.
• _S / _M / _L (small/medium/large) sono varianti all’interno della famiglia K — _M mantiene alcuni tensori particolarmente sensibili a una precisione superiore rispetto a _S.
• _0 (come in Q8_0, Q4_0) indica la più vecchia e semplice quantizzazione a blocchi. Q8_0 è ancora ampiamente utilizzato perché, a 8 bit, il metodo semplice è già quasi privo di perdite; Q4_0 è ormai obsoleto — si consiglia di preferire i prefissi Q4_K_M.
• IQ (ad esempioIQ2_M, IQ3_XS) che indicano le "i-quants", basate su una matrice di importanza e progettate per comprimere i modelli sotto i 4 bit con minori danni rispetto alle alternative.
• F16 / BF16 / F32 indicano pesi non quantizzati a 16 o 32 bit — la qualità di riferimento, ma con dimensioni massime.

Ecco quanto costano effettivamente le opzioni più comuni, utilizzando come esempio modelli istruzionali da 8 miliardi di parametri della famiglia Llama (le dimensioni sono approssimative e variano leggermente da modello a modello):

Quant	Dimensione file (modello 8B)	Qualità rispetto a F16	Quando utilizzare
F16	~16,1 GB	Riferimento	Per benchmarking o per ulteriori quantizzazioni; raramente vale la pena eseguirlo
Q8_0	~8,5 GB	Praticamente indistinguibile	Se si dispone di VRAM sufficiente e si desidera la massima qualità
Q6_K	~6,6 GB	Perdita trascurabile	Ottima qualità con un risparmio significativo di dimensioni
Q5_K_M	~5,7 GB	Perdita molto lieve	Buon compromesso
Q4_K_M	~4,9 GB	Perdita contenuta, generalmente accettabile	L'impostazione predefinita standard. La migliore qualità per gigabyte per la maggior parte degli utenti
Q3_K_M	~4,0 GB	Degrado percettibile	Solo quando Q4 non entra effettivamente nella memoria disponibile
Q2_K / IQ2	~3,2 GB	Degrado significativo	Ultima risorsa; spesso è preferibile un modello più piccolo a Q4

Due regole utili: la quantizzazione danneggia i modelli piccoli più di quelli grandi (un modello da 70B a Q3 si comporta molto meglio di uno da 8B a Q3) e al di sotto di Q4 la curva della qualità cala bruscamente. In caso di dubbio, Q4_K_M è l'impostazione predefinita della comunità per una ragione ben precisa.

Scelta della quantizzazione in base alla tua VRAM

La memoria totale necessaria è approssimativamente pari a dimensione del file + cache del contesto + overhead. Prevedere un margine aggiuntivo di 1–2 GB rispetto alla dimensione del file per alcuni migliaia di token di contesto; tale margine va aumentato ulteriormente se si utilizzano contesti molto lunghi. Il modello funziona alla massima velocità quando l'intero carico rientra nella VRAM della GPU; gli strumenti basati su llama.cpp possono scaricare le parti eccedenti nella RAM di sistema, soluzione comunque funzionante ma progressivamente più lenta man mano che aumenta il numero di livelli spostati.

VRAM	Ciò che trova comodamente spazio
8 GB	modelli da 7–8B a Q4_K_M o Q5_K_M
12 GB	8B a Q8_0, oppure 12–14B a Q4_K_M
16 GB	14B a Q5_K_M/Q6_K
24 GB	~32B a Q4_K_M, oppure 14B a Q8_0 con contesto lungo

Per valori esatti relativi a un modello specifico e a una determinata lunghezza di contesto, lo strumento Calcolatore VRAM esegue automaticamente i calcoli necessari, mentre una suddivisione dettagliata per singolo modello è disponibile in Requisiti di VRAM per ogni principale modello linguistico di grandi dimensioni (LLM). Se stai scegliendo l'hardware piuttosto che una specifica quantizzazione, inizia da le migliori GPU per LLM locali.

GGUF vs safetensors

Questi due formati coesistono perché servono runtime diversi, non perché uno stia prevalendo sull'altro.

	GGUF	safetensors
Progettato per	llama.cpp e il suo ecosistema	L'ecosistema Hugging Face / PyTorch
Contenuto	Pesi + tokenizer + configurazione in un unico file	Solo tensori; configurazione e tokenizer sono file JSON separati
Quantizzazione	Integrata nel formato (Q4_K_M, ecc.)	Generalmente FP16/BF16; quantizzati tramite metodi esterni (GPTQ, AWQ)
Runtime tipici	Ollama, LM Studio, llama.cpp, KoboldCpp, Jan	transformers, vLLM, TGI, SGLang
Punto ottimale	Hardware consumer, ibrido CPU+GPU, utilizzo singolo	GPU per datacenter, erogazione ad alto throughput, addestramento

La decisione riguarda in realtà quale software si esegue: gli strumenti desktop e Ollama richiedono GGUF; gli stack per l’hosting su GPU e qualsiasi attività che coinvolga il fine-tuning richiedono safetensors. I publisher di modelli rilasciano tipicamente prima i file safetensors, e la comunità li converte in GGUF entro pochi giorni.

Origine dei file GGUF

Quasi tutti i file GGUF sono ospitati su Hugging Face. Labs pubblica occasionalmente GGUF ufficiali, ma la maggior parte proviene da quantizzatori della comunità — account come bartowski, unsloth, lmstudio-community e ggml-org — che convertono ogni nuovo rilascio nell'intera gamma di quantizzazioni disponibili. Un repository chiamato, ad esempio, Meta-Llama-3.1-8B-Instruct-GGUF conterrà un file per ciascun livello di quantizzazione.

Puoi anche convertire autonomamente un modello usando gli strumenti di llama.cpp: convert_hf_to_gguf.py trasforma un modello Hugging Face in un GGUF in F16, mentre il binario llama-quantize (compilato insieme a llama.cpp) lo comprime nella quantizzazione prescelta, ad esempio. modello llama-quantize model-f16.gguf model-Q4_K_M.gguf Q4_K_M.

Caricamento di un file GGUF in Ollama

Ollama può scaricare direttamente repository GGUF da Hugging Face, specificando la quantizzazione dopo i due punti:

ollama run hf.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF:Q4_K_M

Per un file già presente sul disco, crea un file di testo semplice denominato Modelfile contenente:

FROM ./my-model.gguf

quindi registrarlo ed eseguirlo:

ollama create my-model -f Modelfile
ollama run my-model

Le versioni attuali di Ollama leggono automaticamente il template di chat incorporato nei metadati GGUF; se un modello importato produce output illeggibile, la soluzione consiste generalmente nell’aggiungere esplicitamente una riga TEMPLATE al file Modelfile. La Guida completa a Ollama tratta in modo approfondito i Modelfile.

Caricamento di un file GGUF in LM Studio

Il metodo standard è il downloader integrato: apri la scheda Discover, cerca un modello e LM Studio elenca le quantizzazioni GGUF disponibili, indicando quali sono compatibili con il tuo hardware. Per importare un file già presente sul disco, usa l’interfaccia a riga di comando (lms import path/to/model.gguf) oppure copialo nella cartella dei modelli di LM Studio — il percorso predefinito esatto varia in base alla versione e al sistema operativo, ma la scheda My Models lo mostra e consente di modificarlo. I file devono risiedere in una struttura di sottocartelle del tipo publisher/model-name/ per essere riconosciuti. Consulta la Guida completa a LM Studio per la procedura dettagliata.

Pronto a eseguirne uno? La nostra guida ai modelli GGUF tratta dimensionamento, download ed esecuzione su Linux, macOS e Windows.

Domande frequenti

GGUF è supportato solo su CPU o utilizza anche la GPU?

Entrambe le opzioni. llama.cpp è nato come progetto di inferenza su CPU, ma trasferisce i layer del modello sulla GPU (CUDA, Metal, Vulkan, ROCm) ed esegue l’intero modello sulla GPU quando questo entra interamente nella VRAM. Ollama e LM Studio gestiscono automaticamente la suddivisione tra CPU e GPU; usando direttamente llama.cpp, puoi controllarla tramite il flag -ngl (numero di layer da assegnare alla GPU).

Qual è la differenza tra Q4_K_M e Q4_K_S?

Entrambe sono quantizzazioni k-quants da ~4 bit; la lettera indica la variante dimensionale. _M (medium) mantiene una maggiore precisione per i tensori più sensibili alla qualità rispetto a _S (small), risultando quindi leggermente più grande e leggermente più performante. La differenza è minima: scegli _M a meno che gli ultimi centinaia di megabyte non facciano la differenza per far entrare il modello nella memoria disponibile.

Quanta qualità si perde effettivamente con la quantizzazione?

Con Q8_0 e Q6_K la perdita è praticamente nulla — test ciechi faticano a distinguerli dall’originale in formato F16. Q4_K_M comporta una lieve perdita misurabile, che la maggior parte degli utenti non nota mai durante una conversazione, sebbene possa influire su compiti particolarmente precisi come la generazione di codice o calcoli matematici. Al di sotto di Q4 la degradazione diventa evidente, e i modelli più piccoli ne risentono di più rispetto a quelli più grandi.

Posso usare GGUF con transformers o vLLM?

Esiste un supporto limitato, ma non è il percorso nativo: transformers può dequantizzare alcuni file GGUF al momento del caricamento, mentre vLLM dispone di un supporto sperimentale per GGUF, la cui compatibilità varia in base all’architettura. Se stai sviluppando su questi stack, preferisci il formato safetensors; GGUF va considerato piuttosto come il formato nativo per i runtime della famiglia llama.cpp.

Perché il mio modello è suddiviso in più file .gguf?

I modelli molto grandi vengono partizionati in parti denominate ad esempio model-00001-of-00002.gguf, principalmente per rimanere al di sotto dei limiti di dimensione imposti dalle piattaforme di hosting. Conserva tutti i file nella stessa cartella e punta il tuo runtime sul primo — llama.cpp e gli strumenti basati su di esso caricheranno automaticamente le parti rimanenti.

Una volta individuata la quantizzazione compatibile con il tuo hardware, la domanda pratica successiva è quale modello utilizzare: la Database di modelli tabella comparativa i migliori modelli locali per Ollama i migliori modelli locali per Ollama