Transformers documentation

GPTQ

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

GPTQ

GPTQ 逐层量化模型,并使用小型校准数据集更新剩余权重,以补偿每层的舍入误差。Transformers 通过 Optimum 和 GPT-QModel 库来运行 GPTQ。您可以使用它在加载模型时对其进行带校准的 2 到 8 位量化,或者加载 Hub 上的众多 GPTQ 检查点之一。

下表总结了 GPTQ 在 Transformers 中的支持情况。

配置GPTQConfig
quant_methodgptq
工作流加载时量化,并进行校准
位2, 3, 4, 8
硬件CUDA、XPU、CPU
保存✅
微调✅
自动编译❌

安装 GPTQ

安装 Optimum 1.24.0 或更高版本以及 GPT-QModel 1.4.3 或更高版本。

pip install -U "optimum>=1.24.0"
pip install -U "gptqmodel>=1.4.3" --no-build-isolation

使用 GPTQ 量化模型

创建一个 GPTQConfig 并指定用于校准的 dataset,然后将其传递给 from_pretrained()。权重在加载后会被量化。由于 GPTQ 建议使用 fp16,因此下面的示例设置了 dtype=torch.float16。

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, GPTQConfig

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
quantization_config = GPTQConfig(bits=4, dataset="c4", tokenizer=tokenizer)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    quantization_config=quantization_config,
    dtype=torch.float16,
    device_map="auto",
)

dataset 是量化模型所必需的参数。请传入 GPTQ 论文中数据集的名称,例如 "wikitext2"、"c4" 或 "c4-new",或者传入一个字符串列表。tokenizer 会负责准备数据集。如果未传入,GPTQ 将从模型的仓库中加载 tokenizer。

Calibration 会逐块运行模型,因此耗时远长于加载。在量化模型之前,请先在 Hub 上检查是否已有现成的 GPTQ 检查点。

加载 GPTQ 检查点

将检查点传递给 from_pretrained(),且不提供 GPTQConfig。Transformers 会从检查点的 config 中读取量化设置。

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct-GPTQ-Int4",
    device_map="auto",
)

若要更改内核或缓冲区大小,请传入一个包含新的 backend 或 max_input_length 的 GPTQConfig。Transformers 仅覆盖这两个加载属性,并保留检查点中的其余设置。

配置 GPTQ

这些 GPTQConfig 参数会改变权重的量化方式。其余参数请参阅 GPTQConfig。

参数默认效果
bits必需每个权重的位数。支持 2、3、4 和 8。
group_size128共享一个缩放因子的权重数量。-1 表示每列使用一个缩放因子。
damp_percent0.1为数值稳定性而添加到平均 Hessian 对角线上的比例。必须在 0 和 1 之间。
desc_actFalse按激活大小降序对列进行量化(act-order)。这可以提高精度,但会减慢推理速度。将其设置为 True 会关闭 act_group_aware。
symTrue使用对称量化。设置为 False 以使用非对称量化。
modules_in_block_to_quantizeNone按顺序列出每个块中需要量化的模块名称列表。未列出的线性层将保持未量化状态。默认情况下,块中的每个线性层都会被量化。需要 Optimum 1.15.0 或更高版本。

选择内核后端

GPT-QModel 通过若干内核之一来运行量化层。backend 参数用于选择其中一个内核,默认值为 "auto",这会让 GPT-QModel 根据您的硬件和检查点自动选择一个内核。下面的示例使用 ExLlamaV2 内核加载检查点。

from gptqmodel import BACKEND
from transformers import AutoModelForCausalLM, GPTQConfig

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct-GPTQ-Int4",
    quantization_config=GPTQConfig(bits=4, backend=BACKEND.EXLLAMA_V2),
    device_map="auto",
)

请参阅 GPT-QModel 的 后端列表 以获取可用值。

局限性

  • GPTQ 仅支持文本模型。加载主要输入不是 input_ids 的模型会引发 RuntimeError。
  • 在 device_map 中启用磁盘卸载的模型进行量化时,会引发 ValueError。
  • 在未安装 GPT-QModel 的情况下加载会引发 ImportError。不支持 AutoGPTQ。
  • 如果没有 device_map,模型将加载到 CPU 上。

资源

Update on GitHub