Como importar um modelo GGUF no Ollama

Duas formas de importar um modelo GGUF para o Ollama

Existem duas formas de importar um modelo GGUF para o Ollama. A opção correta depende de onde o ficheiro está neste momento. Se o modelo estiver num repositório do Hugging Face, um comando ollama run descarrega-o e executa-o, sem envolver um Modelfile. Se o ficheiro .gguf já estiver no disco do servidor, escreva um Modelfile com duas linhas e execute ollama create.

Ambos os métodos terminam no mesmo resultado: um modelo com nome na biblioteca local do Ollama que ollama run e que a API do Ollama pode disponibilizar. Use o primeiro método quando outra pessoa publicou o ficheiro. Use o segundo quando quantizou o modelo, quando o ficheiro chegou através de scp ou rsync, ou quando a máquina não consegue aceder ao Hugging Face.

Um ficheiro GGUF é um único binário que contém os pesos, o tokenizador e os metadados do modelo. É o formato que o llama.cpp lê, e o Ollama baseia-se no llama.cpp. Por isso, quase todos os modelos abertos têm uma conversão GGUF criada pela comunidade. O Ollama também pode importar um diretório de pesos .safetensors, mas esse é um método separado. A secção sobre --quantize abaixo explica onde ele se enquadra.

Tudo o que se segue pressupõe que o Ollama já está instalado e que o respetivo serviço está em execução. Se não estiver, comece por instalar o Ollama numa VPS e depois volte aqui. Execute ollama list primeiro. Se devolver uma tabela, mesmo vazia, em vez de um erro de ligação, o servidor está em execução e o resto deste guia funcionará.

Rota 1: executar um GGUF do Hugging Face sem Modelfile

Ollama pode obter um GGUF diretamente de um repositório do Hugging Face. O comando é o caminho do repositório com o prefixo hf.co/:

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

Tanto hf.co como huggingface.co funcionam como nome de domínio. Um exemplo real da documentação do Hugging Face:

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

A primeira execução descarrega o ficheiro, por isso o prompt de chat só aparece depois de o download terminar. Depois disso, o modelo fica na sua biblioteca local e inicia rapidamente. Abra uma segunda shell e execute ollama list para ver o nome com que foi armazenado. Esse nome é toda a string hf.co/... com a respetiva tag, e é longa para escrever sempre. Atribua-lhe um alias curto:

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

Esta rota só funciona em repositórios que contêm efetivamente ficheiros GGUF. Um repositório que publique apenas pesos .safetensors não fornece nada para esta rota descarregar, pelo que precisa de uma das importações locais descritas mais abaixo.

Que quantização o Ollama escolhe?

A documentação do Ollama no Hugging Face, consultada em 10 October 2026, é explícita sobre o valor predefinido: "By default, the Q4_K_M quantization scheme is used, when it's present inside the model repo. If not, we default to picking one reasonable quant type present inside the repo." Assim, um repositório que publique dez quantizações fornece Q4_K_M, enquanto um repositório sem Q4_K_M fornece uma opção escolhida pelo Ollama. Consulte novamente essa página antes de depender deste comportamento, porque os valores predefinidos podem mudar.

Peça uma quantização específica adicionando-a como 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

O nome da quantização não diferencia maiúsculas de minúsculas, por isso :iq3_m e :IQ3_M significam a mesma coisa. Também pode passar o nome exato do ficheiro como tag. Esta é a forma segura quando os nomes curtos de um repositório são ambíguos. A tag tem de identificar um ficheiro existente nesse repositório. Por isso, abra o separador Files and versions e consulte os nomes reais dos ficheiros antes de escrever um. A quantização pretendida depende da memória disponível e da qualidade, e a diferença entre Q4, Q8 e FP16 explica devidamente esse compromisso.

Rota 2: importar um ficheiro .gguf do seu próprio disco

Quando o ficheiro já está no servidor, precisa de um Modelfile. Pode ter uma única linha. Crie um diretório, coloque o Modelfile nesse diretório e indique o ficheiro a FROM:

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

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

Guarde-o como Modelfile e, em seguida, crie o modelo:

ollama create my-model

Por predefinição, ollama create lê um ficheiro chamado Modelfile no diretório atual. Use -f quando o ficheiro tiver outro nome ou estiver noutra localização, como em ollama create my-model -f /home/you/models/my-model/Modelfile. Execute ollama create --help para ver a flag e o respetivo valor predefinido na sua versão. O caminho em FROM pode ser absoluto ou relativo ao Modelfile, por isso FROM ./my-model-Q4_K_M.gguf funciona quando ambos estão no mesmo diretório. Um caminho absoluto elimina qualquer dúvida.

Verifique o resultado antes de confiar nele:

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

ollama list deve agora incluir my-model. ollama show my-model apresenta a arquitetura, o número de parâmetros, o tamanho do contexto e a quantização que o Ollama leu dos metadados do próprio ficheiro. Leia esses valores em vez de confiar no nome do ficheiro, porque um nome de ficheiro é uma cadeia que alguém introduziu manualmente. Se o modelo responder ao seu prompt de teste em linguagem normal e depois parar, a importação funcionou. Se não funcionar, consulte a secção sobre templates abaixo, porque essa é quase sempre a causa.

Há um aspeto importante sobre o espaço em disco: ollama create copia o GGUF para o próprio armazenamento de modelos do Ollama, em vez de referenciar o ficheiro na localização atual. Os pesos ficam armazenados duas vezes até remover o original. Elimine o ficheiro de origem quando ollama run my-model funcionar ou mantenha-o num local pelo qual não esteja a pagar duas vezes. onde o Ollama mantém os modelos no disco apresenta a estrutura e explica como movê-los.

Quando --quantize se aplica e quando não se aplica

ollama create tem uma flag --quantize e, atualmente, esta aplica-se apenas a um caso: um modelo importado de um diretório com pesos .safetensors. O texto de ajuda no código-fonte atual do Ollama, verificado em 10 October 2026, é "Quantize safetensors model to this level (e.g. nvfp4)", e os valores aceites são int4, int8, nvfp4, mxfp4 e mxfp8. Nomes de quantização GGUF, como q8_0 ou q4_K_M, são rejeitados como tipos não suportados. A documentação de importação do Ollama é clara sobre GGUF: "Ollama does not quantize GGUF models during import."

ollama create --quantize int8 my-model

Esse comando pressupõe um Modelfile cuja linha FROM aponta para o diretório que contém os ficheiros .safetensors.

Não passe essa flag quando FROM indicar um .gguf, independentemente da respetiva precisão. Um GGUF FP16 ou FP32 é recusado da mesma forma que um Q4_K_M, com um erro que começa por "create-time quantization is only supported for safetensors imports". Um .gguf cujo nome contenha Q4_K_M ou Q5_K_S já foi quantizado, e a precisão descartada não pode ser recuperada. O llama-quantize do llama.cpp pode recodificar esse ficheiro como outro tipo, incluindo Q8_0, quando passa --allow-requantize, mas o manual avisa que isto "can severely reduce quality compared to quantizing from 16bit or 32bit", e um ficheiro Q4 reescrito como Q8 fica maior sem melhorar. Para reduzir o tamanho de um GGUF de precisão total, execute primeiro llama-quantize nesse ficheiro. Essa é a ferramenta indicada pela documentação do Ollama. Em seguida, importe o ficheiro que ela gerar. Se a origem for um repositório Hugging Face com ficheiros .safetensors, pode apontar FROM para esse diretório e deixar ollama create fazer a importação, usando --quantize se quiser reduzir o tamanho, ou convertê-lo com convert_hf_to_gguf.py a partir do repositório llama.cpp e importar o GGUF gerado pelo script. Como o Ollama e o llama.cpp se relacionam explica por que motivo essas ferramentas pertencem ao outro projeto.

Porque é que um GGUF importado responde com texto ilegível ou nunca termina?

Esta é a falha que a maioria dos tutoriais de importação omite, e é aquela que vai encontrar. Os sintomas parecem indicar um modelo danificado. Os tokens de controlo aparecem como texto visível na resposta, com cadeias como <|im_start|>assistant ou <|end|>. O modelo responde, depois escreve uma nova pergunta do utilizador e responde também a essa pergunta. A geração continua até premir Ctrl+C.

O modelo está correto. O problema está no template de chat. Um template de chat é o invólucro que transforma a sua mensagem na sequência exata de tokens com que o modelo foi treinado. Cada modelo usa os seus próprios marcadores para indicar onde termina o prompt do sistema e começa a intervenção do utilizador. O Ollama escolhe um por si: a documentação afirma que um template "will be selected automatically from a list of commonly used templates", com base nos metadados tokenizer.chat_template incorporados no ficheiro GGUF. Quando esses metadados estão em falta ou não correspondem a nenhum template da lista, é utilizado um invólucro genérico. O modelo recebe então um prompt com um formato diferente de tudo o que viu no treino e nunca encontra o marcador de fim de intervenção que aprendeu a utilizar para parar.

Mostre o template que o Ollama escolheu efetivamente:

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

Um template vazio ou obviamente genérico confirma o problema. Escreva o template manualmente no 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|>"

Recrie o modelo com ollama create my-model e envie novamente o mesmo prompt de teste. O parâmetro stop funciona como uma proteção: indica ao Ollama que deve interromper a geração quando essa cadeia aparecer. Isto elimina o sintoma de a geração nunca terminar enquanto ainda ajusta o próprio invólucro. Se a resposta continuar porque nenhum dos marcadores indicados aparece, um limite num_predict interrompe a geração após uma quantidade fixa de tokens, independentemente do que o template produzir.

O template tem de ser um template Go, não um template Jinja. A documentação do Hugging Face afirma isto diretamente. É importante porque o campo tokenizer.chat_template no repositório original do modelo contém Jinja. Colá-lo sem alterações não funciona. A sintaxe do Ollama tem três variáveis: {{ .System }} para o prompt do sistema, {{ .Prompt }} para a mensagem do utilizador e {{ .Response }} para a resposta do modelo. Encontre os marcadores reais de intervenção do modelo no respetivo model card ou no seu tokenizer_config.json. Depois, converta-os manualmente para essa sintaxe Go.

Existe um atalho que evita a maior parte desse trabalho. Muitos modelos partilham um formato de prompt. Se outro modelo da sua biblioteca utilizar o mesmo formato, execute ollama show --template nesse modelo e copie o resultado.

Os ficheiros template, system e params num repositório Hugging Face

A opção do Hugging Face oferece os mesmos controlos através de ficheiros no repositório, em vez de instruções num Modelfile. Se for proprietário do repositório ou estiver a publicar a sua própria quantização, adicione-os aí para que todos os ollama run hf.co/... os utilizem.

• Um ficheiro chamado template contém o template Go. Aplica-se a mesma regra: Go, não Jinja.
• Um ficheiro chamado system contém o prompt do sistema.
• Um ficheiro chamado params contém os parâmetros de amostragem e tem de estar em JSON.

Um ficheiro params mínimo:

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

Quando não é proprietário do repositório, não pode adicionar esses ficheiros. Transfira o modelo uma vez, execute ollama show --modelfile hf.co/... para guardar o que recebeu e guarde esse resultado como um Modelfile. A linha FROM aponta para o blob que o Ollama já transferiu. Assim, pode editar as linhas TEMPLATE e PARAMETER e executar ollama create para criar uma cópia local corrigida sem transferir novamente nada. Esta é a forma padrão de corrigir uma quantização com problemas pertencente a outra pessoa.

Como importar um repositório GGUF privado

Um repositório privado precisa da chave SSH do Ollama na sua conta do Hugging Face. O método documentado para esta opção usa uma chave SSH em vez de um token de API. Por isso, um token que já tenha não permite aceder ao repositório.

Mostre a chave pública. Num servidor Linux onde o Ollama foi instalado com o script oficial, o serviço é executado como o utilizador ollama. Por isso, a chave está no diretório inicial desse utilizador:

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

Se iniciar o ollama serve manualmente como o seu próprio utilizador, o caminho será ~/.ollama/id_ed25519.pub. Copie a linha completa, abra as definições da sua conta do Hugging Face em https://huggingface.co/settings/keys e adicione-a como uma nova chave SSH. O comando normal passa então a funcionar nos seus repositórios privados:

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

Se o pull continuar a falhar depois de adicionar a chave, provavelmente mostrou o ficheiro errado. O servidor faz o download e apresenta a sua própria chave. Além disso, um servidor iniciado pelo systemd nunca lê o ~/.ollama do seu utilizador. Por isso, a chave no seu diretório inicial não é a que o Hugging Face vê.

O modelo cabe no seu VPS?

O número que determina isso é o tamanho do ficheiro no disco mais a memória necessária para a janela de contexto. Os pesos são carregados para a memória e ocupam aproximadamente o mesmo espaço que ocupam no ficheiro. A alocação do contexto é acrescentada a esse valor e aumenta com o número de tokens permitido. Execute ollama list para consultar o tamanho que o Ollama registou para o modelo. Compare-o com free -h no servidor e reserve margem para o sistema operativo e para os restantes serviços em execução. Se preferir consultar esse cálculo já feito com um modelo real, executar o Nemotron 3.5 Lightning num VPS indica a tag exata a descarregar, a RAM necessária e se um servidor apenas com CPU consegue acompanhar.

O contexto é a parte que muitas pessoas esquecem. Um modelo que é carregado com a janela predefinida pode falhar quando aumenta num_ctx, porque essa alocação aumenta de acordo com a janela solicitada. Definir num_ctx e o custo em memória explica o dimensionamento. Quando o total é demasiado grande, a solução habitual é usar uma quantização menor do mesmo modelo. Essa é a alternativa analisada em a comparação entre Q4 e Q8.

A falha não é subtil. Num VPS apenas com CPU, o kernel encerra o processo através do mecanismo out of memory killer. journalctl -u ollama -n 50 e dmesg mostram o encerramento. Num servidor com GPU, ollama ps apresenta uma coluna PROCESSOR que indica se o modelo carregado foi colocado na memória da GPU, na memória do sistema ou dividido entre ambas. Um modelo que passou parte para a memória do sistema continua a responder, mas lentamente. Medir tokens por segundo transforma “lentamente” num valor que pode comparar entre quantizações.

Verifique o que importou

Execute estes quatro comandos depois de qualquer importação, nesta ordem:

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

ollama list confirma que o modelo existe e mostra o tamanho registado pelo Ollama. ollama show confirma que o Ollama leu os metadados necessários do GGUF. ollama show --modelfile confirma qual template e quais parâmetros serão realmente usados. Esta é a verificação que deteta o problema de saída ilegível antes dos seus utilizadores. O prompt de teste verifica toda a cadeia, porque um modelo com um template inválido falha até no pedido mais curto. Quando esse prompt devolver uma resposta correta, o nome atribuído ao modelo será o mesmo nome usado por qualquer outro componente que comunique com a API do Ollama, incluindo um agente de programação apontado para o seu próprio servidor. Remova uma importação inválida com ollama rm my-model e crie-a novamente. Esse comando elimina a cópia do Ollama e deixa o seu .gguf de origem intacto.

FAQ

Posso importar um GGUF para o Ollama sem escrever um Modelfile?

Sim, quando o ficheiro está num repositório do Hugging Face. ollama run hf.co/{username}/{repository} faz o pull e executa-o diretamente, e ollama run hf.co/{username}/{repository}:{quantization} seleciona uma quantização específica. Um Modelfile só é necessário para um .gguf que já esteja no seu próprio disco. Nesse caso, pode conter apenas a linha FROM /path/to/file.gguf, seguida de ollama create my-model.

Que quantização o Ollama descarrega quando não especifico nenhuma?

A documentação do Hugging Face, consultada em 10 October 2026, diz que Q4_K_M é usado quando essa quantização está presente no repositório. Caso contrário, o Ollama escolhe um tipo de quantização razoável disponível no repositório. Adicione uma tag como :Q8_0 para controlar essa escolha. Confirme o que recebeu efetivamente com ollama show <model>. Esse comando apresenta a quantização dos metadados do ficheiro, e não do respetivo nome.

Porque é que o meu modelo importado repete o texto ou nunca termina a geração?

O template de chat não corresponde ao modelo. O Ollama seleciona automaticamente um template a partir dos metadados tokenizer.chat_template no GGUF. Quando esses metadados estão ausentes ou não são reconhecidos, é usado um wrapper genérico. Nesse caso, o modelo nunca recebe o marcador de fim de turno com que foi treinado. Apresente o template atual com ollama show --template <model>. Depois, adicione um bloco TEMPLATE e uma linha PARAMETER stop ao Modelfile e execute novamente ollama create. Escreva-o como um template Go. O template Jinja do repositório original não funciona.

Devo usar --quantize num GGUF que descarreguei?

Não. --quantize funciona apenas com importações de safetensors durante ollama create. Recusa qualquer origem GGUF, incluindo uma em FP16 ou FP32, e apresenta um erro a indicar que os modelos GGUF devem ser quantizados antes da importação. Um ficheiro cujo nome já inclua uma quantização, como Q4_K_M, já foi convertido. Quantizá-lo novamente não recupera a precisão perdida: llama-quantize --allow-requantize pode reescrevê-lo como Q8_0, mas o resultado será maior sem ser melhor. Para obter um ficheiro mais pequeno a partir de um GGUF de precisão total, execute nele o llama-quantize do llama.cpp e importe o resultado.

Como faço pull de um repositório GGUF privado?

Adicione a chave pública SSH do Ollama à sua conta do Hugging Face. Apresente-a com sudo cat /usr/share/ollama/.ollama/id_ed25519.pub numa instalação Linux padrão ou com ~/.ollama/id_ed25519.pub quando executar o servidor como o seu próprio utilizador. Depois, adicione-a na página de definições das chaves SSH da sua conta. A partir daí, ollama run hf.co/{username}/{repository} funciona nos seus próprios repositórios privados e nos repositórios de uma organização a que pertença.