Do último checkpoint do treino até o modelo respondendo num motor de inferência — com a extensão de arquivo e o software explícitos em cada etapa, os comandos exatos de conversão e a diferença real entre os tipos de quantização.
Um grafo hierárquico, de cima para baixo. A cada etapa muda o software que opera e o arquivo que sai dela. O nó destacado em verde é o ponto onde o caminho se ramifica para outros motores.
Durante o treino, você salva checkpoints que guardam os pesos mais o estado do otimizador (momentos do Adam, learning-rate scheduler, etc.). É o formato “vivo”, pesado e pensado para retomar o treino — não para servir.
Os pesos são exportados no padrão de fato de hoje: .safetensors — mais seguro que .bin porque é só um mapa de tensores, não executa código arbitrário ao carregar. Não é um arquivo solto: é uma pasta com pesos + as configs que descrevem o modelo e o tokenizer.
.safetensors.
ver caminhos alternativos →
O Ollama roda em cima do llama.cpp, que não lê safetensors direto. Ele precisa do .gguf: um arquivo único e autocontido (pesos + tokenizer + metadados juntos), otimizado para inferência em CPU/GPU. A pasta HF entra, sai um .gguf — normalmente ainda em FP16.
Reduz a precisão dos pesos (FP16 → INT4/INT5/INT8) para encolher o arquivo e acelerar a inferência. A saída continua .gguf, só que bem menor. Tipos comuns: Q4_K_M, Q5_K_M, Q8_0.
Você escreve um Modelfile (texto puro, parecido com um Dockerfile) apontando para o .gguf e definindo system prompt, temperatura e template de chat. O ollama create importa o gguf para o storage interno; o ollama run serve o modelo.
O arquivo que “viaja” pelo pipeline principal, em uma linha.
Sequência completa, da clonagem do llama.cpp ao ollama run. Os nomes mudaram com o tempo — hoje o script é convert_hf_to_gguf.py e o binário é llama-quantize (não mais convert.py/quantize).
# clonar e compilar (org atual: ggml-org)
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build && cmake --build build --config Release -j
# GPU NVIDIA: cmake -B build -DGGML_CUDA=ON
# dependências do conversor Python
pip install -r requirements.txtpython convert_hf_to_gguf.py ./meu-modelo-hf \
--outfile meu-modelo-f16.gguf \
--outtype f16
# --outtype aceita: f32, f16, bf16, q8_0, auto
# a quantização "fina" (K-quants / I-quants) fica para o llama-quantize, abaixo./build/bin/llama-quantize \
meu-modelo-f16.gguf \
meu-modelo-Q4_K_M.gguf \
Q4_K_M# 1) calcula a imatrix a partir de um texto de calibração
./build/bin/llama-imatrix \
-m meu-modelo-f16.gguf \
-f calibracao.txt \
-o meu-modelo.imatrix
# 2) quantiza usando a imatrix (melhora muito Q2/Q3 e IQ*)
./build/bin/llama-quantize \
--imatrix meu-modelo.imatrix \
meu-modelo-f16.gguf \
meu-modelo-IQ4_XS.gguf \
IQ4_XSFROM ./meu-modelo-Q4_K_M.gguf
PARAMETER temperature 0.7
PARAMETER num_ctx 4096
PARAMETER stop "<|im_end|>"
SYSTEM """Você é um assistente útil e direto."""
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""# importa o gguf para o storage interno do Ollama
ollama create meu-modelo -f Modelfile
# conversa com o modelo
ollama run meu-modeloQuantizar troca precisão por tamanho e velocidade. Há três famílias, e o equilíbrio entre elas é o que decide o tipo. Números abaixo são para um modelo de 7B de referência (a referência canônica do llama-quantize); o tamanho escala com o modelo.
| Tipo | Bits/peso ≈ | Tamanho (7B) | Δ perplexidade | Qualidade | Quando usar |
|---|---|---|---|---|---|
| Q2_KK | ~2,6 | 2,67 GB | +0,87 | Só se a RAM for crítica — perda extrema, não recomendado sem imatrix. | |
| Q3_K_MK | ~3,9 | 3,06 GB | +0,24 | Hardware bem limitado; aceitável em modelos grandes. | |
| Q4_0legado | ~4,5 | 3,50 GB | +0,25 | Evite — mesma faixa de tamanho do Q3_K_M, mas pior. Prefira K-quants. | |
| Q4_K_MKrecomendado | ~4,8 | 3,80 GB | +0,05 | O ponto ideal. Melhor equilíbrio tamanho × qualidade para uso geral. | |
| Q5_K_MK | ~5,7 | ≈ 4,45 GB | ≈ +0,02 | Quando sobra memória — perda quase imperceptível. Ótimo p/ código e raciocínio. | |
| Q6_KK | ~6,6 | ≈ 5,15 GB | ≈ 0 | Praticamente sem perda; passo intermediário até o FP16. | |
| Q8_0legado | ~8,5 | ≈ 6,7 GB | ≈ 0 | Quase idêntico ao FP16. Use como “referência de ouro” ou quando qualidade > tamanho. | |
| IQ4_XSi-quant | ~4,3 | ≈ 3,5 GB | ≈ +0,04 | Qualidade de Q4_K_M com arquivo menor — exige imatrix; inferência um pouco mais lenta. |
Δ perplexidade = aumento em relação ao FP16 (menor é melhor). Valores de Q2_K a Q4_K_M vêm da tabela oficial do llama-quantize; os de Q5_K_M para cima são aproximados (marcados com ≈).
Blocos de 32 pesos com uma escala cada. Q4_0 é simétrico (só escala); Q4_1 é afim (escala + offset). Simples e rápido de gerar, mas pior qualidade/tamanho que os K-quants — hoje preteridos, exceto o Q8_0.
Super-blocos de 256 pesos em que as próprias escalas dos sub-blocos são quantizadas → menos bits/peso para a mesma qualidade. Tensores críticos (atenção, ffn) ficam em precisão maior. _S/_M/_L controlam o quanto. Padrão moderno.
Codebooks não-lineares guiados por uma matriz de importância (imatrix): aloca mais bits aos tensores mais sensíveis. Vence em bitrates muito baixos (<4 bpw), ao custo de precisar da imatrix antes e de inferência mais lenta.
IQ2_XXS · IQ3_XXS · IQ4_XS · IQ4_NL …Como ler um nome como Q4_K_M ou IQ3_XXS.
Todos partem do mesmo ponto: a pasta .safetensors do passo 2. GGUF é específico do llama.cpp/Ollama — os motores abaixo usam outros formatos.
Serve a pasta HF direto, sem GGUF. Alto throughput em GPU graças ao PagedAttention e batching contínuo. É o padrão para servir em produção com volume.
Text Generation Inference, da Hugging Face. Também lê .safetensors direto; entregue como container. Foco em throughput e streaming em GPU.
Exporta o grafo para .onnx — multiplataforma (CPU, GPU, mobile, navegador). Bom quando você precisa de portabilidade entre hardwares e runtimes.
Compila um motor .engine específico para a GPU NVIDIA. Performance máxima, mas o engine fica amarrado à GPU e à versão — recompile ao trocar de hardware.
Converte para .tflite (LiteRT / TensorFlow Lite). Roda on-device com delegados de NPU/GPU. Caminho típico para apps Android.
Core ML, empacotado como .mlpackage. Usa o Neural Engine em iPhone/iPad/Mac. Gerado pelo coremltools a partir do modelo PyTorch.