O que é o formato de ficheiro GGUF?
Um arquivo .gguf é um GGML Universal Format File, o contêiner binário usado pelo llama.cpp para armazenar um modelo de linguagem grande. Georgi Gerganov e a comunidade ggml o introduziram em agosto de 2023 como o sucessor dos formatos mais antigos GGML, GGMF e GGJT. Um único arquivo .gguf contém os pesos do modelo, o tokenizador e cada hiperparâmetro como metadados de chave-valor tipados, portanto, não são necessários arquivos de configuração separados para carregar e executar o modelo.
O formato foi construído para ser autossuficiente, extensível e mapeável em memória. Como os metadados são armazenados como pares chave-valor com namespaces em vez de uma lista fixa, novos campos podem ser adicionados sem quebrar leitores mais antigos. Os pesos são geralmente quantizados, de 2-bit até 8-bit e incluindo K-quants como Q4_K_M, o que permite que modelos de tamanho considerável rodem em CPUs e GPUs de consumo. Cada arquivo começa com a string mágica de quatro bytes GGUF, seguida por um número de versão; a versão atual é a 3.
Segurança e proteção
RISCO: LOWGGUF is a data container for model weights and metadata, not an executable, so opening one does not run code by itself. The main practical risks are large file sizes and downloading models from untrusted sources; a malformed file could in theory exploit a bug in the loader, so use up-to-date inference tools and reputable model repositories.
Detalhes do formato
em resumoNOME COMPLETOGGML Universal Format Filetambém conhecido como GGML Universal File, GGUF model
DESENVOLVEDORGeorgi Gerganov and the ggml/llama.cpp communitydesde August 2023
CATEGORIAArquivos de Dados
TIPO MIMEapplication/octet-stream
TIPOBinary
PADRÃOAberto · livre de royalties
Esta extensão também é usada por…
- Genome Graphical User Format - Rarely, .gguf has been used ad hoc by hobby projects for GUI layout data, unrelated to the machine-learning format described here.
MAGIC BYTES · ASSINATURA DO ARQUIVO
OFFSET
00010203
HEX
47475546
ASCII
GGUF
First 4 bytes are the ASCII string GGUF (0x47 0x47 0x55 0x46), followed by a 4-byte version, 8-byte tensor count and 8-byte metadata count.
Programas que abrem arquivos GGUF
Windows6 apps
LM Studio
Freemium Browse, download and chat with .gguf models through a desktop GUI, with per-model quantization choices.
Ollama
Código aberto Load a local .gguf file via a Modelfile and serve it for chat or API use with one command.
llama.cpp
Código aberto Run inference directly on a .gguf model with llama-cli or llama-server, the reference implementation of the format.
GPT4All
Código aberto Add a downloaded .gguf model to the local model folder and chat with it offline.
koboldcpp
Código aberto Load a .gguf model for text generation and roleplay with a self-contained executable. 
macOS4 apps
LM Studio
Freemium Download and run .gguf models with Apple Silicon acceleration through a desktop GUI.
Ollama
Código aberto Serve a local .gguf model via a Modelfile using Metal acceleration on Apple hardware.
llama.cpp
Código aberto Run .gguf models with llama-cli, built with Metal support for Apple Silicon. 
Linux4 apps
llama.cpp
Código aberto Build from source and run .gguf models with CUDA, ROCm or CPU backends via llama-cli and llama-server.
text-generation-webui
Código aberto Load .gguf models through the llama.cpp loader in a browser-based interface.
Web1 app
Hugging Face GGUF viewer
Gratuito Inspect a .gguf file's metadata, tensor list and quantization in the browser without downloading it. Detalhes técnicos
especificação profunda| Encoding | Binary |
| Byte order | Little-endian by default; big-endian supported since version 3 |
| Container | Single-file container holding header, metadata key-value block, tensor info block and raw tensor data |
| Compression | None as a container; weights are stored using GGUF quantization schemes (Q2 through Q8, K-quants such as Q4_K_M, IQ variants, plus F16/BF16/F32) |
| Typical size | Roughly 0.5 GB to over 100 GB depending on parameter count and quantization level |
| Structure | Header (magic, version, tensor count, metadata count) then namespaced key-value metadata, then per-tensor info (name, dimensions, type, offset), then aligned raw tensor data. Default alignment is 32 bytes and must be a multiple of 8. |
| Integrity | No built-in checksum; the metadata block is self-describing and validated at load time |
| Platforms | Windows, macOS, Linux |
| Notes | A GGUF file is self-contained: it bundles the model weights, tokenizer and all hyperparameters as typed metadata, so no separate config files are needed. Metadata keys use lower_snake_case with period-separated namespaces and keys can be up to 65,535 bytes. Over 40 quantization types are supported. Large models can be sharded across multiple .gguf files with llama-gguf-split. |
| Lançado | August 2023 |
| Versão mais recente | Version 3 |
| Padrão aberto | Sim · livre de royalties |
| Especificação | github.com |
Conversões de GGUF
Possível
.GGUF .SAFETENSORSGUIA
Sim - você pode dequantizar um GGUF em uma pasta de fragmentos .safetensors, mas uma fonte quantizada nunca…
Como converter
.GGUF .ONNXGUIA
Sim - mas apenas indiretamente: você desquantiza o GGUF de volta para pesos PyTorch/safetensors de precisão…
Como converter
.GGUF .PTHGUIA
Sim - você pode desquantizar um GGUF de volta para um dicionário de estados PyTorch .pth/.bin, mas apenas…
Como converter
Perguntas e Respostas da Comunidade
perguntado por usuáriosAinda não há perguntas - seja o primeiro a perguntar sobre arquivos GGUF.
Perguntas frequentes
Como eu abro um arquivo GGUF?
Use um executor de LLM local como LM Studio, Ollama, Jan ou GPT4All, ou carregue-o diretamente com
llama.cpp. Essas ferramentas leem o arquivo .gguf e permitem que você converse com o modelo. Clicar duas vezes no arquivo não fará nada útil por si só.Qual programa cria arquivos GGUF?
Eles são produzidos pelos scripts de conversão do
llama.cpp, principalmente o convert_hf_to_gguf.py, que transforma um modelo do Hugging Face em um .gguf, opcionalmente seguido pelo llama-quantize para reduzi-lo a uma quantização menor, como Q4_K_M.O que significa o Q4_K_M em um nome de arquivo GGUF?
É o tipo de quantização. Q4 significa aproximadamente pesos de 4 bits, K refere-se ao método K-quant baseado em blocos e M é a variante de tamanho/qualidade média (medium). Números menores resultam em arquivos menores e menor qualidade; F16 ou F32 não são quantizados.
Posso converter um arquivo GGUF de volta para o modelo original?
Parcialmente. Você pode dequantizá-lo para pesos
.safetensors ou PyTorch com scripts da comunidade, mas como a maioria dos arquivos GGUF é quantizada, a conversão é «lossy» e não restaura os pesos originais exatos.Por que meu arquivo GGUF é tão grande?
Um
.gguf contém todos os pesos do modelo em um único arquivo. O tamanho do arquivo escala com o número de parâmetros e o nível de quantização, portanto, um modelo grande em alta precisão pode facilmente exceder dezenas de gigabytes.Arquivos GGUF são seguros para baixar?
O formato em si não contém código executável, por isso é mais seguro que formatos baseados em pickle. Ainda assim, baixe modelos apenas de fontes confiáveis e mantenha seu software de inferência atualizado para o caso de bugs no carregador.
Referências
1GGUF - Wikipediaen.wikipedia.org
2Official GGUF specification (ggml docs)github.com
