diffusers/v0.43.0/zh/quantization/gguf.md

GGUF

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

以下示例将使用 GGUF Q2_K 量化变体加载 FLUX.1 DEV transformer 模型。

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

pip install -U gguf

由于 GGUF 是一种单文件格式，请使用 ~FromSingleFileMixin.from_single_file 加载模型，并传入 GGUFQuantizationConfig。

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

用于动态反量化的函数基于 city96 的出色工作，他创建了由 compilade 编写的原始 numpy 实现的 PyTorch 移植版本。

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 库：

pip install -U kernels

安装完成后，设置 DIFFUSERS_GGUF_CUDA_KERNELS=true 以在可用时使用优化内核。请注意，与原始 GGUF 实现相比，CUDA 内核可能会引入微小的数值差异，从而导致生成图像出现细微的视觉变化。若要禁用 CUDA 内核，请将环境变量设置为 DIFFUSERS_GGUF_CUDA_KERNELS=false。

GGUF 内核从 Isotr0py/ggml 仓库下载，该仓库的发布者并非 Hub 上受信任的内核发布者。加载它会从 Hub 下载并执行代码，因此 Diffusers 要求您通过设置 DIFFUSERS_TRUST_REMOTE_KERNELS=true 来明确选择加入。有关详细信息，请参阅 信任远程内核。

支持的量化类型

• 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 格式以进行推理。运行转换：