Formato GGUF: o que é e como executá-lo

A modelo GGUF é um modelo de linguagem grande empacotado no formato de arquivo GGUF — um contêiner de arquivo único que armazena os pesos quantizados, o tokenizador, os hiperparâmetros e o modelo de prompt de um modelo. Foi criado por Georgi Gerganov e pelo projeto llama.cpp em agosto de 2023 para substituir o formato mais antigo GGML. O GGUF torna possível baixar um único arquivo, apontar um runtime para ele e obter um LLM local funcionando em um laptop ou estação de trabalho.

O que o GGUF realmente é

GGUF significa GPT-Generated Unified Format. Estruturalmente, trata-se de um arquivo binário com um cabeçalho, um bloco de metadados no formato chave-valor, um índice de tensores e os próprios dados dos tensores. A especificação oficial do GGUF no repositório ggml define essa estrutura.

Duas propriedades são relevantes para os usuários:

• Autossuficiente. O arquivo inclui o tokenizador, tokens especiais, IDs de EOS/BOS, modelo de conversa e metadados da arquitetura. Você não precisa de um arquivo separado tokenizer.json ou config.json ao lado dele.
• Mapeável na memória. Os runtimes usam mmap() para mapear o arquivo, de modo que a inicialização é quase instantânea e o sistema operacional carrega os pesos sob demanda. É por isso que um GGUF de 40 GB abre em segundos, mesmo em um SSD lento.

O GGUF substituiu o GGML porque este último não possuía versionamento, misturava metadados com pesos e apresentava falhas sempre que surgia uma nova arquitetura. Já o GGUF é versionado e extensível.

Quantização: o esquema de nomenclatura

A maioria dos arquivos GGUF que você baixa está quantizada — ou seja, os pesos são armazenados com menos bits do que o original em FP16. O sufixo no nome do arquivo indica qual esquema foi utilizado. As famílias atuais estão documentadas no README de quantização do llama.cpp.

Quant	Bits/peso (aproximadamente)	Uso típico
Q2_K	~2.6	Menor tamanho, perda de qualidade perceptível
Q3_K_M	~3.9	Compressão agressiva
Q4_K_M	~4.8	Padrão mais comum — bom equilíbrio entre tamanho e qualidade
Q5_K_M	~5.7	Qualidade superior, arquivo maior
Q6_K	~6.6	Quase sem perdas em comparação com FP16
Q8_0	~8.5	Efetivamente sem perdas, cerca de 2× o tamanho do Q4
F16 / BF16	16	Referência não quantizada

O _K As variantes k-quants utilizam precisão variável por bloco de tensor. Os sufixos _M / _S / _L indicam predefinições médias, pequenas ou grandes de mistura de blocos. Variantes mais recentes (por exemplo, IQ IQ4_XS ) empregam calibração por matriz de importância para melhorar a qualidade ao mesmo orçamento de bits.) use importance-matrix calibration for better quality at the same bit budget.

Como regra prática para VRAM, considere o tamanho do arquivo no disco e adicione aproximadamente 1–3 GB para o cache KV em contextos curtos, e mais para contextos longos. A partir da base de dados de modelos Convly: Llama 3.1 8B precisa de cerca de 5 GB em 4 bits, Llama 3.3 70B cerca de 40 GB e Mistral 7B cerca de 4,5 GB. Para modelos maiores, o tabela de requisitos de VRAM é a pesquisa mais rápida.

Onde obter arquivos GGUF

Quase toda a distribuição de GGUF ocorre no Hugging Face. Pesquise pelo nome do modelo seguido de “GGUF”. Requantizadores confiáveis incluem bartowski, Qwen (oficial para Qwen3), lmstudio-community, unsloth e MaziyarPanahi. A Meta, o Google, a Mistral e a Microsoft publicam algumas versões oficiais em GGUF; para os demais, a comunidade realiza a quantização a partir dos modelos originais em safetensors.

Um repositório normalmente contém um arquivo por nível de quantização, por exemplo, Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf. Para modelos com mais de ~50 GB, o arquivo é dividido em fragmentos (shards) nomeados como -00001-of-00003.gguf; os ambientes de execução carregam-nos automaticamente a partir do primeiro fragmento.

Executando um modelo GGUF

Linux

Compile o llama.cpp a partir do código-fonte ou instale o binário pré-compilado. Com 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
./build/bin/llama-cli -m ~/models/llama-3.1-8b-instruct-Q4_K_M.gguf 
    -p "Explique o GGUF em um único parágrafo." -n 256 -ngl 99

O -ngl A flag -ngl (n-gpu-layers) define quantas camadas do transformador serão movidas para a GPU. Defina-a com um valor alto o suficiente para que todo o modelo caiba na VRAM; se você esgotar a memória, reduza esse valor e as camadas restantes permanecerão na CPU. Para disponibilizar uma API HTTP compatível com OpenAI, use llama-server na porta 8080 por padrão.

macOS

No Apple Silicon, o llama.cpp usa automaticamente o backend Metal. Instale via Homebrew:

brew install llama.cpp
llama-cli -m ~/models/qwen3-8b-Q5_K_M.gguf -p "Olá" -ngl 99

A memória unificada significa que o limite -ngl é sua RAM total menos a sobrecarga do sistema operacional. Um Mac da série M com 32 GB de RAM executa confortavelmente o Qwen3 14B ou Gemma 3 12B em Q4_K_M — o banco de dados lista esses modelos com aproximadamente 9 GB e 8 GB de VRAM, respectivamente.

Para uma interface gráfica (GUI), LM Studio é a escolha habitual no Mac. Ele baixa arquivos GGUF diretamente do Hugging Face e expõe um servidor local compatível com a API OpenAI.

Windows

Três rotas práticas:

• Ollama. Instale a partir do ollama.com/download, então ollama run llama3.1:8b. O Ollama faz o download de suas próprias versões curadas em GGUF. Para carregar um arquivo arbitrário, crie um Modelfile com uma linha FROM ./mymodel.gguf e execute ollama create mymodel -f Modelfile. Consulte nosso Guia de instalação do Ollama.
• LM Studio. Instalação em um clique, navegação e download de GGUF por meio de uma interface gráfica, com controle deslizante para descarregar carga para a GPU.
• binários pré-compilados do llama.cpp. O projeto fornece pacotes ZIP pré-compilados para Windows com suporte a CPU, CUDA e Vulkan na lançamentos no GitHub. Descompacte e execute llama-cli.exe da mesma forma que no Linux.

Quanto à escolha da GPU, o guia de GPUs locais para LLMs aborda as opções atuais de preço/VRAM.

GGUF versus Safetensors versus AWQ versus 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.

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

O GGUF pressupõe inferência com fluxo único e tamanho de lote igual a 1. A vazão é muito menor que a do vLLM ou do TensorRT-LLM sob carga concorrente, e não há atenção paginada. Se você está disponibilizando uma API para tráfego real, uma implantação em FP16 ou AWQ com vLLM superará o GGUF em tokens/segundo/dólar, mesmo antes de considerar o tempo gasto pelos desenvolvedores.

Além disso, ele apresenta falhas no extremo superior do espectro de tamanhos de modelo. Kimi K3 requer cerca de 1,4 TB de VRAM em 4 bits e DeepSeek V4-Pro cerca de 800 GB — trata-se de implantações multi-nó, não cargas de trabalho GGUF para desktop. E, para modelos hospedados de ponta como Claude Sonnet 4.6 a US$ 3 na entrada / US$ 15 na saída por 1 milhão de tokens ou Gemini 3.6 Flash a US$ 1,50 na entrada / US$ 7,50 na saída, não existem pesos locais para conversão. Faça as contas no calculadora de autohospedagem versus API antes de se comprometer com a compra de uma GPU.

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.

Perguntas frequentes

GGUF é a mesma coisa que GGML?

Não. GGML foi o formato anterior usado pelo llama.cpp até meados de 2023. GGUF o substituiu em agosto de 2023 com um cabeçalho versionado, metadados embutidos e um layout estável de tensores. Arquivos .bin GGML antigos não são mais carregados pela versão atual do llama.cpp; você precisa encontrar uma versão GGUF re-quantizada.

Qual quantização devo baixar?

Comece com Q4_K_M. Ele se adapta à maior variedade possível de hardware, e a perda de qualidade em relação ao FP16 é pequena para a maioria dos modelos com mais de 7 bilhões de parâmetros. Suba para Q5_K_M ou Q6_K se você tiver VRAM ociosa e valorizar precisão em codificação ou raciocínio. Reduza para Q3_K_M ou uma variante IQ3 apenas se o modelo, de outra forma, não couber na memória disponível.

O modelos GGUF pode usar minha GPU?

Sim. O llama.cpp suporta CUDA (NVIDIA), ROCm (AMD), Metal (Apple), Vulkan (multi-fornecedor) e SYCL (Intel). A flag -ngl descarrega camadas para a GPU. Se o modelo couber inteiramente na VRAM, o throughput fica próximo ao de runtimes dedicados a GPU; em descarga parcial, a velocidade é determinada pela camada mais lenta, seja qual for o nível de memória em que ela resida.

GGUF funciona com modelos de visão ou áudio?

Parcialmente. O llama.cpp suporta modelos multimodais no estilo LLaVA por meio de um arquivo mmproj GGUF pareado que contém o projetor visual. O suporte a Qwen-VL, Gemma 3 Vision e similares foi adicionado progressivamente, mas ainda fica atrás das versões textuais. Modelos de áudio como Whisper têm seu próprio formato relacionado, tratado por whisper.cpp, e não pelo binário principal do llama.cpp.

Como escolher um modelo GGUF compatível com meu hardware?

Consulte o modelo na base de dados de modelos Convly para obter sua estimativa de VRAM em 4 bits, depois subtraia 1–3 GB de margem para contexto e sobrecarga do sistema operacional. Em uma placa de 24 GB, Qwen3 32B (~20 GB) ou Gemma 3 27B (~16 GB) em Q4 são opções confortáveis. O Calculadora de VRAM lida com contextos mais longos, cujo cache KV cresce significativamente.

Arquivos GGUF são seguros para execução?

Os pesos em si são apenas números — ao contrário de checkpoints baseados em pickle do Python, o GGUF não executa código ao ser carregado. O risco reside em um arquivo maliciosamente elaborado que dispare um bug no parser do runtime. Prefira uploaders conhecidos do Hugging Face (bartowski, unsloth, lmstudio-community, contas oficiais dos fornecedores) e mantenha o llama.cpp, o Ollama ou o LM Studio atualizados.