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 cuantiza un modelo capa por capa y utiliza un pequeño conjunto de datos de calibración para actualizar los pesos restantes de modo que compensen el error de redondeo de cada capa. Transformers ejecuta GPTQ a través de Optimum y la biblioteca GPT-QModel. Úsalo para cuantizar un modelo a 2 a 8 bits con calibración mientras se carga, o para cargar uno de los muchos puntos de control GPTQ en el Hub.

La tabla siguiente resume lo que GPTQ admite en Transformers.

ConfigGPTQConfig
quant_methodgptq
Flujo de trabajoCuantizar al cargar, con calibración
Bits2, 3, 4, 8
HardwareCUDA, XPU, CPU
Guardar✅
Ajuste fino✅
Compilación automática❌

Instalar GPTQ

Instale Optimum 1.24.0 o posterior y GPT-QModel 1.4.3 o posterior.

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

Cuantizar un modelo con GPTQ

Cree una GPTQConfig con un dataset para la calibración y pásela a from_pretrained(). Los pesos se cuantizan después de cargarlos. GPTQ recomienda fp16, por lo que el ejemplo siguiente establece 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 es obligatorio para cuantizar un modelo. Pasa el nombre de un conjunto de datos del artículo de GPTQ, "wikitext2", "c4" o "c4-new", o una lista de cadenas de texto. El tokenizer prepara el conjunto de datos. Si no pasas uno, GPTQ carga el tokenizer desde el repositorio del modelo.

Calibration ejecuta el modelo bloque por bloque, por lo que tarda mucho más que la carga. Antes de cuantizar un modelo, compruebe en el Hub si existe un checkpoint GPTQ existente.

Cargar un punto de control de GPTQ

Pase el checkpoint a from_pretrained() sin un GPTQConfig. Transformers lee la configuración de cuantización desde la configuración del checkpoint.

from transformers import AutoModelForCausalLM

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

Para cambiar el tamaño del kernel o del buffer, pase un GPTQConfig con el nuevo backend o max_input_length. Transformers solo sobrescribe estos dos atributos de carga y mantiene el resto de la configuración del checkpoint.

Configurar GPTQ

Estos parámetros de GPTQConfig modifican cómo se cuantizan los pesos. Consulte GPTQConfig para el resto.

ParámetroPredeterminadoEfecto
bitsobligatorioNúmero de bits por peso. Admite 2, 3, 4 y 8.
group_size128Número de pesos que comparten una escala. -1 utiliza una escala por columna.
damp_percent0.1Fracción de la diagonal de la Hessiana promedio que se añade para la estabilidad numérica. Debe estar entre 0 y 1.
desc_actFalseCuantiza las columnas en orden de tamaño de activación decreciente (act-order). Puede mejorar la precisión y ralentizar la inferencia. Establecerlo en True desactiva act_group_aware.
symTrueUtiliza cuantización simétrica. Establezca False para cuantización asimétrica.
modules_in_block_to_quantizeNoneListas de nombres de módulos en cada bloque a cuantizar, en orden. Las capas lineales no incluidas en la lista permanecen sin cuantizar. Con el valor predeterminado, se cuantiza cada capa lineal del bloque. Requiere Optimum 1.15.0 o posterior.

Elija un backend de kernel

GPT-QModel ejecuta las capas cuantizadas a través de uno de varios kernels. El parámetro backend selecciona uno y su valor predeterminado es "auto", lo que permite que GPT-QModel elija un kernel para su hardware y checkpoint. El ejemplo siguiente carga un checkpoint con el kernel 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",
)

Consulte la lista de backends de GPT-QModel para ver los valores disponibles.

Limitaciones

  • GPTQ solo admite modelos de texto. Cargar un modelo cuya entrada principal no sea input_ids provoca un RuntimeError.
  • Cuantizar un modelo con descargado en disco en su device_map genera un ValueError.
  • Cargar sin GPT-QModel instalado provoca un ImportError. AutoGPTQ no es compatible.
  • Sin un device_map, el modelo se carga en la CPU.

Recursos

Update on GitHub