GGUF, safetensors: entender os formatos de modelos

#Por que esses formatos existem

Um LLM, uma vez treinado, é apenas um enorme saco de números: os pesos (weights), ou seja, os bilhões de parâmetros que codificam o que o modelo “sabe”. O formato de arquivo é simplesmente a forma como esses números são armazenados no disco. É preciso decidir como armazená-los, como lê-los rapidamente e quais informações complementares (o vocabulário, a arquitetura, as configurações) incluir junto com eles.

Historicamente, esses pesos eram salvos no formato .bin do PyTorch (pickle Python), prático mas lento para carregar e, principalmente, perigoso: um arquivo pickle pode executar código arbitrário ao ser aberto. Dois formatos se impuseram para resolver problemas diferentes. safetensors atende à necessidade dos pesquisadores e das plataformas: armazenamento seguro e rápido, fiel à precisão original. GGUF atende à necessidade de inferência local: um arquivo único, compacto, quantizado, pronto para rodar em CPU ou GPU de uso comum.

#safetensors : o formato Hugging Face

safetensors é o formato padrão do ecossistema Hugging Face. Criado para substituir o pickle do PyTorch, seu principal argumento está no próprio nome: segurança. O arquivo contém apenas dados (os tensores de pesos) e um pequeno cabeçalho JSON que descreve sua forma e seu tipo. Nenhum código executável, portanto nenhum risco de abrir um arquivo malicioso. Bônus: o carregamento é mais rápido graças ao mapeamento de memória, que permite ler os pesos diretamente do disco sem primeiro copiar tudo para a RAM.

Seguro por design

Sem código executável, ao contrário dos antigos .bin/.pt em pickle. É possível baixar um safetensors sem medo de execução de código.

Precisão total

Os pesos são geralmente armazenados em FP16 ou BF16 (16 bits), até mesmo FP32. É a precisão de treinamento, a que serve de referência.

Feito para ser transformado

É o formato de partida para o fine-tuning, a fusão de modelos (merge), a quantização ou a conversão para outros formatos.

Frequentemente dividido

Um grande modelo é dividido em vários arquivos (shards) acompanhados de um índice JSON, pois um único arquivo de dezenas de GB seria inviável.

O lado negativo: um arquivo safetensors em FP16 é volumoso. Um modelo de 7B pesa cerca de 14 GB (2 bytes por parâmetro), um de 70B em torno de 140 GB. Para treinamento e pesquisa em GPU de servidor, é uma boa escolha. Para rodar um modelo em sua máquina, geralmente é muito pesado — daí o interesse na quantização e no GGUF.

#GGUF: o formato de inferência local

GGUF (GPT-Generated Unified Format) é o formato originado do projeto llama.cpp, o motor de inferência que executa LLMs de forma eficiente tanto em CPU quanto em GPU. Ele substituiu o antigo formato GGML em 2023. Sua ideia principal: colocar tudo em um único arquivo. Os pesos, o vocabulário do tokenizer, os metadados de arquitetura (número de camadas, tamanho da janela de contexto), o template de chat — tudo fica empacotado junto. Você baixa um arquivo, executa e funciona.

Arquivo único e autônomo

Pesos + tokenizer + metadados em um único .gguf. Sem pasta de configuração para montar, sem dependência Python para instalar.

Quantizado

Projetado para armazenar pesos comprimidos (4, 5, 6, 8 bits). É isso que torna os grandes modelos acessíveis em hardware de uso comum.

CPU + GPU + offload

O llama.cpp pode distribuir as camadas entre GPU e RAM do sistema. É possível rodar um modelo maior que a sua VRAM, com uma pequena perda de velocidade.

Portátil

O mesmo arquivo .gguf funciona no Windows, macOS (Metal) e Linux, com Ollama, LM Studio, Jan ou diretamente com llama.cpp.

A quantização é o ponto central. Ela consiste em armazenar cada peso em menos bits (4 em vez de 16, por exemplo), o que divide o tamanho por 3 a 4 com uma perda de qualidade mínima se a escolha for bem feita. É isso que permite que um modelo de 7B caiba em cerca de 5 GB de VRAM em vez de 14. Os níveis comuns encontrados: Q4_K_M (melhor equilíbrio, recomendado por padrão), Q5_K_M (um nível acima em qualidade), Q8_0 (quase sem perda, mais pesado) e FP16 (não quantizado, referência).

#Por que Ollama e LM Studio querem o GGUF

Ollama e LM Studio são construídos sobre llama.cpp (ou um mecanismo equivalente), e llama.cpp oferece suporte nativo a GGUF. Isso não é um capricho: é o que torna essas ferramentas tão simples. Como o GGUF já contém o tokenizer, a arquitetura e o template de chat, a ferramenta não precisa adivinhar nada. Ela lê o arquivo, aloca a memória e responde a você. Sem ambiente Python, sem dependências a resolver, sem configuração a escrever.

Quando você executa `ollama pull llama3.2`, o Ollama baixa, na realidade, um GGUF do seu registro e o armazena no seu repositório de modelos. Você nunca vê o arquivo, mas o formato usado internamente é mesmo GGUF. Já o LM Studio mostra explicitamente os arquivos GGUF disponíveis e suas quantizações no momento do download.

# Ollama récupère un GGUF depuis sa registry et le sert sur localhost:11434
ollama pull llama3.2
ollama run llama3.2

# Vérifier que le daemon répond
curl http://localhost:11434/api/tags

#Ler o nome de um arquivo sem se enganar

No Hugging Face, os nomes dos arquivos GGUF seguem uma convenção legível uma vez que se conhece o código. Tome um exemplo típico: `Qwen2.5-7B-Instruct-Q4_K_M.gguf`. Cada parte contém uma informação.

Qwen2.5

A família e a versão do modelo.

7B

Número de parâmetros: 7 bilhões. Esse é o primeiro indicador da VRAM necessária.

Instruct

A variante treinada para seguir instruções e conversar (em oposição à variante -base, bruta, não alinhada para chat).

Q4_K_M

Quantização: 4 bits, variante K_M (medium). Compromisso qualidade/tamanho recomendado por padrão.

.gguf

O formato. Você sabe que ele rodará em Ollama, LM Studio ou llama.cpp sem conversão.

O sufixo de quantização é a parte mais útil para decodificar. O número indica a quantidade de bits por peso; as letras K_S / K_M / K_L indicam variantes (Small, Medium, Large) que protegem mais ou menos as camadas sensíveis. Quanto maior o número, maior o arquivo e mais fidelidade ele apresenta.

Q4_K_M

~4 bits, médio. A escolha padrão: a melhor qualidade em relação ao tamanho na imensa maioria dos casos.

Q5_K_M

~5 bits. Um passo a mais em qualidade, arquivo um pouco mais pesado. Bom se a VRAM permitir.

Q8_0

8 bits. Quase indistinguível do não quantizado, mas duas vezes mais pesado que Q4. Para puristas ou tarefas exigentes.

Q2_K / Q3_K

2 a 3 bits. Muito compacto, mas com perda visível de qualidade. Reservar para casos em que a memória é realmente crítica.

FP16 / F16

Não quantizado, precisão total de 16 bits. A referência, mas pesado — prefira safetensors nesse caso.

#Qual baixar de acordo com sua ferramenta

A questão prática resume-se a: qual ferramenta eu vou usar? O formato decorre da resposta, não o inverso.

Ollama, LM Studio, Jan, llama.cpp

→ GGUF. Essas ferramentas foram feitas para isso. Escolha a quantização de acordo com sua VRAM (Q4_K_M por padrão).

vLLM, TGI, Transformers (Python)

→ safetensors. Esses motores de servidor carregam o formato nativo do Hugging Face, geralmente em FP16 ou com sua própria quantização (AWQ, GPTQ).

Ajuste fino, fusão, quantização por conta própria

→ safetensors. Esse é o formato de trabalho: partimos da precisão plena para transformar o modelo.

Você ainda não sabe

→ GGUF quantizado se for para uso local na sua máquina. É o mais simples e mais econômico.

Para escolher a quantização adequada, baseie-se na sua VRAM. Referências em Q4: um modelo 3B cabe em ~2 GB, um 7B em ~5 GB, um 14B em ~9 GB, um 32B em ~19 GB, um 70B em ~40 GB. Uma RTX 3060 de 12 GB roda confortavelmente modelos de 7B a 14B em Q4; uma RTX 4090 de 24 GB é indicada para modelos 32B; para modelos 70B, é preciso buscar uma placa com muita VRAM ou um Mac com memória unificada (M4 Pro 24-48 GB).

#Converter safetensors para GGUF

Às vezes, um modelo é publicado apenas no formato safetensors (algo frequente no dia do lançamento) e você quer rodá-lo no Ollama. Nesse caso, é necessário convertê-lo para GGUF e, opcionalmente, quantizá-lo. A ferramenta de referência é o script `convert_hf_to_gguf.py` fornecido pelo llama.cpp. O processo ocorre em duas etapas: primeiro converter para GGUF em precisão completa, depois quantizar com a ferramenta `llama-quantize`.

1. 01
   Obter o llama.cpp e suas dependências

   Clone o repositório llama.cpp e instale as dependências Python do script de conversão. Esse repositório contém convert_hf_to_gguf.py.
2. 02
   Baixar o modelo safetensors

   Recupere o diretório completo do modelo do Hugging Face (pesos .safetensors + config.json + arquivos do tokenizer). Tudo deve estar presente, não apenas os pesos.
3. 03
   Converter para GGUF FP16

   Execute convert_hf_to_gguf.py no diretório do modelo. Você obtém um .gguf em precisão total (16 bits), volumoso, mas fiel.
4. 04
   Quantizar em Q4_K_M

   Processe o GGUF FP16 com llama-quantize, escolhendo o nível desejado (Q4_K_M por padrão). O arquivo final é 3 a 4 vezes mais leve.
5. 05
   Importar para Ollama

   Escreva um Modelfile apontando para o .gguf quantizado e crie o modelo com o comando ollama create. Ele poderá então ser usado como qualquer outro modelo Ollama.

# 1. Cloner llama.cpp et installer les dépendances de conversion
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

# 2. Convertir le dossier safetensors en GGUF pleine précision
python convert_hf_to_gguf.py ./mon-modele-hf --outfile mon-modele-f16.gguf --outtype f16

# 3. Quantifier en Q4_K_M (compromis recommandé)
./llama-quantize mon-modele-f16.gguf mon-modele-Q4_K_M.gguf Q4_K_M

# Créer un Modelfile minimal
printf 'FROM ./mon-modele-Q4_K_M.gguf\n' > Modelfile

# Enregistrer le modèle dans Ollama
ollama create mon-modele -f Modelfile
ollama run mon-modele

#Outros formatos que você encontra

GGUF e safetensors cobrem o essencial, mas alguns outros nomes aparecem ao longo dos downloads. Conhecer esses nomes evita surpresas ruins.

.bin / .pt (pickle)

O formato antigo do PyTorch. Funcional, mas não seguro (pode executar código). Progressivamente substituído por safetensors — evite se houver uma alternativa disponível.

GPTQ / AWQ

Quantizações para execução em GPU com vLLM e Transformers, armazenadas em safetensors. Rápidas em GPUs NVIDIA, mas não podem ser lidas pelo Ollama/llama.cpp.

MLX

O formato da Apple para seu framework MLX, otimizado para o chip Apple Silicon. Usado por alguns aplicativos nativos do Mac, distinto do GGUF.

ONNX

Um formato de intercâmbio entre frameworks, principalmente para implantação industrial e em dispositivos de borda. Raro no uso de LLMs locais pelo público em geral.

GGML

Antecessor do GGUF (mesmo projeto). Obsoleto: se encontrar .ggml, procure a versão .gguf equivalente.

#Perguntas frequentes

GGUF ou safetensors, qual é o melhor?

Nenhum dos dois é melhor em termos absolutos: eles atendem a usos diferentes. GGUF para rodar um modelo localmente (Ollama, LM Studio), safetensors para o ecossistema Hugging Face, o fine-tuning e os motores de servidor. O “melhor” depende da sua ferramenta.

Um GGUF é pior que um safetensors?

Um GGUF quantizado perde um pouco de precisão em comparação com o safetensors FP16 original. Em Q4_K_M ou Q5_K_M, a diferença é mínima e raramente perceptível no uso. Em Q2/Q3, ela se torna visível.

Posso usar um safetensors diretamente no Ollama?

Na maioria dos casos, não diretamente: o Ollama espera arquivos GGUF. É necessário converter o arquivo safetensors para GGUF com o llama.cpp antes. Algumas versões recentes aceitam a importação de safetensors, mas o GGUF continua sendo a opção confiável.

Por que tantos arquivos em uma página do Hugging Face?

Um modelo é frequentemente dividido em vários shards (safetensors ou GGUF), além dos arquivos de configuração e tokenizer. Para GGUF, você geralmente quer um único arquivo por quantização (ou todos os pedaços de uma série dividida).

#Para se aprofundar

Agora que os formatos não têm mais segredos, esses guias dão continuidade ao tema de forma natural.

Escolher sua quantização (Q4, Q5, Q8, FP16)

Guia detalhado para escolher o nível de quantização de um GGUF de acordo com sua VRAM e suas necessidades de qualidade.

O que é o Ollama e como ele funciona

Entender a ferramenta que baixa e serve os GGUF localmente, com os comandos básicos.

Compreender a janela de contexto

Outro parâmetro que afeta a memória: os tokens e o contexto, combinados com a escolha de quantização.