Modelos GGUF: O que são e como executá-los

GGUF (GPT-Generated Unified Format) é o formato de arquivo usado pelo ecossistema llama.cpp/ggml para armazenar um modelo pronto para inferência. Um único .gguf arquivo contém os tensores quantizados, além de tudo necessário para usá-los: vocabulário, configurações do tokenizador, modelo de conversação (chat template) e metadados da arquitetura. Ele substituiu o formato mais antigo GGML em agosto de 2023 e é agora o padrão de fato para executar modelos em laptops, desktops e CPUs.

O que realmente há dentro de um arquivo .gguf

Um arquivo GGUF é composto por um cabeçalho, um bloco de metadados com pares chave-valor e, em seguida, os dados dos tensores. Os metadados são a parte que realmente importa na prática — é por isso que um modelo GGUF não requer arquivos auxiliares. A documentação GGUF do Hugging Face descreve a estrutura e o visualizador integrado de metadados GGUF do Hub, que permite inspecionar o tipo de quantização, o comprimento do contexto e o modelo de conversação (chat template) de um arquivo antes de baixar vários gigabytes dele.

Chaves típicas de metadados incluem a arquitetura (llama, qwen3, gemma3, phi3), o comprimento de contexto de treinamento, as configurações RoPE, o vocabulário completo e o modelo de conversação Jinja. Um carregador lê esse bloco e se configura automaticamente; você não precisa passar manualmente um tokenizador ou um formato de prompt.

GGUF versus safetensors

	GGUF	safetensors
Runtime principal	llama.cpp, Ollama, LM Studio	PyTorch, vLLM, Transformers, TGI
Arquivos por modelo	Um (ou fragmentos numerados)	Pesos mais pasta de configuração/tokenizador
Quantização	Incorporada (Q4_K_M, Q8_0, IQ…)	Normalmente FP16/BF16, ou variantes GPTQ/AWQ
CPU + descarga parcial para GPU	Sim, objetivo central de projeto	Limitado e lento
Atendimento concorrente em lote	Fraco	Fortes
Ajuste fino	Não (converta de volta primeiro)	Sim

Como ler o nome de um arquivo GGUF

Os arquivos normalmente são nomeados Modelo-Nome-8B-Instruct-Q4_K_M.gguf. O sufixo indica a combinação de quantização. O número representa a largura nominal em bits; _K significa k-quants, que mantêm os tensores de atenção e incorporação (embedding) com maior precisão do que os pesos principais da camada feed-forward; S/M/L são variantes pequena/média/grande dessa combinação.

Quant	Aprox. bits/peso	Tamanho aproximado, modelo de 8B	Quando usá-lo
Q8_0	~8.5	~8,5 GB	Referência quase sem perdas; apenas para modelos pequenos
Q6_K	~6.6	~6,6 GB	Você tem VRAM de sobra
Q5_K_M	~5.7	~5,7 GB	Padrão com viés para qualidade
Q4_K_M	~4.9	~4,9 GB	O padrão habitual
Q4_0	~4.5	~4,5 GB	Legado; alguns aceleradores preferem esse formato
Q3_K_M	~3.9	~4,0 GB	Comprimir um modelo maior em pouca VRAM
Q2_K / IQ2	~2,5–3,4	~2,5–3,4 GB	Último recurso; degradação perceptível

Trate a coluna de bits por peso como aproximada. Os tamanhos reais variam conforme a arquitetura do modelo (um vocabulário amplo inflaciona os tensores de embedding) e conforme a versão do llama.cpp, pois as combinações de quantização são ajustadas ao longo do tempo. A família IQ (de IQ2_XXS até IQ4_NL) usa calibração por matriz de importância para manter melhor desempenho em larguras de bit muito baixas, e quantizadores como Bartowski e Unsloth publicam variantes IQ além dos K-quants padrão.

O consenso da comunidade — não uma medição da Convly — é que Q4_K_M representa o ponto ideal e que a qualidade cai acentuadamente abaixo de cerca de 3 bits por peso: modelos menores degradam-se mais rapidamente do que modelos maiores na mesma quantização.

Dimensionamento: quais modelos GGUF cabem na sua GPU

O tamanho do arquivo é o piso, não o total. Adicione o cache KV para seu comprimento de contexto, além de cerca de 500 MB–1 GB de sobrecarga. Essas cifras de 4 bits vêm do Convly models database:

Modelo	VRAM em 4 bits	Contexto	GPU realista
Gemma 3 4B	~3 GB	128K	Qualquer placa com 6 GB, GPU integrada
Mistral 7B	~4,5 GB	32K	Placa com 8 GB
Llama 3.1 8B	~5 GB	128K	Placa com 8 GB
Qwen3 14B	~9 GB	128K	Placa com 12 GB
Phi-4	~9 GB	16K	Placa com 12 GB
Gemma 3 27B	~16 GB	128K	Placa com 24 GB
Qwen3 32B	~20 GB	128K	Placa com 24 GB
Llama 3.3 70B	~40 GB	128K	2×24 GB ou memória unificada de 48 GB
DeepSeek R1 (completo)	~400 GB	128K	Apenas em servidores multi-GPU

Modelos Mixture-of-Experts são a armadilha aqui. Qwen3 30B-A3B ativa apenas ~3B parâmetros por token, mas ainda exige que todos os ~18 GB permaneçam residentes na memória. No extremo, o banco de dados estima Kimi K3 em ~1,4 TB a 4 bits — um GGUF existe, em princípio, mas nenhuma única máquina que você possua consegue armazená-lo. Para um valor exato no seu comprimento de contexto, use o calculadora de VRAM ou a análise detalhada por modelo em Requisitos de VRAM para todos os principais modelos de linguagem (LLM). Se você ainda está escolhendo hardware, melhores GPUs para LLMs locais aborda a relação custo-benefício entre VRAM e preço.

Onde baixar modelos GGUF

• Hugging Face — filtre a lista de modelos com library=gguf. A maioria dos repositórios fornece todas as quantizações em um único repositório; baixe apenas o arquivo necessário, não o repositório inteiro.
• biblioteca do Ollama — ollama.com/library oferece GGUF pré-empacotados com o modelo de conversação já configurado. Consulte o Lista de modelos do Ollama.
• LM Studio — a guia Descobrir do aplicativo pesquisa repositórios GGUF no Hugging Face e indica quais quantizações cabem na RAM/VRAM detectada do seu sistema. Passo a passo: Guia completo do LM Studio.

Modelos grandes chegam fragmentados como model-00001-of-00003.gguf e assim por diante. Baixe todos os fragmentos na mesma pasta e aponte o carregador para o fragmento 00001 — ele localizará automaticamente os demais.

Executando modelos GGUF no Linux

Compile o llama.cpp com suporte CUDA:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j

Os binários ficam em build/bin/. Inicie um servidor compatível com OpenAI:

./build/bin/llama-server -m ~/models/model-Q4_K_M.gguf -c 8192 -ngl 99 --port 8080

-ngl (--n-gpu-layers) é o controle de descarga (offload): 99 significa "todos os layers na GPU", 0 significa CPU apenas, e valores intermediários dividem o modelo quando ele não cabe inteiramente na GPU. -c define o contexto; mantê-lo no contexto total treinado do modelo pode consumir mais VRAM do que os próprios pesos. O endpoint resultante é http://localhost:8080/v1/chat/completions.

Duas ressalvas sobre versões: a flag CMake era LLAMA_CUBLAS nas versões anteriores, e os binários foram renomeados (main → llama-cli, server → llama-server) em 2024. Verifique o README do repositório para a versão que você clonou. Para GPUs AMD ou Intel, substitua a flag do backend ROCm/Vulkan/SYCL documentada lá, em vez de tentar adivinhar.

Se você usar o Ollama em vez disso, os modelos ficam em /usr/share/ollama/.ollama/models quando ele é executado como serviço do sistema, ou ~/.ollama/models para uma instalação por usuário. Veja como instalar o Ollama.

Executando modelos GGUF no macOS

O Apple Silicon é incomumente eficiente com GGUF porque a memória unificada permite que a GPU acesse a maior parte da RAM do sistema — um Mac de 64 GB pode carregar um modelo de 70B em 4 bits com cerca de 40 GB, que exigiria duas placas de PC com 24 GB cada.

brew install llama.cpp
llama-server -m ~/models/model-Q4_K_M.gguf -c 8192 --port 8080

A descarga para Metal está habilitada na compilação do Homebrew, portanto, normalmente você não precisa -ngl. O macOS limita quanto de RAM a GPU pode alocar (ajustável via um iogpu sysctl, cujo valor varia conforme a versão do macOS), então deixe uma margem de segurança para o sistema operacional. O Ollama armazena modelos em ~/.ollama/models; o LM Studio usa ~/.lmstudio/models nas versões atuais e ~/.cache/lm-studio/models nas versões mais antigas — a guia Meus Modelos exibe e permite alterar o caminho real.

Executando modelos GGUF no Windows

Três abordagens, da mais simples à mais complexa:

1. LM Studio — instalador gráfico, busca integrada de modelos e alternador para servidor local. A melhor opção padrão para usuários não desenvolvedores.
2. Ollama — instalador nativo para Windows; os modelos são salvos em C:Users.ollamamodels. Defina a variável de ambiente OLLAMA_MODELS para movê-los para fora da unidade do sistema. Contexto adicional: o que é Ollama.
3. Binários pré-compilados do llama.cpp — a página de Lançamentos no GitHub publica builds compactadas para Windows por backend (CUDA, Vulkan, CPU). Descompacte e execute llama-server.exe -m model.gguf -ngl 99 no PowerShell. Escolha a build CUDA para GPUs NVIDIA; o Vulkan é a opção segura e compatível com fornecedores diversos (AMD e Intel Arc).

Detalhes específicos do Windows: a verificação em tempo real do Windows Defender reduz significativamente o tempo de carregamento inicial de arquivos de vários gigabytes, e executar o llama.cpp dentro do WSL2 consome uma parcela da memória RAM destinada à máquina virtual. As compilações nativas para Windows geralmente representam o caminho mais simples.

Carregando um GGUF arbitrário no Ollama

Versões recentes do Ollama conseguem baixar diretamente do Hugging Face:

ollama run hf.co/<user>/<repo>:Q4_K_M

Para um arquivo local, crie um Modelfile no mesmo diretório:

FROM ./model-Q4_K_M.gguf

então ollama create my-model -f Modelfile e ollama run my-model. Se o GGUF não incluir um modelo de conversação utilizável, adicione uma linha TEMPLATE e PARAMETER stop — as diretivas exatas suportadas no Modelfile evoluíram ao longo das versões, portanto consulte ollama help create para verificar as opções disponíveis na sua versão. Seleções recomendadas: melhores LLMs locais para Ollama.

Quando GGUF não é a solução adequada

GGUF optimizes one user at a time. Serving many concurrent requests, or needing tensor parallelism across GPUs, points to safetensors with vLLM or SGLang. And running locally is not automatically cheaper: hosted Llama 3.3 70B is $0.10 in / $0.32 out per 1M tokens, while frontier hosted models like Claude Sonnet 5 custam US$ 2,00 por entrada e US$ 10,00 por saída a cada 1 milhão de tokens para contexto de 1 milhão. Calcule seu volume estimado usando a Calculadora de custos de API e o calculadora de ponto de equilíbrio entre hospedagem local e uso de API antes de comprar uma GPU.

GGUF versus safetensors, AWQ e GPTQ

Formato	Runtime principal	Precisão	Melhor para
GGUF	llama.cpp, Ollama, LM Studio	2–8 bits + F16	CPU, mista CPU/GPU, Apple Silicon, uso individual
Safetensors (FP16/BF16)	Transformers, vLLM	16 bits	Treinamento, pesquisa, inferência em precisão total
AWQ	vLLM, AutoAWQ	4 bits	Atendimento em GPU com alta vazão
GPTQ	vLLM, ExLlamaV2	3–8 bits	Inferência exclusiva em GPU com processamento em lote
MLX	MLX (Apple)	4–16 bits	Exclusivo para Apple Silicon

Escolha GGUF quando o alvo for um único usuário em hardware heterogêneo ou quando você quiser garantir que o modelo seja executado mesmo na CPU. Escolha vLLM com safetensors AWQ/GPTQ ao servir muitos usuários simultâneos em uma GPU de datacenter.

Convertendo um modelo para GGUF

Se um modelo existe no Hugging Face como safetensors, mas ainda ninguém o quantizou, o fluxo de trabalho é:

# no repositório llama.cpp
pip install -r requirements.txt
python convert_hf_to_gguf.py /caminho/para/o-modelo-hf --outfile model-f16.gguf
./build/bin/llama-quantize model-f16.gguf model-Q4_K_M.gguf Q4_K_M

O script de conversão só suporta arquiteturas que o llama.cpp já aprendeu — llama, mistral, qwen2/3, gemma, phi e uma lista crescente de outras. Arquiteturas novas exigem primeiramente uma alteração no código. Os nomes de arquivos e flags no script mudaram entre versões do llama.cpp, portanto verifique python convert_hf_to_gguf.py --help contra o commit usado na sua compilação.

Para saber de onde surgiu esse formato e como o GGUF substituiu o GGML, consulte O que é GGUF?.

Perguntas frequentes

O que significa GGUF e como ele difere do GGML?

GGUF significa GPT-Generated Unified Format (Formato Unificado Gerado por GPT). O GGML foi o formato anterior do mesmo projeto; ele perdia compatibilidade sempre que novos metadados eram necessários. O GGUF introduziu um bloco extensível de metadados baseado em pares chave-valor, permitindo adicionar novas arquiteturas e opções sem invalidar arquivos antigos. Arquivos .bin GGML anteriores ao GGUF não são mais carregados pela versão atual do llama.cpp.

Qual quantização devo baixar?

Comece com Q4_K_M. Se o modelo ainda deixar vários GB de VRAM livres, avance para Q5_K_M ou Q6_K. Se não couber na memória disponível, prefira um modelo menor em Q4_K_M em vez do mesmo modelo em Q2_K — um modelo de 14B em 4 bits geralmente supera um modelo de 32B distorcido para 2 bits. Verifique a adequação usando o calculadora de VRAM no comprimento de contexto pretendido.

Posso executar modelos GGUF sem uma GPU?

Yes — CPU-only inference is what GGUF was built for. Speed is bound by memory bandwidth, so expect single-digit tokens per second for a 7B–8B model at Q4_K_M on typical dual-channel desktop RAM, and slower for anything larger. Small models like Gemma 3 4B (~3 GB at 4-bit) are the practical CPU-only choice.

Posso converter um modelo do Hugging Face para GGUF eu mesmo?

Sim. O llama.cpp inclui um script de conversão (convert_hf_to_gguf.py nas versões atuais; o nome do arquivo usava hífens nas versões anteriores) que gera um GGUF em F16, seguido pela compressão desse arquivo pelo binário llama-quantize para uma quantização alvo. Consulte a ajuda do script com --help na cópia que você clonou, e confirme se sua arquitetura é suportada antes de iniciar — arquiteturas não suportadas falham durante a conversão.

Os modelos GGUF suportam visão ou chamadas de ferramentas?

A chamada de ferramentas funciona onde o modelo define essa funcionalidade no seu modelo de conversação (chat template) e seu carregador respeita esse modelo. Modelos multimodais exigem um segundo arquivo — um GGUF mmproj que contém o projetor visual — carregado em conjunto com os pesos textuais. As ferramentas multimodais no llama.cpp já foram renomeadas e reorganizadas mais de uma vez, portanto siga sempre a documentação atual do repositório, e não tutoriais antigos.

A quantização altera a janela de contexto?

Não. O contexto é uma propriedade do modelo, não da quantização: o Llama 3.3 70B tem 128K e o Llama 4 Scout tem 10M, independentemente de você executá-lo em F16 ou Q4_K_M. O que muda é se você consegue acomodar o cache KV necessário para aquele contexto na memória disponível. Compare contexto e preços entre modelos na Ranking de LLMs.