Come importare un modello GGUF in Ollama

Due metodi per importare un modello GGUF in Ollama

Esistono due modi per importare un modello GGUF in Ollama; il metodo corretto dipende dalla posizione attuale del file. Se il modello si trova in un repository Hugging Face, un comando ollama run lo scarica ed esegue senza bisogno di un Modelfile. Se il file .gguf si trova già sul disco del server, è necessario scrivere un Modelfile di due righe ed eseguire ollama create.

Entrambi i percorsi portano allo stesso risultato: un modello denominato nella libreria locale di Ollama che ollama run e l'API di Ollama possono gestire. Utilizzare il primo metodo quando il file è stato pubblicato da terzi. Utilizzare il secondo quando il modello è stato quantizzato autonomamente, quando il file è arrivato tramite scp o rsync, oppure quando la macchina non può raggiungere Hugging Face.

Un file GGUF è un binario unico che contiene pesi, tokenizer e metadati del modello. È il formato letto da llama.cpp; poiché Ollama è basato su llama.cpp, quasi tutti i modelli aperti dispongono di una conversione GGUF creata dalla community. Ollama non carica direttamente una cartella di pesi .safetensors, motivo per cui il passaggio di conversione è necessario.

Tutto ciò che segue presuppone che Ollama sia già installato e che il relativo servizio sia in esecuzione. In caso contrario, iniziare con l'installazione di Ollama su una VPS e tornare qui. Eseguire prima ollama list. Se il comando restituisce una tabella, anche vuota, invece di un errore di connessione, il server è attivo e il resto di questa 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 utilizza il percorso del repository con il prefisso hf.co/:

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

Sia hf.co che huggingface.co funzionano come nome di dominio. Un esempio reale tratto dalla documentazione di Hugging Face:

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

Il primo avvio scarica il file, quindi il prompt della chat non appare finché il download non è completato. Successivamente, il modello è presente nella libreria locale e si avvia rapidamente. Apri una seconda shell ed esegui ollama list per vedere il nome con cui è stato salvato. Tale nome corrisponde all'intera stringa hf.co/... con il relativo tag, che risulta lunga da digitare ogni volta. Assegna un alias breve:

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

Questo percorso funziona solo sui repository che contengono effettivamente file GGUF. Un repository che pubblica pesi .safetensors e nient'altro non fornisce a Ollama nulla da recuperare; in tal caso è necessario il passaggio di conversione descritto più avanti.

Quale quantizzazione sceglie Ollama?

La documentazione di Ollama su Hugging Face, consultata il 25 agosto 2026, è esplicita riguardo al valore predefinito: "Per impostazione predefinita, viene utilizzato lo schema di quantizzazione Q4_K_M, quando presente all'interno del repository del modello. In caso contrario, scegliamo automaticamente un tipo di quantizzazione ragionevole presente nel repository." Un repository che pubblica dieci quantizzazioni fornisce quindi Q4_K_M, mentre un repository privo di Q4_K_M ne propone una scelta da Ollama per tuo conto. Rileggi quella pagina prima di farvi affidamento, poiché le impostazioni predefinite cambiano.

Richiedi una quantizzazione specifica aggiungendola 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 è sensibile alle maiuscole, quindi :iq3_m e :IQ3_M significano la stessa cosa. Puoi anche passare il nome esatto del file come tag, che rappresenta la forma sicura quando i nomi brevi in un repository sono ambigui. Il tag deve corrispondere a un file esistente in quel repository, quindi apri la scheda Files and versions e leggi i nomi dei file reali prima di digitarne uno. La scelta della quantizzazione dipende da considerazioni su memoria e qualità, e la differenza tra Q4, Q8 e FP16 copre adeguatamente tale compromesso.

Percorso due: importare un file .gguf dal proprio disco

Quando il file si trova già sul server, è necessario un Modelfile. Può essere composto da una sola riga. Crea una directory, inserisci il Modelfile al suo interno e punta FROM al file:

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

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

Salvalo come Modelfile, quindi compila il modello:

ollama create my-model

ollama create legge per impostazione predefinita un file chiamato Modelfile nella directory corrente. Usa -f quando il file ha un nome diverso o si trova altrove, come in ollama create my-model -f /home/you/models/my-model/Modelfile. Esegui ollama create --help per visualizzare il flag e il suo valore predefinito durante la compilazione. Il percorso in FROM può essere assoluto o relativo al Modelfile, quindi FROM ./my-model-Q4_K_M.gguf funziona quando entrambi si trovano nella stessa directory. Un percorso assoluto elimina ogni incertezza.

Verifica il risultato prima di utilizzarlo:

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 stampa l'architettura, il numero di parametri, la lunghezza del contesto e la quantizzazione che Ollama ha letto dai metadati del file. Leggi questi valori invece di fidarti del nome del file, poiché il nome è una stringa digitata manualmente. Se il modello risponde al tuo prompt di test in linguaggio naturale e poi si ferma, l'importazione è riuscita. In caso contrario, consulta la sezione sui template qui sotto, poiché è quasi sempre quella la causa.

Un aspetto importante riguardo allo spazio su disco: ollama create copia il file GGUF nell'archivio modelli di Ollama invece di fare riferimento al file nella sua posizione originale. I pesi occupano il disco due volte finché non rimuovi l'originale. Elimina il file sorgente una volta che ollama run my-model funziona, oppure conservalo in un luogo dove non paghi per il doppio spazio. dove Ollama conserva i suoi modelli su disco descrive il layout e come spostarlo.

Quando --quantize si applica e quando no

ollama create dispone di un flag --quantize, utile in un solo caso: un modello sorgente in FP16 o FP32, ovvero pesi a piena precisione. La documentazione di importazione di Ollama elenca q8_0 oltre alle varianti k-means q4_K_S e q4_K_M come target.

ollama create --quantize q4_K_M my-model

Non utilizzare questo flag su un file già quantizzato. Un .gguf il cui nome contiene Q4_K_M o Q5_K_S ha già subito questo processo. La quantizzazione è una conversione unidirezionale verso una precisione inferiore, quindi non è possibile tornare da Q4 a Q8. Se la tua sorgente è un repository Hugging Face di file .safetensors, convertilo prima con convert_hf_to_gguf.py dal repository llama.cpp, che è lo strumento indicato dalla documentazione di Ollama, quindi importa il file GGUF generato dallo script. Come Ollama e llama.cpp sono correlati spiega perché lo script di conversione appartiene 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 file 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 ed esegue direttamente, mentre ollama run hf.co/{username}/{repository}:{quantization} seleziona una quantizzazione specifica. Un Modelfile è necessario solo per un .gguf già presente sul disco locale; in tal caso può consistere nella singola riga FROM /path/to/file.gguf seguita da ollama create my-model.

Quale quantizzazione scarica Ollama se non ne specifico una?

La documentazione di Hugging Face, consultata il 25 agosto 2026, afferma che viene utilizzato Q4_K_M quando tale quantizzazione è presente nel repository; in caso contrario, Ollama seleziona una tipologia di quantizzazione ragionevole tra quelle disponibili. Aggiungi un tag come :Q8_0 per controllarla. Verifica cosa hai effettivamente ricevuto con ollama show <model>, che stampa la quantizzazione dai metadati del file anziché dal suo nome.

Perché il mio modello importato si ripete o non smette mai di generare?

Il template di chat non corrisponde al modello. Ollama seleziona automaticamente un template dai metadati tokenizer.chat_template all'interno del GGUF; quando tali metadati mancano o non sono riconosciuti, viene applicato un wrapper generico, impedendo al modello di rilevare il marcatore di fine turno su cui è stato addestrato. Stampa quello corrente con ollama show --template <model>, quindi aggiungi un blocco TEMPLATE e una riga PARAMETER stop al Modelfile ed esegui nuovamente ollama create. Scrivilo come un template Go. Il template Jinja del repository originale non funzionerà.

Devo usare --quantize su un GGUF che ho scaricato?

No. --quantize converte una sorgente FP16 o FP32 durante ollama create, e un file il cui nome contiene già una quantizzazione, come Q4_K_M, è già stato convertito. La precisione non può essere recuperata quantizzando nuovamente e non esiste un percorso di ripristino verso l'alto. Usa questo flag solo se hai convertito tu stesso dei file safetensors in un GGUF a piena precisione e desideri ora una versione più piccola.

Come posso effettuare 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 da ~/.ollama/id_ed25519.pub se esegui il server come tuo utente, quindi aggiungila nella pagina delle impostazioni delle chiavi SSH del tuo account. Dopodiché, ollama run hf.co/{username}/{repository} funzionerà sui tuoi repository privati e su quelli appartenenti a un'organizzazione di cui fai parte.