GGUF
GGUF, llama.cpp'nin bir LLM'nin ağırlıklarını, belirteçleyicisini ve meta verilerini depolamak için kullandığı tek dosyalı biçimdir; genellikle yerel donanım için 4-8 bite niceleme yapılır.
GGUF, llama.cpp arkasındaki C tensör kitaplığı GGML üzerinde çalışan modelleri ve bu temelin üzerine kurulu araçları depolamaya yönelik ikili dosya biçimidir. Tek bir GGUF dosyası, bir büyük dil modelini (LLM) çalıştırmak için gereken her şeyi içerir: mimariyi ve hiperparametreleri, belirteçleyici söz varlığını, sohbet şablonunu ve genellikle model niceleme ile ağırlık başına 2 ila 8 bite sıkıştırılan model ağırlıklarını. llama.cpp projesi, önceki GGML, GGMF ve GGJT biçimlerinin yerini almak üzere GGUF'yi Ağustos 2023'te kullanıma sundu. GGUF, dizüstü bilgisayar CPU'sunda, Apple Silicon Mac'te veya tüketici tipi GPU'da yerel çıkarım için açık ağırlıklı modelleri paylaşmanın standart yolu hâline geldi; Hugging Face üzerinde binlerce GGUF deposu bulunuyor.
GGUF Dosyasının İç Yapısı#
GGUF belirtimi, sırayla gelen dört bölümü tanımlar. Başlıkta sihirli baytlar GGUF, biçim sürümü (şu anda 3) ve tensörlerle meta veri girdilerinin sayısı bulunur. Ardından general.architecture, llama.context_length, tokenizer.ggml.tokens ve tokenizer.chat_template gibi türü belirlenmiş anahtar-değer meta verileri gelir; bunlar modelin belirteçlemesini ve istem biçimini dosyanın içine gömer. Sonraki tabloda her tensörün adı, şekli, veri türü ve ofseti listelenir. En son tensör verileri gelir; varsayılan olarak 32 baytlık hizalamaya kadar doldurulur, böylece çalışma zamanı dosyayı bellek eşlemeli olarak neredeyse anında yükleyebilir. Okuyucular meta verileri anahtara göre arar; bu sayede eski dosyaları bozmadan yeni mimariler ve alanlar eklenebilir.
Her tensör kendi türünü taşır; bu nedenle tek bir dosya farklı hassasiyetleri bir arada barındırabilir. llama.cpp deposunda bakımı yapılan gguf Python paketi, biçimi okuyup yazar ve çeşitli niceleme türlerini uygular:
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}")İki meta veri anahtarını, general.architecture ve llama.context_length, listeler; ardından F16 için ağırlık başına 16,0 bit ve 0,0001 ortalama hata, Q8_0 için 8,5 bit ve 0,0045, Q4_0 içinse 4,5 bit ve 0,0719 bildirir. Q8_0 ve Q4_0, her blok için bir FP16 ölçeğiyle birlikte 32 ağırlıktan oluşan blokları depolar; fazladan yarım bit buradan gelir.
Niceleme Türleri#
GGUF'nin niceleme türleri üç nesle ayrılır. Q4_0 ve Q8_0 gibi özgün blok biçimleri, her 32 ağırlık için bir ölçek kullanır. Q4_K ve Q6_K gibi K-nicelemeleri, blokları niceleme uygulanmış ölçeklerle 256 ağırlık içeren süper bloklar hâlinde gruplandırır; Q4_K_M gibi dosya adları, en hassas tensörleri daha yüksek hassasiyette tutan bir karışımı belirtir. IQ2_XXS ve IQ4_XS gibi I-nicelemeleri, genellikle llama-imatrix aracının örnek metinden hesapladığı bir önem matrisiyle yönlendirilerek ağırlık başına yaklaşık 2 ila 4 bite ulaşır; böylece en etkili ağırlıklar en yüksek hassasiyeti korur. Yeni eklemeler arasında OpenAI'nin gpt-oss'ı yayımlarken kullandığı 4 bitlik kayan nokta biçimi MXFP4 de bulunur. Yayımlanmış GGUF dosyalarının çoğu aynı dönüştürme yolundan gelir:
GGUF ve Diğer Model Biçimleri#
- GGML, GGMF ve GGJT: Önceki llama.cpp biçimleri, hiperparametreleri mimari alanı olmayan türsüz bir liste olarak saklıyordu; bu nedenle bir parametre eklemek mevcut dosyaları bozuyordu.
- Safetensors: Hugging Face'in, genellikle tam veya yarım hassasiyetteki ham tensörleri güvenli biçimde saklama formatıdır; yapılandırma ve belirteçleyici ayrı dosyalarda tutulur.
- ONNX: Ağırlıklarla birlikte hesaplama grafiğinin tamamını saklar; böylece ONNX uyumlu her çalışma zamanı, mimariye özgü kod olmadan modeli çalıştırabilir.
GGUF Modellerini Çalıştırma#
llama.cpp, GGUF dosyalarını komut satırından ya da OpenAI uyumlu bir API sunan llama-server olarak çalıştırır. Ayrıca istediğin sayıda katmanı GPU'ya aktarırken geri kalanını CPU'da çalıştırabilir; böylece GPU belleğinden büyük bir model de çalıştırılabilir. Ollama ve LM Studio, GGUF modellerini bir model kitaplığı ve sohbet arayüzü arkasında çalıştırır; Hugging Face Hub ise her GGUF dosyasının meta verilerini ve tensör türlerini tarayıcıda gösterir. Yerel çıkarım, istemleri makinede tutar; bu, veri gizliliği ve çevrimdışı uç yapay zekâ kullanımları açısından önemlidir. Ultralytics LLM arayüzü, OpenAI uyumlu Chat Completions uç noktaları üzerinden llama-server veya Ollama'nın sunduğu bir GGUF modelini çağırabilir; böylece YOLO26 işlem hattı, verileri bir bulut API'sine göndermeden yerel bir modelden algılamalarını açıklamasını isteyebilir. Biçim dil modellerinin ötesinde de kullanılır: ComfyUI-GGUF özel düğümleri, tüketici tipi GPU'ların belleğine sığmaları için FLUX.1 gibi niceleme uygulanmış difüzyon modellerini GGUF dosyalarından yükler.










