# GGUF

[GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md) é um formato de arquivo único usado para armazenar modelos para inferência com [GGML](https://github.com/ggerganov/ggml), contendo os metadados do modelo e os tensores. Ele suporta muitos tipos de dados quantizados (consulte a [tabela de tipos de quantização](https://hf.co/docs/hub/en/gguf#quantization-types)), o que economiza uma quantidade significativa de memória.

    

## Carregar modelos GGUF

Instale o [kernels](https://huggingface.co/docs/kernels/index), caso contrário, o caminho compactado recorre à [dequantização](#dequantize) completa no carregamento.

```bash
pip install kernels
```

Os pesos permanecem empacotados quando o kernel do Hub [ggml-org/ggml-quantization](https://huggingface.co/ggml-org/ggml-quantization) está disponível. O carregador usa MPS por padrão quando esse kernel está presente e executa os matmuls diretamente nos blocos empacotados. Se o kernel não estiver disponível, o modelo é desquantizado no carregamento.

```py
from transformers import AutoModelForCausalLM, AutoTokenizer

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

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

O mesmo load funciona para o Qwen3.5 MoE.

```py
moe_model_id = "unsloth/Qwen3.5-35B-A3B-GGUF"
moe_filename = "Qwen3.5-35B-A3B-Q4_K_M.gguf"

moe_model = AutoModelForCausalLM.from_pretrained(moe_model_id, gguf_file=moe_filename)
moe_tokenizer = AutoTokenizer.from_pretrained(moe_model_id, gguf_file=moe_filename)
```

O caminho empacotado atualmente suporta Qwen3.5 e Qwen3.5 MoE. Os carregamentos empacotados usam float32 automaticamente, pois é mais rápido no MPS. Se você definir outro `dtype`, o carregador retorna um aviso. Outras arquiteturas passam pelo carregador legado.

## Atenção

No MPS, com os kernels instalados, [ggml-attn](https://huggingface.co/kernels/ggml-org/ggml-attn) é a atenção padrão ao carregar um arquivo GGUF: o mesmo kernel de flash-attention que o llama.cpp usa para decode e prefill. Se o kernel não puder ser obtido, o modelo mantém sua implementação de atenção. A passagem de `attn_implementation` (por exemplo, `"sdpa"`) sempre tem precedência.

Você também pode passá-lo explicitamente:

```py
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, attn_implementation="ggml-org/ggml-attn"
)
```

## Desquantizar

A desquantização descompacta cada peso no momento do carregamento e devolve um modelo denso comum. É o recurso de fallback sempre que o caminho rápido e compactado não se aplica. Você também pode solicitá-lo explicitamente com [GgufConfig](/docs/transformers/main/pt/main_classes/quantization#transformers.GgufConfig).

```py
import torch

from transformers import AutoModelForCausalLM, GgufConfig

quantization_config = GgufConfig(dequantize=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, quantization_config=quantization_config, dtype=torch.bfloat16
)
```

Você obtém um modelo denso regular no `dtype` que você passou.

Arquiteturas diferentes de Qwen3.5 e Qwen3.5 MoE passam pelo carregador legado, que sempre realiza a desquantização.

> [!TIP]
> O carregador legado suporta Llama, Mistral, Qwen2, Qwen2Moe, Phi3, Bloom, Falcon, StableLM, GPT2, Starcoder2 e [muitos outros](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/ggml.py).

## Servir

[transformers serve](../serve-cli/serving) lista cada arquivo `.gguf` em um repositório como um modelo próprio. Um modelo GGUF é nomeado como `<repo>:<file>.gguf`, pois um repositório contém várias quantizações e o id precisa indicar qual delas carregar. As solicitações o nomeiam da mesma forma.

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