Transformers documentation

GGUF

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

GGUF

GGUF là định dạng tệp đơn được sử dụng để lưu trữ các mô hình cho suy luận với GGML, bao gồm metadata và các tensor của mô hình. Định dạng này hỗ trợ nhiều kiểu dữ liệu lượng tử hóa (xem bảng kiểu lượng tử hóa), giúp tiết kiệm đáng kể bộ nhớ.

Tải các mô hình GGUF

Cài đặt kernels, nếu không đường dẫn đóng gói sẽ quay về dequantization đầy đủ khi tải.

pip install kernels

Trọng số vẫn được giữ ở dạng nén khi kernel Hub ggml-org/ggml-quantization khả dụng. Trình nạp mặc định sử dụng MPS khi kernel đó có mặt và thực hiện các phép nhân ma trận trực tiếp trên các khối đã nén. Nếu kernel không khả dụng, mô hình sẽ được khử lượng tử hóa khi nạp.

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "unsloth/Qwen3.5-4B-GGUF"
filename = "Qwen3.5-4B-Q4_K_M.gguf"

model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)
tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)

Cùng một lệnh load này cũng hoạt động với Qwen3.5 MoE.

moe_model_id = "unsloth/Qwen3.5-35B-A3B-GGUF"
moe_filename = "Qwen3.5-35B-A3B-Q4_K_M.gguf"

moe_model = AutoModelForCausalLM.from_pretrained(moe_model_id, gguf_file=moe_filename)
moe_tokenizer = AutoTokenizer.from_pretrained(moe_model_id, gguf_file=moe_filename)

Đường dẫn đóng gói hiện hỗ trợ Qwen3.5 và Qwen3.5 MoE. Việc nạp đóng gói tự động sử dụng float32 vì nó nhanh hơn trên MPS. Nếu bạn đặt một dtype khác, trình nạp sẽ trả về một cảnh báo. Các kiến trúc khác sẽ đi qua trình nạp kế thừa.

Chú ý

Trên MPS, khi đã cài đặt các kernel, ggml-attn là cơ chế attention mặc định khi tải tệp GGUF: cùng kernel flash-attention mà llama.cpp sử dụng cho decode và prefill. Nếu không thể tải kernel, mô hình sẽ giữ nguyên cách triển khai attention của nó. Việc truyền attn_implementation (ví dụ "sdpa") luôn có ưu tiên cao hơn.

Bạn cũng có thể truyền nó một cách tường minh:

model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, attn_implementation="ggml-org/ggml-attn"
)

Khử lượng tử

Dequantizing giải nén mọi trọng số tại thời điểm tải và trả về một mô hình dense thông thường. Đây là phương án dự phòng cho mọi trường hợp mà con đường nén nhanh không áp dụng được. Bạn cũng có thể yêu cầu nó một cách rõ ràng bằng GgufConfig.

import torch

from transformers import AutoModelForCausalLM, GgufConfig

quantization_config = GgufConfig(dequantize=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, quantization_config=quantization_config, dtype=torch.bfloat16
)

Bạn sẽ nhận được một mô hình dense thông thường với dtype mà bạn đã truyền vào.

Các kiến trúc khác ngoài Qwen3.5 và Qwen3.5 MoE sẽ đi qua trình nạp (loader) cũ, luôn thực hiện khử lượng tử hóa (dequantize).

Trình nạp cũ hỗ trợ Llama, Mistral, Qwen2, Qwen2Moe, Phi3, Bloom, Falcon, StableLM, GPT2, Starcoder2 và nhiều hơn.

Cung cấp

transformers serve liệt kê mỗi tệp .gguf trong một kho lưu trữ như một mô hình riêng biệt. Một mô hình GGUF được đặt tên là <repo>:<file>.gguf, vì một kho lưu trữ chứa nhiều bản lượng tử hóa và id phải chỉ rõ bản nào cần tải. Các yêu cầu cũng gọi tên mô hình theo cách tương tự.

transformers serve unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf
Update on GitHub