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.