Introduzione

Negli ultimi mesi l’esecuzione di modelli di intelligenza artificiale su laptop è diventata più semplice grazie a llama.cpp, il motore di inferenza che alimenta strumenti locali come Ollama, LM Studio e Jan. Ora Hugging Face ha introdotto il supporto per i modelli GGUF all’interno della libreria Transformers, consentendo di caricare checkpoint quantizzati con le consuete chiamate from_pretrained e generare testo direttamente sulla propria macchina.

Che cos’è il formato GGUF?

GGUF, sviluppato dal team di llama.cpp, è un formato di file unico che racchiude i pesi del modello, i metadati, le informazioni del tokenizer e, facoltativamente, un template per la chat. Il formato supporta diversi livelli di quantizzazione, consentendo di bilanciare precisione e consumo di memoria. Alcune delle varianti più comuni sono:

Q4KM: pesi a 4 bit con tensori sensibili a precisione più alta.
Q5KM e Q6_K: offrono un compromesso intermedio tra dimensione del file e accuratezza.

Le versioni quantizzate sono particolarmente utili per far girare modelli di grandi dimensioni su hardware con memoria limitata, ad esempio un laptop con 16 GB di RAM.

Pubblicazioni e risorse disponibili

Numerosi editori mettono a disposizione checkpoint GGUF già quantizzati sul Hub di Hugging Face. Tra i più noti troviamo:

Unsloth
LM Studio Community
Bartowski

Questi repository offrono una gamma di quantizzazioni, consentendo all’utente di scegliere la versione più adatta alla propria macchina. I modelli GGUF hanno già superato la soglia dei milioni di download a livello globale.

Come caricare un modello GGUF con Transformers

Il caricamento è estremamente semplice: basta fornire l’identificatore del repository sul Hub e il nome del file GGUF al metodo from_pretrained. Esempio:

model = AutoModelForCausalLM.from_pretrained(
"unsloth/Qwen3.5-4B-GGUF",
filename="Qwen3.5-4B-Q4KM.gguf"
)

Non è necessaria alcuna configurazione aggiuntiva. Se i pesi rimangono compressi su Metal, Transformers carica automaticamente i kernel ggml/Metal compatibili e utilizza ggml-attn come implementazione dell’attenzione. Qualora il kernel specifico non fosse disponibile, il caricatore ricade su sdpa con un avviso, o può essere forzato esplicitamente con attn_implementation="sdpa".

Integrazione con `transformers serve`

Il modello GGUF può essere esposto tramite transformers serve, che crea un’API compatibile con OpenAI. La sintassi per specificare il modello è:

--model unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4KM.gguf

Le opzioni --reasoning off o --reasoning on controllano l’attivazione del template di chat “thinking” (se presente). Il valore predefinito auto segue il comportamento di default del template.

Client compatibili

Qualsiasi client che supporti l’API OpenAI può interagire con il modello locale. Alcuni esempi:

Jan
Pi
Applicazioni personalizzate tramite le librerie Python OpenAI

Il flusso di lavoro è: il client invia la richiesta di generazione, Transformers esegue il modello sul Mac (o su altra GPU supportata) e restituisce la risposta in tempo reale.

Benchmark di prestazioni

Il riferimento di velocità è rappresentato da llama.cpp. Sono stati confrontati tre checkpoint GGUF:

Modello denso piccolo (Qwen3.5‑4B‑Q4KM)
Modello denso più grande
Modello mixture‑of‑experts (MoE)

Le misurazioni sono state effettuate su un MacBook Pro M2 Max con 32 GB di memoria unificata, macOS 13.6, PyTorch 2.12.1 e kernel ggml 0.17.0.

Per llama.cpp si è usato lo strumento llama-bench (-m <file> -p 0 -n 128 -r 3), che riporta tg128, cioè il tasso di generazione di token su 128 token decodificati, escludendo il pre‑fill. Per Transformers la metrica è stata la generazione di 128 token a partire da un prompt di 12 token, includendo il pre‑fill.

I risultati mostrano che Transformers si avvicina molto a llama.cpp su tutti e tre i checkpoint, nonostante le differenze metodologiche (inclusione del pre‑fill). Ciò dimostra l’efficacia dei kernel ggml integrati nella libreria Transformers.

Perché scegliere llama.cpp o Transformers?

llama.cpp rimane la scelta consigliata quando la priorità è l’efficienza massima di inferenza locale: il runtime dedicato, la gestione della memoria e il supporto hardware esteso sono ottimizzati per questo scopo.

Transformers, invece, offre una base solida per la definizione dei modelli, l’interoperabilità con PyTorch e una vasta ecosfera di tool. L’integrazione di GGUF permette di combinare la comodità di Transformers con le prestazioni di llama.cpp.

Opportunità future

L’obiettivo a medio termine è portare le performance di ggml a modelli che non sono ancora supportati da llama.cpp. Grazie ai kernel ggml disponibili su PyTorch, possiamo accelerare architetture emergenti, modelli di ricerca e varianti personalizzate senza dover implementare l’intero modello in llama.cpp.

Questa strategia si estende anche a modalità diverse dal solo testo: visione artificiale, audio e modelli multimodali potrebbero riutilizzare kernel di attenzione, normalizzazione e moltiplicazione matriciale compatibili, riducendo il tempo di sviluppo di nuove soluzioni.

Implementazione pratica in Python

Abbiamo voluto dim