BroadRouter
Começar

GGUF (formato de modelo do llama.cpp)

Atualizado em

GGUF é um formato de arquivo binário para armazenar modelos de linguagem para inferência com runtimes baseados em GGML, como o llama.cpp. Um único arquivo GGUF guarda os pesos, muitas vezes quantizados, e os metadados necessários para carregar o modelo, incluindo detalhes do tokenizer e da arquitetura, e pode ser mapeado em memória para carregar rápido.

Também chamado de: arquivo GGUF, formato GGUF, modelo GGUF, formato do llama.cpp, GGUF file, GGUF format, llama.cpp format

Se você já baixou um modelo para rodar no notebook, provavelmente era um arquivo terminado em .gguf.

Como funciona

A especificação do ggml descreve o GGUF como um formato binário para armazenar modelos para inferência com o GGML e executores baseados nele, pensado para carregar e salvar rápido. Ele substituiu os formatos antigos GGML, GGMF e GGJT. Entre os objetivos declarados estão:

  • Arquivo único. Um modelo pode ser compartilhado e carregado sem arquivos extras.
  • Compatível com mmap. O runtime pode mapear os pesos em memória em vez de copiá-los.
  • Extensível. Novos metadados podem ser adicionados sem quebrar modelos antigos.
  • Informação completa. Tudo o que é preciso para carregar o modelo está no arquivo.

Um arquivo GGUF tem um cabeçalho (um magic number, a versão do formato, a contagem de tensores e de metadados), pares chave-valor de metadados tipados, uma tabela com nomes, formas, tipos e offsets dos tensores, um preenchimento até um limite de alinhamento (32 bytes por padrão) e, por fim, os dados dos tensores.

Os nomes de arquivo seguem uma convenção. O exemplo da especificação, Mixtral-8x7B-v0.1-KQ2.gguf, se divide em nome base, rótulo de tamanho (oito especialistas de 7B, veja mixture of experts), versão e codificação.

A maioria dos arquivos GGUF é quantizada. A tabela do Hugging Face lista os tipos mais comuns:

Tipo Bits por peso Observações
Q8_0 8 Arredondamento ao mais próximo (legado), blocos de 32 pesos
Q6_K 6,5625 Super-blocos k-quant
Q5_K 5,5 Super-blocos k-quant
Q4_K 4,5 Super-blocos k-quant
IQ4_XS 4,25 Usa uma matriz de importância
Q2_K 2,625 Super-blocos k-quant

Por que isso importa

  • Uso local e na borda. O Hugging Face lista llama.cpp, LM Studio, GPT4All e Ollama entre as ferramentas que usam GGUF. É o caminho comum para rodar um modelo open-weight em uma CPU, um Mac ou uma única GPU de consumo.
  • O tokenizer vai junto com os pesos. Como os metadados ficam no arquivo, um chat template ou uma configuração de tokenizer errados ou ausentes numa conversão podem mudar a qualidade da saída.
  • A qualidade depende do tipo de quantização. Um arquivo Q2 e um Q8 do mesmo modelo, na prática, não são o mesmo modelo. Compare iguais com iguais.
  • Diferente dos formatos de serving em GPU. Engines de servidor como o vLLM incluem o GGUF entre os formatos suportados, mas o serving em GPU em produção usa mais formatos como AWQ ou FP8.

Na BroadNet Inference

A API da BroadNet serve modelos via HTTP; ela não distribui arquivos GGUF, e você nunca carrega pesos. O catálogo da BroadNet informa que, em laboratório, ela rodou o Qwen3.8 27B como GGUF Q4_K_M com um projetor de visão e um drafter de multi-token prediction no llama.cpp, ao lado de uma build AWQ INT4 no vLLM para AMD ROCm. Ele não diz qual formato serve a API pública. Se você está comparando um setup GGUF local com uma API, o guia de custo de self-hosting vs. API e modelos open-weight vs. fechados cobrem os trade-offs.

Perguntas frequentes

O que significa um nome como Q4_K?

É o tipo de quantização. A tabela do Hugging Face descreve o Q4_K como quantização de 4 bits em super-blocos de 8 blocos de 32 pesos, cerca de 4,5 bits por peso. Menos bits usam menos memória e normalmente custam mais qualidade.

Posso chamar um modelo GGUF pelo formato da API da OpenAI?

O arquivo em si, não. Você o carrega em um runtime como o servidor do llama.cpp, o Ollama ou o LM Studio, e é esse runtime que o serve. Confira na documentação do runtime qual API ele expõe.

GGUF é a mesma coisa que safetensors?

Não. O Hugging Face descreve o safetensors como um formato só de tensores, enquanto o GGUF codifica em um único arquivo tanto os tensores quanto um conjunto padronizado de metadados.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity