O que é GGUF? O formato de arquivo para LLMs por trás do Ollama e do llama.cpp, explicado

GGUF (geralmente expandido como GPT-Generated Unified Format, ou Formato Unificado Gerado por GPT) é um formato de arquivo binário para armazenar modelos de linguagem de grande porte: os pesos, o tokenizador e todos os metadados de configuração em um único arquivo autocontido. É o formato nativo do llama.cpp, e é o que Ollama, LM Studio, KoboldCpp, Jan e a maioria das outras aplicações locais para LLMs efetivamente executam. Se você já baixou um arquivo com a extensão .gguf, ou puxou um modelo com ollama run, você estava utilizando esse formato.

O que um arquivo GGUF realmente contém

Um arquivo GGUF começa com os quatro bytes ASCII GGUF, seguidos por um número de versão, uma seção de metadados em par chave-valor e, em seguida, os próprios tensores. Os metadados representam a decisão de projeto mais importante: eles armazenam a arquitetura do modelo, o comprimento máximo de contexto, o vocabulário do tokenizador, o modelo de conversa (chat template) e os detalhes da quantização como chaves nomeadas, permitindo que um ambiente de execução carregue qualquer arquivo GGUF sem necessitar de um arquivo separado config.json ou arquivos de tokenizador ao lado dele.

Três consequências práticas decorrem desse projeto:

• Um único arquivo representa o modelo inteiro. Você pode copiar um arquivo .gguf entre máquinas e ele funcionará imediatamente. (Modelos muito grandes são às vezes divididos em partes numeradas, como -00001-of-00002.gguf, mas isso ainda corresponde logicamente a um único modelo.)
• É mapeável na memória. Os ambientes de execução podem usar mmap o arquivo e carregar os pesos sob demanda por paginação, o que torna o carregamento rápido e permite que modelos maiores que a memória RAM disponível sejam inicializados.
• A quantização está incorporada ao formato. Um arquivo GGUF armazena pesos já comprimidos com 2–8 bits por peso, razão pela qual um modelo de 8 bilhões de parâmetros pode ter apenas 4,9 GB em vez de 16 GB.

Por que o GGUF substituiu o GGML

Antes de agosto de 2023, o llama.cpp usava um formato chamado GGML (nomeado após a biblioteca de tensores subjacente). O GGML funcionava, mas tinha um defeito estrutural: seu layout de arquivo era rígido e não versionado. Toda vez que o llama.cpp adicionava uma nova funcionalidade — novas arquiteturas, métodos de quantização aprimorados, parâmetros de escalonamento RoPE — o formato precisava ser alterado, e todos os arquivos de modelos existentes em todos os discos rígidos deixavam de funcionar. Em poucos meses, os usuários tiveram de baixar novamente ou converter novamente toda a sua coleção de modelos diversas vezes.

O GGUF, introduzido pelo projeto llama.cpp em agosto de 2023, resolveu esse problema com duas mudanças:

• Versionamento. O arquivo declara explicitamente sua versão de formato, permitindo que os leitores saibam exatamente como analisá-lo.
• Metadados extensíveis no formato chave-valor. Novas informações (um novo campo de arquitetura, um modelo de conversação, um hiperparâmetro adicional) são simplesmente novas chaves. Arquivos antigos sem essa chave continuam carregáveis; arquivos novos com ela funcionam em ambientes de execução atualizados. Nada é quebrado retroativamente.

O llama.cpp descartou o suporte ao GGML logo após essa mudança, e o ecossistema seguiu o mesmo caminho. Hoje, GGML sobrevive apenas como nome da biblioteca de tensores subjacente; se você encontrar um arquivo de modelo com extensão .ggml ou .bin de 2023, ele não será carregado por nenhuma ferramenta atual, devendo-se baixar, em vez disso, uma versão no formato GGUF.

Como interpretar os sufixos de quantização

Todo nome de arquivo GGUF inclui um sufixo como Q4_K_M que descreve o grau de compressão aplicado aos pesos. O padrão é o seguinte:

• O número após Q indica aproximadamente os bits por peso: Q4 ≈ 4 bits, Q8 ≈ 8 bits. Menos bits significam um arquivo menor e qualidade reduzida.
• _K indica os métodos mais recentes de "k-quant", que alocam bits adicionais para os tensores mais relevantes à qualidade da saída. Para o mesmo tamanho de arquivo, uma quantização K supera o estilo anterior.
• _S / _M / _L (pequeno/médio/grande) são variantes dentro de uma mesma família K — _M mantém alguns tensores mais sensíveis com maior precisão do que _S.
• _0 (como em Q8_0, Q4_0) indica a antiga e mais simples quantização por blocos. Q8_0 ainda é amplamente utilizada porque, com 8 bits, o método simples já é praticamente sem perdas; Q4_0 está quase obsoleto — prefira os prefixos Q4_K_M.
• IQ (comoIQ2_M, IQ3_XS…), que são "i-quants" construídos com uma matriz de importância, usados para comprimir modelos abaixo de 4 bits com menos degradação do que as alternativas.
• F16 / BF16 / F32 indicam pesos não quantizados de 16 ou 32 bits — a qualidade de referência, com o maior tamanho possível.

A seguir, apresentamos os custos práticos das opções mais comuns, usando modelos instrucionais da classe Llama de 8B como exemplo (os tamanhos são aproximados e variam ligeiramente conforme o modelo):

Duas regras úteis: a quantização prejudica mais modelos pequenos do que grandes (um modelo de 70B em Q3 se mantém muito melhor do que um de 8B em Q3), e abaixo do Q4 a curva de qualidade cai acentuadamente. Em caso de dúvida, Q4_K_M é o padrão da comunidade por um bom motivo.

Escolhendo uma quantização adequada à sua VRAM

A memória total necessária é aproximadamente tamanho do arquivo + cache de contexto + sobrecarga. Reserve 1–2 GB além do tamanho do arquivo para alguns milhares de tokens de contexto; reserve ainda mais se você usar contextos longos. O modelo executa na maior velocidade possível quando todo esse conjunto cabe na VRAM da GPU; ferramentas baseadas em llama.cpp podem descarregar as camadas restantes para a RAM do sistema, o que ainda funciona, mas fica muito mais lento à medida que mais camadas são descarregadas.

Para números exatos sobre um modelo específico e comprimento de contexto, a Calculadora de VRAM faz os cálculos automaticamente, e há uma análise detalhada por modelo em Requisitos de VRAM para todos os principais modelos de linguagem (LLM). Se você está escolhendo hardware em vez de uma quantização, comece com as melhores GPUs para LLMs locais.

GGUF versus safetensors

Esses dois formatos coexistem porque atendem a ambientes de execução diferentes, não porque um esteja superando o outro.

A decisão realmente envolve qual software você usa: ferramentas desktop e Ollama exigem GGUF; pilhas de atendimento em GPU e qualquer tarefa envolvendo ajuste fino exigem safetensors. Os publicadores de modelos normalmente lançam primeiro os safetensors, e a comunidade converte para GGUF em poucos dias.

De onde vêm os arquivos GGUF

Quase todos os arquivos GGUF estão hospedados no Hugging Face. Laboratórios ocasionalmente publicam oficialmente versões GGUF, mas a maioria vem de quantizadores da comunidade — contas como bartowski, unsloth, lmstudio-community e ggml-org — que convertem cada novo lançamento para toda a gama de níveis de quantização. Um repositório chamado algo como Meta-Llama-3.1-8B-Instruct-GGUF conterá um arquivo para cada nível de quantização.

Você também pode converter um modelo pessoalmente usando as ferramentas do llama.cpp: convert_hf_to_gguf.py converte um modelo do Hugging Face para um GGUF em F16, e o binário llama-quantize (compilado ao construir o llama.cpp) comprime-o para a quantização escolhida, por exemplo. modelo llama-quantize model-f16.gguf model-Q4_K_M.gguf Q4_K_M.

Carregando um GGUF no Ollama

O Ollama pode baixar diretamente repositórios GGUF do Hugging Face, especificando a quantização após os dois-pontos:

ollama run hf.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF:Q4_K_M

Para um arquivo que você já possui em disco, crie um arquivo de texto simples chamado Modelfile contendo:

FROM ./my-model.gguf

em seguida, registre-o e execute-o:

ollama create my-model -f Modelfile
ollama run my-model

As versões atuais do Ollama leem automaticamente o modelo de conversação (chat template) embutido nos metadados do GGUF; se um modelo importado gerar saída ilegível, a correção geralmente consiste em adicionar explicitamente uma linha TEMPLATE ao Modelfile. O guia completo do Ollama aborda os Modelfiles em profundidade.

Carregando um GGUF no LM Studio

O caminho habitual é o downloader integrado: abra a guia Descobrir (Discover), pesquise um modelo e o LM Studio listará as quantizações GGUF disponíveis, indicando quais delas são compatíveis com seu hardware. Para importar um arquivo que você já possui, use a interface de linha de comando (CLI) (lms import path/to/model.gguf) ou coloque-o no diretório de modelos do LM Studio — o caminho padrão exato varia conforme a versão e o sistema operacional, mas a guia Meus Modelos (My Models) mostra-o e permite alterá-lo. Os arquivos devem estar organizados em uma estrutura de subpastas no formato editor/nome-do-modelo/ para serem reconhecidos. Consulte o guia completo do LM Studio para o passo a passo completo.

Perguntas frequentes

O GGUF é exclusivamente para CPU ou também utiliza a GPU?

Ambas as opções são possíveis. O llama.cpp nasceu como um projeto de inferência para CPU, mas transfere camadas do modelo para a GPU (CUDA, Metal, Vulkan, ROCm) e pode executar totalmente na GPU quando o modelo cabe inteiramente na VRAM. O Ollama e o LM Studio gerenciam automaticamente a divisão entre CPU e GPU; ao usar diretamente o llama.cpp, você controla essa divisão com a flag -ngl (número de camadas na GPU).

Qual é a diferença entre Q4_K_M e Q4_K_S?

Ambas são quantizações k-quants de aproximadamente 4 bits; a letra indica a variante de tamanho. _M (médio) preserva mais tensores sensíveis à qualidade em precisão superior comparado ao _S (pequeno), sendo portanto ligeiramente maior e ligeiramente melhor. A diferença é pequena — escolha _M a menos que os últimos poucos centenas de megabytes sejam decisivos para saber se o modelo cabe na memória disponível.

Quanta qualidade eu realmente perco com a quantização?

Nas quantizações Q8_0 e Q6_K, praticamente nenhuma — testes cegos têm dificuldade em distingui-las da representação F16. A Q4_K_M apresenta uma pequena perda mensurável, que a maioria dos usuários nunca percebe em conversas, embora possa fazer diferença em tarefas precisas, como geração de código ou cálculos matemáticos. Abaixo da Q4, a degradação torna-se evidente, e modelos menores sofrem mais do que modelos maiores.

Posso usar GGUF com transformers ou vLLM?

Há suporte, mas ele é limitado e não representa o caminho nativo — o transformers pode desquantizar alguns arquivos GGUF durante o carregamento, e o vLLM possui suporte experimental para GGUF, cuja disponibilidade varia conforme a arquitetura. Se você está desenvolvendo sobre essas pilhas, utilize safetensors; o GGUF deve ser considerado, preferencialmente, o formato destinado às implementações da família llama.cpp.

Por que meu modelo está dividido em vários arquivos .gguf?

Modelos muito grandes são fragmentados em partes nomeadas, por exemplo, model-00001-of-00002.gguf— principalmente para respeitar os limites de tamanho de arquivo em plataformas de hospedagem. Mantenha todas as partes na mesma pasta e aponte seu ambiente de execução para o primeiro arquivo; o llama.cpp e as ferramentas construídas sobre ele carregam automaticamente as demais.

Uma vez que você sabe qual quantização é compatível com seu hardware, a próxima pergunta prática é qual modelo utilizar nela — a banco de dados de modelos lista detalhada contém especificações, requisitos de VRAM e preços para 37 modelos atuais, e os melhores modelos locais para Ollama é uma boa lista inicial para começar.