BroadRouter
Inizia

GGUF (formato dei modelli llama.cpp)

Aggiornato

GGUF è un formato di file binario per salvare modelli linguistici da usare per l’inferenza con runtime basati su GGML, come llama.cpp. Un solo file GGUF contiene i pesi, spesso quantizzati, e i metadati necessari a caricare il modello, compresi tokenizer e dettagli dell’architettura, e può essere mappato in memoria per un caricamento rapido.

Detto anche: file GGUF, formato GGUF, modello GGUF, formato llama.cpp, GGUF file, GGUF format, llama.cpp format

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.

Domande frequenti

Cosa significa un nome come Q4_K?

È il tipo di quantizzazione. La tabella di Hugging Face descrive Q4_K come quantizzazione a 4 bit in super-blocchi di 8 blocchi da 32 pesi, circa 4,5 bit per peso. Meno bit usano meno memoria e di solito costano più qualità.

Posso chiamare un modello GGUF con il formato dell’API OpenAI?

Non il file in sé. Lo carichi in un runtime come il server di llama.cpp, Ollama o LM Studio, ed è quel runtime a servirlo. Controlla nella documentazione del runtime quale API espone.

GGUF è la stessa cosa di safetensors?

No. Hugging Face descrive safetensors come un formato solo per i tensori, mentre GGUF codifica in un unico file sia i tensori sia un insieme standardizzato di metadati.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity