Formato GGUF: um guia completo para inferência local de LLM

O que é GGUF?

GGUF, sigla para GGML Unified Format, é um formato de arquivo binário que reúne pesos do modelo, dados do tokenizador, metadados da arquitetura e informações de quantização em um único arquivo portátil para inferência com runtimes baseados em GGML, especialmente o llama.cpp.

O GGUF resolve um problema de implantação de LLMs. Muitos formatos exigem manter vários arquivos juntos, incluindo pesos, arquivos do tokenizador, arquivos de configuração e código de carregamento específico da arquitetura. O GGUF simplifica isso, deixando o arquivo do modelo em grande parte autoexplicativo.

Um arquivo GGUF normalmente contém:

• Tensores do modelo
• Pesos quantizados ou não quantizados
• Vocabulário do tokenizador
• Configuração do tokenizador
• Metadados da arquitetura do modelo
• Configurações de comprimento de contexto
• Dimensões de embeddings
• Quantidade de cabeças de atenção
• Configuração de RoPE
• Nomes, formas e tipos de dados dos tensores

A ideia central é que o arquivo se descreve. O runtime pode inspecionar os metadados, entender a arquitetura, carregar o tokenizador e mapear os tensores sem depender de um config.json separado ou de uma pasta do tokenizador.

Isso não significa que todo arquivo GGUF seja universalmente compatível com qualquer runtime para sempre. O runtime ainda precisa suportar a arquitetura e os tipos de tensor usados no arquivo. Porém, o GGUF facilita muito essa compatibilidade em relação a formatos antigos, pois o arquivo carrega informações estruturadas mais ricas.

Quatro características que definem o GGUF são:

1. Implantação em arquivo único
2. Suporte a memory mapping para carregamento eficiente
3. Metadados extensíveis em pares chave-valor tipados
4. Suporte a vários tipos de quantização, de formatos agressivos de poucos bits até precisão total

O GGUF foi introduzido como parte do ecossistema do llama.cpp e GGML em 2023. Hoje é o formato dominante para distribuir LLMs quantizados locais no Hugging Face.

GGUF vs. GGML

O GGML (Georgi Gerganov Machine Learning) foi o predecessor do GGUF. Ele foi importante por possibilitar as primeiras inferências locais. No entanto, passou a ter limitações práticas à medida que o ecossistema se expandiu além dos modelos LLaMA originais.

Dores comuns do GGML incluíam:

• Tratamento de metadados menos flexível
• Mais suposições de carregamento específicas da arquitetura
• Manuseio de tokenizador e configuração menos autônomo
• Dificuldade de extensibilidade com o surgimento de novas famílias de modelos

O GGUF resolveu essas limitações com um formato mais estruturado. Ele introduziu metadados tipados, melhor embedding do tokenizador e um layout de arquivo mais claro. Isso facilitou o suporte a mais arquiteturas no llama.cpp e em ferramentas relacionadas, sem redesenhar constantemente o pipeline de carregamento.

Para o usuário, a diferença principal é simples: o GGUF é o formato moderno. Se você está baixando modelos hoje, quase sempre deve escolher GGUF em vez dos arquivos GGML antigos.

GGUF vs. GPTQ e AWQ

Ao pesquisar formatos de arquivo, você deve ter visto GGUF, GPTQ (Generative Post-Training Quantization) e AWQ (Activation-Aware Weight Quantization). Eles são frequentemente discutidos juntos porque os três visam tornar a inferência de LLM mais eficiente. Porém, não pertencem à mesma categoria.

GGUF é principalmente um formato de arquivo e um contêiner de implantação. Ele suporta muitos tipos de quantização e está intimamente associado à inferência local no estilo llama.cpp.

GPTQ e AWQ são métodos de quantização e ecossistemas comumente usados para inferência otimizada em GPU, especialmente em hardware NVIDIA por meio de frameworks como Transformers, ExLlama, AutoGPTQ e fluxos compatíveis com vLLM.

Se a sua meta é máxima compatibilidade entre laptops, desktops, Apple Silicon e hardware misto, o GGUF costuma ser a escolha mais segura.

Se o objetivo é máximo throughput em servidores de inferência NVIDIA dedicados, GPTQ, AWQ, FP8 ou outros formatos otimizados para GPU podem ser mais adequados.

Por que usar GGUF?

O GGUF ficou popular por resolver problemas práticos de implantação. Eu também passei a achar bem conveniente para implantar localmente sem aquela bagunça de configuração.

Rodar LLMs localmente costumava envolver ferramentas fragmentadas, pesos grandes e sem compressão, formatos de modelo incompatíveis e etapas de setup complicadas. O GGUF agora ajuda a padronizar boa parte desse fluxo.

Em vez de pensar em vários arquivos e scripts de carregamento, o usuário pode focar em escolher o modelo certo, definir o nível de quantização e rodar a inferência.

Rode modelos localmente

O GGUF permite rodar LLMs na sua própria máquina. Isso significa:

• Sem custo por token de API
• Sem dependência de um provedor de inferência hospedado
• Sem necessidade de enviar prompts para uma API de terceiros
• Inferência offline é possível após o download do modelo

Isso é especialmente útil para fluxos sensíveis à privacidade. Desenvolvedores podem não querer enviar código proprietário, documentos internos, registros de clientes ou prompts confidenciais para uma API externa.

Inferência local não é automaticamente segura por si só. Você ainda precisa gerenciar bem sua máquina, logs, aplicativos e controle de acesso. Mas o GGUF torna a implantação local privada muito mais acessível.

Para praticar rodando modelos localmente, veja nossos tutoriais sobre servir o Mistral Medium 3.5 com SGLang, rodar o DeepSeek V4 Flash localmente, rodar o modelo eficiente Bonsai 1-bit em um laptop antigo e rodar o MiniMax M2 localmente como assistente de código.

Flexibilidade de hardware

O GGUF é útil porque funciona em muitas configurações de hardware.

Dependendo do runtime e do backend, modelos GGUF podem rodar em:

• Máquinas só com CPU
• GPUs NVIDIA via CUDA
• Apple Silicon via Metal
• GPUs AMD via HIP ou Vulkan
• GPUs Intel via SYCL ou Vulkan
• Alguns ambientes ARM e mobile

Essa flexibilidade é um dos motivos de o llama.cpp ter se tornado influente. Ele não foi projetado apenas para GPUs de servidor de alto nível. Foi pensado para tornar a inferência local possível em uma ampla gama de hardwares.

Por exemplo, um usuário de Mac pode contar com aceleração via Metal, enquanto um usuário de desktop Linux pode usar CUDA ou Vulkan. Um usuário apenas com CPU ainda pode rodar modelos menores quantizados, embora a geração seja mais lenta.

Amplo suporte no ecossistema

O GGUF é suportado por várias ferramentas de inferência local. Exemplos incluem:

• llama.cpp para linha de comando e inferência em servidor
• Ollama para gestão de modelos via CLI e acesso por API
• LM Studio para uma interface gráfica desktop
• GPT4All para chat local com foco em privacidade
• KoboldCpp para roleplay local e fluxos de geração de texto
• Jan e Open WebUI como interfaces locais de IA

Isso importa porque o usuário não fica preso a uma única interface. O mesmo formato geral de modelo pode ser usado em diferentes fluxos.

Um desenvolvedor pode fazer benchmark de um modelo no llama.cpp, conversar com ele no LM Studio, servi-lo via Ollama e conectá-lo a uma interface de navegador via Open WebUI.

Distribuição no Hugging Face

O Hugging Face se tornou um grande hub de distribuição de modelos GGUF.

Fonte: Hugging Face

Muitos modelos populares de pesos abertos recebem variantes GGUF carregadas pela comunidade pouco depois do lançamento. Esses repositórios costumam incluir várias opções de quantização para o usuário escolher a que melhor se adapta ao seu hardware.

As variantes mais comuns incluem:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0
• IQ4_XS
• IQ3_M
• IQ2_XXS

Isso significa que, muitas vezes, a conversão manual é desnecessária. Para os modelos mais populares, alguém da comunidade já criou arquivos GGUF com níveis comuns de quantização.

Controle granular de tamanho vs. qualidade

O GGUF dá ao usuário controle fino sobre a troca entre tamanho e qualidade. Você pode escolher:

• Quantizações menores para máquinas com pouca memória
• Quantizações intermediárias para uso diário equilibrado
• Quantizações de mais bits para código, raciocínio ou saídas estruturadas
• Precisão total ou quase total quando memória não é um gargalo

Essa flexibilidade é uma das maiores vantagens do formato. Em vez de um alvo de implantação fixo, o GGUF permite adaptar a mesma família de modelos a vários patamares de hardware.

Como o GGUF funciona?

Um arquivo GGUF é organizado em três partes principais:

1. Cabeçalho
2. Metadados e informações de tensor
3. Dados dos tensores

A estrutura exata é definida pela especificação do GGUF. O ponto importante é que metadados e informações dos tensores aparecem antes dos dados brutos, permitindo que o runtime entenda o que vai carregar.

O cabeçalho

O cabeçalho identifica o arquivo como GGUF e informa ao runtime como analisar o restante. Ele inclui:

• Número mágico do GGUF
• Versão do formato
• Quantidade de tensores
• Quantidade de pares chave-valor de metadados

Arquivos GGUF modernos geralmente usam a versão 3.

Engines de inferência checam primeiro o número mágico. Se o arquivo não começar com o identificador esperado do GGUF, o runtime pode rejeitá-lo antes de tentar analisar tensores ou alocar memória.

É um passo simples, mas importante, de segurança e confiabilidade. Evita que um runtime trate acidentalmente um binário não relacionado como modelo.

Pares chave-valor de metadados

Os metadados do GGUF são um armazenamento tipado de pares chave-valor. Eles podem descrever:

• Informações gerais do modelo
• Família de arquitetura
• Comprimento de contexto
• Tamanho do embedding
• Número de camadas
• Número de cabeças de atenção
• Parâmetros de RoPE
• Vocabulário do tokenizador
• Tokens especiais
• Informações de quantização

As chaves normalmente são namespaced. Exemplos:

• general.architecture
• general.alignment
• llama.context_length
• tokenizer.ggml.tokens

O namespace é importante porque permite ao GGUF suportar muitas arquiteturas sem mudar o formato inteiro. Um modelo da família LLaMA pode usar chaves llama.*, enquanto outras famílias usam metadados específicos da sua arquitetura.

Esse é um dos motivos de o GGUF ter se adaptado bem a modelos além da família LLaMA original, incluindo arquiteturas como Qwen, Mistral, Gemma, DeepSeek, Phi, entre outras.

Informações e dados dos tensores

Após os metadados, o arquivo armazena as informações e os dados dos tensores.

As informações descrevem:

• Nome do tensor
• Forma
• Tipo de dado
• Offset dentro da seção de dados dos tensores

A seção de dados contém de fato os pesos do modelo. Esses pesos podem estar em precisão total ou em um dos tipos de tensores quantizados suportados pelo GGUF.

O GGUF usa um valor de alinhamento definido nos metadados, comumente general.alignment. Muitos arquivos GGUF usam alinhamento de 32 bytes, mas o correto é dizer que o alinhamento é controlado por metadados, e não fixo no formato.

O alinhamento importa porque permite que os runtimes acessem blocos de tensores de forma eficiente.

Memory mapping

Uma das vantagens práticas do GGUF é o memory mapping, frequentemente chamado de mmap.

Com memory mapping, o sistema operacional pode mapear o arquivo do modelo na memória virtual, em vez de obrigar o runtime a copiar o arquivo inteiro para a RAM de uma vez.

Isso pode deixar a inicialização do modelo bem mais rápida, especialmente em SSDs. Também permite ao sistema operacional paginar os dados do modelo conforme necessário.

No entanto, memory mapping não faz milagre. O modelo ainda precisa de largura de banda de memória e de RAM/VRAM suficientes para rodar bem. Se o sistema estiver paginando do disco o tempo todo, a inferência pode ficar lenta.

Uma forma melhor de pensar no mmap é:

• Melhora a eficiência de carregamento
• Reduz cópias desnecessárias
• Deixa o SO gerenciar a paginação
• Não elimina os requisitos de memória da inferência

Entendendo os tipos de quantização do GGUF

Quantização comprime os pesos do modelo em representações de menor precisão.

Em vez de armazenar cada peso como um valor de ponto flutuante de 16 bits, um modelo quantizado guarda valores aproximados usando menos bits. Isso reduz o tamanho em disco, o uso de RAM e VRAM e a pressão sobre a largura de banda de memória.

O insight principal é que muitos pesos de redes neurais não precisam de precisão total em ponto flutuante durante a inferência. Um modelo cuidadosamente quantizado pode preservar boa parte do comportamento original, ficando dramaticamente menor.

Nomenclatura de quantização no GGUF

Os nomes de quantização do GGUF normalmente seguem este padrão:

• Q significa quantizado
• O número sugere os bits aproximados por peso
• K se refere à família k-quant
• S, M e L geralmente indicam variantes small, medium e large

Exemplos incluem:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0

O nome é um bom guia, mas não define exatamente o tamanho total do arquivo. O tamanho real depende da mistura de tensores, da arquitetura, dos metadados, do tamanho do tokenizador e de haver tensores em maior precisão.

Tipos comuns de quantização em GGUF

Esses números são aproximações para modelos densos de classe 7B. Arquiteturas mais novas, modelos de mixture-of-experts, tokenizadores maiores e diferentes layouts de tensor podem alterar o tamanho real.

Na prática, o Q4_K_M virou o padrão popular por oferecer um ótimo equilíbrio entre tamanho e qualidade. Muitos usuários acham suficiente para chat geral, sumarização, reescrita e exploração de IA local.

Q5_K_M e Q6_K costumam ser escolhas melhores para workloads mais exigentes, como programação ou instruções em múltiplas etapas

O motivo é simples: essas tarefas são mais sensíveis a pequenas degradações de qualidade.

K-quants vs. I-quants

K-quants são a família de quantização amplamente usada por trás de formatos como Q4_K_M, Q5_K_M e Q6_K.

Eles usam esquemas de quantização em grupo, com informações de escala que ajudam a preservar o comportamento do modelo reduzindo os requisitos de memória. São populares por serem confiáveis, amplamente suportados e fáceis de encontrar em releases GGUF da comunidade.

I-quants, frequentemente escritos como formatos IQ, são tipos mais novos de quantização, como:

• IQ4_XS
• IQ3_M
• IQ2_XXS
• IQ1_S

Os I-quants são projetados para alcançar melhor qualidade em tamanhos muito pequenos. Eles podem usar técnicas como quantização sensível à importância e codebooks de quantização não lineares. Alguns fluxos usam uma matriz de importância (imatrix) para preservar pesos mais importantes durante a quantização.

A troca aqui é a complexidade. I-quants podem gerar excelentes resultados de tamanho vs. qualidade, especialmente em taxas de bits muito baixas, mas podem exigir fluxos de quantização e suporte em runtime mais cuidadosos.

Para a maioria dos iniciantes, K-quants continuam sendo o ponto de partida mais simples.

Escolhendo o nível de quantização para seu hardware

A tabela a seguir traz pontos de partida práticos. Trate como regras de bolso, não garantias rígidas. Comprimento de contexto, overhead do sistema operacional, offload para GPU, tamanho do cache KV e a arquitetura específica do modelo podem mudar os requisitos de memória.

Regras gerais:

• Use Q4_K_M como padrão seguro para a maioria das inferências locais.
• Use Q5_K_M quando a qualidade importar mais do que economizar cada gigabyte.
• Use Q6_K ou Q8_0 quando houver memória disponível e você quiser mais fidelidade.
• Evite Q2_K para trabalho sério, a menos que esteja testando cenários extremamente limitados em memória.
• Reserve memória extra para o cache KV, especialmente com janelas de contexto longas.

O cache KV é fácil de ignorar. Um modelo pode caber na RAM com contexto curto, mas falhar ou ficar lento com contexto muito longo, pois o cache cresce com o comprimento da sequência.

O ecossistema GGUF

A adoção do GGUF é impulsionada tanto pelas ferramentas quanto pelo formato em si.

Um formato só se torna útil quando os usuários conseguem baixar, rodar, inspecionar, converter e servir modelos com facilidade. O GGUF se beneficia de um ecossistema forte de ferramentas de linha de comando, apps desktop, APIs e repositórios hospedados.

1. llama.cpp

O llama.cpp é o runtime GGUF original e mais importante. É um engine de inferência em C/C++ criado por Georgi Gerganov e mantido pela comunidade GGML. Seu objetivo principal é viabilizar inferência eficiente de LLM com setup mínimo em várias plataformas de hardware.

O llama.cpp moderno suporta vários backends, incluindo:

• CPU
• CUDA para GPUs NVIDIA
• Metal para dispositivos Apple
• Vulkan
• HIP para GPUs AMD via ROCm
• SYCL para GPUs Intel
• OpenCL em ambientes selecionados
• Outros backends especializados como CANN, OpenVINO e WebGPU, conforme suporte da plataforma

Ele também inclui ferramentas de conversão, quantização, serving, benchmark e inferência via linha de comando. Ferramentas comuns incluem:

• convert_hf_to_gguf.py
• llama-quantize
• llama-cli
• llama-server
• llama-bench

Os comandos para criar um build básico de CPU com CMake são:

cmake -B build
cmake --build build --config Release

Para algumas configurações, certas flags precisam ser adicionadas ao primeiro desses comandos:

• Desativar Apple Metal no macOS (ativado por padrão): -DGGML_METAL=OFF
• Build com Vulkan: -DGGML_VULKAN=1
• Build com CUDA para GPUs NVIDIA: -DGGML_CUDA=ON

Observe que os builds atuais usam opções CMake GGML_*, como GGML_CUDA, GGML_VULKAN e GGML_HIP.

2. Ollama

Ollama é uma das formas mais fáceis de rodar modelos locais. Ele oferece:

• Uma CLI simples
• Gerenciamento e download de modelos
• Uma API REST local
• Bibliotecas oficiais em Python e JavaScript
• Integração com muitas interfaces locais de IA

O Ollama armazena e gerencia os modelos para você, então o usuário geralmente não interage diretamente com arquivos .gguf. Porém, o Ollama é construído em torno da inferência local compatível com o llama.cpp e também pode importar arquivos GGUF via um workflow de Modelfile.

O Ollama expõe uma API local em:

http://localhost:11434/api

Dois endpoints muito usados são:

• /api/generate para completion de prompt
• /api/chat para mensagens em estilo chat

Para iniciantes, o Ollama costuma ser o caminho mais rápido do zero à inferência local.

3. LM Studio

Fonte: LM Studio

O LM Studio é um aplicativo desktop para descobrir, baixar e conversar com modelos locais. É útil para quem prefere uma interface gráfica em vez da linha de comando.

4. GPT4All

Fonte: GPT4All

O GPT4All é outro aplicativo de IA local multiplataforma, focado em fluxos de chatbot privados e locais. Ele suporta modelos GGUF e oferece um ambiente amigável para iniciantes em inferência local.

Essas ferramentas tornam o GGUF acessível para não especialistas. Não é preciso entender CMake, layouts de tensor ou os bastidores da quantização para experimentar um modelo local.

Como começar com modelos GGUF

Há duas formas práticas de começar:

1. Usar o Ollama para a experiência mais simples.
2. Usar o llama.cpp diretamente para ter mais controle.

Rodando um modelo com o Ollama

O fluxo mais simples é baixar o modelo e iniciar uma sessão de chat interativa:

ollama pull llama3.3
ollama run llama3.3

Para chamar o modelo em Python usando a API REST:

import requests

payload = {
    "model": "llama3.3",
    "prompt": "Give me three practical use cases for GGUF.",
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/generate",
    json=payload
)

print(response.json()["response"])

Para aplicações em estilo chat, use /api/chat:

import requests

payload = {
    "model": "llama3.3",
    "messages": [
        {"role": "user", "content": "What is GGUF used for?"}
    ],
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/chat",
    json=payload
)

print(response.json()["message"]["content"])

O campo stream: false é importante para scripts simples. Sem ele, o Ollama retorna um stream de objetos JSON em vez de uma resposta JSON final.

Você também pode usar a biblioteca oficial do Ollama em Python:

from ollama import chat

response = chat(
    model="llama3.3",
    messages=[
        {"role": "user", "content": "Explain GGUF quantization simply."}
    ]
)

print(response.message.content)

Rodando um arquivo GGUF com o llama.cpp

Se você já tem um arquivo .gguf, pode rodá-lo diretamente com o llama.cpp após compilar o projeto.

Exemplo:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Explain the difference between GGUF and GPTQ." \
  -n 256

Se você habilitou suporte a GPU, pode fazer offload de camadas para a GPU:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Summarize GGUF in five bullet points." \
  -n 256 \
  -ngl 99

A flag -ngl controla quantas camadas são descarregadas na GPU. Um valor alto como 99 é comum para descarregar o máximo possível, supondo que o modelo caiba na VRAM.

Para servir via API, use o llama-server:

./build/bin/llama-server \
  -m models/model.Q4_K_M.gguf \
  -ngl 99 \
  --host 127.0.0.1 \
  --port 8080

Isso fornece uma interface de servidor local para integrar o llama.cpp em aplicações.

Convertendo um modelo do Hugging Face para GGUF

A maioria dos usuários não precisa converter modelos manualmente, pois releases GGUF da comunidade são amplamente disponíveis.

No entanto, a conversão manual é útil quando:

• Você fez fine-tuning do seu próprio modelo
• Ainda não existe versão GGUF
• Você quer controlar o processo de quantização
• Você precisa de um tipo específico de quantização

Um fluxo típico é:

1. Baixar um modelo do Hugging Face.
2. Convertê-lo para GGUF.
3. Quantizar o arquivo GGUF.

Exemplo:

huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3 \
  --local-dir mistral-7b

Depois, converta para GGUF:

python convert_hf_to_gguf.py mistral-7b \
  --outfile mistral-f16.gguf \
  --outtype f16

Depois, quantize:

./build/bin/llama-quantize \
  mistral-f16.gguf \
  mistral-q4_k_m.gguf \
  Q4_K_M

Nos fluxos atuais do llama.cpp, convert_hf_to_gguf.py e llama-quantize são as ferramentas relevantes. Tutoriais antigos podem mencionar scripts de conversão obsoletos ou nomes de binários antigos.

Vantagens e limitações do formato GGUF

O GGUF é otimizado para inferência local prática. Ele não substitui universalmente todo formato de modelo ou stack de serving.

Para inferência com foco em CPU, Apple Silicon, hardware misto e privacidade, o GGUF costuma ser uma excelente escolha.

Para implantação em servidores NVIDIA com alto throughput, outros formatos e engines podem ser mais rápidos, dependendo do modelo, tamanho de lote, método de quantização e framework de serving.

Considerações finais

O GGUF torna a inferência local de LLMs prática ao empacotar tudo o que o runtime precisa (pesos, tokenizador, metadados, info de quantização) em um único arquivo portátil. Sua força real é o ecossistema ao redor: llama.cpp, Ollama, LM Studio e Hugging Face fizeram dele o formato padrão para implantação de IA local.

Para a maioria dos usuários, o caminho é simples: instale o Ollama, faça o pull de um modelo e rode. Q4_K_M é um padrão sólido; suba para Q5_K_M ou Q6_K quando precisar de melhor raciocínio ou código e tiver memória de sobra.

Se você quer se aprofundar em implantação de LLMs, otimização de modelos e fluxos de inferência local, vale explorar a trilha de carreira Associate AI Engineer for Data Scientists ou Associate AI Engineer for Developers.