Como rodar modelos GGUF localmente: Ollama, llama.cpp e vLLM

Baixou um arquivo .gguf e está se perguntando como rodá-lo de fato? Caminho mais rápido: ollama run hf.co/<repo>:Q4_K_M — o Ollama puxa o GGUF direto do Hugging Face e o serve. GGUF é o formato de modelo em arquivo único que o llama.cpp criou e que toda ferramenta de LLM local hoje fala, então o mesmo arquivo roda no Ollama, llama.cpp, LM Studio, Jan e (com ressalvas) vLLM. Este guia cobre cada runner com comandos prontos para colar, como escolher a quantização certa para sua VRAM e os erros de load que você realmente vai encontrar.

O que é um arquivo GGUF?

GGUF (GGML Universal File) é um formato de contêiner para modelos de linguagem quantizados. Um único arquivo guarda os pesos, o tokenizador e os metadados do modelo — nada mais para baixar, nenhuma sopa de config. Os pesos lá dentro estão quantizados: comprimidos de floats de 16 bits para inteiros de 4 bits (ou menos), e é por isso que um modelo 9B que exige ~18 GB em precisão total cabe em ~5,5 GB como arquivo Q4 e roda numa GPU gamer ou até numa CPU.

Duas coisas importam no nome de um arquivo GGUF:

1. O modelo base — gemma-3-4b-it-GGUF é um Gemma 3 4B fine-tunado e exportado para GGUF.
2. A tag de quant — Q4_K_M, Q8_0, IQ4_XS e companhia dizem o quão agressivamente os pesos foram comprimidos. Mais sobre escolher uma abaixo.

O Ollama roda modelos GGUF?

Sim — GGUF é o formato nativo do Ollama, e desde 2024 ele puxa um direto do Hugging Face sem você precisar encostar num arquivo:

# Puxe um quant GGUF direto do Hugging Face e converse com ele
ollama run hf.co/bartowski/gemma-2-9b-it-GGUF:Q4_K_M

# A tag de quant depois dos dois-pontos escolhe o arquivo dentro do repo
ollama run hf.co/ggml-org/gemma-3-4b-it-GGUF:Q8_0

Já baixou um .gguf por conta própria? Aponte um Modelfile para ele:

# Modelfile — uma linha basta
FROM ./gemma-2-9b-it-Q4_K_M.gguf

ollama create gemma9b -f Modelfile
ollama run gemma9b

O Ollama decide o GPU offload automaticamente e expõe uma API compatível com OpenAI na porta 11434, então qualquer coisa que fale essa API usa o modelo. O preço é controle: você não escolhe quantas camadas vão para a GPU.

Como rodar um arquivo GGUF no llama.cpp?

O llama.cpp é de onde o GGUF vem — o formato existe para ele — então o suporte é o mais profundo e o mais fresco. O binário llama-server entrega ao mesmo tempo uma UI de chat e um endpoint compatível com OpenAI:

# Baixa direto do Hugging Face (escolhe um GGUF compatível com a sua máquina)
llama-server -hf ggml-org/gemma-3-4b-it-GGUF --port 8080

# Ou rode um arquivo que você já tem, com GPU offload total
llama-server -m ./gemma-2-9b-it-Q4_K_M.gguf -ngl 99 --port 8080

O -ngl 99 empurra 99 camadas para a GPU; coloque abaixo do que sua VRAM permite e o resto fica na CPU. Esse controle fino de offload parcial é o superpoder do llama.cpp — um modelo 9B roda bem numa placa de 6 GB com 20 das 48 camadas offloaded, só mais devagar. Para um prompt one-shot em vez de servidor, troque o llama-server pelo llama-cli com a mesma flag -m.

O LM Studio é a mesma engine atrás de uma GUI de desktop: solte um .gguf na pasta de modelos dele (ou busque no Hugging Face dentro do app) e clique em carregar. Para a escolha da ferramenta em si, a comparação Ollama vs LM Studio cobre qual colocar por baixo dos seus modelos.

Qual quantização GGUF baixar?

Resposta padrão: Q4_K_M. É o ponto ideal da comunidade — a um ou dois por cento da qualidade em precisão total por cerca de um quarto do tamanho. A escada, do maior para o menor:

• Q8_0 — quase sem perdas; use se sua VRAM engole 8,5 bits por peso sem sentir.
• Q6_K / Q5_K_M — um degrau abaixo em tamanho, ainda excelente para modelos 30B+.
• Q4_K_M — o padrão. Para modelos de 7–14B, é aqui que a qualidade por GB atinge o pico.
• IQ4_XS / Q3_K_M — para espremer um modelo grande numa placa pequena; a perda de qualidade fica perceptível.
• Q2_K e abaixo — último recurso; o modelo começa a degradar em bobagem no meio da frase.

A regra de bolso para caber: tamanho do arquivo em GB mais ~1–2 GB de overhead de contexto devem caber na sua VRAM. Um Q4_K_M de 4,7 GB de um modelo 9B fica confortável numa placa de 8 GB. Prefira um modelo menor com quant melhor a um modelo maior com quant ruim — um 4B em Q8 geralmente ganha de um 9B em Q2.

GGUF vs Safetensors: qual formato você precisa?

Safetensors é o formato de arquivo não quantizado — pesos em precisão total para treinar, fazer fine-tuning e para ferramentas como transformers e ComfyUI. GGUF é o formato quantizado e rodável para inferência no seu próprio hardware. Você não faz fine-tuning num GGUF, e não roda um arquivo safetensors no Ollama ou no llama.cpp sem converter antes (é para isso que existe o script convert_hf_to_gguf.py no llama.cpp). Regra: treinar ou pipeline de imagem → safetensors; chat e servir local → GGUF. Se a sua busca começou como “gguf vs safetensors”, essa divisão é a resposta inteira.

Qual runner GGUF usar?

Runner	Melhor para	Instalação	GPU offload	API compatível com OpenAI
Ollama	Serviço configure-e-esqueça	One-liner com curl	Automático	Sim (:11434/v1)
llama.cpp	Controle máximo, recursos mais novos	Build ou gerenciador de pacotes	Ajuste manual -ngl	Sim (llama-server)
LM Studio	GUI de desktop, navegar modelos	Download do app	Automático	Sim (servidor local)
vLLM	Servir muitos usuários em lote	pip install vllm	Automático	Sim (nativo)

Escolha o Ollama se você quer o serviço subindo no boot e fora da vista — é o que uso no meu homelab para servir modelos para tudo na rede. Escolha o llama.cpp quando precisar de um recurso no dia em que ele sai (arquiteturas novas chegam lá primeiro) ou quiser controle de memória nível camada. Escolha o LM Studio por uma GUI. Escolha o vLLM só quando um modelo precisa atender muitos usuários simultâneos — o suporte a GGUF dele funciona, mas é de segunda classe perto dos formatos nativos.

Por que meu modelo GGUF não carrega?

Os quatro erros que cobrem a maioria dos casos:

1. unknown model architecture — o GGUF usa uma arquitetura que seu runtime antecede (MoE novos e modelos de visão chegam sem parar). Atualize o Ollama ou recompile o llama.cpp; não existe outro conserto.
2. Out of memory no load — o quant é grande demais para sua VRAM mais o contexto. Caia um degrau (Q4_K_M → Q3_K_M), baixe o -ngl ou encolha o contexto com -c 4096.
3. Download truncado / corrompido — o load do GGUF falha com erro de magic number ou de metadados. Baixe de novo e compare o SHA256 exibido na página do Hugging Face.
4. ollama run ./model.gguf recusa — esperado: o run do Ollama recebe nomes de modelo, não caminhos de arquivo. Use o caminho do Modelfile mostrado acima.

Um último ângulo que vale conhecer: um endpoint GGUF local combina bem com ferramentas de código agênticas — aponte um cliente compatível com OpenAI para ele e as completions custam só a eletricidade. Os melhores LLMs locais para código testaram quais modelos merecem a vaga depois que a encanagem deste guia funciona.