# GGUF

O formato de arquivo GGUF é tipicamente usado para armazenar modelos para inferência com [GGML](https://github.com/ggerganov/ggml) e suporta uma variedade de opções de quantização por bloco. O Diffusers suporta o carregamento de checkpoints pré-quantizados e salvos no formato GGUF via carregamento com `from_single_file` em classes de Model. O carregamento de checkpoints GGUF via Pipelines não é suportado no momento.

O exemplo a seguir carregará o modelo de transformer [FLUX.1 DEV](https://huggingface.co/black-forest-labs/FLUX.1-dev) usando a variante de quantização GGUF Q2_K.

Antes de começar, instale o gguf no seu ambiente

```shell
pip install -U gguf
```

Como o GGUF é um formato de arquivo único, use `~FromSingleFileMixin.from_single_file` para carregar o modelo e passe o [GGUFQuantizationConfig](/docs/diffusers/main/pt/api/quantization#diffusers.GGUFQuantizationConfig).

Ao usar checkpoints GGUF, os pesos quantizados permanecem em um `dtype` de baixa memória (tipicamente `torch.uint8`) e são desquantizados dinamicamente e convertidos para o `compute_dtype` configurado durante a passagem de cada módulo pelo modelo. O `GGUFQuantizationConfig` permite definir o `compute_dtype`.

As funções usadas para a desquantização dinâmica são baseadas no excelente trabalho realizado por [city96](https://github.com/city96/ComfyUI-GGUF), que criou as versões em Pytorch da implementação original em [`numpy`](https://github.com/ggerganov/llama.cpp/blob/master/gguf-py/gguf/quants.py) feita por [compilade](https://github.com/compilade).

```python
import torch

from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig

ckpt_path = (
    "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf"
)
transformer = FluxTransformer2DModel.from_single_file(
    ckpt_path,
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)
pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()
prompt = "A cat holding a sign that says hello world"
image = pipe(prompt, generator=torch.manual_seed(0)).images[0]
image.save("flux-gguf.png")
```

## Usando kernels CUDA otimizados com GGUF

Kernels CUDA otimizados podem acelerar a inferência de modelos quantizados GGUF em aproximadamente 10%. Essa funcionalidade requer uma GPU compatível com `torch.cuda.get_device_capability` maior que 7 e a biblioteca de kernels:

```shell
pip install -U kernels
```

Depois de instalado, defina `DIFFUSERS_GGUF_CUDA_KERNELS=true` para usar kernels otimizados quando disponíveis. Observe que os kernels CUDA podem introduzir pequenas diferenças numéricas em comparação com a implementação original do GGUF, o que pode causar variações visuais sutis nas imagens geradas. Para desativar o uso de kernels CUDA, defina a variável de ambiente `DIFFUSERS_GGUF_CUDA_KERNELS=false`.

Os kernels GGUF são baixados do repositório [`Isotr0py/ggml`](https://huggingface.co/Isotr0py/ggml), cujo publicador não é um publicador de kernels confiável no Hub. Carregá-lo baixa e executa código do Hub, portanto, o Diffusers exige que você opte explicitamente por isso definindo `DIFFUSERS_TRUST_REMOTE_KERNELS=true`. Consulte [Confiança em kernels remotos](../optimization/attention_backends#trusting-remote-kernels) para mais detalhes.

## Tipos de Quantização Suportados

- BF16
- Q4_0
- Q4_1
- Q5_0
- Q5_1
- Q8_0
- Q2_K
- Q3_K
- Q4_K
- Q5_K
- Q6_K

## Converter para GGUF

Use o Space abaixo para converter um checkpoint do Diffusers para o formato GGUF para inferência. executar conversão:

<iframe src="https://diffusers-internal-dev-diffusers-to-gguf.hf.space" frameborder="0" width="850" height="450"
>

```py
import torch

from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig

ckpt_path = (
    "https://huggingface.co/sayakpaul/different-lora-from-civitai/blob/main/flux_dev_diffusers-q4_0.gguf"
)
transformer = FluxTransformer2DModel.from_single_file(
    ckpt_path,
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    config="black-forest-labs/FLUX.1-dev",
    subfolder="transformer",
    dtype=torch.bfloat16,
)
pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()
prompt = "A cat holding a sign that says hello world"
image = pipe(prompt, generator=torch.manual_seed(0)).images[0]
image.save("flux-gguf.png")
```

Ao usar checkpoints GGUF no formato Diffusers, é obrigatório fornecer o caminho do `config` do modelo. Se o config do modelo estiver em uma `subfolder`, isso também precisa ser especificado.