# GGUF

GGUF 文件格式通常用于存储供 [GGML](https://github.com/ggerganov/ggml) 进行推理的模型，并支持多种按块量化的选项。Diffusers 支持通过 Model 类使用 `from_single_file` 加载以 GGUF 格式预先量化并保存的检查点。目前尚不支持通过 Pipelines 加载 GGUF 检查点。

以下示例将使用 GGUF Q2_K 量化变体加载 [FLUX.1 DEV](https://huggingface.co/black-forest-labs/FLUX.1-dev) transformer 模型。

在开始之前，请在您的环境中安装 gguf

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

由于 GGUF 是一种单文件格式，请使用 `~FromSingleFileMixin.from_single_file` 加载模型，并传入 [GGUFQuantizationConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.GGUFQuantizationConfig)。

使用 GGUF 检查点时，量化权重会保持在低内存 `dtype`（通常为 `torch.uint8`）中，并在模型中每个模块的前向传播过程中动态反量化并转换为配置的 `compute_dtype`。`GGUFQuantizationConfig` 允许你设置 `compute_dtype`。

用于动态反量化的函数基于 [city96](https://github.com/city96/ComfyUI-GGUF) 的出色工作，他创建了由 [compilade](https://github.com/compilade) 编写的原始 [`numpy`](https://github.com/ggerganov/llama.cpp/blob/master/gguf-py/gguf/quants.py) 实现的 PyTorch 移植版本。

```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，并安装 kernels 库：

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

安装完成后，设置 `DIFFUSERS_GGUF_CUDA_KERNELS=true` 以在可用时使用优化内核。请注意，与原始 GGUF 实现相比，CUDA 内核可能会引入微小的数值差异，从而导致生成图像出现细微的视觉变化。若要禁用 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")
```

使用 Diffusers 格式的 GGUF 检查点时，必须提供模型的 `config` 路径。如果模型配置位于某个 `subfolder` 中，也需要指定该子文件夹。