Transformers documentation

HQQ

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

HQQ

Half-Quadratic Quantization (HQQ) tối ưu hóa các tham số lượng tử hóa chỉ từ trọng số, do đó không cần dữ liệu hiệu chuẩn. Hãy sử dụng nó để lượng tử hóa mô hình xuống còn 1 hoặc 2 bit trong khi tải.

Bảng dưới đây tóm tắt những gì HQQ hỗ trợ trong Transformers.

Cấu hìnhHqqConfig
quant_methodhqq
Quy trình làm việcLượng tử hóa khi tải
Bits1, 2, 3, 4, 8
Phần cứngCUDA, XPU
Lưu✅
Tinh chỉnh✅
Tự động biên dịch❌

Cài đặt HQQ

Cài đặt hqq 0.2.1 hoặc mới hơn.

pip install -U hqq

Lượng tử hóa một mô hình bằng HQQ

Tạo một HqqConfig và truyền nó vào from_pretrained(). Ví dụ bên dưới lượng tử hóa mọi lớp tuyến tính xuống 4 bit theo các nhóm 64 trọng số.

import torch
from transformers import AutoModelForCausalLM, HqqConfig

quantization_config = HqqConfig(nbits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    quantization_config=quantization_config,
    device_map="cuda",
)

Cấu hình HQQ

Các tham số HqqConfig này thay đổi cách các trọng số được lượng tử hóa.

Tham sốMặc địnhHiệu ứng
nbits4Số bit cho mỗi trọng số. Hỗ trợ 8, 4, 3, 2 và 1.
group_size64Số lượng trọng số chia sẻ một thang đo và một điểm không. Các nhóm nhỏ hơn sẽ chính xác hơn và sử dụng nhiều bộ nhớ hơn.
axis1Trục để nhóm trọng số, có thể là 0 hoặc 1. Các backend torchao và BitBlas nhanh hơn chỉ hoạt động với 1.
view_as_floatFalseLưu trữ các trọng lượng đã lượng tử hóa dưới dạng kiểu float, dành cho huấn luyện phân tán.
skip_modules["lm_head"]Các loại lớp không thực hiện lượng tử hóa.

Lượng tử hóa các kiểu lớp với các cài đặt khác nhau

Truyền dynamic_config để lượng hóa từng loại lớp tuyến tính với các cài đặt riêng. Mỗi khóa là một nhãn lớp, tên module với model, layers và số thứ tự lớp đã bị loại bỏ. Ví dụ, model.layers.3.self_attn.q_proj có nhãn self_attn.q_proj.

Ví dụ dưới đây lượng tử hóa các phép chiếu attention xuống 4 bit và các phép chiếu MLP xuống 3 bit.

q4_config = {"nbits": 4, "group_size": 64}
q3_config = {"nbits": 3, "group_size": 32}
quantization_config = HqqConfig(dynamic_config={
    "self_attn.q_proj": q4_config,
    "self_attn.k_proj": q4_config,
    "self_attn.v_proj": q4_config,
    "self_attn.o_proj": q4_config,
    "mlp.gate_proj": q3_config,
    "mlp.up_proj": q3_config,
    "mlp.down_proj": q3_config,
})

Một tag được áp dụng cho loại layer đó trong mọi decoder layer, do đó bạn không thể đặt cấu hình khác nhau cho một decoder layer so với các layer khác. Các layer Linear có tag không có trong dynamic_config sẽ không bị lượng tử hóa. Các tag tương tự được sử dụng để khớp với skip_modules.

Chọn một backend

HQQ chạy các lớp đã lượng tử hóa thông qua một backend từ thư viện hqq. Các backend PyTorch và CUDA hoạt động với fine-tuning PEFT và các GPU đời cũ. Chuyển đổi backend bằng HQQLinear.set_backend.

from hqq.core.quantize import HQQBackend, HQQLinear

HQQLinear.set_backend(HQQBackend.PYTORCH)

Để suy luận 4-bit nhanh hơn, hãy chuyển đổi mô hình đã lượng tử hóa sang backend kernel đã hợp nhất, chẳng hạn như torchao, sau khi tải nó. Backend torchao cần axis=1, đây là giá trị mặc định.

from hqq.utils.patching import prepare_for_inference

prepare_for_inference(model, backend="torchao_int4")

Xem hướng dẫn Backend của hqq để biết các backend khả dụng.

Hạn chế

  • HQQ không thể offload sang CPU hoặc disk. Việc tải với device_map bao gồm "cpu" hoặc "disk" sẽ gây ra ValueError.
  • Layer tags không thể nhắm vào một lớp decoder cụ thể, do đó dynamic_config và skip_modules được áp dụng cho một loại lớp trên toàn bộ mô hình.

Tài nguyên

Update on GitHub