GGUF (Model Formatı)

#GGUF #llama.cpp #Kuantizasyon #YerelLLM #Ollama #ModelFormat

Büyük dil modellerini tokenizer ve meta veriyle birlikte tek dosyada depolayan, CPU üzerinde kantizasyonlu çalıştırmaya optimize edilmiş model formatı.

GGUF (GPT-Generated Unified Format), büyük dil modellerini (LLM) tek bir dosyada saklamak ve dağıtmak için tasarlanmış ikili bir dosya biçimidir. Ağırlıklar, tokenizer yapılandırması, model mimarisi ve hiperparametreler gibi tüm bileşenler bu tek dosyada bir araya getirilir; bu sayede modeli farklı sistemlerde çalıştırmak için ek yapılandırma dosyasına gerek kalmaz. GGUF, Ağustos 2023'te llama.cpp projesi tarafından eski GGML formatının yerini almak üzere geliştirildi. GGML'in önemli bir dezavantajı vardı: model yapısı değiştiğinde önceki sürümlerle uyumsuzluk oluşuyor ve kullanıcılar dosyalarını yeniden indirmek zorunda kalıyordu. GGUF ise genişletilebilir meta veri yapısıyla geriye dönük uyumluluğu korur. Formatın en önemli özelliği niceleme (quantization) desteğidir. Niceleme, model ağırlıklarını 32 bitlik kayan nokta yerine daha az bit kullanan tam sayılarla temsil ederek dosya boyutunu ve bellek gereksinimini büyük ölçüde azaltır. Başlıca niceleme düzeyleri şunlardır: - **Q4_K_M**: 4 bit, orta ölçekli k-niceleme; kalite ile hız arasında iyi denge sağlar ve 7B modelleri için önerilen standarttır. - **Q5_K_M**: 5 bit, biraz daha yüksek doğruluk; disk alanı pahasına daha iyi çıktı üretir. - **Q8_0**: 8 bit; orijinal modele en yakın kaliteyi sunar, ancak dosya boyutu oldukça büyüktür. - **Q2_K**: 2 bit; bellek kısıtlı cihazlar için minimize edilmiş seçenek, ancak çıktı kalitesi belirgin düşer. GGUF dosyaları; llama.cpp, Ollama, LM Studio ve GPT4All gibi araçlarla sorunsuz çalışır. Bu araçlar, GGUF modellerini CPU ile çalıştırabilir, GPU katmanlarına kısmi yükleyebilir (GPU offloading) ya da Apple Silicon'ın Metal API'si aracılığıyla hızlandırabilir. Hugging Face Model Hub'da binlerce hazır GGUF dosyası barındırılmakta; topluluk tarafından dönüştürülmüş ve nicelenmiş modeller kolayca indirilebilmektedir. Alternatif formatlarla karşılaştırıldığında GGUF, taşınabilirlik açısından öne çıkar. GPTQ ve AWQ GPU odaklı niceleme formatları olduğundan CPU desteği sınırlıdır. Safetensors ise güvenli ve hızlı yükleme sunar ancak ayrı tokenizer dosyası gerektirir. GGUF'un tek dosya + CPU uyumluluğu yaklaşımı, lokal ve edge dağıtım senaryolarında onu özellikle avantajlı kılar.

GGUF Nedir?

GGUF (GPT-Generated Unified Format), büyük dil modellerini tek bir taşınabilir dosyada saklayan ikili bir formattır. Model ağırlıkları, tokenizer, mimari bilgileri ve meta veriler tek çatı altında birleştirilir.

GGML'den GGUF'a Geçiş

GGUF, Ağustos 2023'te llama.cpp projesi tarafından GGML formatının yerine geliştirildi. GGML sürüm uyumsuzluklarına eğilimliydi; GGUF ise genişletilebilir meta veri yapısı sayesinde geriye dönük uyumluluğu korur.

Niceleme Düzeyleri

GGUF'un temel avantajı esnek niceleme (quantization) desteğidir. Q4_K_M (4 bit, önerilen), Q5_K_M (5 bit, daha yüksek doğruluk), Q8_0 (8 bit, en yüksek kalite) ve Q2_K (2 bit, minimum bellek) gibi seçenekler sunulur. Her düzey, kalite ile dosya boyutu arasında farklı bir denge kurar.

Ekosistem ve Araçlar

llama.cpp, Ollama, LM Studio ve GPT4All gibi araçlar GGUF formatını destekler. Bu araçlar CPU çalıştırma, GPU offloading ve Apple Silicon Metal hızlandırması gibi seçenekler sunar. Hugging Face Model Hub'da binlerce hazır GGUF modeli barındırılmaktadır.

Alternatif Formatlarla Karşılaştırma

GPTQ ve AWQ GPU odaklı niceleme formatlarıdır; CPU desteği kısıtlıdır. Safetensors güvenli ve hızlı yükleme sağlar ancak ayrı tokenizer dosyası gerektirir. GGUF'un tek dosya + CPU uyumluluğu, lokal ve edge dağıtımda belirgin avantaj sunar.

Sıkça Sorulan Sorular

GGUF dosyası nasıl indirilir? Hugging Face Model Hub'da ilgili modeli arayıp .gguf uzantılı dosyayı indirin; Ollama veya LM Studio ile doğrudan yükleyebilirsiniz.

Hangi niceleme düzeyini seçmeliyim? Çoğu kullanım için Q4_K_M iyi bir başlangıç noktasıdır. Yüksek doğruluk gerekiyorsa Q5_K_M veya Q8_0 tercih edin.

GGUF GPU'da çalışır mı? Evet, llama.cpp ve Ollama GPU katmanlarını destekler; tam GPU yerine kısmi offloading de yapılabilir.

terminal GGUF Modelini Çalıştırma ve Kendiniz Dönüştürme

En kısa yol Ollama. 0.3.13 ve sonraki sürümler Hugging Face'teki GGUF depolarını doğrudan çalıştırır: ollama run hf.co/bartowski/Qwen2.5-7B-Instruct-GGUF:Q4_K_M. Etiket kısmına niceleme adını yazarsınız, Ollama dosyayı indirip kaydeder.

Dosyayı elle indirmek isterseniz: huggingface-cli download bartowski/Qwen2.5-7B-Instruct-GGUF --include "*Q4_K_M.gguf" --local-dir ./models (yeni sürümlerde komut hf download oldu).

Yerel dosyayı Ollama'ya tanıtmak için iki satırlık bir Modelfile yeterli: FROM ./models/Qwen2.5-7B-Instruct-Q4_K_M.gguf ve PARAMETER num_ctx 8192. Ardından ollama create qwen-yerel -f Modelfile ve ollama run qwen-yerel.

llama.cpp'yi kaynaktan derlemek daha fazla ayar imkanı verir: git clone https://github.com/ggml-org/llama.cpp sonra cmake -B build -DGGML_CUDA=ON ve cmake --build build --config Release -j. Apple Silicon'da Metal varsayılan açıktır, CUDA bayrağına gerek yoktur.

Tek seferlik soru için: ./build/bin/llama-cli -m model.gguf -ngl 99 -c 8192 --jinja -p "Soru". Buradaki -ngl GPU'ya taşınacak katman sayısıdır, 99 yazmak pratikte tümü anlamına gelir; VRAM yetmezse sayıyı düşürürsünüz.

API olarak kullanmak için: ./build/bin/llama-server -m model.gguf -ngl 99 -c 8192 --host 0.0.0.0 --port 8080. Sunucu OpenAI uyumlu /v1/chat/completions uç noktası açar, mevcut OpenAI istemcilerinizi base_url değiştirerek bağlayabilirsiniz.

Hugging Face'te GGUF sürümü yayınlanmamış bir modeli kendiniz dönüştürebilirsiniz. Önce bağımlılıkları kurun: pip install -r llama.cpp/requirements.txt.

Dönüştürme betiği safetensors klasörünü tek bir F16 dosyaya çevirir: python llama.cpp/convert_hf_to_gguf.py ./Qwen2.5-7B-Instruct --outfile qwen-f16.gguf --outtype f16. Betik tokenizer'ı ve sohbet şablonunu da meta veriye gömer, bu yüzden ayrı dosya taşımanız gerekmez.

Ardından istediğiniz düzeye nicelersiniz: ./build/bin/llama-quantize qwen-f16.gguf qwen-Q4_K_M.gguf Q4_K_M. Desteklenen düzeylerin listesini argümansız çalıştırarak görebilirsiniz.

4 bitin altına inecekseniz önem matrisi (imatrix) kalite farkı yaratır. Önce temsili bir metin dosyasıyla matris çıkarılır: ./build/bin/llama-imatrix -m qwen-f16.gguf -f kalibrasyon.txt -o imatrix.dat. Sonra niceleme bu matrisle yapılır: ./build/bin/llama-quantize --imatrix imatrix.dat qwen-f16.gguf qwen-IQ4_XS.gguf IQ4_XS. Kalibrasyon metnine hedef dilden örnek koymak Türkçe çıktı kalitesini korumaya yardım eder.

LoRA adaptörünüz varsa önce birleştirip (merge) sonra dönüştürün; llama.cpp ayrı adaptör yükleyebilse de birleştirilmiş model hem daha hızlı hem de tek dosya kalır. Büyük modelleri parçalı yazmak için llama-gguf-split --split --split-max-size 20G kullanılır.

compare_arrows 7B Modelde Niceleme Düzeyleri: Dosya Boyutu ve Bellek

  • check_circle Q2_K (2,83 GB): En küçük dosya, en yüksek kalite kaybı. 6,74B parametreli 7B sınıfı bir modelde referans boyut. Yalnızca 4 GB VRAM gibi sert bellek kısıtları varsa anlamlıdır; üretim yanıtlarında kayda değer bozulma görülür.
  • check_circle Q3_K_M (3,30 GB): Q2_K'ya göre belirgin kalite artışı, boyut yarım GB fazla. 6 GB'lık kartlarda uzun bağlamla birlikte çalışmak için makul bir taban.
  • check_circle Q4_K_M (4,08 GB): Kalite ve boyut dengesinde varsayılan tercih. 8 GB VRAM'e bağlam belleğiyle birlikte sığar. Aksi bir gereksinim yoksa 7B modellerde bununla başlayın.
  • check_circle Q5_K_M (4,78 GB): Q4_K_M'ye göre ölçülebilir ama küçük bir doğruluk kazancı, 700 MB ek boyut. 12 GB kart kullanıyorsanız bedava sayılabilecek bir yükseltme.
  • check_circle Q6_K (5,53 GB): F16'ya yakın kalite. Kod üretimi ve yapılandırılmış çıktı (JSON, fonksiyon çağrısı) gibi hata toleransı düşük işlerde tercih edilir.
  • check_circle Q8_0 (7,16 GB): Pratikte kayıpsız kabul edilir. Genelde kıyaslama referansı olarak veya daha düşük nicelemelerin kalitesini doğrulamak için kullanılır.
  • check_circle F16 (yaklaşık 13,5 GB): Niceleme yok. Dönüştürme zincirinde ara adım olarak üretilir; günlük kullanımda dosya boyutu ve bellek maliyeti gerekçelendirilmesi zor bir tercihtir.
  • check_circle Bağlam belleği payı: Yukarıdaki sayılar yalnızca ağırlıkları kapsar. KV önbelleği için 8K bağlamda 0,5 ile 2 GB arası ek bellek ayırın; 32K bağlamda bu pay birkaç GB'a çıkar. Sığmıyorsa bağlamı kısın ya da -ngl ile katmanların bir kısmını CPU'da bırakın.

bug_report Sık Karşılaşılan GGUF Hataları ve Çözümleri

  • check_circle unknown model architecture: Yeni çıkan bir mimariyi eski bir llama.cpp veya Ollama sürümü tanımaz. Çözüm: depoyu güncelleyip yeniden derleyin (git pull, cmake --build build) veya Ollama'yı son sürüme yükseltin. GGUF dosyasında sorun yoktur, okuyucu eskidir.
  • check_circle wrong number of tensors: Parçalı yayınlanmış bir modelin yalnızca bir dosyası indirilmiştir. Çözüm: 00001-of-0000N ile biten tüm parçaları aynı klasöre indirin ve ilk parçayı -m ile verin; llama.cpp kalanları kendisi bulur. Gerekirse llama-gguf-split --merge ile tek dosyaya birleştirin.
  • check_circle Model çok yavaş çalışıyor: GPU katmanı verilmediğinde her şey CPU'da koşar. Çözüm: llama.cpp'de -ngl 99 ekleyin, sığmıyorsa sayıyı kademeli düşürün. Ollama'da Modelfile'a PARAMETER num_gpu yazarak aynı ayarı yaparsınız. Yükleme sırasındaki offloaded satırında kaç katmanın GPU'ya gittiğini görebilirsiniz.
  • check_circle Bağlam beklenenden kısa: llama.cpp varsayılan olarak modelin tam bağlamını açmaz. Çözüm: -c 8192 gibi açık bir değer verin ya da modelin eğitildiği bağlamı kullanmak için -c 0 yazın. Ollama tarafında PARAMETER num_ctx ile ayarlanır; istemciden gönderilen ayar Modelfile'ı geçersiz kılabilir.
  • check_circle Çıktı tekrarlıyor ya da rol etiketleri sızıyor: Sohbet şablonu uygulanmamıştır. Çözüm: llama-cli ve llama-server komutuna --jinja ekleyerek dosyanın içindeki şablonu kullandırın. Ayrıca base değil instruct sürümünü indirdiğinizden emin olun.
  • check_circle Bellek yetersiz hatası veya donma: Dosya mmap ile açıldığında sistem belleği dolabilir. Çözüm: --no-mmap deneyin, bir alt niceleme düzeyine inin veya bağlamı kısaltın. Toplam ihtiyaç kabaca dosya boyutu artı KV önbelleği kadardır.
  • check_circle Ollama modeli yeniden indiriyor: Modelfile'daki FROM yolu göreli verildiğinde Ollama dosyayı kendi deposuna kopyalar ve disk iki katına çıkar. Çözüm: mutlak yol kullanın ve gereksiz kopyaları ollama list ile görüp ollama rm ile temizleyin.

help Sıkça Sorulan Sorular

  • check_circle GGUF dosyası nasıl çalıştırılır? En hızlı yol Ollama: ollama run hf.co/kullanici/depo-GGUF:Q4_K_M komutu dosyayı indirir ve sohbeti başlatır. Yerel bir dosyanız varsa iki satırlık Modelfile (FROM ile dosya yolu) yazıp ollama create ile kaydedersiniz. llama.cpp tarafında llama-cli tek seferlik soru için, llama-server ise OpenAI uyumlu bir API açmak için kullanılır.
  • check_circle Hangi niceleme düzeyini seçmeliyim? 7B sınıfı bir modelde Q4_K_M (yaklaşık 4,1 GB) kalite ve boyut dengesinde varsayılan tercihtir. 12 GB veya üstü VRAM varsa Q5_K_M veya Q6_K'ya çıkmak küçük ama ölçülebilir bir doğruluk kazancı verir. 4 bitin altına yalnızca bellek gerçekten sıkıştığında inin, kalite kaybı belirginleşir.
  • check_circle Safetensors modelini GGUF'a nasıl çeviririm? llama.cpp deposundaki convert_hf_to_gguf.py betiği model klasörünü tek bir F16 GGUF dosyasına çevirir, ardından llama-quantize ile istediğiniz düzeye nicelersiniz. 4 bitin altına inecekseniz önce llama-imatrix ile önem matrisi çıkarıp niceleme sırasında --imatrix ile verin.
  • check_circle GGUF mu safetensors mı, hangisi ne zaman? Tek kullanıcılı yerel çalıştırmada, CPU veya karışık CPU artı GPU kurulumlarında GGUF daha uygundur: tek dosya, düşük bellek, geniş araç desteği. Sunucuda çoklu eşzamanlı istek servis edecekseniz vLLM veya SGLang ile safetensors ağırlıkları kullanmak toplu işlem sayesinde belirgin şekilde daha yüksek verim verir.
  • check_circle GGUF modeli sadece CPU ile çalışır mı? Evet, GGUF'un ana tasarım hedeflerinden biri budur. GPU olmadan da çalışır, hız çekirdek sayısına ve bellek bant genişliğine bağlıdır. -ngl parametresiyle katmanların bir kısmını GPU'ya taşıyıp geri kalanını CPU'da bırakmak da mümkündür, bu karışık mod düşük VRAM'li makinelerde en pratik çözümdür.