Se hai scaricato un modello da far girare su un portatile, probabilmente era un file che finisce in .gguf.
Come funziona
La specifica di ggml descrive GGUF come un formato binario per salvare modelli da usare per l’inferenza con GGML e con esecutori basati su GGML, pensato per caricare e salvare in fretta. Ha sostituito i vecchi formati GGML, GGMF e GGJT. Tra i suoi obiettivi dichiarati:
- File singolo. Un modello si condivide e si carica senza file aggiuntivi.
- Compatibile con mmap. Il runtime può mappare i pesi in memoria invece di copiarli.
- Estendibile. Si possono aggiungere nuovi metadati senza rompere i modelli più vecchi.
- Informazioni complete. Tutto ciò che serve per caricare il modello sta nel file.
Un file GGUF ha un’intestazione (un magic number, la versione del formato, il numero di tensori e di metadati), coppie chiave-valore di metadati tipizzati, una tabella con nomi, forme, tipi e offset dei tensori, un padding fino a un confine di allineamento (32 byte di default) e infine i dati dei tensori.
I nomi dei file seguono una convenzione. L’esempio della specifica, Mixtral-8x7B-v0.1-KQ2.gguf, si scompone in nome base, etichetta di dimensione (otto esperti da 7B, vedi mixture of experts), versione e codifica.
La maggior parte dei file GGUF è quantizzata. La tabella di Hugging Face elenca i tipi più comuni:
| Tipo | Bit per peso | Note |
|---|---|---|
| Q8_0 | 8 | Arrotondamento al più vicino (legacy), blocchi da 32 pesi |
| Q6_K | 6,5625 | Super-blocchi k-quant |
| Q5_K | 5,5 | Super-blocchi k-quant |
| Q4_K | 4,5 | Super-blocchi k-quant |
| IQ4_XS | 4,25 | Usa una matrice di importanza |
| Q2_K | 2,625 | Super-blocchi k-quant |
Perché è importante
- Uso in locale e su edge. Hugging Face elenca llama.cpp, LM Studio, GPT4All e Ollama tra gli strumenti che usano GGUF. È la strada abituale per far girare un modello open-weight su una CPU, un Mac o una singola GPU consumer.
- Il tokenizer viaggia con i pesi. Dato che i metadati stanno nel file, un chat template o un’impostazione del tokenizer sbagliati o mancanti in una conversione possono cambiare la qualità dell’output.
- La qualità dipende dal tipo di quantizzazione. Un file Q2 e un file Q8 dello stesso modello, in pratica, non sono lo stesso modello. Confronta cose omogenee.
- Diverso dai formati di serving su GPU. Motori server come vLLM includono GGUF tra i formati supportati, ma il serving su GPU in produzione usa più spesso formati come AWQ o FP8.
Su BroadNet Inference
L’API di BroadNet serve i modelli via HTTP; non distribuisce file GGUF, e non carichi mai pesi tu stesso. Il catalogo di BroadNet riporta che in laboratorio ha fatto girare Qwen3.8 27B come GGUF Q4_K_M con un proiettore di visione e un drafter multi-token prediction su llama.cpp, insieme a una build AWQ INT4 su vLLM per AMD ROCm. Non dice quale formato serva l’API pubblica. Se stai confrontando un setup GGUF in locale con un’API, la guida ai costi del self-hosting rispetto all’API e modelli open-weight o chiusi spiegano i compromessi.