Importar um modelo GGUF do Hugging Face para Ollama

#Por que importar um GGUF do Hugging Face

Ollama mantém uma biblioteca de modelos práticos (ollama.com/library), mas ela é deliberadamente limitada: os mantenedores publicam nela os modelos mais solicitados, em quantizações escolhidas para esses modelos. Assim que você procura um fine-tune especializado, uma versão recém-lançada, um modelo em francês ou uma quantização específica, precisa buscá-lo no Hugging Face — a maior plataforma de compartilhamento de modelos com pesos abertos.

O formato GGUF (sucessor do GGML) é o que o Ollama entende nativamente: um único arquivo que contém os pesos quantizados, o tokenizer e os metadados do modelo. Colaboradores como TheBloke, bartowski ou unsloth publicam milhares de arquivos GGUF prontos para uso, muitas vezes em cerca de dez quantizações por modelo. Saber importá-los dá acesso a todo esse ecossistema na sua instalação do Ollama.

Modelos recentes

Um modelo publicado ontem no Hugging Face é utilizável antes mesmo de aparecer na biblioteca oficial do Ollama.

Fine-tunes de nicho

Modelos especializados (código, medicina, interpretação de papéis, francês) que ninguém se deu ao trabalho de empacotar oficialmente.

Quantização precisa

Escolher exatamente o nível (Q4_K_M, Q5_K_M, Q8_0…) que cabe na sua VRAM, em vez de se limitar à variante padrão.

Modelos privados

Seus próprios fine-tunes ou GGUF baixados, importados localmente via um Modelfile.

#Pré-requisitos

Ollama instalado

Versão recente (0.5+) para suporte nativo ao hf.co. O daemon escuta por padrão em http://localhost:11434. Verifique com « ollama --version ».

Uma conexão com internet

Para o método direto que baixa do Hugging Face. Em seguida, o modelo roda 100% localmente.

VRAM ou RAM suficiente

Como referência em Q4: um 7B cabe em ~5 GB, um 14B em ~9 GB, um 32B em ~19 GB e um 70B em ~40 GB. Sem GPU, é a RAM que importa, mas a execução é mais lenta.

O nome de um repositório GGUF

Por exemplo, bartowski/Qwen3.5-9B-Instruct-GGUF. Localize-o na URL da página do modelo no Hugging Face.

Para encontrar um repositório GGUF, a busca do Hugging Face permite filtrar por formato. Busque o nome do modelo e acrescente “GGUF”, ou filtre pela biblioteca “GGUF” na barra lateral. Abra a aba “Files and versions”: nela, você verá a lista de arquivos .gguf, um por quantização, com seus tamanhos em GB — uma informação valiosa para as próximas etapas.

#Método direto: ollama run hf.co/...

É, de longe, a forma mais simples de importar um modelo GGUF do Hugging Face para o Ollama. Desde a versão 0.5, o Ollama consegue baixar um GGUF diretamente de um repositório do Hugging Face com um único comando, sem baixar o arquivo manualmente nem escrever um Modelfile. A sintaxe usa o caminho do repositório com o prefixo hf.co/.

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

Sem especificar a quantização, o Ollama escolhe uma opção padrão (geralmente Q4_K_M, se ela existir no repositório). Para selecionar uma quantização específica, adicione-a após dois-pontos, exatamente como uma tag de modelo comum. O nome da tag corresponde ao sufixo do arquivo .gguf, sem diferenciar maiúsculas de minúsculas.

# 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 baixa o arquivo, salva no seu armazenamento local e inicia a conversa. O modelo aparece em seguida em « ollama list » com seu nome completo hf.co/... e é reiniciado instantaneamente. Você pode dar a ele um apelido mais curto com « ollama cp » se o nome parecer muito longo para digitar.

# 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

#Escolher a quantização adequada de acordo com sua VRAM

O mesmo modelo é publicado em várias quantizações: esse é o compromisso central entre qualidade e memória. Quanto mais agressiva for a quantização (menos bits por peso), menor será o arquivo e mais facilmente ele caberá em uma placa modesta — ao custo de uma leve perda de precisão. Uma boa prática é escolher a quantização mais alta que caiba confortavelmente na sua VRAM.

Q4_K_M — recomendado

O melhor equilíbrio para a grande maioria dos usos. Perda de qualidade quase imperceptível, uso reduzido de memória. Escolher por padrão se você estiver em dúvida.

Q5_K_M — um nível acima

Ligeiramente mais pesado, ligeiramente mais preciso. Interessante se sua VRAM tiver margem e você quiser o máximo de qualidade sem passar para 8 bits.

Q8_0 — quase sem perda

Muito próximo do modelo não quantizado, mas cerca de duas vezes mais pesado que o Q4. Reservado para casos em que a menor degradação importa e onde a VRAM não falta.

FP16 — precisão completa

O modelo não quantizado, o mais pesado. Raramente necessário para inferência local: Q8_0 é suficiente quase sempre e reduz a memória pela metade.

Para estimar se uma quantização cabe na memória, use como referência o tamanho do arquivo .gguf exibido no Hugging Face, mais uma margem de aproximadamente 1 a 2 GB para o contexto e o sistema. Aqui estão os valores de referência de VRAM em Q4_K_M por tamanho de modelo e os GPUs típicos que os executam.

3B ≈ 2 GB

Funciona em qualquer lugar, mesmo em uma placa de entrada ou na CPU. Ideal para uma RTX 3060 de 12 GB, com bastante margem para o contexto.

7B ≈ 5 GB

Confortável em RTX 3060 12 GB, RTX 4070 12 GB. O formato mais versátil para uso diário.

14B ≈ 9 GB

RTX 4070 12 GB (no limite), RTX 4080 16 GB com folga. Um bom patamar de qualidade para raciocínio e programação.

32B ≈ 19 GB

RTX 4090 de 24 GB ou Mac M4 Pro com memória unificada. Uma opção de alto desempenho acessível para uma estação de trabalho.

70B ≈ 40 GB

Requer 48 GB ou mais: Mac Studio com bastante memória unificada ou uma configuração com várias GPUs. Mude para Q4 ou para uma quantização ainda mais agressiva.

#Método Modelfile: FROM fichier.gguf

O método direto assume que o GGUF está no Hugging Face e é acessível online. Mas se você já baixou um arquivo .gguf manualmente, criou o seu com llama.cpp ou deseja personalizar o modelo (prompt de sistema, parâmetros), é necessário usar um Modelfile. É um pequeno arquivo de texto, no estilo de um Dockerfile, que descreve como construir um modelo Ollama a partir de um GGUF local.

A diretiva central é FROM, que aponta para o caminho do arquivo .gguf. Crie um arquivo chamado « Modelfile » (sem extensão) ao lado do seu GGUF, com pelo menos esta linha.

FROM ./mon-modele.Q4_K_M.gguf

Em seguida, crie o modelo com “ollama create”, dando a ele o nome que desejar. O Ollama lê o GGUF, registra-o em seu armazenamento e o disponibiliza como qualquer outro modelo.

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

# Le lancer
ollama run mon-modele

Um Modelfile completo pode ir muito além: definir um prompt de sistema, ajustar os parâmetros de amostragem e, principalmente, definir o TEMPLATE — o formato de chat esperado pelo modelo. É aqui que a maioria dos problemas de qualidade é resolvida, como vemos na seção seguinte.

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|>
"""

#Corrigir um template de chat quebrado

Essa é a principal armadilha da importação de GGUF. Um modelo importado pode responder de qualquer jeito: frases que nunca terminam, tags estranhas na saída (<|im_end|>, [INST], <end_of_turn>), respostas que ignoram a pergunta ou entram em loop. Nove em cada dez vezes, não é o modelo que é ruim — é o template de chat que não corresponde ao usado durante seu treinamento.

Cada família de modelos espera um formato de conversa específico: ChatML (<|im_start|>) para Qwen e muitos fine-tunes, [INST]...[/INST] para Mistral e Llama 2, <start_of_turn> para Gemma, um formato específico para Llama 3. Se o GGUF incluir o template errado em seus metadados, ou se Ollama inferir um incorreto, as respostas pioram. O sintoma mais comum: tags de fim de turno aparecem literalmente na resposta em vez de interromper a geração.

Sintoma: tags visíveis

O modelo exibe <|im_end|> ou <|eot_id|> em sua resposta. Falta um PARAMETER stop correspondente, ou o template não emite o token de fim correto.

Sintoma: geração infinita

O modelo nunca para e encadeia os turnos sozinho. O token de parada esperado não está declarado.

Sintoma: respostas incoerentes

O modelo ignora o prompt de sistema ou responde fora do assunto. O formato dos papéis (system/user/assistant) não corresponde ao usado no treinamento.

A correção consiste em fornecer o TEMPLATE correto e os PARAMETER stop corretos em um Modelfile. A fonte de referência é a “model card” do modelo original no Hugging Face: procure a seção “prompt format” ou “chat template”, que indica o formato exato. Para um modelo ChatML (Qwen e derivados), o template e os stops ficam assim.

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|>"

Reconstrua em seguida com « ollama create » e teste. Uma dica eficaz para recuperar o template correto sem reescrevê-lo: parta de um modelo oficial da mesma família já presente no Ollama e examine seu Modelfile gerado, depois reutilize seu bloco 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

#Solução de problemas

« Error: pull model manifest »

O caminho hf.co está mal escrito, o repositório é privado/gated ou a sua versão de Ollama é muito antiga. Verifique a URL exata do repositório e atualize Ollama.

A tag de quantização não existe

O Ollama informa que a tag não foi encontrada: abra “Files and versions” no Hugging Face e copie o sufixo exato do arquivo .gguf (por exemplo, Q4_K_M, IQ4_XS). Não há distinção entre maiúsculas e minúsculas, mas o nome deve corresponder.

Modelo muito lento / respostas aos trancos

Parte do modelo passa a usar a RAM e a CPU por falta de VRAM. Verifique com « ollama ps » se ele está rodando na GPU ou na CPU e escolha uma quantização com menos bits ou um modelo menor.

O repositório contém apenas safetensors

Nenhum arquivo .gguf disponível: procure uma versão « GGUF » convertida pela comunidade ou converta o modelo você mesmo com os scripts do llama.cpp.

Saídas com tags indesejadas

Template de chat incorreto: veja a seção anterior e forneça o TEMPLATE correto e as diretivas PARAMETER stop por meio de um Modelfile.

#Para se aprofundar

Importar um GGUF depende de duas habilidades básicas do ecossistema Ollama. Estes guias do site dão continuidade a este guia:

Escolher sua quantização (Q4, Q5, Q8, FP16)

Compreender detalhadamente o equilíbrio entre qualidade e memória para escolher a versão GGUF adequada de acordo com sua placa.

Personalizar um modelo com Ollama Modelfile

Ir além com o Modelfile: prompts de sistema, parâmetros, templates e múltiplas variantes de um mesmo modelo.

Instalar o Ollama: Windows, macOS e Linux

Guia de instalação básico, atualizado, se você começar do zero antes de importar seus primeiros GGUF.