Importare un modello GGUF da Hugging Face in Ollama

#Perché importare un GGUF da Hugging Face

Ollama mantiene una libreria di modelli pratici (ollama.com/library), ma è volutamente limitata: i manutentori vi pubblicano i modelli più richiesti, con quantizzazioni scelte per ciascuno. Quando cerchi un fine-tune specializzato, una versione appena uscita, un modello in francese o una quantizzazione precisa, devi andare a cercarlo su Hugging Face — la più grande piattaforma di condivisione di modelli open-weight.

Il formato GGUF (successore di GGML) è quello che Ollama comprende nativamente: un file unico che contiene i pesi quantizzati, il tokenizer e i metadati del modello. Collaboratori come TheBloke, bartowski o unsloth pubblicano migliaia di GGUF pronti all'uso, spesso in una decina di quantizzazioni per modello. Sapere come importarli sblocca tutto questo ecosistema all'interno della tua installazione Ollama.

Modelli recenti

Un modello pubblicato ieri su Hugging Face è utilizzabile ancora prima di comparire nella libreria ufficiale di Ollama.

Modelli con fine-tuning di nicchia

Modelli specializzati (codice, medicina, gioco di ruolo, francese) che nessuno si è preso la briga di distribuire ufficialmente in un pacchetto.

Quantizzazione precisa

Scegliere esattamente il livello (Q4_K_M, Q5_K_M, Q8_0…) che rientra nella tua VRAM, anziché limitarsi alla sola variante predefinita.

Modelli privati

I tuoi modelli sottoposti a fine-tuning o i file GGUF scaricati, importati localmente tramite un Modelfile.

#Prerequisiti

Ollama installato

Versione recente (0.5+) per il supporto nativo di hf.co. Il daemon è in ascolto per impostazione predefinita su http://localhost:11434. Verifica con « ollama --version ».

Una connessione internet

Per il metodo diretto che scarica da Hugging Face. Successivamente il modello funziona al 100% localmente.

Abbastanza VRAM o RAM

Come riferimento, in Q4: un 7B rientra in circa 5 GB, un 14B in circa 9 GB, un 32B in circa 19 GB, un 70B in circa 40 GB. Senza GPU, conta la RAM, ma l'esecuzione è più lenta.

Il nome di un repository GGUF

Ad esempio bartowski/Qwen3.5-9B-Instruct-GGUF. Individualo nell'URL della pagina Hugging Face del modello.

Per trovare un repository GGUF, la ricerca di Hugging Face permette di filtrare per formato. Cerca il nome del modello e aggiungi «GGUF», oppure filtra per la libreria «GGUF» nella barra laterale. Apri la scheda «Files and versions»: vedrai l'elenco dei file .gguf, uno per quantizzazione, con le rispettive dimensioni in GB — un'informazione preziosa per i passaggi successivi.

#Metodo diretto: ollama run hf.co/...

È di gran lunga il modo più semplice per importare un modello GGUF da Hugging Face in Ollama. Dalla versione 0.5, Ollama può scaricare un GGUF direttamente da un repository Hugging Face con un solo comando, senza scaricare il file a mano né scrivere un Modelfile. La sintassi riprende il percorso del repository preceduto da hf.co/.

# Format : ollama run hf.co/{utilisateur}/{depot}
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF

Se non ne specifichi una, Ollama sceglie una quantizzazione predefinita (generalmente Q4_K_M, se esiste nel repository). Per selezionare una quantizzazione precisa, aggiungila dopo i due punti, esattamente come un normale tag di modello. Il nome del tag corrisponde al suffisso del file .gguf, senza distinzione tra maiuscole e minuscole.

# Choisir explicitement Q5_K_M
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q5_K_M

# Ou une version plus légère pour une petite carte
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M

Ollama scarica il file, lo salva nel suo archivio locale e avvia la conversazione. Il modello appare successivamente in « ollama list » con il suo nome completo hf.co/... e si riavvia istantaneamente. Puoi assegnargli un alias più breve con « ollama cp » se il nome ti sembra troppo lungo da digitare.

# Copier vers un alias court
ollama cp hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M qwen-fr

# Désormais utilisable simplement
ollama run qwen-fr

#Scegliere la giusta quantizzazione in base alla VRAM

Lo stesso modello è pubblicato in diverse quantizzazioni: è il compromesso centrale tra qualità e memoria. Più la quantizzazione è aggressiva (meno bit per peso), più il file è piccolo e più facilmente trova spazio su una scheda modesta, a costo di una leggera perdita di precisione. La buona prassi è scegliere la quantizzazione più alta che trovi comodamente spazio nella tua VRAM.

Q4_K_M — raccomandato

Il miglior compromesso per la stragrande maggioranza degli usi. Perdita di qualità quasi impercettibile, ingombro in memoria ridotto. Da scegliere per default se hai dubbi.

Q5_K_M — un livello sopra

Un po’ più pesante, un po’ più preciso. Interessante se la tua VRAM ha margine e vuoi il massimo della qualità senza passare agli 8 bit.

Q8_0 — quasi senza perdita

Molto vicino al modello non quantizzato, ma circa due volte più pesante del Q4. Riservato ai casi in cui anche il minimo peggioramento della qualità conta e la VRAM non manca.

FP16 — precisione completa

Il modello non quantizzato, il più pesante. Raramente necessario per l'inferenza locale: Q8_0 basta quasi sempre e dimezza la memoria.

Per stimare se un modello quantizzato entra in memoria, fai riferimento alla dimensione del file .gguf indicata su Hugging Face, aggiungendo un margine di circa 1–2 GB per il contesto e il sistema. Ecco i valori di riferimento della VRAM in Q4_K_M per dimensione del modello e le GPU tipiche che permettono di eseguirlo.

3B ≈ 2 GB

Funziona ovunque, anche su una scheda di fascia bassa o sulla CPU. Ideale su una RTX 3060 da 12 GB, con ampio margine per il contesto.

7B ≈ 5 GB

Comodo su RTX 3060 12 GB, RTX 4070 12 GB. Il formato più versatile per un uso quotidiano.

14B ≈ 9 GB

RTX 4070 12 GB (al limite), RTX 4080 16 GB con ampio margine. Un buon livello di qualità per il ragionamento e la scrittura di codice.

32B ≈ 19 GB

RTX 4090 da 24 GB, oppure Mac M4 Pro con memoria unificata. La fascia alta accessibile su una workstation.

70B ≈ 40 GB

Richiede almeno 48 GB: un Mac Studio con molta memoria unificata o una configurazione multi-GPU. Passa a Q4 o a una quantizzazione ancora più aggressiva.

#Metodo Modelfile: FROM fichier.gguf

Il metodo diretto presuppone che il GGUF sia su Hugging Face e accessibile online. Ma se hai già scaricato manualmente un file .gguf, hai creato il tuo con llama.cpp o vuoi personalizzare il modello (system prompt, parametri), devi usare un Modelfile. È un piccolo file di testo, simile a un Dockerfile, che descrive come costruire un modello Ollama a partire da un GGUF locale.

L'istruzione centrale è FROM, che punta al percorso del file .gguf. Crea un file chiamato « Modelfile » (senza estensione) accanto al tuo GGUF, con almeno questa riga.

FROM ./mon-modele.Q4_K_M.gguf

Poi costruisci il modello con «ollama create», assegnandogli il nome che preferisci. Ollama legge il GGUF, lo registra nel suo archivio e lo rende disponibile come qualsiasi altro modello.

# Construire le modèle depuis le Modelfile du dossier courant
ollama create mon-modele -f ./Modelfile

# Le lancer
ollama run mon-modele

Un Modelfile completo può andare molto oltre: fissare un system prompt, regolare i parametri di sampling e soprattutto definire il TEMPLATE — il formato di chat atteso dal modello. È lì che si risolve la maggior parte dei problemi di qualità, come si vede nella sezione successiva.

FROM ./mon-modele.Q4_K_M.gguf

# System prompt par défaut
SYSTEM """Tu es un assistant francophone concis et précis."""

# Paramètres d'inférence
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
PARAMETER stop "<|im_end|>"

# Template de chat (exemple format ChatML)
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""

#Correggere un template della chat non funzionante

È la trappola numero uno dell'importazione di GGUF. Un modello importato può rispondere in modo incoerente: frasi che non finiscono mai, tag strani nell'output (<|im_end|>, [INST], <end_of_turn>), risposte che ignorano la domanda o entrano in un ciclo ripetitivo. Nove volte su dieci, non è il modello a essere scadente — è il template della chat che non corrisponde a quello usato durante il suo addestramento.

Ogni famiglia di modelli richiede un formato di conversazione preciso: ChatML (<|im_start|>) per Qwen e molti modelli fine-tuned, [INST]...[/INST] per Mistral e Llama 2, <start_of_turn> per Gemma, un formato specifico per Llama 3. Se il GGUF contiene il template sbagliato nei suoi metadati, o se Ollama ne deduce uno errato, la qualità delle risposte peggiora. Il sintomo più comune: i tag di fine turno compaiono come testo nella risposta invece di interrompere la generazione.

Sintomo: tag visibili

Il modello mostra <|im_end|> o <|eot_id|> nella sua risposta. Manca un PARAMETER stop corrispondente, oppure il template non emette il token di fine corretto.

Sintomo: generazione infinita

Il modello non si ferma mai e continua autonomamente con i turni di conversazione. Il token di arresto previsto non è dichiarato.

Sintomo: risposte incoerenti

Il modello ignora il system prompt o risponde fuori tema. Il formato dei ruoli (system/user/assistant) non corrisponde a quello usato nell'addestramento.

La correzione consiste nel fornire il TEMPLATE corretto e le corrette direttive PARAMETER stop in un Modelfile. Il riferimento autorevole è la « model card » su Hugging Face del modello originale: cerca la sezione « prompt format » o « chat template », che indica il formato esatto. Per un modello ChatML (Qwen e derivati), il template e le sequenze di arresto si presentano così.

FROM ./mon-modele.Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""

PARAMETER stop "<|im_start|>"
PARAMETER stop "<|im_end|>"

Ricostruisci poi con « ollama create » e testa. Un trucco efficace per recuperare il template corretto senza riscriverlo: parti da un modello ufficiale della stessa famiglia già presente in Ollama e ispeziona il suo Modelfile generato, poi riprendine il blocco TEMPLATE.

# Voir le Modelfile complet d'un modèle officiel de la même famille
ollama show --modelfile qwen3.5:9b

# Copiez-en le bloc TEMPLATE et les PARAMETER stop
# dans votre propre Modelfile, puis reconstruisez
ollama create mon-modele -f ./Modelfile

#Risoluzione dei problemi

« Error: pull model manifest »

Il percorso hf.co è mal scritto, il repository è privato/gated, o la tua versione di Ollama è troppo vecchia. Verifica l'URL esatto del repository e aggiorna Ollama.

Il tag di quantizzazione non esiste

Ollama risponde che il tag non è stato trovato: apri «Files and versions» su Hugging Face e copia il suffisso esatto del file .gguf (es. Q4_K_M, IQ4_XS). Non viene fatta distinzione tra maiuscole e minuscole, ma il nome deve corrispondere.

Modello molto lento / risposte a scatti

Il modello viene eseguito in parte nella RAM di sistema e sulla CPU per mancanza di VRAM. Controlla con «ollama ps» se gira sulla GPU o sulla CPU e passa a una quantizzazione con meno bit oppure a un modello più piccolo.

Il repository contiene soltanto safetensors

Nessun file .gguf disponibile: cerca una versione « GGUF » convertita dalla comunità oppure converti tu stesso il modello con gli script di llama.cpp.

Output contaminati da tag

Template di chat errato: consulta la sezione precedente e fornisci il TEMPLATE corretto e i PARAMETER stop tramite un Modelfile.

#Per approfondire

Importare un GGUF richiede due competenze di base dell'ecosistema Ollama. Queste guide del sito approfondiscono quanto trattato in questa guida:

Scegliere la quantizzazione (Q4, Q5, Q8, FP16)

Capire in dettaglio il compromesso qualità/memoria per scegliere la giusta variante GGUF in base alla tua scheda.

Personalizzare un modello con Ollama Modelfile

Andare oltre con il Modelfile: prompt di sistema, parametri, template e varianti multiple dello stesso modello.

Installare Ollama: Windows, macOS e Linux

La guida aggiornata all’installazione di base, se parti da zero prima di importare i tuoi primi GGUF.