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 único comando ollama run transfere-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 ponto: um modelo com nome na biblioteca local do Ollama, que ollama run e a API do Ollama podem disponibilizar. Use o primeiro método quando outra pessoa tiver publicado o ficheiro. Use o segundo quando tiver feito a quantização do modelo, quando o ficheiro tiver chegado por scp ou rsync, ou quando a máquina não conseguir aceder ao Hugging Face.

Um ficheiro GGUF é um único ficheiro binário que contém os pesos, o tokenizador e os metadados do modelo. É o formato lido pelo llama.cpp, e o Ollama é baseado no llama.cpp. Por isso, quase todos os modelos abertos têm uma conversão GGUF mantida pela comunidade. O Ollama não carrega diretamente uma pasta de pesos .safetensors, por isso a etapa de conversão existe por uma razão.

Tudo o que 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 num VPS e depois volte a este guia. Execute ollama list primeiro. Se devolver uma tabela, mesmo vazia, em vez de um erro de ligação, o servidor está ativo e o restante deste guia funcionará.

Rota um: executar um GGUF do Hugging Face sem Modelfile

Ollama pode obter um GGUF diretamente de um repositório do Hugging Face. O comando usa 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 transfere o ficheiro, por isso o prompt de chat só aparece depois de a transferência terminar. Depois disso, o modelo fica na biblioteca local e arranca rapidamente. Abra uma segunda shell e execute ollama list para ver o nome com que foi armazenado. Esse nome é a cadeia hf.co/... completa, incluindo a 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 contenham realmente ficheiros GGUF. Um repositório que publique pesos .safetensors e nada mais não dá ao Ollama nenhum ficheiro para obter. Nesse caso, precisa da etapa de conversão descrita mais abaixo.

Que quantização escolhe o Ollama?

A documentação do Ollama no Hugging Face, consultada em 25 August 2026, é explícita quanto ao 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-lhe Q4_K_M. Um repositório sem Q4_K_M deixa a escolha a cargo do 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 o mesmo. Também pode passar o nome exato do ficheiro como tag. Esta é a forma segura quando os nomes abreviados de um repositório são ambíguos. A tag tem de identificar um ficheiro existente nesse repositório. Abra o separador Files and versions e leia os nomes reais dos ficheiros antes de escrever um. A quantização pretendida depende da memória disponível e da qualidade desejada. A diferença entre Q4, Q8 e FP16 explica corretamente este compromisso.

Rota dois: 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 aponte FROM para o ficheiro:

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

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

Guarde esse conteúdo como Modelfile e, em seguida, construa 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 compilaçã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 essa 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 comprimento 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 de caracteres escrita manualmente por alguém. Se o modelo responder ao seu prompt de teste em linguagem normal e depois parar, a importação funcionou. Se isso não acontecer, consulte a secção sobre templates abaixo, porque essa é quase sempre a causa.

Tenha em conta 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 onde este se encontra. Os pesos ficam duas vezes no disco até remover o original. Elimine o ficheiro de origem quando ollama run my-model funcionar ou mantenha-o num local onde não esteja a ocupar espaço duplicado. onde o Ollama mantém os modelos no disco explica a estrutura e como a mover.

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

ollama create tem uma flag --quantize, que existe para um único caso: um modelo de origem em FP16 ou FP32, ou seja, pesos em precisão total. A documentação de importação do Ollama indica q8_0 e as variantes k-means q4_K_S e q4_K_M como destinos.

ollama create --quantize q4_K_M my-model

Não passe essa flag para um ficheiro que já esteja quantizado. Um .gguf cujo nome contenha Q4_K_M ou Q5_K_S já passou por este processo, e a flag não tem nada para fazer. A quantização é uma conversão unidirecional de uma precisão superior para uma inferior, por isso não existe um caminho de Q4 de volta para Q8. Se a origem for um repositório Hugging Face com ficheiros .safetensors, converta-os primeiro com convert_hf_to_gguf.py, do repositório llama.cpp, que é a ferramenta indicada pela documentação do Ollama. Em seguida, importe o GGUF criado por esse script. Como o Ollama e o llama.cpp se relacionam explica por que motivo o script de conversão pertence 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} obtém e executa o ficheiro 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 descarrega o Ollama quando não especifico nenhuma?

A documentação do Hugging Face, consultada em 25 August 2026, indica 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>. Este comando apresenta a quantização dos metadados do ficheiro, e não do nome do ficheiro.

Porque é que o meu modelo importado repete o texto ou nunca para de gerar?

O chat template não corresponde ao modelo. O Ollama seleciona automaticamente um template a partir dos metadados tokenizer.chat_template dentro do GGUF. Quando esses metadados estão ausentes ou não são reconhecidos, é usado um wrapper genérico. Nesse caso, o modelo não vê 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 converte uma origem FP16 ou FP32 durante ollama create. Um ficheiro cujo nome já inclui uma quantização, como Q4_K_M, já foi convertido. Não é possível recuperar a precisão quantizando novamente, nem existe um processo para voltar a uma precisão superior. Use esta flag apenas quando tiver convertido safetensors para um GGUF de precisão total e quiser agora criar um ficheiro mais pequeno.

Como obtenho 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 normal, ou com ~/.ollama/id_ed25519.pub quando executar o servidor com 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.