Formato GGUF: guida completa all’inferenza locale degli LLM

Che cos’è GGUF?

GGUF, acronimo di GGML Unified Format, è un formato di file binario che impacchetta pesi del modello, dati del tokenizer, metadati dell’architettura e informazioni di quantizzazione in un singolo file portatile per l’inferenza con runtime basati su GGML, in particolare llama.cpp.

GGUF risolve un problema di distribuzione degli LLM. Molti formati di modello richiedono di mantenere insieme diversi file, inclusi pesi del modello, file del tokenizer, file di configurazione e codice di caricamento specifico per l’architettura. GGUF semplifica rendendo il file del modello in gran parte auto-descrittivo.

Un file GGUF in genere contiene:

• Tensori del modello
• Pesi quantizzati o non quantizzati
• Vocabolario del tokenizer
• Configurazione del tokenizer
• Metadati dell’architettura del modello
• Impostazioni della lunghezza del contesto
• Dimensioni degli embedding
• Numero di teste di attenzione
• Configurazione RoPE
• Nomi, forme e tipi di dato dei tensori

L’idea chiave è che il file si descrive da solo. Il runtime può ispezionare i metadati, comprendere l’architettura, caricare il tokenizer e mappare i tensori senza fare affidamento su un config.json separato o su una cartella del tokenizer.

Questo non significa che ogni file GGUF sia universalmente compatibile con ogni runtime per sempre. Il runtime deve comunque supportare l’architettura del modello e i tipi di tensore usati nel file. Tuttavia, GGUF rende quella compatibilità molto più semplice rispetto ai formati più vecchi perché il file include molte più informazioni strutturate.

Quattro caratteristiche distintive di GGUF sono:

1. Distribuzione in un singolo file
2. Supporto al memory mapping per un caricamento efficiente
3. Metadati estendibili tipizzati key-value
4. Supporto per molti tipi di quantizzazione, dalle forme a basso numero di bit fino alla piena precisione

GGUF è stato introdotto come parte dell’ecosistema llama.cpp e GGML nel 2023. Oggi è il formato dominante per distribuire LLM locali quantizzati su Hugging Face.

GGUF vs. GGML

Il formato GGML (Georgi Gerganov Machine Learning) è stato il predecessore di GGUF. È stato importante perché ha reso possibile le prime inferenze locali. Tuttavia, aveva limitazioni pratiche quando l’ecosistema si è ampliato oltre i modelli LLaMA originali.

I problemi comuni di GGML includevano:

• Gestione dei metadati meno flessibile
• Maggiori assunzioni di caricamento specifiche per architettura
• Gestione di tokenizer e configurazione meno auto-contenuta
• Estendibilità più difficile con l’apparire di nuove famiglie di modelli

GGUF ha risolto queste limitazioni con un formato più strutturato. Ha introdotto metadati tipizzati, embedding del tokenizer migliorati e un layout di file più chiaro. Questo ha reso più facile per llama.cpp e strumenti correlati supportare più architetture senza dover riprogettare continuamente la pipeline di caricamento.

Per gli utenti, la differenza importante è semplice: GGUF è il formato moderno. Se oggi scarichi modelli, quasi sempre dovresti scegliere GGUF anziché i vecchi file GGML.

GGUF vs. GPTQ e AWQ

Informandoti sui formati di file, avrai sicuramente incontrato GGUF, GPTQ (Generative Post-Training Quantization) e AWQ (Activation-Aware Weight Quantization). Se ne parla spesso insieme perché tutti e tre servono a rendere l’inferenza degli LLM più efficiente. Tuttavia, non appartengono alla stessa categoria.

GGUF è principalmente un formato di file e un contenitore di distribuzione. Supporta molti tipi di quantizzazione ed è strettamente associato all’inferenza locale in stile llama.cpp.

GPTQ e AWQ sono metodi di quantizzazione ed ecosistemi comunemente usati per l’inferenza ottimizzata su GPU, in particolare su hardware NVIDIA tramite framework come Transformers, ExLlama, AutoGPTQ e workflow compatibili con vLLM.

Se il tuo obiettivo è la massima compatibilità tra laptop, desktop, Apple Silicon e hardware misto, GGUF è di solito la scelta più sicura.

Se il tuo obiettivo è il massimo throughput su server di inferenza NVIDIA dedicati, GPTQ, AWQ, FP8 o altri formati di serving ottimizzati per GPU potrebbero essere più adatti.

Perché usare GGUF?

GGUF è diventato popolare perché risolve problemi pratici di distribuzione. Personalmente lo trovo comodissimo quando faccio deploy in locale senza tutta la confusione di setup.

Eseguire LLM locali significava strumenti frammentati, pesi non compressi molto grandi, formati di modello incompatibili e passaggi di configurazione complicati. Ora GGUF può aiutarti a standardizzare gran parte di quel flusso di lavoro.

Invece di pensare a molti file separati e script di caricamento, gli utenti possono concentrarsi sulla scelta del modello giusto, del livello di quantizzazione e sull’esecuzione dell’inferenza.

Esegui i modelli in locale

GGUF ti consente di eseguire LLM sulla tua macchina. Questo significa:

• Nessun costo per token via API
• Nessuna dipendenza da un provider di inferenza hosted
• Nessuna necessità di inviare prompt a un’API di terze parti
• Inferenza offline possibile dopo aver scaricato il modello

È particolarmente utile per workflow sensibili alla privacy. Gli sviluppatori potrebbero non voler inviare codice proprietario, documenti interni, dati dei clienti o prompt riservati a un’API esterna.

L’inferenza locale non è automaticamente sicura di per sé. Devi comunque gestire correttamente macchina, log, applicazioni e controlli di accesso. Ma GGUF rende molto più accessibile il deploy locale privato.

Per fare pratica con i modelli in locale, vedi i nostri tutorial su eseguire Mistral Medium 3.5 con SGLang, eseguire DeepSeek V4 Flash in locale, eseguire l’efficiente modello Bonsai a 1 bit su un vecchio laptop e eseguire MiniMax M2 in locale come assistente di coding.

Flessibilità hardware

GGUF è utile perché funziona su molte configurazioni hardware.

A seconda del runtime e del backend, i modelli GGUF possono girare su:

• Macchine solo CPU
• GPU NVIDIA tramite CUDA
• Apple Silicon tramite Metal
• GPU AMD tramite HIP o Vulkan
• GPU Intel tramite SYCL o Vulkan
• Alcuni ambienti ARM e mobile

Questa flessibilità è una delle ragioni per cui llama.cpp è diventato influente. Non è stato progettato solo per GPU server di fascia alta. È stato pensato per rendere possibile l’inferenza locale su un’ampia gamma di hardware.

Per esempio, un utente Mac può affidarsi all’accelerazione Metal, mentre un utente Linux desktop può usare CUDA o Vulkan. Un utente solo CPU può comunque eseguire modelli quantizzati più piccoli, anche se la velocità di generazione sarà inferiore.

Ampio supporto nell’ecosistema

GGUF è supportato da molti strumenti di inferenza locale. Esempi includono:

• llama.cpp per inferenza da riga di comando e server
• Ollama per gestione dei modelli via CLI e accesso API
• LM Studio per una GUI desktop
• GPT4All per chat locali orientate alla privacy
• KoboldCpp per roleplay locale e workflow di generazione testo
• Jan e Open WebUI per interfacce IA locali

Questo conta perché gli utenti non sono vincolati a un’unica interfaccia. Lo stesso formato generale di modello può essere usato in workflow diversi.

Uno sviluppatore può fare benchmark di un modello con llama.cpp, chattarci in LM Studio, servirlo tramite Ollama e collegarlo a un’interfaccia browser tramite Open WebUI.

Distribuzione su Hugging Face

Hugging Face è diventato un importante hub di distribuzione per i modelli GGUF.

Fonte: Hugging Face

Molti modelli a pesi aperti popolari ricevono varianti GGUF caricate dalla community poco dopo il rilascio. Questi repository spesso includono diverse opzioni di quantizzazione così che gli utenti possano scegliere un modello adatto al proprio hardware.

Varianti caricate comuni includono:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0
• IQ4_XS
• IQ3_M
• IQ2_XXS

Questo significa che spesso non è necessario convertire manualmente. Per i modelli più popolari, qualcuno nella community ha già creato file GGUF per i livelli di quantizzazione più comuni.

Controllo granulare dimensione-qualità

GGUF offre un controllo fine sul compromesso tra dimensione e qualità. Puoi scegliere:

• Quantizzazioni più piccole per macchine con poca memoria
• Quantizzazioni intermedie per un uso quotidiano bilanciato
• Quantizzazioni a più bit per coding, ragionamento o output strutturati
• Piena o quasi piena precisione quando la memoria non è un vincolo

Questa flessibilità è uno dei vantaggi maggiori del formato. Invece di un unico target di distribuzione fisso, GGUF consente di adattare la stessa famiglia di modelli a molti livelli hardware.

Come funziona GGUF?

Un file GGUF è organizzato in tre parti principali:

1. Header
2. Metadati e informazioni sui tensori
3. Dati dei tensori

La struttura esatta è definita dalla specifica GGUF. L’idea importante è che metadati e informazioni sui tensori compaiono prima dei dati grezzi dei tensori, consentendo a un runtime di capire cosa sta per caricare.

L’header

L’header identifica il file come GGUF e indica al runtime come effettuare il parsing del resto del file. Include:

• Magic number per GGUF
• Versione del formato
• Conteggio dei tensori
• Conteggio delle coppie key-value dei metadati

I file GGUF moderni usano comunemente la versione 3.

I motori di inferenza controllano prima il magic number. Se il file non inizia con l’identificatore GGUF atteso, il runtime può rifiutarlo prima di provare a fare il parsing dei tensori o allocare memoria.

È un passaggio semplice ma importante per sicurezza e affidabilità. Impedisce a un runtime di trattare accidentalmente un file binario non correlato come un modello.

Coppie key-value di metadati

I metadati GGUF sono un archivio key-value tipizzato. Questi metadati possono descrivere:

• Informazioni generali sul modello
• Famiglia di architetture
• Lunghezza del contesto
• Dimensione degli embedding
• Numero di layer
• Numero di teste di attenzione
• Parametri RoPE
• Vocabolario del tokenizer
• Token speciali
• Informazioni di quantizzazione

Le chiavi sono di solito con namespace. Esempi includono:

• general.architecture
• general.alignment
• llama.context_length
• tokenizer.ggml.tokens

Il namespacing è importante perché consente a GGUF di supportare molte architetture senza cambiare l’intero formato di file. Un modello della famiglia LLaMA può usare chiavi llama.*, mentre altre famiglie possono usare metadati specifici per la propria architettura.

Questo è uno dei motivi per cui GGUF si è adattato bene a modelli oltre la famiglia LLaMA originale, incluse architetture come Qwen, Mistral, Gemma, DeepSeek, Phi e altre.

Informazioni sui tensori e dati dei tensori

Dopo i metadati, il file memorizza informazioni sui tensori e i dati dei tensori.

Le informazioni sui tensori descrivono:

• Nome del tensore
• Forma
• Tipo di dato
• Offset nella sezione dei dati dei tensori

La sezione dei dati dei tensori contiene i pesi effettivi del modello. Questi pesi possono essere memorizzati in piena precisione o in uno dei tipi di tensore quantizzato supportati da GGUF.

GGUF usa un valore di allineamento definito nei metadati, comunemente general.alignment. Molti file GGUF usano un allineamento a 32 byte, ma il modo corretto di descriverlo è che l’allineamento è controllato dai metadati piuttosto che codificato in modo permanente.

L’allineamento è importante perché consente ai runtime di accedere ai blocchi di tensori in modo efficiente.

Memory mapping

Uno dei vantaggi pratici di GGUF è il memory mapping, spesso chiamato mmap.

Con il memory mapping, il sistema operativo può mappare il file del modello nella memoria virtuale invece di costringere il runtime a copiare l’intero file in RAM in anticipo.

Questo può far sembrare l’avvio del modello molto più veloce, specialmente su SSD. Consente anche al sistema operativo di paginare i dati del modello secondo necessità.

Tuttavia, il memory mapping non fa miracoli. Il modello ha comunque bisogno di sufficiente banda di memoria pratica e RAM o VRAM disponibile per funzionare bene. Se il tuo sistema fa continuamente paging dal disco, l’inferenza può diventare lenta.

Un modo migliore per pensare a mmap è questo:

• Migliora l’efficienza di caricamento
• Riduce copie inutili
• Lascia al sistema operativo la gestione del paging
• Non elimina i requisiti di memoria dell’inferenza

Capire i tipi di quantizzazione GGUF

La quantizzazione comprime i pesi del modello in rappresentazioni a precisione inferiore.

Invece di memorizzare ogni peso come un valore a 16 bit in virgola mobile, un modello quantizzato memorizza valori approssimati usando meno bit. Questo riduce la dimensione su disco, l’uso di RAM e VRAM e la pressione sulla banda di memoria.

L’intuizione chiave è che molti pesi delle reti neurali non necessitano della piena precisione in virgola mobile durante l’inferenza. Un modello quantizzato con cura può preservare gran parte del comportamento originale diventando però molto più piccolo.

Nomenclatura della quantizzazione GGUF

I nomi di quantizzazione GGUF seguono di solito questo schema:

• Q significa quantizzato
• Il numero suggerisce i bit per peso approssimativi
• K si riferisce alla famiglia k-quant
• S, M e L indicano di solito varianti small, medium e large

Esempi includono:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0

Il nome è una guida utile, ma non è sempre un’indicazione esatta della dimensione totale del file. La dimensione reale dipende dal mix di tensori, dall’architettura, dai metadati, dalla dimensione del tokenizer e dal fatto che alcuni tensori restino a precisione più alta.

Tipi comuni di quantizzazione GGUF

Questi numeri sono approssimazioni per modelli densi classe 7B. Architetture più recenti, modelli mixture-of-experts, tokenizer più grandi e layout di tensori diversi possono cambiare la dimensione reale del file.

In pratica, Q4_K_M è diventato un default popolare perché offre un buon equilibrio tra dimensione e qualità. Molti utenti lo trovano sufficiente per chat generali, sintesi, riscritture e lavoro esplorativo di IA locale.

Q5_K_M e Q6_K sono spesso scelte migliori per carichi più esigenti, come coding o follow-up di istruzioni multi-step

Il motivo è semplice: questi compiti sono più sensibili a piccole degradazioni di qualità.

K-quant vs. I-quant

I K-quant sono la famiglia di quantizzazione ampiamente utilizzata dietro formati come Q4_K_M, Q5_K_M e Q6_K.

Usano schemi di quantizzazione raggruppata con informazioni di scaling che aiutano a preservare il comportamento del modello riducendo i requisiti di memoria. Sono popolari perché affidabili, ampiamente supportati e facili da trovare nelle release GGUF della community.

Gli I-quant, spesso scritti come formati IQ, sono tipi di quantizzazione più recenti come:

• IQ4_XS
• IQ3_M
• IQ2_XXS
• IQ1_S

Gli I-quant sono progettati per ottenere una qualità migliore a dimensioni molto piccole. Possono usare tecniche come quantizzazione consapevole dell’importanza e codebook di quantizzazione non lineari. Alcuni workflow usano una matrice di importanza, spesso chiamata imatrix, per preservare i pesi più importanti durante la quantizzazione.

Il compromesso è la complessità. Gli I-quant possono produrre ottimi risultati dimensione-qualità, soprattutto a bitrate molto bassi, ma possono richiedere workflow di quantizzazione e supporto runtime più attenti.

Per la maggior parte dei principianti, i K-quant restano il punto di partenza più semplice.

Scegliere un livello di quantizzazione per il tuo hardware

La seguente tabella offre punti di partenza pratici. Considerali regole empiriche, non garanzie ferree. Lunghezza del contesto, overhead del sistema operativo, offload su GPU, dimensione della cache KV e specifica architettura del modello possono tutti modificare i requisiti di memoria.

Regole generali:

• Usa Q4_K_M come default sicuro per la maggior parte delle inferenze locali.
• Usa Q5_K_M quando la qualità conta più del risparmio di ogni gigabyte.
• Usa Q6_K o Q8_0 quando la memoria è disponibile e vuoi una fedeltà migliore.
• Evita Q2_K per lavoro serio a meno che tu non stia testando scenari estremi vincolati dalla memoria.
• Lascia memoria extra per la cache KV, soprattutto con finestre di contesto lunghe.

La cache KV è facile da trascurare. Un modello può entrare in RAM con una lunghezza di contesto corta ma fallire o rallentare con una lunghezza molto maggiore perché la cache cresce con la sequenza.

L’ecosistema GGUF

L’adozione di GGUF è trainata tanto dagli strumenti quanto dal formato stesso.

Un formato diventa utile solo quando gli utenti possono scaricare, eseguire, ispezionare, convertire e servire facilmente i modelli. GGUF beneficia di un ecosistema forte tra strumenti da riga di comando, app desktop, API e repository di modelli hosted.

1. llama.cpp

llama.cpp è il runtime GGUF originale e più importante. È un motore di inferenza leggero in C/C++ creato da Georgi Gerganov e mantenuto dalla community GGML. Il suo obiettivo principale è abilitare un’inferenza LLM efficiente con setup minimo su molte piattaforme hardware.

Il llama.cpp moderno supporta molti backend, tra cui:

• CPU
• CUDA per GPU NVIDIA
• Metal per dispositivi Apple
• Vulkan
• HIP per GPU AMD tramite ROCm
• SYCL per GPU Intel
• OpenCL in ambienti selezionati
• Altri backend specializzati come CANN, OpenVINO e WebGPU, a seconda del supporto della piattaforma

Include anche strumenti per conversione, quantizzazione, serving, benchmarking e inferenza da riga di comando. Strumenti comuni includono:

• convert_hf_to_gguf.py
• llama-quantize
• llama-cli
• llama-server
• llama-bench

I comandi per creare una build CMake base su CPU sono:

cmake -B build
cmake --build build --config Release

Per alcune configurazioni, è necessario aggiungere determinate flag al primo di questi due comandi:

• Disattiva Apple Metal su macOS (abilitato di default): -DGGML_METAL=OFF
• Build Vulkan: -DGGML_VULKAN=1
• Build CUDA per GPU NVIDIA: -DGGML_CUDA=ON

Nota che le build attuali usano opzioni CMake GGML_* come GGML_CUDA, GGML_VULKAN e GGML_HIP.

2. Ollama

Ollama è uno dei modi più semplici per eseguire modelli locali. Fornisce:

• Una CLI semplice
• Download e gestione dei modelli
• Una REST API locale
• Librerie ufficiali Python e JavaScript
• Integrazione con molte interfacce IA locali

Ollama archivia e gestisce i modelli per te, quindi l’utente di solito non interagisce direttamente con i file .gguf. Tuttavia, Ollama è costruito attorno all’inferenza locale compatibile con llama.cpp e può anche importare file GGUF tramite un workflow Modelfile.

Ollama espone un’API locale a:

http://localhost:11434/api

Due endpoint usati spesso sono:

• /api/generate per il completamento dei prompt
• /api/chat per messaggi in stile chat

Per i principianti, Ollama è spesso il percorso più rapido da zero all’inferenza locale.

3. LM Studio

Fonte: LM Studio

LM Studio è un’app desktop per scoprire, scaricare e chattare con modelli locali. È utile per chi preferisce un’interfaccia grafica invece degli strumenti da riga di comando.

4. GPT4All

Fonte: GPT4All

GPT4All è un’altra applicazione IA multipiattaforma focalizzata su workflow di chatbot locali e privati. Supporta i modelli GGUF e offre un ambiente adatto ai principianti per l’inferenza locale.

Questi strumenti rendono GGUF accessibile ai non specialisti. Gli utenti non devono capire CMake, layout dei tensori o dettagli interni della quantizzazione solo per provare un modello locale.

Come iniziare con i modelli GGUF

Ci sono due modi pratici per iniziare:

1. Usa Ollama per l’esperienza più semplice.
2. Usa direttamente llama.cpp per avere più controllo.

Eseguire un modello con Ollama

Il workflow più semplice è scaricare il modello e avviare una sessione di chat interattiva:

ollama pull llama3.3
ollama run llama3.3

Per chiamare il modello da Python usando la REST API:

import requests

payload = {
    "model": "llama3.3",
    "prompt": "Give me three practical use cases for GGUF.",
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/generate",
    json=payload
)

print(response.json()["response"])

Per applicazioni in stile chat, usa /api/chat:

import requests

payload = {
    "model": "llama3.3",
    "messages": [
        {"role": "user", "content": "What is GGUF used for?"}
    ],
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/chat",
    json=payload
)

print(response.json()["message"]["content"])

Il campo stream: false è importante per script semplici. Senza di esso, Ollama restituisce uno stream di oggetti JSON invece di una singola risposta JSON finale.

Puoi anche usare la libreria Python ufficiale di Ollama:

from ollama import chat

response = chat(
    model="llama3.3",
    messages=[
        {"role": "user", "content": "Explain GGUF quantization simply."}
    ]
)

print(response.message.content)

Eseguire un file GGUF con llama.cpp

Se hai già un file .gguf, puoi eseguirlo direttamente con llama.cpp dopo aver compilato il progetto.

Esempio:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Explain the difference between GGUF and GPTQ." \
  -n 256

Se hai abilitato il supporto GPU, puoi fare offload dei layer sulla GPU:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Summarize GGUF in five bullet points." \
  -n 256 \
  -ngl 99

Il flag -ngl controlla il numero di layer portati su GPU. Un valore alto come 99 si usa comunemente per fare offload del più possibile, supponendo che il modello rientri nella VRAM.

Per il serving via API, usa llama-server:

./build/bin/llama-server \
  -m models/model.Q4_K_M.gguf \
  -ngl 99 \
  --host 127.0.0.1 \
  --port 8080

Questo ti fornisce un’interfaccia server locale per integrare llama.cpp nelle applicazioni.

Convertire un modello Hugging Face in GGUF

La maggior parte degli utenti non ha bisogno di convertire manualmente i modelli perché le release GGUF della community sono ampiamente disponibili.

Tuttavia, la conversione manuale è utile quando:

• Hai effettuato il fine-tuning del tuo modello
• Non esiste ancora una versione GGUF
• Vuoi controllare tu stesso il processo di quantizzazione
• Hai bisogno di un tipo specifico di quantizzazione

Un workflow tipico è:

1. Scaricare un modello da Hugging Face.
2. Convertirlo in GGUF.
3. Quantizzare il file GGUF.

Esempio:

huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3 \
  --local-dir mistral-7b

Poi converti in GGUF:

python convert_hf_to_gguf.py mistral-7b \
  --outfile mistral-f16.gguf \
  --outtype f16

Quindi quantizza:

./build/bin/llama-quantize \
  mistral-f16.gguf \
  mistral-q4_k_m.gguf \
  Q4_K_M

Nell’attuale workflow di llama.cpp, convert_hf_to_gguf.py e llama-quantize sono gli strumenti rilevanti. Tutorial più vecchi possono riferirsi a script di conversione deprecati o a nomi di binari precedenti.

Vantaggi e limiti del formato GGUF

GGUF è ottimizzato per l’inferenza locale pratica. Non è un sostituto universale per ogni formato di modello o stack di serving.

Per l’inferenza incentrata su CPU, Apple Silicon, hardware misto e privacy, GGUF è spesso un’ottima scelta.

Per il deployment su server NVIDIA ad alto throughput, altri formati e motori possono essere più veloci a seconda di modello, batch size, metodo di quantizzazione e framework di serving.

Considerazioni finali

GGUF rende pratica l’inferenza LLM locale impacchettando tutto ciò di cui un runtime ha bisogno (pesi, tokenizer, metadati, info di quantizzazione) in un unico file portatile. La sua vera forza è l’ecosistema attorno: llama.cpp, Ollama, LM Studio e Hugging Face lo hanno reso il formato predefinito per il deploy dell’IA locale.

Per la maggior parte degli utenti, il percorso è semplice: installa Ollama, scarica un modello ed eseguilo. Q4_K_M è un default solido; passa a Q5_K_M o Q6_K quando ti serve un miglior output di ragionamento o coding e hai memoria a sufficienza.

Se vuoi approfondire il deploy degli LLM, l’ottimizzazione dei modelli e i workflow di inferenza locale, esplora il percorso di carriera Associate AI Engineer for Data Scientists o Associate AI Engineer for Developers.