Thư viện Transformers giờ đây hỗ trợ chạy trực tiếp mô hình GGUF với hiệu suất tiệm cận llama.cpp

Chúng tôi đang bổ sung hỗ trợ để chạy các mô hình GGUF một cách hiệu quả trong transformers, nhờ đó bạn có thể sử dụng các checkpoint có kích thước phù hợp với bộ nhớ máy tính xách tay của mình thông qua các API transformers quen thuộc. Hãy chọn một tệp GGUF từ Hub, tải nó bằng from_pretrained và bắt đầu tạo nội dung trên chính máy tính của bạn.

Việc chạy các mô hình AI trên máy tính xách tay đã trở nên dễ dàng hơn nhiều và llama.cpp đóng một vai trò quan trọng trong đó. Công cụ suy luận (inference engine) của nó cung cấp sức mạnh cho các công cụ AI cục bộ như Ollama, LM Studio và Jan. Cùng với các dự án như MLX, nó đã giúp việc suy luận cục bộ trở thành một lựa chọn thiết thực cho nhu cầu sử dụng hàng ngày.

Một ví dụ gần đây về trải nghiệm AI cục bộ:

Đây là nơi chúng ta đang đứng ở thời điểm hiện tại. Và tôi sẽ không nói dối đâu, cảm giác thực sự rất kỳ diệu 🧙‍♀️

Qwen3.6 27B đang chạy bên trong tác nhân lập trình Pi thông qua Llama.cpp trên MacBook Pro.

Đối với các tác vụ không tầm thường trên các cơ sở mã @huggingface, trải nghiệm này rất, rất gần với việc đạt được hiệu năng của Opus mới nhất trong Claude… pic.twitter.com/lsIxLoUneU

GGUF, được phát triển bởi đội ngũ llama.cpp, là định dạng được sử dụng rộng rãi cho suy luận cục bộ. Đội ngũ này cũng chia sẻ các checkpoint đã được lượng tử hóa (quantized) dưới tên ggml-org trên Hub. Các nhà xuất bản như Unsloth, LM Studio Community và bartowski cũng cung cấp các checkpoint GGUF sẵn sàng sử dụng với nhiều mức lượng tử hóa khác nhau, để người dùng có thể chọn phiên bản phù hợp với máy tính của mình. Các mô hình GGUF đã được tải xuống hàng triệu lần.

Chúng tôi cũng muốn giúp việc chạy các mô hình này cục bộ với transformers trở nên dễ dàng hơn. Khả năng tương thích chỉ hữu ích nếu mô hình chạy mượt mà. Để mang lại hiệu suất gần với llama.cpp, chúng tôi đang tái sử dụng các nhân (kernels) ggml nền tảng của nó thông qua thư viện kernels và giảm bớt chi phí xử lý trong quá trình generate. Trọng tâm ban đầu của chúng tôi là suy luận cục bộ trên Apple Silicon, bắt đầu với kiến trúc Qwen3.5.

Định dạng tệp GGUF là gì?

GGUF đóng gói trọng số mô hình và siêu dữ liệu (metadata), bao gồm thông tin tokenizer và một chat template tùy chọn, vào trong một tệp duy nhất. Nó hỗ trợ các mức lượng tử hóa khác nhau, cho phép bạn đánh đổi một phần độ chính xác để có dung lượng bộ nhớ nhỏ hơn. Các biến thể như Q4_K_M kết hợp các độ chính xác tensor, chủ yếu sử dụng trọng số 4-bit trong khi vẫn giữ các tensor nhạy cảm ở độ chính xác cao hơn.

Dưới đây là cách lượng tử hóa thay đổi kích thước tệp của mô hình Qwen3.5-4B từ Unsloth:

Chúng tôi khuyên bạn nên bắt đầu với Q4_K_M, sau đó thử Q5_K_M hoặc Q6_K nếu bạn có nhiều bộ nhớ hơn. Lượng tử hóa mạnh hơn có thể giúp các mô hình lớn hơn vừa với bộ nhớ, nhưng sự đánh đổi về chất lượng phụ thuộc vào mô hình và tác vụ. Hãy đánh giá nó dựa trên công việc thực tế mà bạn muốn mô hình thực hiện. Tài liệu GGUF trên Hub mô tả các loại lượng tử hóa khả dụng.

Tải GGUF với transformers

Để bắt đầu, bạn cần:

Để tải một mô hình GGUF, hãy truyền model_id trên Hub và tên tệp của nó dưới dạng gguf_file vào hàm from_pretrained.

Không cần cấu hình bổ sung: khi các trọng số vẫn được đóng gói trên Metal, transformers sẽ tự động tải các nhân lớp ggml/Metal tương thích và sử dụng ggml-org/ggml-attn làm cơ chế thực thi attention. Nếu nhân đó không thể được tìm thấy, mô hình sẽ quay lại sử dụng "sdpa" kèm theo cảnh báo, và bạn luôn có thể ép buộc sử dụng "sdpa" bằng cách truyền tham số attn_implementation="sdpa" một cách rõ ràng. Xem tài liệu GGUF để biết thêm các tùy chọn tải.

Đó là bước duy nhất dành riêng cho GGUF. Mọi thứ sau đó đều là API transformers tiêu chuẩn:

Nếu không có nhân lượng tử hóa tương thích, trình tải sẽ quay lại giải lượng tử hóa (dequantize) mô hình và sử dụng nhiều bộ nhớ hơn.

Phục vụ (Serve) GGUF với giao diện ưa thích của bạn

Bạn cũng có thể sử dụng cùng một checkpoint với transformers serve, vốn cung cấp một API tương thích với OpenAI:

Đối số model sử dụng định dạng <model_id>:<filename>.gguf: trước dấu hai chấm là kho lưu trữ trên Hub (unsloth/Qwen3.5-4B-GGUF), và sau đó là tệp cần tải (Qwen3.5-4B-Q4_K_M.gguf). Điều này giúp chọn một mức lượng tử hóa cụ thể từ một kho lưu trữ có thể chứa nhiều phiên bản.

Đối với các mô hình có chat template hỗ trợ suy luận (thinking), hãy thêm --reasoning off để bỏ qua hoặc --reasoning on để kích hoạt. Mặc định là --reasoning auto, tuân theo thiết lập mặc định của chat template. Xem các tùy chọn suy luận để biết chi tiết.

Bạn có thể kết nối một client như Jan hoặc Pi bằng cách thêm một nhà cung cấp tương thích OpenAI tùy chỉnh với các cài đặt sau:

transformers chạy mô hình trên máy Mac của bạn, trong khi client cung cấp giao diện hội thoại. Cùng một endpoint đó có thể được sử dụng bởi các client khác hỗ trợ API này.

So sánh hiệu năng với llama.cpp

Tham chiếu của chúng tôi về hiệu suất suy luận cục bộ là llama.cpp. Sự so sánh dưới đây tập trung vào ba checkpoint GGUF: một mô hình dense nhỏ, một mô hình dense lớn hơn và một mô hình mixture-of-experts.

Cột llama.cpp lấy từ công cụ llama-bench (bản build 5f55650a7, release b10200, Metal backend từ ggml 0.18.0), chạy lệnh llama-bench -m <file> -p 0 -n 128 -r 3, báo cáo chỉ số tg128: tốc độ tạo token trên 128 token đã giải mã, tính trung bình qua ba lần lặp lại, không bao gồm quá trình xử lý prompt. Cột transformers là kết quả generate tạo ra cùng 128 token từ một prompt 12 token, lấy kết quả tốt nhất trong ba lần chạy thử (warmed runs), và bao gồm cả quá trình prefill.

Được đo trên MacBook Pro M2 Max, 32 GB bộ nhớ hợp nhất (unified memory), macOS 26.6, PyTorch 2.12.1, kernels 0.17.0, đang cắm sạc.

Đối với cột còn lại:

Transformers đạt hiệu suất gần với llama.cpp trên cả ba checkpoint. Biểu đồ sử dụng các phép đo được mô tả ở trên; nó không ngụ ý các điều kiện benchmark hoàn toàn giống hệt nhau, vì phép đo của Transformers bao gồm cả prefill trong khi llama-bench chỉ báo cáo thông lượng giải mã (decode-only throughput).

transformers và llama.cpp

Khi GGML và llama.cpp gia nhập Hugging Face, chúng tôi đã mô tả vai trò bổ sung cho nhau của chúng: llama.cpp cung cấp nền tảng cho suy luận cục bộ, trong khi transformers cung cấp nền tảng cho định nghĩa mô hình. Hỗ trợ GGUF giúp đưa hai thành phần này lại gần nhau hơn.

llama.cpp vẫn là công cụ được chúng tôi khuyến nghị khi ưu tiên của bạn là suy luận cục bộ hiệu quả. Runtime chuyên dụng, quản lý bộ nhớ và khả năng hỗ trợ phần cứng rộng rãi của nó đều được xây dựng xung quanh mục tiêu đó. Sự tích hợp này mang đến cho các nhà phát triển một cách thuận tiện để làm việc với cùng các checkpoint GGUF bên trong transformers:

Đối với trường hợp cuối cùng đó, hãy sử dụng GgufConfig(dequantize=True):

Ngoài GGUF: các nhân ggml cho nhiều mô hình hơn

Cơ hội lớn hơn là mang hiệu suất của ggml đến với các mô hình mà llama.cpp không hỗ trợ.

transformers đã cung cấp các triển khai PyTorch cho các kiến trúc này. Với các nhân ggml và lược đồ lượng tử hóa có sẵn trong PyTorch, chúng ta có thể hướng tới việc tăng tốc các thao tác được hỗ trợ của chúng mà không cần phải triển khai toàn bộ mô hình trong llama.cpp trước. Điều này đặc biệt hữu ích cho các kiến trúc mới, mô hình nghiên cứu và các biến thể tùy chỉnh có thể không bao giờ nhận được bản triển khai llama.cpp chuyên dụng.

Cơ hội đó mở rộng ra ngoài chính định dạng GGUF. Một nhân (kernel) hoạt động trên các tensor; nó không yêu cầu toàn bộ mô hình phải đến từ một tệp GGUF. Các khối xây dựng tương tự có thể được tích hợp vào các mô hình transformers khác và quy trình tải. Điều này cũng mở ra con đường cho các phương thức khác: các mô hình thị giác máy tính, mô hình âm thanh và mô hình đa phương thức có thể tái sử dụng các nhân attention, chuẩn hóa và nhân ma trận tương thích mà không cần phải có bản triển khai đầy đủ trong llama.cpp trước. Mỗi kiến trúc vẫn cần được tích hợp và xác thực; các ví dụ GGUF ban đầu ở đây bao gồm việc tạo văn bản.

Suy luận cục bộ nhanh với Python và PyTorch