GGUF
GGUF é o formato de arquivo único que o llama.cpp usa para armazenar os pesos, o tokenizador e os metadados de um LLM, muitas vezes quantizados para 4 a 8 bits para uso em hardware local.
GGUF é um formato de ficheiro binário para armazenar modelos executados no GGML, a biblioteca de tensores em C que está na base do llama.cpp e das ferramentas construídas sobre ele. Um ficheiro GGUF contém tudo o que é necessário para executar um modelo de linguagem grande (LLM): a arquitetura e os hiperparâmetros, o vocabulário do tokenizador, o modelo de chat e os pesos do modelo, normalmente comprimidos por quantização do modelo para entre 2 e 8 bits por peso. O projeto llama.cpp introduziu o GGUF em agosto de 2023 para substituir os formatos anteriores GGML, GGMF e GGJT, e tornou-se a forma padrão de partilhar modelos de pesos abertos para inferência local num CPU de portátil, num Mac com Apple Silicon ou numa GPU de consumo, com milhares de repositórios GGUF no Hugging Face.
O interior de um ficheiro GGUF#
A especificação GGUF define quatro partes, pela seguinte ordem. Um cabeçalho contém os bytes mágicos GGUF, a versão do formato (atualmente 3) e as contagens de tensores e entradas de metadados. A seguir vêm metadados tipados de chave-valor, como general.architecture, llama.context_length, tokenizer.ggml.tokens e tokenizer.chat_template, que incorporam no próprio ficheiro a tokenização e o formato de prompt do modelo. Uma tabela enumera depois o nome, a forma, o tipo de dados e o deslocamento de cada tensor; os dados dos tensores vêm por último, preenchidos por padrão até um alinhamento de 32 bytes, para que o ambiente de execução possa mapear o ficheiro na memória e carregá-lo quase instantaneamente. Os leitores procuram os metadados pela chave, pelo que é possível adicionar novas arquiteturas e campos sem comprometer a compatibilidade com ficheiros mais antigos.
Cada tensor tem o seu próprio tipo, pelo que um ficheiro pode combinar precisões. O pacote Python gguf, mantido no repositório llama.cpp, escreve e lê o formato e implementa vários tipos de quantização:
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")Apresenta as duas chaves de metadados, general.architecture e llama.context_length, e depois indica 16,0 bits por peso com um erro médio de 0,0001 para F16, 8,5 bits e 0,0045 para Q8_0, e 4,5 bits e 0,0719 para Q4_0. Q8_0 e Q4_0 armazenam blocos de 32 pesos com uma escala FP16 por bloco, de onde vem o meio bit adicional.
Tipos de quantização#
Os tipos de quantização GGUF dividem-se em três gerações. Os formatos de bloco originais, como Q4_0 e Q8_0, usam uma escala por cada 32 pesos. Os K-quants, como Q4_K e Q6_K, agrupam blocos em superblocos de 256 pesos com escalas quantizadas, e nomes de ficheiros como Q4_K_M indicam uma combinação que mantém os tensores mais sensíveis numa precisão superior. Os I-quants, como IQ2_XXS e IQ4_XS, chegam a cerca de 2 a 4 bits por peso, normalmente orientados por uma matriz de importância que llama-imatrix calcula a partir de texto de amostra, para que os pesos mais influentes mantenham a maior precisão. Entre as adições mais recentes está o MXFP4, o formato de vírgula flutuante de 4 bits usado pela OpenAI para lançar o gpt-oss. A maioria dos ficheiros GGUF publicados provém do mesmo processo de conversão:
GGUF e outros formatos de modelo#
- GGML, GGMF e GGJT: Os formatos anteriores do llama.cpp armazenavam os hiperparâmetros como uma lista sem tipos e sem um campo de arquitetura, pelo que adicionar um parâmetro comprometia a compatibilidade com os ficheiros existentes.
- Safetensors: Formato do Hugging Face para armazenar tensores brutos de forma segura, geralmente em precisão completa ou meia precisão, mantendo a configuração e o tokenizador em ficheiros separados.
- ONNX: Armazena um grafo de computação completo juntamente com os pesos, para que qualquer ambiente de execução compatível com ONNX possa executar o modelo sem código específico da arquitetura.
Execução de modelos GGUF#
O llama.cpp executa ficheiros GGUF pela linha de comando ou como llama-server, que disponibiliza uma API compatível com OpenAI, e pode transferir qualquer número de camadas para uma GPU enquanto as restantes são executadas no CPU, permitindo executar até modelos maiores do que a memória da GPU. O Ollama e o LM Studio executam modelos GGUF através de uma biblioteca de modelos e de uma interface de chat, e o Hugging Face Hub mostra os metadados e os tipos de tensores de cada ficheiro GGUF no navegador. A inferência local mantém os prompts na máquina, o que é importante para a privacidade dos dados e para usos de IA de borda sem ligação à Internet. A interface LLM da Ultralytics pode chamar um modelo GGUF servido por llama-server ou pelo Ollama através dos respetivos endpoints de Chat Completions compatíveis com OpenAI, para que um pipeline YOLO26 possa pedir a um modelo local que descreva as deteções sem enviar dados para uma API na nuvem. O formato também vai além dos modelos de linguagem: os nós personalizados do ComfyUI-GGUF carregam modelos de difusão quantizados, como o FLUX.1, a partir de ficheiros GGUF, para que caibam na memória das GPUs de consumo.










