Come importare un modello GGUF in Ollama

Due modi per importare un modello GGUF in Ollama

Esistono due modi per importare un modello GGUF in Ollama. La scelta dipende dalla posizione attuale del file. Se il modello si trova in un repository Hugging Face, un comando ollama run lo scarica e lo avvia, senza usare un Modelfile. Se il file .gguf è già presente sul disco del server, è sufficiente scrivere un Modelfile di due righe ed eseguire ollama create.

Entrambi i metodi producono lo stesso risultato: un modello con nome nella libreria Ollama locale, che ollama run e l'API Ollama possono fornire ai client. Usa il primo metodo quando il file è stato pubblicato da terzi. Usa il secondo se hai quantizzato tu il modello, se il file è arrivato tramite scp o rsync, oppure se il server non può raggiungere Hugging Face.

Un file GGUF è un singolo file binario che contiene pesi, tokenizer e metadati del modello. È il formato letto da llama.cpp e Ollama si basa su llama.cpp. Per questo quasi tutti i modelli open source hanno una conversione GGUF realizzata dalla community. Ollama può anche importare una directory di pesi .safetensors, ma questo è un percorso separato. La sezione --quantize seguente spiega dove si colloca.

Quanto segue presuppone che Ollama sia già installato e che il relativo servizio sia in esecuzione. In caso contrario, inizia da installare Ollama su un VPS e poi torna qui. Esegui prima ollama list. Se restituisce una tabella, anche vuota, invece di un errore di connessione, il server è attivo e il resto della guida funzionerà.

Percorso uno: eseguire un GGUF da Hugging Face senza Modelfile

Ollama può scaricare un GGUF direttamente da un repository Hugging Face. Il comando usa il percorso del repository con il prefisso hf.co/:

ollama run hf.co/{username}/{repository}

Sia hf.co sia huggingface.co funzionano come nome di dominio. Ecco un esempio reale tratto dalla documentazione di Hugging Face:

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

La prima esecuzione scarica il file, quindi il prompt della chat non viene visualizzato finché il download non è completato. In seguito il modello si trova nella libreria locale e si avvia rapidamente. Apri una seconda shell ed esegui ollama list per vedere il nome con cui è stato memorizzato. Il nome corrisponde all'intera stringa hf.co/... con il relativo tag, quindi è lungo da digitare ogni volta. Assegnagli un alias breve:

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

Questo percorso funziona solo con i repository che contengono effettivamente file GGUF. Un repository che pubblica soltanto pesi .safetensors e nessun altro formato non offre file da scaricare tramite questo metodo; devi quindi usare una delle importazioni locali descritte più avanti.

Quale quantizzazione sceglie Ollama?

La documentazione di Ollama su Hugging Face, consultata il 10 ottobre 2026, è chiara sul comportamento predefinito: «Per impostazione predefinita viene usato lo schema di quantizzazione Q4_K_M, se presente nel repository del modello. In caso contrario, viene scelto il tipo di quantizzazione ragionevole disponibile nel repository.» Un repository che pubblica dieci quantizzazioni ti fornisce quindi Q4_K_M; se Q4_K_M non è presente, Ollama sceglie una quantizzazione al posto tuo. Rileggi quella pagina prima di basarti su questo comportamento, perché le impostazioni predefinite possono cambiare.

Per richiedere una quantizzazione specifica, aggiungila come tag:

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

Il nome della quantizzazione non distingue tra maiuscole e minuscole, quindi :iq3_m e :IQ3_M indicano la stessa cosa. Puoi anche specificare il nome file esatto come tag. Questa è la forma più sicura quando i nomi brevi presenti in un repository sono ambigui. Il tag deve indicare un file esistente nel repository. Apri quindi la scheda Files and versions e leggi i nomi file reali prima di inserirne uno. La scelta della quantizzazione dipende dalla memoria disponibile e dalla qualità desiderata. La differenza tra Q4, Q8 e FP16 descrive in dettaglio questo compromesso.

Percorso 2: importare un file .gguf dal proprio disco

Quando il file si trova già sul server, serve un Modelfile. Può contenere una sola riga. Crea una directory, inserisci al suo interno il Modelfile e passa a FROM il percorso del file:

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

Salva il file come Modelfile, quindi crea il modello:

ollama create my-model

Per impostazione predefinita, ollama create legge un file denominato Modelfile nella directory corrente. Usa -f quando il file ha un altro nome o si trova in un'altra posizione, come in ollama create my-model -f /home/you/models/my-model/Modelfile. Esegui ollama create --help per visualizzare il flag e il relativo valore predefinito nella tua build. Il percorso in FROM può essere assoluto oppure relativo al Modelfile; per questo FROM ./my-model-Q4_K_M.gguf funziona quando entrambi si trovano nella stessa directory. Un percorso assoluto elimina ogni ambiguità.

Verifica il risultato prima di considerarlo attendibile:

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ollama list dovrebbe ora includere my-model. ollama show my-model mostra l'architettura, il numero di parametri, la lunghezza del contesto e la quantizzazione che Ollama ha letto dai metadati del file. Usa questi valori invece di fidarti del nome del file, perché un nome è soltanto una stringa inserita manualmente. Se il modello risponde al prompt di test in linguaggio naturale e poi si arresta, l'importazione è riuscita. In caso contrario, passa alla sezione sui template riportata di seguito, perché questa è quasi sempre la causa.

È importante considerare lo spazio su disco: ollama create copia il GGUF nell'archivio dei modelli di Ollama invece di fare riferimento al file nella posizione originale. Finché non rimuovi l'originale, i pesi occupano spazio due volte. Elimina il file sorgente quando ollama run my-model funziona oppure conservalo in una posizione per cui non paghi due volte lo spazio utilizzato. dove Ollama conserva i modelli su disco descrive la struttura e spiega come spostarla.

Quando si applica --quantize e quando no

ollama create dispone di un flag --quantize, che attualmente si applica a un solo caso: un modello importato da una directory contenente pesi .safetensors. Il testo della guida nella versione corrente del codice sorgente di Ollama, verificata il 10 ottobre 2026, è "Quantize safetensors model to this level (e.g. nvfp4)", e i valori accettati sono int4, int8, nvfp4, mxfp4 e mxfp8. I nomi delle quantizzazioni GGUF, come q8_0 o q4_K_M, vengono rifiutati come tipi non supportati. La documentazione di Ollama è chiara per quanto riguarda GGUF: "Ollama does not quantize GGUF models during import."

ollama create --quantize int8 my-model

Questo comando presuppone un Modelfile la cui riga FROM punta alla directory che contiene i file .safetensors.

Non passare quel flag quando FROM identifica un .gguf, indipendentemente dalla precisione. Un GGUF FP16 o FP32 viene rifiutato nello stesso modo di un Q4_K_M, con un errore che inizia con "create-time quantization is only supported for safetensors imports". Un .gguf il cui nome contiene Q4_K_M o Q5_K_S è già stato quantizzato e la precisione eliminata non può essere recuperata. llama-quantize di llama.cpp può ricodificare un file di questo tipo come un altro formato, incluso Q8_0, quando passi --allow-requantize, ma il relativo manuale avverte che questa operazione "can severely reduce quality compared to quantizing from 16bit or 32bit"; inoltre, un file Q4 riscritto come Q8 è più grande senza offrire una qualità migliore. Per ridurre le dimensioni di un GGUF a piena precisione, esegui prima llama-quantize sul file. È lo strumento indicato dalla documentazione di Ollama. Importa quindi il file generato. Se la sorgente è un repository Hugging Face di file .safetensors, puoi puntare FROM a quella directory e lasciare che ollama create la importi, usando --quantize se vuoi ridurne le dimensioni. In alternativa, puoi convertirla con convert_hf_to_gguf.py dal repository llama.cpp e importare il GGUF generato dallo script. Come sono collegati Ollama e llama.cpp spiega perché questi strumenti appartengono all'altro progetto.

Perché un file GGUF importato risponde con caratteri illeggibili o non si ferma mai?

Questo è il fallimento che la maggior parte dei tutorial sull'importazione ignora, ed è quello che incontrerai. I sintomi sembrano quelli di un modello danneggiato. I token di controllo appaiono come testo visibile nella risposta, stringhe come <|im_start|>assistant o <|end|>. Il modello risponde, poi scrive una nuova domanda dell'utente e risponde anche a quella. La generazione continua finché non premi Ctrl+C.

Il modello è integro. Il template di chat è errato. Un template di chat è il wrapper che trasforma il tuo messaggio nell'esatta sequenza di token su cui il modello è stato addestrato, con i propri marcatori per indicare dove termina il prompt di sistema e inizia il turno dell'utente. Ollama ne sceglie uno per te: la documentazione afferma che un template "verrà selezionato automaticamente da un elenco di template comunemente usati", basandosi sui metadati tokenizer.chat_template integrati all'interno del file GGUF. Quando tali metadati mancano, o quando non corrispondono a nulla nell'elenco, ottieni un wrapper generico. Il modello vede quindi un prompt strutturato in modo diverso da qualsiasi cosa presente nel suo addestramento, quindi non incontra mai il marcatore di fine turno su cui ha imparato a fermarsi.

Stampa ciò che Ollama ha scelto effettivamente:

ollama show --template my-model
ollama show --modelfile my-model

Un template vuoto o palesemente generico lo conferma. Scrivi il template tu stesso nel Modelfile:

FROM /home/you/models/my-model-Q4_K_M.gguf

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

PARAMETER stop "<|end|>"

Ricostruisci con ollama create my-model e invia nuovamente lo stesso prompt di test. Il parametro stop è la tua rete di sicurezza: dice a Ollama di interrompere la generazione quando appare quella stringa, il che pone fine al sintomo del "non si ferma mai" anche mentre stai ancora perfezionando il wrapper stesso. Se la risposta continua comunque perché non appare mai alcun marcatore da te indicato, un limite num_predict la interromperà a un numero fisso di token, indipendentemente da ciò che il template emette.

Il template deve essere un template Go, non un template Jinja. La documentazione di Hugging Face lo dichiara esplicitamente, ed è importante perché il campo tokenizer.chat_template nel repository originale del modello contiene Jinja. Incollarlo senza modifiche non funziona. La sintassi di Ollama ha tre variabili: {{ .System }} per il prompt di sistema, {{ .Prompt }} per il messaggio dell'utente e {{ .Response }} per la risposta del modello. Trova i veri marcatori di turno del modello nella sua scheda (model card) o nel suo tokenizer_config.json, quindi riscrivili manualmente in quella sintassi Go.

Una scorciatoia permette di risparmiare gran parte di questo lavoro. Molti modelli condividono un formato di prompt comune, quindi se un altro modello nella tua libreria ne usa uno identico, esegui ollama show --template su di esso e copia ciò che viene stampato.

I file template, system e params in un repository Hugging Face

Il percorso Hugging Face offre gli stessi controlli dei file nel repository, anziché le istruzioni in un Modelfile. Se sei il proprietario del repository, o se stai pubblicando una tua quantizzazione, aggiungili lì e ogni ollama run hf.co/... li rileverà.

• Un file chiamato template contiene il template Go. Stessa regola: Go, non Jinja.
• Un file chiamato system contiene il system prompt.
• Un file chiamato params contiene i parametri di campionamento e deve essere in formato JSON.

Un file params minimale:

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

Quando non sei il proprietario del repository, non puoi aggiungere quei file. Scarica il modello una volta, esegui ollama show --modelfile hf.co/... per esportare ciò che hai ricevuto e salva l'output come Modelfile. La sua riga FROM punta al blob che Ollama ha già scaricato, quindi modifica le righe TEMPLATE e PARAMETER ed esegui ollama create per creare una copia locale fissa senza scaricare nuovamente nulla. Questa è la procedura standard per correggere una quantizzazione difettosa creata da altri.

Come importare un repository GGUF privato

Un repository privato richiede la chiave SSH di Ollama sul tuo account Hugging Face. Il metodo documentato per questa procedura utilizza una chiave SSH anziché un token API, pertanto un token già in tuo possesso non consentirà l'accesso.

Visualizza la chiave pubblica. Su un server Linux dove Ollama è stato installato con lo script ufficiale, il servizio viene eseguito come utente ollama, quindi la chiave si trova nella home directory di tale utente:

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

Se avvii ollama serve personalmente come tuo utente, il percorso è invece ~/.ollama/id_ed25519.pub. Copia l'intera riga, apri le impostazioni del tuo account Hugging Face su https://huggingface.co/settings/keys e aggiungila come nuova chiave SSH. Il comando standard funzionerà quindi sui tuoi repository privati:

ollama run hf.co/{username}/{repository}

Se il pull fallisce ancora dopo aver aggiunto la chiave, probabilmente hai visualizzato il file errato. Il server esegue il download e presenta la propria chiave; un server avviato da systemd non legge mai il file ~/.ollama del tuo utente, quindi la chiave presente nella tua home directory non è quella che Hugging Face rileva.

Il modello può essere eseguito sul tuo VPS?

Il parametro determinante è la dimensione del file su disco sommata alla memoria richiesta dalla finestra di contesto. I pesi vengono caricati in memoria occupando uno spazio simile a quello del file, mentre l'allocazione del contesto si aggiunge a questo valore, aumentando in base al numero di token consentiti. Esegui ollama list per leggere la dimensione registrata da Ollama per il modello, confrontala con free -h sulla macchina e lascia un margine per il sistema operativo e per qualsiasi altro processo in esecuzione sul server. Se preferisci consultare un calcolo già effettuato su un modello reale, eseguire Nemotron 3.5 Lightning su un VPS indica il tag esatto da scaricare, la RAM necessaria e se un server basato solo su CPU è in grado di gestire il carico.

Il contesto è l'elemento che viene spesso trascurato. Un modello caricato con la finestra predefinita può fallire una volta aumentato num_ctx, poiché tale allocazione scala in base alla finestra richiesta. Impostare num_ctx e il relativo costo in memoria contiene i dettagli sul dimensionamento. Quando il totale è troppo elevato, la soluzione consiste solitamente nell'utilizzare una quantizzazione inferiore dello stesso modello, un compromesso analizzato in confronto tra Q4 e Q8.

Il fallimento non è un evento ambiguo. Su un VPS basato solo su CPU, l'OOM killer (out of memory killer) del kernel interrompe il processo e journalctl -u ollama -n 50 insieme a dmesg mostrano l'avvenuta terminazione. Su una macchina dotata di GPU, ollama ps stampa una colonna PROCESSOR che indica se il modello caricato risiede nella memoria della GPU, nella memoria di sistema o se è suddiviso tra entrambe. Un modello che ha saturato la memoria della GPU e si è spostato nella memoria di sistema risponde comunque, seppur lentamente. Misurare i token al secondo trasforma il concetto di "lentamente" in un valore numerico confrontabile tra diverse quantizzazioni.

Verifica dell'importazione

Esegui questi quattro comandi dopo ogni importazione, rispettando quest'ordine:

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

ollama list conferma l'esistenza del modello e mostra la dimensione registrata da Ollama. ollama show conferma che Ollama ha letto i metadati necessari dal file GGUF. ollama show --modelfile mostra il template e i parametri che verranno effettivamente utilizzati; questo controllo permette di individuare errori di output prima che si verifichino per gli utenti. Il prompt di test verifica l'intera catena, poiché un modello con un template non valido fallisce anche con la richiesta più breve. Una volta che il prompt restituisce un risultato corretto, il nome assegnato al modello è quello da utilizzare per qualsiasi altro strumento che comunichi con le API di Ollama, incluso un agente di programmazione puntato sul tuo server. Rimuovi un'importazione non riuscita con ollama rm my-model e ripeti la procedura di creazione. Questo comando elimina la copia di Ollama lasciando intatto il file sorgente .gguf.

FAQ

Posso importare un GGUF in Ollama senza scrivere un Modelfile?

Sì, quando il file si trova in un repository Hugging Face. ollama run hf.co/{username}/{repository} lo scarica e lo esegue direttamente, mentre ollama run hf.co/{username}/{repository}:{quantization} seleziona una quantizzazione specifica. Un Modelfile serve solo per un .gguf già presente sul disco locale; in questo caso può contenere la sola riga FROM /path/to/file.gguf, seguita da ollama create my-model.

Quale quantizzazione scarica Ollama quando non ne specifico una?

La documentazione di Hugging Face, consultata il 10 ottobre 2026, indica che viene usato Q4_K_M quando questa quantizzazione è presente nel repository. In caso contrario, Ollama sceglie un tipo di quantizzazione ragionevole tra quelli disponibili nel repository. Aggiungi un tag come :Q8_0 per controllare la scelta. Verifica cosa hai effettivamente ricevuto con ollama show <model>, che legge la quantizzazione dai metadati del file, non dal suo nome.

Perché il modello importato ripete le risposte o non interrompe mai la generazione?

Il chat template non corrisponde al modello. Ollama seleziona automaticamente un template dai metadati tokenizer.chat_template presenti nel GGUF. Se questi metadati mancano o non vengono riconosciuti, Ollama usa un wrapper generico. Di conseguenza, il modello non vede il marker di fine turno con cui è stato addestrato. Stampa il template attuale con ollama show --template <model>, quindi aggiungi un blocco TEMPLATE e una riga PARAMETER stop al Modelfile, poi esegui di nuovo ollama create. Scrivilo come template Go. Il template Jinja del repository originale non funziona.

Devo usare --quantize su un GGUF scaricato?

No. --quantize funziona solo sulle importazioni di safetensors durante ollama create e rifiuta qualsiasi sorgente GGUF, inclusi i file FP16 e FP32, mostrando un errore che indica di quantizzare i modelli GGUF prima dell'importazione. Un file il cui nome include già una quantizzazione, ad esempio Q4_K_M, è già stato convertito. Quantizzarlo di nuovo non può recuperare la precisione persa: llama-quantize --allow-requantize può riscriverlo come Q8_0, ma il risultato è più grande senza essere migliore. Per ottenere un file più piccolo da un GGUF a precisione completa, esegui su quel file llama-quantize di llama.cpp e importa il risultato.

Come posso eseguire il pull di un repository GGUF privato?

Aggiungi la chiave pubblica SSH di Ollama al tuo account Hugging Face. Stampala con sudo cat /usr/share/ollama/.ollama/id_ed25519.pub su un'installazione Linux standard, oppure con ~/.ollama/id_ed25519.pub quando esegui il server con il tuo utente, quindi aggiungila nella pagina delle impostazioni delle chiavi SSH del tuo account. A quel punto, ollama run hf.co/{username}/{repository} funziona sui tuoi repository privati e sui repository di un'organizzazione di cui fai parte.