Transformers passa a rodar quantizados GGUF do llama.cpp nativamente

A Hugging Face publicou em 22 de setembro de 2026 um post assinado por Marc Sun, Arthur Zucker e Lysandre Debut anunciando que a biblioteca transformers agora carrega e executa checkpoints no formato GGUF reutilizando os próprios kernels Metal do llama.cpp. Na prática, isso significa pegar um modelo quantizado publicado por alguém como Unsloth, LM Studio Community ou bartowski no Hub e rodá-lo com AutoModelForCausalLM.from_pretrained, sem converter nada e sem sair da API que quem já usa transformers conhece de cor.

Por que isso importa pra quem já usa Ollama ou llama.cpp

GGUF é o formato criado pelo time do llama.cpp para empacotar pesos, tokenizer e chat template num arquivo só, com diferentes níveis de quantização. É o formato por trás de Ollama, LM Studio e Jan, e já teve milhões de downloads no Hub. Até agora, se você queria usar esses mesmos checkpoints dentro de um pipeline transformers (para fine-tuning, avaliação, hooks de debug ou geração customizada), a rota normal era converter o GGUF de volta para o formato safetensors ou manter dois ecossistemas de ferramentas separados. A integração muda isso: o arquivo GGUF passa a ser uma entrada válida direta.

O ganho não é performance bruta acima do llama.cpp puro (a própria Hugging Face é clara: llama.cpp continua sendo a recomendação quando o objetivo é só inferência local eficiente). O ganho é ferramental: dá pra inspecionar ativações intermediárias com hooks, escrever um loop de geração customizado em Python↳Python56 conteúdosVSCode + Python + Alexa: Desenvolva e teste skills para alexa localmente com pythonDev (Back & Front) · out 2025Dominando decoradores em Python: um guia completo com exemplosDev (Back & Front) · jan 2025Desenvolvimento de software: diferenças entre Python, JavaScript e JavaGestão Dev & TI · nov 2024Ver tudo em Dev (Back & Front) →, plugar LogitsProcessor próprios, ou pegar um GGUF já quantizado e continuar treinando a partir dele com GgufConfig(dequantize=True).

Como carregar um GGUF hoje

O requisito inicial é específico: Mac com Apple Silicon, uma das duas últimas versões do PyTorch e a versão de desenvolvimento do transformers (o suporte ainda não está numa release estável, só na branch main), junto com a lib kernels:

pip install -U "git+https://github.com/huggingface/transformers.git" kernels

O carregamento em si não exige configuração extra além de apontar o repositório e o arquivo:

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "unsloth/Qwen3.5-4B-GGUF"
filename = "Qwen3.5-4B-Q4_K_M.gguf"

tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)
model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)

Daí em diante é a API padrão: apply_chat_template, generate, decode. Quando os pesos ficam empacotados e rodando em Metal, o transformers carrega sozinho os kernels ggml compatíveis e usa ggml-org/ggml-attn como implementação de atenção; se o kernel não estiver disponível, cai para sdpa com um aviso (e dá pra forçar isso manualmente). Sem um kernel de quantização compatível, o carregador desempacota o modelo inteiro antes de rodar, o que consome bem mais memória, um detalhe que muda o cálculo de quanto RAM unificada você realmente precisa.

Também dá pra subir um servidor OpenAI-compatible direto do checkpoint quantizado:

transformers serve "unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf"

A sintaxe :.gguf resolve o problema de repositórios que hospedam várias quantizações do mesmo modelo. O endpoint resultante em http://localhost:8000/v1 conversa com qualquer cliente que fale a API da OpenAI, incluindo Jan ou Pi, apontando o Model ID para o mesmo par repositório:arquivo.

Quanto custa cada nível de quantização

O post traz os números de tamanho de arquivo para o Qwen3.5-4B da Unsloth, que ajudam a decidir onde começar:

| Variante | Tamanho | Trade-off | |---|---|---| | BF16 | 8,42 GB | referência sem quantização | | Q6_K | 3,53 GB | mais precisão que as menores | | Q5_K_M | 3,14 GB | meio-termo tamanho/precisão | | Q4_K_M | 2,74 GB | ponto de partida prático |

A recomendação da própria Hugging Face é começar em Q4_K_M e subir para Q5_K_M ou Q6_K se sobrar memória, sempre avaliando na tarefa real que o modelo vai fazer, porque a perda de qualidade da quantização agressiva varia de modelo para modelo.

O benchmark contra o llama.cpp

A comparação de performance foi feita num MacBook Pro M2 Max com 32 GB de memória unificada, macOS 26.6, PyTorch 2.12.1 e kernels 0.17.0, plugado na tomada. Do lado do llama.cpp, o número vem do llama-bench (build 5f55650a7, release b10200, backend Metal do ggml 0.18.0) rodando llama-bench -m -p 0 -n 128 -r 3, medindo só a taxa de geração de token (tg128), sem prompt processing. Do lado do transformers, a medição é um generate completo produzindo os mesmos 128 tokens a partir de um prompt de 12 tokens, melhor de três execuções aquecidas, incluindo o prefill. A própria equipe avisa que as condições não são idênticas (uma inclui prefill, a outra não), mas o resultado apresentado é que o transformers chega perto do llama.cpp nos três checkpoints testados: um modelo denso pequeno, um denso maior e um mixture-of-experts.

Esse resultado não é mágica de framework: é reutilização direta dos kernels Metal do ggml. A lib kernels distribui builds desses kernels pelo Hub e o transformers passa a chamá-los. São cinco peças: ggml-quantization (lê pesos quantizados sem expandir a matriz inteira antes de cada decode), ggml-norm (funde normalizações, incluindo a RMSNorm zero-centrada do Qwen3.5/Qwen3.8), ggml-attn (flash attention em Metal), ggml-gated-delta-net (acelera a camada de atenção linear híbrida do Qwen3.5/3.8) e um topk próprio da Hugging Face para roteamento de especialistas em modelos MoE.

Duas otimizações que valem para qualquer modelo

Além dos kernels, o post descreve duas mudanças no loop de generate que não são específicas de GGUF e passam a valer para qualquer modelo do transformers: remover cedo a máscara de atenção quando não há padding (PR #48814) e adiar a checagem de critério de parada para que a CPU continue agendando trabalho enquanto a GPU decodifica (PR #47975). São ajustes de sincronização CPU/GPU, o tipo de coisa que não aparece em changelog chamativo mas reduz o tempo morto entre tokens gerados, especialmente relevante para quem já reclamava de latência alta rodando modelos maiores localmente.

Onde isso ainda não chega

A lista de limitações declaradas é objetiva: o caminho de inferência empacotada (packed) só funciona em MPS por enquanto, então quem depende de CUDA em Linux↳Linux34 conteúdosKali Linux em um Servidor VPS: como, quando e por que usar?DevSecOps · dez 2024Construindo um Windows Service ou Linux Daemon com Worker Service & .NET Core – Parte 2Dev (Back & Front) · jul 2020Criando uma WebApi utilizando .NET, Linux e VSCodeDev (Back & Front) · ago 2019Ver tudo em DevSecOps → ou Windows não ganha nada disso hoje, só a rota de dequantização, que consome mais memória. Batching com padding ainda não tem o mesmo ganho de performance dos inputs sem padding, e a cobertura de arquitetura está restrita a Qwen3.5 (denso e MoE) e checkpoints compatíveis de Qwen3.8. Ou seja: se seu caso de uso é Llama, Mistral, Gemma ou qualquer outra família fora dessa lista, ou se você precisa de throughput em lote numa GPU CUDA em produção, essa integração ainda não resolve. A Hugging Face pede issues no repositório com o checkpoint e o caso de uso para priorizar a expansão de cobertura.

Para quem serve na prática

O recorte é claro: isso não substitui llama.cpp ou Ollama para quem só quer rodar um modelo local rápido, e a própria Hugging Face reconhece o llama.cpp como referência de eficiência. O valor aparece em cenários híbridos, como avaliar a qualidade de um GGUF com os workflows de avaliação que você já mantém em transformers, validar se uma conversão para GGUF preservou os pesos corretamente comparando com o checkpoint original, prototipar um logits processor customizado sem reescrever a lógica de geração em outra linguagem, ou pegar um checkpoint quantizado e continuar o fine-tuning a partir dele. Para times brasileiros rodando protótipos em MacBooks antes de decidir se vale subir GPU na nuvem, a integração reduz o atrito de manter dois pipelines de ferramentas (um para experimentar em transformers, outro para servir localmente com GGUF), mas o suporte MPS-only e a cobertura limitada a Qwen3.5/3.8 deixam claro que ainda é uma peça inicial, não um substituto de stack de produção.

Fonte: Hugging Face Blog