GGUF
GGUF là định dạng một tệp mà llama.cpp dùng để lưu trọng số, tokenizer và metadata của LLM, thường được lượng tử hóa xuống 4–8 bit để chạy trên phần cứng cục bộ.
GGUF là định dạng tệp nhị phân dùng để lưu model chạy trên GGML, thư viện tensor C đứng sau llama.cpp, và các công cụ được xây dựng trên thư viện này. Một tệp GGUF chứa mọi thứ cần thiết để chạy một mô hình ngôn ngữ lớn (LLM): kiến trúc và siêu tham số, từ vựng tokenizer, mẫu hội thoại và trọng số model, thường được nén bằng lượng tử hóa model xuống còn 2 đến 8 bit mỗi trọng số. Dự án llama.cpp giới thiệu GGUF vào tháng 8 năm 2023 để thay thế các định dạng GGML, GGMF và GGJT trước đó; GGUF đã trở thành cách tiêu chuẩn để chia sẻ các model có trọng số mở cho suy luận cục bộ trên CPU của laptop, máy Mac Apple Silicon hoặc GPU phổ thông, với hàng nghìn kho GGUF trên Hugging Face.
Bên trong tệp GGUF#
Đặc tả GGUF quy định bốn phần theo thứ tự. Phần header chứa các byte magic GGUF, phiên bản định dạng (hiện là 3) và số lượng tensor cùng mục siêu dữ liệu. Tiếp theo là siêu dữ liệu khóa-giá trị có kiểu, chẳng hạn general.architecture, llama.context_length, tokenizer.ggml.tokens và tokenizer.chat_template, nhúng tokenization và định dạng prompt của model ngay trong tệp. Sau đó là bảng liệt kê tên, hình dạng, kiểu dữ liệu và độ lệch của từng tensor; dữ liệu tensor nằm cuối cùng, mặc định được đệm đến căn chỉnh 32 byte để runtime có thể ánh xạ tệp vào bộ nhớ và tải gần như tức thì. Trình đọc tra cứu siêu dữ liệu theo khóa, nhờ đó có thể bổ sung kiến trúc và trường mới mà không làm hỏng các tệp cũ.
Mỗi tensor có kiểu riêng, vì vậy một tệp có thể kết hợp nhiều độ chính xác. Gói Python gguf, được duy trì trong kho llama.cpp, ghi và đọc định dạng này, đồng thời triển khai một số kiểu lượng tử hóa:
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")Phần này liệt kê hai khóa siêu dữ liệu general.architecture và llama.context_length, sau đó báo cáo 16.0 bit mỗi trọng số với sai số trung bình 0.0001 cho F16, 8.5 bit và 0.0045 cho Q8_0, cùng 4.5 bit và 0.0719 cho Q4_0. Q8_0 và Q4_0 lưu các khối gồm 32 trọng số với một hệ số tỷ lệ FP16 cho mỗi khối, tạo ra phần nửa bit bổ sung.
Các kiểu lượng tử hóa#
Các kiểu lượng tử hóa của GGUF thuộc ba thế hệ. Các định dạng khối ban đầu như Q4_0 và Q8_0 dùng một hệ số tỷ lệ cho mỗi 32 trọng số. Các kiểu lượng tử hóa K như Q4_K và Q6_K nhóm khối thành siêu khối gồm 256 trọng số với hệ số tỷ lệ được lượng tử hóa; tên tệp như Q4_K_M đánh dấu một kiểu kết hợp giữ các tensor nhạy nhất ở độ chính xác cao hơn. Các kiểu lượng tử hóa I như IQ2_XXS và IQ4_XS đạt khoảng 2 đến 4 bit mỗi trọng số, thường được định hướng bằng ma trận độ quan trọng mà llama-imatrix tính từ văn bản mẫu để các trọng số có ảnh hưởng lớn nhất giữ được độ chính xác cao nhất. Các bổ sung mới hơn gồm MXFP4, định dạng dấu phẩy động 4 bit mà OpenAI dùng để phát hành gpt-oss. Hầu hết tệp GGUF đã công bố đều được tạo từ cùng một quy trình chuyển đổi:
GGUF so với các định dạng model khác#
- GGML, GGMF và GGJT: Các định dạng llama.cpp trước đây lưu siêu tham số dưới dạng danh sách không định kiểu, không có trường kiến trúc, vì vậy việc thêm một tham số sẽ làm hỏng các tệp hiện có.
- Safetensors: Định dạng của Hugging Face để lưu tensor thô an toàn, thường ở độ chính xác đầy đủ hoặc một nửa, trong khi cấu hình và tokenizer được lưu trong các tệp riêng.
- ONNX: Lưu toàn bộ đồ thị tính toán cùng với trọng số, nhờ đó mọi runtime tương thích với ONNX đều có thể thực thi model mà không cần mã dành riêng cho kiến trúc.
Chạy model GGUF#
llama.cpp chạy tệp GGUF từ dòng lệnh hoặc dưới dạng llama-server, cung cấp API tương thích với OpenAI; công cụ này có thể chuyển bất kỳ số lớp nào sang GPU trong khi các lớp còn lại chạy trên CPU, nhờ đó model lớn hơn bộ nhớ GPU vẫn có thể chạy. Ollama và LM Studio chạy model GGUF thông qua thư viện model và giao diện chat, còn Hugging Face Hub hiển thị siêu dữ liệu và kiểu tensor của từng tệp GGUF trong trình duyệt. Suy luận cục bộ giữ prompt trên máy, điều quan trọng đối với quyền riêng tư dữ liệu và các trường hợp sử dụng AI biên ngoại tuyến. Giao diện LLM của Ultralytics có thể gọi model GGUF được cung cấp bởi llama-server hoặc Ollama thông qua các endpoint Chat Completions tương thích với OpenAI của chúng, nhờ đó quy trình YOLO26 có thể yêu cầu model cục bộ mô tả các đối tượng được phát hiện mà không gửi dữ liệu đến API đám mây. Định dạng này còn mở rộng ra ngoài các model ngôn ngữ: các node tùy chỉnh ComfyUI-GGUF tải các model khuếch tán đã lượng tử hóa như FLUX.1 từ tệp GGUF để chúng vừa với bộ nhớ của GPU phổ thông.










