GGUF Dönüşümü: HF Modelini Yerel Çalıştırmaya Hazırlamak

Hugging Face’te yayınlanan büyük dil modelleri varsayılan olarak tam veya yarı hassasiyetli ağırlıklarla dağıtılır; bu hâliyle hem dosya boyutları büyük hem de sıradan çıkarım araçlarıyla uyumsuz olabilir. GGUF, llama.cpp ekosisteminin geliştirdiği ve yerel çıkarımın fiilî standardı hâline gelen dosya biçimidir. Bu rehber, bir Hugging Face modelinin GGUF’a dönüştürülmesini, kuantalama seviyelerinin anlamını ve doğru seviyenin nasıl seçildiğini ansiklopedik biçimde aktarır.

GGUF Biçimi Nedir

GGUF, model ağırlıklarını, mimari meta verisini ve tokenleştirici bilgisini tek bir dosyada toplayan bir kapsayıcıdır. Öncesindeki GGML biçiminin yerini almış ve dağıtım sürecini büyük ölçüde kolaylaştırmıştır: artık modeli çalıştırmak için ayrı bir tokenizer dosyası veya yapılandırma dosyası taşımak gerekmez, tek dosya yeterlidir. Biçim, kuantalanmış tamsayı ağırlıkları desteklediği için 7B sınıfı bir modeli 14 GB yerine 4 GB civarına sıkıştırabilir.

Ollama, llama.cpp, LM Studio ve Gemini’nin yerel araçları gibi yaygın çözümler GGUF dosyalarını doğrudan yükleyebilir. Bu uyumluluk, dönüşümün bir kez yapılıp her yerde kullanılabilmesini sağlar.

Ön Koşullar

Dönüşüm için üç bileşen gerekir: Python 3.9 veya üzeri bir ortam, llama.cpp deposu ve yeterli disk alanı. Disk hesabı dikkat ister; f16 hâlindeki bir 7B model yaklaşık 14 GB yer kaplar ve kuantalama sırasında hem kaynak hem hedef dosya diskte bulunur, dolayısıyla en az iki katı boş alan planlanmalıdır. Bellek açısından dönüşüm CPU üzerinde yürütülür ancak büyük modellerde RAM yetmezliği yaşanabilir; 13B ve üzeri modeller için 32 GB RAM rahat bir eşiktir.

llama.cpp deposu klonlanıp Python bağımlılıkları kurulur:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
python -m pip install -r requirements.txt

Kuantalama aracının kullanılabilmesi için llama.cpp’nin derlenmesi de gerekir; derleme seçenekleri llama.cpp optimizasyon rehberinde ayrıntılı ele alınır.

Dönüşüm Adımları

Birinci Aşama: Hugging Face Modelini GGUF’a Çevirme

1. Model, Hugging Face’ten yerel diske indirilir; huggingface-cli veya git kullanılabilir.
2. Depodaki dönüşüm betiği çalıştırılır ve çıktı f16 hassasiyetiyle üretilir:

python convert_hf_to_gguf.py /models/ornek-model --outtype f16 --outfile ornek-model-f16.gguf

3. Betik, model mimarisini tanıdığından emin olur; desteklenmeyen mimaride hata verir ve dosyayı üretmez.

Burada kritik bir ayrıntı vardır: convert_hf_to_gguf.py betiği yalnızca sınırlı bir çıktı tipi kümesini destekler; f32, f16, bf16, q8_0 ve auto gibi seçenekler sunar. Popüler kuantalama seviyeleri olan Q4_K_M veya Q5_K_M bu betikle üretilmez; bunlar ikinci aşamada ayrı bir araçla yapılır.

İkinci Aşama: Kuantalama

1. f16 dosyası, llama-quantize aracına verilir ve hedef seviye belirtilir:

./llama-quantize ornek-model-f16.gguf ornek-model-Q4_K_M.gguf Q4_K_M

2. İşlem sonunda orijinal f16 dosyası arşivlenebilir veya silinebilir.
3. Üretilen dosya llama-cli veya Ollama ile test edilerek kalite kontrolü yapılır.

Kuantalama Seviyeleri

Kuantalama, ağırlıkların düşük bit çözünürlüğünde temsil edilmesidir; her seviye dosya boyutu ile kalite arasında farklı bir denge kurar. Yaygın seviyeler şöyledir: Q8_0 yaklaşık 8,5 bit ağırlıkla neredeyse kayıpsız kabul edilir. Q6_K, 6,6 bit ile yüksek kalite sunar ve boyut artışı sınırlıdır. Q5_K_M, 5,7 bit ile dengeli bir orta noktadır. Q4_K_M, 4,8 bit ile kalite- boyut dengesinin en popüler noktasıdır; yerel toplulukta varsayılan tercih çoğunlukla budur. Q4_K_S, biraz daha küçük dosya üretir ve kalite kaybı hafiftir. Q3_K_M ve Q2_K gibi agresif seviyeler yalnızca bellek çok kısıtlıysa kullanılmalıdır; Q2 seviyesinde metin üretim kalitesinde belirgin bozulma görülür.

Ortak kalıpta _M soneki, kuantalama sırasında kritik tensörlere ekstra hassasiyet ayrılan orta (medium) varyantı belirtir; _S soneki ise küçük varyanttır.

Hangi Kuantum Ne Zaman Seçilir

Seçim üç etkenle yapılır: mevcut bellek, hedef görev ve kabul edilebilir kalite. 8 GB VRAM’li bir GPU’da 7B model için Q4_K_M ideal noktadır; model tamamen VRAM’a sığar ve hız en üst düzeye çıkar. 12-16 GB bellekte Q5_K_M veya Q6_K tercih edilerek kalite yükseltilebilir. Kod üretimi, matematik ve mantık gibi hassasiyet gerektiren görevlerde mümkün olan en yüksek seviye seçilmelidir; bu görevlerde agresif kuantaların hata oranı belirgin biçimde artar. Sohbet ve özetleme gibi daha affedici görevlerde Q4_K_M genellikle yeterlidir.

Kural olarak, donanım izin verdiği sürece daha büyük parametreli bir modelin agresif kuantalanmış hâli yerine daha küçük parametreli bir modelin yüksek kuantalı hâli tercih edilir; örneğin 14B Q4 yerine 8B Q6 çoğu durumda daha tutarlı sonuç verir. Son karar her zaman aynı görev kümesi üzerinde karşılaştırmalı testle verilmelidir.

Ollama’ya Özel GGUF Eklemek

Dönüşüm sürecinin son adımı çoğu zaman üretilen dosyayı bir çalışma ortamına kaydetmektir. Ollama, kendi kütüphanesi dışındaki GGUF dosyalarını Modelfile aracılığıyla kabul eder. Boş bir Modelfile içinde FROM satırına yerel dosyanın yolu yazılır, ardından ollama create komutuyla model kayıt altına alınır:

FROM ./ornek-model-Q4_K_M.gguf

ollama create ozel-model -f Modelfile

Bu kayıttan sonra özel model, kütüphanedeki diğer modeller gibi run, list ve rm komutlarıyla yönetilir. Dağıtım amaçlı bir kayıt defterine yükleme de mümkündür; Ollama kütüphanesindeki model sayfalarında yerel GGUF dosyalarının nasıl içe aktarılacağı ayrıntılı biçimde açıklanır. llama.cpp kullanıcıları için ise ek bir adım gerekmez; dosya doğrudan llama-cli veya llama-server’a verilir. LM Studio ve benzeri masaüstü araçları da GGUF dosyalarını model klasörüne kopyalamakla tanır. Tek biçim, çok ortam: GGUF’un en büyük pratik değeri budur.

Ölçek Karşılaştırması ve Maliyet Dengesi

Farklı seviyelerin dosya boyutu, parametre sayısıyla doğrusal ölçeklenir. Kural olarak parametre başına yaklaşık şu boyutlar hesaplanır: Q8_0 seviyesinde bir milyar parametre yaklaşık 1 GB, Q6_K seviyesinde yaklaşık 0,8 GB, Q5_K_M seviyesinde yaklaşık 0,7 GB, Q4_K_M seviyesinde ise 0,6-0,7 GB tutar. Bu oranlarla 7B modelin Q4_K_M kuantası 4-5 GB, Q8_0 kuantası ise 7-8 GB civarında çıkar. Oranlar kabadır; kelime dağarcığı boyutu ve mimari farklılıklar sonuçta küçük sapmalara yol açar, ancak planlama için yeterlidir.

Maliyet dengesi yalnızca diskte değil bellekte de geçerlidir. Bellek kullanımı, dosya boyutuna bağlam önbelleğini ekleyerek hesaplanır; uzun bağlam, dosyanın kendisinden büyük bellek talebi yaratabilir. Bu yüzden donanım planlaması yapılırken model dosyasına yüzde 15-25 pay eklenmesi sağlıklıdır. Kalite tarafında ise kayıp doğrusal değildir: Q8’den Q6’ya geçiş farkı zor fark edilirken, Q3’ten Q2’ye geçiş yanıtları görünür biçimde bozar. Yatırımın en yüksek getirisi, orta seviyelerde üstte kalan Q4_K_M ve Q5_K_M noktalarındadır; bu iki seviye, çoğu donanım için en verimli duraklardır.

Çoklu Seviye Üretimi ve Değerlendirme Düzeni

Ciddi bir dağıtım hazırlığında, tek seviyeyle yetinmeyip bir dizi kuantalama üretmek standart uygulamadır. Aynı f16 kaynaktan Q4_K_S, Q4_K_M, Q5_K_M ve Q6_K sürümleri sırayla üretilir; her biri aynı görev setiyle test edilir. Görev seti, modelin gerçek kullanım amacını yansıtmalıdır: kod tamamlama araçları için derlenebilir kod örnekleri, sohbet asistanı için doğal diyalog senaryoları, özetleyici için uzun metinler. Her sürüm, set üzerinde çalışan ölçütlerle karşılaştırılır; yanıt tutarlılığı, gerçek bilginin korunması ve şablon uyumu en sık kullanılan ölçütlerdir.

Değerlendirmede insan yargısının yanında otomatik ölçütler de kullanılabilir; bilinen doğru cevaplara yakınlık, biçim uyumu ve yanıt uzunluğu istatistikleri tabloya dökülür. Sonuç tablosu, hangi seviyenin hangi bellek bandında sunulacağına dair veriye dayalı karar sağlar. Hugging Face’te yayınlanan bağımsız kuantalama değerlendirmeleri de referans olarak kullanılabilir; ancak topluluk ölçümleri model başına değiştiği için kendi görev seti üzerindeki ölçüm her zaman birincil kaynaktır. Süreç bir kez kurulduğunda, yeni model sürümlerinin kuantalama işi tekrarlanabilir bir boru hattına dönüşür.

Yaygın Hatalar ve İpuçları

En yaygın hata, kuantalamanın doğrudan dönüşüm betiğiyle yapılmaya çalışılmasıdır; betik desteklemediği seviye verildiğinde hata üretir ve doğru yöntem llama-quantize kullanmaktır. İkinci yaygın sorun, disk alanı yetersizliğidir; dönüşüm sırasında f16 ve kuantalı dosya birlikte bulunur. Üçüncüsü, tokenizer ve özel token uyumsuzluklarıdır; mimari llama.cpp tarafından desteklenmeyen çok yeni modellerde dönüştürme betiğinin güncel sürümü kullanılmalı, depo düzenli olarak çekilmelidir.

Kalite kontrolü için kuantalanmış modelin bilinen sorulara yanıtları orijinal modelle karşılaştırılmalıdır. Aynı f16 kaynaktan birden çok seviye üretmek, karşılaştırmalı değerlendirme için pratiktir; f16 dosyası bir kez saklanarak Q4, Q5 ve Q8 sürümleri ayrı ayrı kuantalanabilir. Son olarak, dağıtım amaçlı üretimde Hugging Face’in GGUF dokümantasyonundaki adlandırma kurallarına uyulması, dosyanın başkaları tarafından doğru yorumlanmasını sağlar.