Transformers documentation
GGUF
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