# GGUF

Формат файлов GGUF обычно используется для хранения моделей для инференса с [GGML](https://github.com/ggerganov/ggml) и поддерживает различные варианты блочного квантования. Diffusers поддерживает загрузку предварительно заквантованных чекпоинтов, сохранённых в формате GGUF, с помощью загрузки `from_single_file` в классах моделей. Загрузка чекпоинтов GGUF через Pipelines в настоящее время не поддерживается.

В следующем примере загружается трансформерная модель [FLUX.1 DEV](https://huggingface.co/black-forest-labs/FLUX.1-dev) с использованием варианта квантования GGUF Q2_K.

Перед началом работы установите gguf в ваше окружение

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

Поскольку GGUF представляет собой формат одного файла, используйте `~FromSingleFileMixin.from_single_file` для загрузки модели и передайте [GGUFQuantizationConfig](/docs/diffusers/main/ru/api/quantization#diffusers.GGUFQuantizationConfig).

При использовании контрольных точек GGUF квантованные веса сохраняются в формате с низким потреблением памяти `dtype`(как правило, `torch.uint8`) и динамически деквантуются и приводятся к заданному `compute_dtype` во время прямого прохода каждого модуля через модель. С помощью `GGUFQuantizationConfig` можно задать `compute_dtype`.

Функции, используемые для динамической деквантизации, основаны на отличной работе, выполненной [city96](https://github.com/city96/ComfyUI-GGUF), который создал порты для PyTorch оригинальной реализации на [`numpy`](https://github.com/ggerganov/llama.cpp/blob/master/gguf-py/gguf/quants.py), выполненной [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")
```

## Использование оптимизированных CUDA-ядер с GGUF

Оптимизированные CUDA-ядра могут ускорить инференс квантованных моделей в формате GGUF примерно на 10%. Для использования этой функции требуется совместимый GPU со значением `torch.cuda.get_device_capability` больше 7 и библиотека ядер:

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

После установки установите `DIFFUSERS_GGUF_CUDA_KERNELS=true`, чтобы использовать оптимизированные ядра, когда они доступны. Обратите внимание, что CUDA-ядра могут вызывать незначительные численные различия по сравнению с исходной реализацией GGUF, что потенциально приводит к незначительным визуальным вариациям в генерируемых изображениях. Чтобы отключить использование CUDA-ядер, установите переменную окружения `DIFFUSERS_GGUF_CUDA_KERNELS=false`.

Ядра GGUF загружаются из репозитория [`Isotr0py/ggml`](https://huggingface.co/Isotr0py/ggml), издатель которого не является доверенным издателем ядер на Hub. При загрузке этого репозитория код с Hub скачивается и выполняется, поэтому Diffusers требует явного подтверждения, задав `DIFFUSERS_TRUST_REMOTE_KERNELS=true`. Подробности — в разделе [Доверие удалённым ядрам](../optimization/attention_backends#trusting-remote-kernels).

## Поддерживаемые типы квантования

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

## Конвертация в GGUF

Используйте Space ниже, чтобы конвертировать чекпоинт Diffusers в формат GGUF для инференса. Запустите конвертацию:

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

При использовании контрольных точек в формате GGUF для Diffusers обязательно нужно указать путь к `config` модели. Если конфигурация модели находится в `subfolder`, это также нужно указать.