Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /pt /quantization /gguf.md

mishig

2 days ago

preview code

download

raw

4.82 kB

# 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/v0.43.0/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.

Xet Storage Details

Size:: 4.82 kB
Xet hash:: 6d7e0de055a880c0bac28bac2a3e7f4e1f9dfd8a6ddd8c87a5601e79a73f4552

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# 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/v0.43.0/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.