GGUF (GGML Universal File) é um formato de arquivo binário projetado para armazenar tanto tensores quanto metadados em um único arquivo, permitindo salvar e carregar dados de modelo rapidamente. Introduzido em agosto de 2023 pelo projeto llama.cpp, foi criado para melhorar a compatibilidade retroativa à medida que o suporte para arquiteturas de modelo adicionais era adicionado. O GGUF substituiu formatos anteriores usados pelo projeto, como o GGML, e é tipicamente produzido convertendo modelos desenvolvidos com outras bibliotecas de aprendizado de máquina como o PyTorch. O formato tornou-se o padrão para distribuir grandes modelos de linguagem quantizados para inferência local, suportado nativamente por ferramentas como llama.cpp, Ollama, LM Studio, GPT4All, Jan e koboldcpp. Em 2026, dezenas de milhares de checkpoints GGUF estão hospedados no Hugging Face, que oferece integração de primeira classe, incluindo um visualizador de metadados, um serviço de endpoint de inferência e uma biblioteca de análise em JavaScript.
História
Os formatos de arquivo de modelo usados pelo projeto llama.cpp evoluíram por quatro estágios nomeados: GGML, GGMF, GGJT e GGUF. O formato GGML original era um contêiner de tensor fino que codificava hiperparâmetros do modelo e informações do tokenizador dentro do carregador; adicionar suporte para uma nova arquitetura de modelo ou esquema de quantização tipicamente exigia mudanças de código que quebravam a compatibilidade com arquivos existentes.
À medida que o llama.cpp cresceu durante 2023 para suportar arquiteturas adicionais além do Llama - incluindo Mistral, Falcon e outras - essas limitações tornaram-se cada vez mais difíceis de gerenciar. O GGUF foi introduzido em 21 de agosto de 2023 como um sucessor incompatível com versões anteriores, com a especificação formalizada através do pull request #302 no repositório ggerganov/ggml. O formato herda o layout geral do GGJT, mas substitui sua lista plana de hiperparâmetros por um sistema de metadados estruturado de chave-valor, permitindo que novos campos - detalhes de arquitetura, vocabulários de tokenizador, parâmetros de treinamento - sejam adicionados sem modificar o carregador ou quebrar modelos mais antigos.
O formato em si passou por três versões internas. A versão 1 estabeleceu a estrutura básica; a versão 2 adicionou preenchimento de alinhamento explícito para suportar mapeamento de memória; e a versão 3, a versão atual, adicionou suporte opcional para big-endian.
Design
O GGUF foca em quantização, o ato de reduzir a precisão nos pesos do modelo. Isso pode levar a uma redução no uso de memória e aumento de velocidade, embora ao custo de reduzir a precisão do modelo. O formato é projetado para ser:
- Autocontido - um único arquivo contém os tensores, o tokenizador e todos os metadados necessários para carregar e executar o modelo, eliminando a necessidade de arquivos de configuração acompanhantes.
- Mapeável em memória - os dados do tensor são alinhados (por padrão a um limite de 32 bytes) para que os pesos possam ser acessados diretamente através de ponteiros sem carregar o arquivo inteiro na RAM, permitindo que modelos maiores que a memória disponível sejam servidos através de paginação do sistema operacional.
- Extensível - o bloco de metadados chave-valor permite que novos campos sejam adicionados sem quebrar a compatibilidade com leitores mais antigos.
O GGUF suporta tipos inteiros quantizados de 2 a 8 bits, formatos de dados de ponto flutuante comuns como float32, float16 e bfloat16, e quantização de 1,58 bits. Várias variantes "K-quant" (como Q4_K, Q5_K e Q6_K) usam um esquema baseado em blocos com valores separados de escala e mínimo por super-bloco, geralmente dando melhor qualidade em uma determinada largura de bits do que as quantizações legadas mais simples, como Q4_0 e Q8_0. O GGUF contém as informações necessárias para executar um modelo de linguagem tipo GPT, como o vocabulário do tokenizador, comprimento de contexto, informações de tensor e outros atributos.
Estrutura do arquivo
Um arquivo GGUF consiste em quatro seções sequenciais: um cabeçalho de tamanho fixo, um bloco de metadados chave-valor, um bloco de informações de tensor e os dados do tensor em si.
Estrutura em nível de byte (little-endian)
Antes da versão 3, os arquivos eram implicitamente little-endian; a versão 3 permite armazenamento big-endian, mas não inclui um sinalizador indicando endianness, então deve ser inferido do contexto.
#### Bloco de metadados
O bloco de metadados é uma sequência de pares chave-valor tipados. As chaves são strings com namespace (por exemplo, general.*, tokenizer.* ou um prefixo específico de arquitetura como llama.*), e os valores podem ser escalares, strings ou arrays - incluindo arrays multidimensionais.
#### Bloco de informações de tensores
Para cada tensor, o bloco de informações armazena seu nome, número de dimensões, forma, tipo de dados e deslocamento de byte dentro da região subsequente tensor_data[]. O esquema de nomenclatura é padronizado entre arquiteturas (por exemplo, blk.0.ffn_gate.weight), para que os carregadores possam localizar pesos independentemente da estrutura de origem.
#### Dados do tensor
Os dados do tensor seguem o bloco de informações e começam no próximo limite de alinhamento. O valor de alinhamento é armazenado nos metadados sob a chave general.alignment; se ausente, o padrão é 32 bytes. Alinhar os dados dessa maneira é o que permite que o arquivo seja mapeado em memória diretamente: os pesos do tensor podem ser lidos através de ponteiros sem uma cópia adicional, o que é importante para operações SIMD, transferências DMA de GPU e eficiência de cache de CPU.
Ferramentas
Modelos armazenados em outros frameworks são tipicamente convertidos para GGUF usando o script convert_hf_to_gguf.py incluído no llama.cpp, que lê checkpoints do Hugging Face (comumente na forma safetensors) e emite um arquivo GGUF em uma precisão base escolhida, como f16 ou bf16. O arquivo resultante pode então ser requantizado para um dos formatos inteiros GGUF com o utilitário llama-quantize, e modelos muito grandes podem ser divididos em vários arquivos com llama-gguf-split.
O projeto llama.cpp também expõe uma API C/C++ (declarada em ggml/include/gguf.h) e um pacote Python, gguf-py, para ler e escrever arquivos GGUF programaticamente.
Adoção
O GGUF é o formato de modelo nativo do llama.cpp e do Ollama, que usa o llama.cpp como seu backend de inferência; modelos Ollama baixados de seu registro são arquivos GGUF internamente, e arquivos GGUF arbitrários do Hugging Face podem ser carregados referenciando-os como hf.co/{user}/{repo}. Outros aplicativos de inferência que consomem GGUF diretamente incluem LM Studio, GPT4All, Jan e koboldcpp.
O Hugging Face suporta o formato como um cidadão de primeira classe em seu hub de modelos, fornecendo um visualizador de metadados GGUF, filtragem pela tag gguf, uma integração de endpoints de inferência e uma grande coleção de checkpoints GGUF enviados pela comunidade.