# GGUF

[GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md) es un formato de archivo único utilizado para almacenar modelos para inferencia con [GGML](https://github.com/ggerganov/ggml), que contiene los metadatos del modelo y los tensores. Admite muchos tipos de datos cuantizados (consulte la [tabla de tipos de cuantización](https://hf.co/docs/hub/en/gguf#quantization-types)), lo que ahorra una cantidad significativa de memoria.

    

## Cargar modelos GGUF

Instala [kernels](https://huggingface.co/docs/kernels/index); de lo contrario, la ruta empaquetada recurrirá a la [dequantization](#dequantize) completa al cargar.

```bash
pip install kernels
```

Los pesos permanecen empaquetados cuando está disponible el kernel del Hub [ggml-org/ggml-quantization](https://huggingface.co/ggml-org/ggml-quantization). El cargador usa MPS de forma predeterminada cuando ese kernel está presente y ejecuta las multiplicaciones de matrices directamente sobre los bloques empaquetados. Si el kernel no está disponible, el modelo se descuantiza al cargarlo.

```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)
```

La misma carga funciona para 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)
```

La ruta empaquetada admite actualmente Qwen3.5 y Qwen3.5 MoE. Las cargas empaquetadas usan float32 automáticamente porque es más rápido en MPS. Si se establece otro `dtype`, el cargador devuelve una advertencia. Otras arquitecturas pasan por el cargador heredado.

## Atención

En MPS, con los kernels instalados, [ggml-attn](https://huggingface.co/kernels/ggml-org/ggml-attn) es la atención predeterminada al cargar un archivo GGUF: el mismo kernel de flash-attention que llama.cpp utiliza para decode y prefill. Si no se puede obtener el kernel, el modelo conserva su implementación de atención. Pasar `attn_implementation` (por ejemplo, `"sdpa"`) siempre tiene prioridad.

También puede pasarlo explícitamente:

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

## Descomprimir

Dequantizar descomprime cada peso en el momento de la carga y devuelve un modelo denso estándar. Es la opción de respaldo cuando la ruta rápida y comprimida no es aplicable. También se puede solicitar explícitamente mediante [GgufConfig](/docs/transformers/v5.23.0/es/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
)
```

Obtienes un modelo denso regular en el `dtype` que pasaste.

Las arquitecturas distintas de Qwen3.5 y Qwen3.5 MoE pasan por el cargador heredado, que siempre realiza la descuantización.

> [!TIP]
> El cargador heredado es compatible con Llama, Mistral, Qwen2, Qwen2Moe, Phi3, Bloom, Falcon, StableLM, GPT2, Starcoder2 y [más](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/ggml.py).

## Servir

[transformers serve](../serve-cli/serving) lista cada archivo `.gguf` de un repositorio como un modelo independiente. Un modelo GGUF se denomina `<repo>:<file>.gguf`, ya que un repositorio contiene varias cuantizaciones y el identificador debe indicar cuál se debe cargar. Las solicitudes lo nombran de la misma manera.

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

