GGUF: cos'è e come leggere il nome prima di scaricarlo

Cos'è un file GGUF

Un file GGUF è un modello linguistico salvato in un solo file, pronto per llama.cpp, Ollama e gli altri programmi che eseguono modelli in locale. Dentro ci sono i pesi del modello, il tokenizer e i metadati che servono per farlo girare. Il nome del file, se sai leggerlo, ti dice architettura, numero di parametri e tipo di quantizzazione prima di scaricare diversi gigabyte.

La quantizzazione è la riduzione della precisione dei pesi: invece di salvare ogni numero a 16 o 32 bit, lo si salva con 8, 4 o anche meno bit. Il file diventa più piccolo e il modello perde un po' di qualità. Quasi tutti i file GGUF che trovi su Hugging Face sono quantizzati, e il nome dice come.

Da dove viene il formato GGUF

GGUF nasce nel progetto llama.cpp. La pull request #2398, che lo introduce, è stata unita il 21 agosto 2023. È stata una modifica incompatibile: i modelli nei formati precedenti andavano convertiti di nuovo.

Prima di GGUF c'erano tre formati, uno dopo l'altro. GGML era la base, senza numero di versione. GGMF aggiungeva una versione. GGJT aggiungeva l'allineamento dei tensori. La specifica ufficiale, nel file docs/gguf.md del repository ggml-org/ggml, presenta GGUF come il loro successore. La differenza principale sono i metadati chiave-valore: un nuovo campo si aggiunge al file senza rompere i programmi che già leggono il formato.

Cosa significa la sigla? La specifica non lo dice. Online circolano varie espansioni, ma nessuna compare nel documento ufficiale, quindi non trattarle come un dato certo.

Com'è fatto un file GGUF dentro

Un tensore è una tabella di numeri a più dimensioni. I pesi di un modello sono centinaia di tensori. Un file GGUF li mette in fila insieme a tutto quello che serve per usarli. Secondo la specifica, le parti sono quattro, in questo ordine:

1. L'header. Inizia con il numero magico 0x47475546, cioè le lettere GGUF in ASCII. Poi vengono la versione del formato (la specifica attuale è la 3), il numero di tensori e il numero di coppie chiave-valore.
2. I metadati chiave-valore: architettura, tokenizer, lunghezza del contesto, template della chat e molto altro.
3. Le informazioni sui tensori: per ognuno, nome, dimensioni, tipo di dato e posizione nel file.
4. I dati dei tensori, allineati a un multiplo fisso di byte.

L'allineamento serve perché il programma possa mappare il file in memoria con mmap e leggere i pesi così come sono, senza copiarli. Per questo un modello GGUF si carica in fretta.

Il punto pratico è che il file è autosufficiente. Un repository in formato safetensors, il formato standard di Hugging Face, divide le cose: i pesi stanno nei file .safetensors, la configurazione in config.json, il tokenizer in tokenizer.json. La documentazione di Hugging Face lo dice in modo chiaro: safetensors contiene solo tensori, GGUF contiene tensori e un insieme standard di metadati. Con un file GGUF scarichi un solo oggetto e hai tutto.

Le chiavi di metadati obbligatorie

La specifica rende obbligatorie poche chiavi:

• general.architecture: l'architettura del modello, per esempio llama. Il programma la legge per scegliere il codice che esegue il modello. Le altre chiavi specifiche usano questo nome come prefisso, per esempio llama.context_length.
• general.quantization_version: la versione dello schema di quantizzazione. È obbligatoria quando i tensori sono quantizzati.
• general.alignment: l'allineamento dei dati in byte. Se manca, si assume 32.

Altre chiavi non sono obbligatorie ma ti interessano. general.name è il nome leggibile del modello. <architettura>.context_length è la lunghezza di contesto con cui il modello è stato addestrato. Non è la stessa cosa del contesto che Ollama usa davvero, come spiega la guida su num_ctx e la lunghezza di contesto in Ollama. tokenizer.chat_template contiene il template che trasforma una conversazione nel testo che il modello si aspetta.

Come leggere il nome di un file GGUF

La specifica propone una convenzione per i nomi. I campi sono separati da trattini, in questo ordine:

<BaseName>-<SizeLabel>-<FineTune>-<Version>-<Encoding>-<Type>-<Shard>.gguf

• BaseName: il nome del modello o dell'architettura.
• SizeLabel: il numero di parametri, con una lettera per la scala. 7B vuol dire 7 miliardi. 8x7B indica un modello con 8 esperti da 7 miliardi ciascuno.
• FineTune: per cosa il modello è stato rifinito, per esempio Instruct o Chat. Facoltativo.
• Version: la versione, nella forma v<maggiore>.<minore>.
• Encoding: il tipo di quantizzazione dei pesi, per esempio Q4_K_M o F16.
• Type: LoRA per un adattatore, oppure vocab per un file che contiene solo il vocabolario. Facoltativo.
• Shard: presente solo se il modello è diviso in più file, nella forma 00001-of-00003.

Gli esempi della specifica sono Mixtral-8x7B-v0.1-KQ2.gguf e Grok-100B-v1.0-Q4_0-00003-of-00009.gguf. Non tutti i repository seguono la convenzione alla lettera. Molti usano le minuscole, altri saltano qualche campo. L'ordine però è quasi sempre questo.

Un esempio italiano: Minerva

Minerva è la famiglia di modelli di Sapienza NLP, il gruppo di ricerca dell'Università La Sapienza di Roma. È addestrata da zero su testo italiano e inglese. Su Hugging Face il repository sapienzanlp/Minerva-7B-instruct-v1.0-GGUF contiene, a ottobre 2026, questo file:

minerva-7b-instruct-v1.0-q4_k_m.gguf

Leggilo campo per campo:

• minerva: il nome del modello.
• 7b: 7 miliardi di parametri.
• instruct: la versione rifinita per seguire istruzioni, adatta alla chat. Il modello base non ha questa parola nel nome.
• v1.0: la versione del modello.
• q4_k_m: quantizzazione K a 4 bit, variante media. È la parte più importante, e la spiego nella prossima sezione.

Non c'è un campo Shard, quindi il modello sta in un solo file. Lo stesso repository contiene 6 file GGUF dello stesso modello. Cambia solo la parte Encoding, e con lei la dimensione:

[
  {
    "label": "f32",
    "dimensione_gb": 29.6
  },
  {
    "label": "f16",
    "dimensione_gb": 14.8
  },
  {
    "label": "q8_0",
    "dimensione_gb": 7.86
  },
  {
    "label": "q6_k",
    "dimensione_gb": 6.07
  },
  {
    "label": "q4_k_m",
    "dimensione_gb": 4.48
  },
  {
    "label": "q4_0",
    "dimensione_gb": 4.22
  }
]

La versione f32 pesa 29.6 GB e la f16 pesa 14.8 GB. Non sono quantizzate: ogni peso è un numero in virgola mobile a 32 o 16 bit. La q8_0 scende a 7.86 GB, la q4_k_m a 4.48 GB e la q4_0 a 4.22 GB. Il nome ti dice quanto spazio ti serve prima ancora di aprire la pagina del file.

Cosa significano Q4_K_M, IQ2_XS e TQ1_0

La parte Encoding segue alcune famiglie. La tabella dei tipi nella documentazione di Hugging Face le descrive tutte.

• F32, F16, BF16: pesi non quantizzati. BF16 è un formato a 16 bit con lo stesso intervallo di valori del formato a 32 bit.
• Q4_0, Q5_1, Q8_0: i tipi più vecchi. I pesi sono divisi in blocchi da 32, e ogni blocco ha un suo fattore di scala. Il numero dopo la Q è il numero di bit per peso.
• Da Q2_K a Q6_K: le K-quant. Usano super-blocchi da 256 pesi, con scale salvate a loro volta in forma compatta. Un Q4_K occupa circa 4,5 bit per peso.
• I suffissi _S, _M e _L (piccolo, medio, grande) indicano un mix. Un file Q4_K_M non usa Q4_K per ogni tensore: alcuni tensori più sensibili restano a una precisione più alta. _S ne alza meno, _L di più, e il file cresce di conseguenza.
• Da IQ1_S a IQ4_XS, più IQ4_NL: quantizzazioni che usano una matrice di importanza (imatrix). È una misura, fatta su un testo di prova, di quali pesi contano di più per il risultato. Permette di scendere a 2 o 3 bit per peso perdendo meno qualità.
• TQ1_0 e TQ2_0: tipi ternari. Ogni peso vale -1, 0 oppure +1, con un fattore di scala condiviso.

I modelli ternari sono un buon esempio di un nome che non basta. A ottobre 2026 il repository prism-ml/Ternary-Bonsai-27B-gguf contiene due file: Ternary-Bonsai-27B-PQ2_0.gguf e Ternary-Bonsai-27B-Q2_g64.gguf. Nessuno dei due è un tipo che trovi nella lista sopra. La scheda del modello spiega che il primo richiede un fork di llama.cpp mantenuto da PrismML, perché usa kernel propri. Il secondo è quello indicato per llama.cpp ufficiale. Dal solo nome non lo potevi sapere.

Quale tipo scegliere per il tuo uso è un'altra domanda, e ha una guida sua: le differenze pratiche tra Q4, Q8 e FP16.

Suffissi che non sono nella specifica

Molti nomi contengono parti che la specifica non definisce. Alcune sono convenzioni diffuse. Un modello MoE (mixture of experts) contiene più reti esperte, e per ogni token ne lavorano solo alcune. In questi modelli un nome come 30B-A3B indica 30 miliardi di parametri in totale e 3 miliardi attivi per token. Anche -GGUF alla fine del nome del repository è solo un'abitudine, per distinguerlo dal repository originale in safetensors.

Altre sigle sono proprie di un singolo autore. Su alcuni repository compaiono suffissi come GSQ-RCO. Non sono nella specifica e non hanno un significato standard. In questi casi apri la scheda del modello (model card) su Hugging Face. Se la scheda non spiega la sigla, non indovinare, e scegli un file con un nome standard.

File divisi: cosa vuol dire -00001-of-00003

Un modello molto grande viene spesso diviso in più file. Il campo Shard usa sempre cinque cifre: -00001-of-00003.gguf è la prima di tre parti. Ti servono tutte, nella stessa cartella. Una parte da sola non è un modello utilizzabile.

llama.cpp carica un modello diviso se gli passi la prima parte, e trova le altre da solo. Se un programma vuole un file unico, puoi unire le parti con lo strumento llama-gguf-split di llama.cpp. Basta indicare la prima parte e il nome del file finale:

llama-gguf-split --merge modello-Q4_K_M-00001-of-00003.gguf modello-Q4_K_M.gguf

Il file unito occupa lo stesso spazio della somma delle parti, quindi controlla il disco prima di farlo.

Come ispezionare un file GGUF

Puoi leggere i metadati di un file GGUF prima di scaricarlo. Hugging Face ha un visualizzatore integrato. Nella scheda dei file di un repository, l'icona accanto a un file .gguf apre una finestra con i metadati e l'elenco dei tensori, con nome, forma e precisione di ognuno. Si apre anche con un indirizzo come questo:

https://huggingface.co/sapienzanlp/Minerva-7B-instruct-v1.0-GGUF?show_tensors=minerva-7b-instruct-v1.0-q4_k_m.gguf

Lì controlli general.architecture e il tipo dei tensori senza scaricare nulla. Se nell'elenco vedi tensori a precisioni diverse, è il mix che il suffisso _M promette.

Dopo il download, sul tuo server, usi il pacchetto Python gguf, mantenuto nel repository di llama.cpp. Installalo con pip dentro un ambiente virtuale, perché su Ubuntu 24.04 un pip install di sistema viene rifiutato con l'errore externally-managed-environment.

sudo apt update && sudo apt install -y python3-venv
python3 -m venv ~/gguf-env
~/gguf-env/bin/pip install gguf

Scarica il file con curl. L'opzione -L è necessaria, perché Hugging Face risponde con un reindirizzamento verso il suo server di distribuzione. Senza -L, curl salva la risposta del reindirizzamento, e ottieni un file di pochi byte con il nome giusto.

curl -L -O https://huggingface.co/sapienzanlp/Minerva-7B-instruct-v1.0-GGUF/resolve/main/minerva-7b-instruct-v1.0-q4_k_m.gguf
ls -lh minerva-7b-instruct-v1.0-q4_k_m.gguf
head -c 4 minerva-7b-instruct-v1.0-q4_k_m.gguf; echo

ls -lh deve mostrare una dimensione vicina a quella indicata su Hugging Face. Secondo la specifica, i primi quattro byte di un file GGUF valido sono le lettere GGUF. Se head stampa altro, per esempio l'inizio di una pagina HTML, il download non è andato a buon fine.

Ora leggi i metadati. L'opzione --no-tensors salta l'elenco dei tensori, che per un modello da 7 miliardi è lungo. --json produce un output da elaborare con altri strumenti.

~/gguf-env/bin/gguf-dump --no-tensors minerva-7b-instruct-v1.0-q4_k_m.gguf
~/gguf-env/bin/gguf-dump --json minerva-7b-instruct-v1.0-q4_k_m.gguf > metadati.json

Cerca nell'output general.architecture, la chiave che finisce in .context_length e tokenizer.chat_template. Queste chiavi spiegano la maggior parte dei problemi al primo avvio.

Quali programmi caricano un file GGUF

GGUF è il formato nativo di llama.cpp, e lo usano i programmi costruiti sulla libreria ggml. La documentazione di Hugging Face cita llama.cpp, LM Studio, GPT4All e Ollama. In Ollama un file GGUF si importa con una riga FROM nel Modelfile, e i passaggi completi sono nella guida su come importare un modello GGUF in Ollama. Se devi scegliere tra i due programmi su un server, il confronto Ollama contro llama.cpp spiega cosa aggiunge Ollama sopra llama.cpp.

vLLM è diverso. È un server pensato per i pesi in safetensors e per servire molti utenti insieme su GPU. A ottobre 2026 la sua documentazione descrive il supporto GGUF come molto sperimentale e poco ottimizzato. Il supporto è stato spostato in un plugin separato, vllm-gguf-plugin, da installare a parte. La documentazione consiglia anche di usare il tokenizer del modello base invece di quello nel file GGUF, perché la conversione del tokenizer da GGUF è lenta e instabile. In pratica, per vLLM scarica la versione safetensors del modello. Quando conviene vLLM e quando no è il tema di Ollama contro vLLM.

Un file GGUF integro può comunque non partire. La causa più comune è un programma più vecchio del modello. Se llama.cpp non conosce il valore di general.architecture, si ferma al caricamento con un errore che contiene unknown model architecture. Aggiornare llama.cpp, o Ollama, risolve. La scheda di Minerva, per esempio, indica la versione minima di llama.cpp che serve.

Cosa controllare prima di scaricare

• L'architettura, nel visualizzatore di Hugging Face, è supportata dalla versione del programma che usi.
• Il tipo nel campo Encoding è standard. Se non lo riconosci, leggi la scheda del modello prima di scaricare.
• Il modello è in un file solo, oppure in più parti che devi scaricare tutte.
• La dimensione del file è compatibile con la tua memoria. Il calcolo completo, contesto incluso, è in quanto è grande il modello che entra nella tua RAM.

FAQ

Cosa significa la sigla GGUF?

La specifica ufficiale del formato, nel repository ggml-org/ggml, non definisce la sigla. Dice solo che GGUF è un formato per salvare modelli da eseguire con ggml e con i programmi basati su ggml. Le espansioni che trovi online non sono ufficiali. Il formato è entrato in llama.cpp con la pull request #2398, unita il 21 agosto 2023, come successore di GGML, GGMF e GGJT.

Qual è la differenza tra GGUF e safetensors?

Un file safetensors contiene solo i tensori, cioè i pesi. La configurazione e il tokenizer stanno in file separati nello stesso repository. Un file GGUF contiene pesi, tokenizer e metadati in un solo file, di solito già quantizzato. llama.cpp, Ollama e LM Studio usano GGUF. vLLM lavora soprattutto con safetensors, e lì il supporto GGUF è sperimentale e passa da un plugin separato.

Cosa vuol dire Q4_K_M nel nome di un file GGUF?

Q4 indica pesi quantizzati a circa 4 bit. K indica la famiglia delle K-quant, che usa super-blocchi da 256 pesi. M vuol dire medio: alcuni tensori più sensibili restano a una precisione più alta, quindi il file è un po' più grande di un Q4_K_S. Nel visualizzatore di Hugging Face vedi il tipo di ogni tensore.

Come si usa un modello GGUF diviso in file -00001-of-0000N?

Scarica tutte le parti nella stessa cartella. Una parte da sola non funziona. llama.cpp carica il modello se gli passi la prima parte, e trova le altre da solo. Se un programma vuole un file unico, unisci le parti con llama-gguf-split --merge, indicando la prima parte e il nome del file finale.

Perché il mio file GGUF appena scaricato non si carica?

Controlla prima il download: head -c 4 sul file deve stampare GGUF, e la dimensione deve corrispondere a quella su Hugging Face. Un curl senza -L salva solo un reindirizzamento di pochi byte. Se il file è integro e l'errore contiene unknown model architecture, il tuo llama.cpp o il tuo Ollama è più vecchio del modello e va aggiornato. Se il tipo di quantizzazione non è standard, leggi la scheda del modello, perché alcuni file richiedono un fork di llama.cpp.