GGUF Formatı: Yerel LLM Çıkarımı için Eksiksiz Kılavuz

GGUF Nedir?

GGUF, yani GGML Unified Format, model ağırlıklarını, tokenizer verilerini, mimari üstverisini ve quantization bilgisini GGML tabanlı çalışma zamanlarında, özellikle de llama.cpp'de çıkarım için tek ve taşınabilir bir dosyada paketleyen ikili bir dosya formatıdır.

GGUF bir LLM dağıtım sorununu çözer. Birçok model formatı, model ağırlıkları, tokenizer dosyaları, yapılandırma dosyaları ve mimariye özel yükleme kodu dahil olmak üzere birkaç dosyayı bir arada tutmayı gerektirir. GGUF bunu, model dosyasını büyük ölçüde kendi kendini tanımlar hale getirerek basitleştirir.

Tipik bir GGUF dosyası şunları içerir:

• Model tensörleri
• Quantize edilmiş veya edilmemiş ağırlıklar
• Tokenizer söz varlığı
• Tokenizer yapılandırması
• Model mimarisi üstverisi
• Bağlam uzunluğu ayarları
• Gömme (embedding) boyutları
• Dikkat başı (attention head) sayıları
• RoPE yapılandırması
• Tensör adları, şekilleri ve veri türleri

Temel fikir, dosyanın kendisini tanımlamasıdır. Çalışma zamanı üstveriyi inceleyebilir, mimariyi anlayabilir, tokenizer'ı yükleyebilir ve tensörleri ayrı bir config.json veya tokenizer klasörüne güvenmeden eşleyebilir.

Bu, her GGUF dosyasının sonsuza dek her çalışma zamanı ile evrensel olarak uyumlu olduğu anlamına gelmez. Çalışma zamanının yine de dosyada kullanılan model mimarisini ve tensör türlerini desteklemesi gerekir. Ancak GGUF, dosya çok daha fazla yapılandırılmış bilgi taşıdığı için eski formatlara göre bu uyumluluğu çok daha kolay hale getirir.

GGUF'u tanımlayan dört özellik şunlardır:

1. Tek dosyalı dağıtım
2. Verimli yükleme için bellek eşleme desteği
3. Genişletilebilir, türlendirilmiş anahtar-değer üstverisi
4. Agresif düşük bitli formatlardan tam hassasiyete kadar birçok quantization türü desteği

GGUF, 2023'te llama.cpp ve GGML ekosisteminin bir parçası olarak tanıtıldı. Şu anda Hugging Face'te quantize edilmiş yerel LLM'leri dağıtmak için baskın format konumundadır.

GGUF vs. GGML

GGML (Georgi Gerganov Machine Learning) formatı, GGUF'un öncülüdür. Erken dönem yerel çıkarımı mümkün kıldığı için önemliydi. Ancak ekosistem orijinal LLaMA modellerinin ötesine geçtikçe pratik sınırlamaları ortaya çıktı.

Yaygın GGML sıkıntıları şunları içeriyordu:

• Daha az esnek üstveri işleme
• Mimariye daha bağımlı yükleme varsayımları
• Daha az kendi kendine yeten tokenizer ve yapılandırma işleme
• Yeni model aileleri ortaya çıktıkça genişletilebilirliğin zorlaşması

GGUF bu sınırlamaları daha yapılandırılmış bir formatla giderdi. Türlendirilmiş üstveri, daha iyi tokenizer embedding desteği ve daha net bir dosya düzeni getirdi. Bu da llama.cpp ve ilgili araçların, yükleme hattını sürekli yeniden tasarlamadan daha fazla mimariyi desteklemesini kolaylaştırdı.

Kullanıcılar için önemli fark basittir: GGUF modern formattır. Bugün model indiriyorsanız, çoğu zaman eski GGML dosyaları yerine GGUF'u seçmelisiniz.

GGUF vs. GPTQ ve AWQ

Dosya formatlarını araştırırken GGUF, GPTQ (Generative Post-Training Quantization) ve AWQ (Activation-Aware Weight Quantization) ile karşılaşmış olmalısınız. Üçü de LLM çıkarımını daha verimli hale getirmek için kullanıldığından genellikle birlikte tartışılır. Ancak aynı kategoride değillerdir.

GGUF öncelikle bir dosya formatı ve dağıtım kabıdır. Birçok quantization türünü destekler ve llama.cpp tarzı yerel çıkarımla yakından ilişkilidir.

GPTQ ve AWQ ise kuantizasyon yöntemleri ve ekosistemleridir; özellikle Transformers, ExLlama, AutoGPTQ ve vLLM uyumlu iş akışları gibi çerçeveler aracılığıyla NVIDIA donanımı üzerinde GPU'ya optimize edilmiş çıkarım için yaygın olarak kullanılır.

Amacınız dizüstü, masaüstü, Apple Silicon ve karma donanımlarda azami uyumluluksa, GGUF genellikle daha güvenli bir seçimdir.

Amacınız adanmış NVIDIA çıkarım sunucularında azami throughput ise, GPTQ, AWQ, FP8 veya diğer GPU'ya optimize edilmiş servis formatları daha uygun olabilir.

Neden GGUF Kullanmalı?

GGUF, pratik dağıtım sorunlarını çözdüğü için popüler hale geldi. Yerelde kurulum karmaşası olmadan dağıtım yaparken de oldukça pratik olduklarını gördüm.

Yerel LLM çalıştırma eskiden parçalı araçlar, büyük sıkıştırılmamış ağırlıklar, uyumsuz model formatları ve karmaşık kurulum adımları içerirdi. GGUF artık bu iş akışının büyük bir kısmını standartlaştırmanıza yardımcı olabilir.

Birçok ayrı dosya ve yükleme betiğini düşünmek yerine, kullanıcılar doğru modeli seçmeye, bir quantization seviyesi belirlemeye ve çıkarımı çalıştırmaya odaklanabilir.

Modelleri yerelde çalıştırın

GGUF, LLM'leri kendi makinenizde çalıştırmanıza olanak tanır. Bu şu anlama gelir:

• Token başına API maliyeti yok
• Barındırılan bir çıkarım sağlayıcısına bağımlılık yok
• İstemleri üçüncü taraf bir API'ye göndermenize gerek yok
• Model indirildikten sonra çevrimdışı çıkarım mümkündür

Bu, özellikle gizlilik açısından hassas iş akışları için yararlıdır. Geliştiriciler, tescilli kodu, dahili belgeleri, müşteri kayıtlarını veya gizli istemleri harici bir API'ye göndermek istemeyebilir.

Yerel çıkarım tek başına otomatik olarak güvenli değildir. Yine de makinenizi, günlükleri, uygulamaları ve erişim kontrolünü düzgün yönetmeniz gerekir. Ancak GGUF, özel yerel dağıtımı çok daha erişilebilir kılar.

Modelleri yerelde çalıştırmaya yönelik uygulamalı pratik için şu eğitimlerimize bakın: SGLang ile Mistral Medium 3.5 servisleme, DeepSeek V4 Flash'i yerelde çalıştırma, eski bir dizüstünde verimli Bonsai 1-bit modeli çalıştırma ve MiniMax M2'yi yerelde bir kodlama asistanı olarak çalıştırma.

Donanım esnekliği

GGUF, birçok donanım yapılandırmasında çalıştığı için kullanışlıdır.

Çalışma zamanı ve arka uca bağlı olarak, GGUF modelleri şuralarda çalışabilir:

• Sadece CPU'lu makineler
• CUDA üzerinden NVIDIA GPU'lar
• Metal üzerinden Apple Silicon
• HIP veya Vulkan üzerinden AMD GPU'lar
• SYCL veya Vulkan üzerinden Intel GPU'lar
• Bazı ARM ve mobil ortamlar

Bu esneklik, llama.cpp'nin etkili olmasının başlıca nedenlerinden biridir. Sadece üst seviye sunucu GPU'ları için tasarlanmadı; geniş bir donanım yelpazesinde yerel çıkarımı mümkün kılmak için tasarlandı.

Örneğin, bir Mac kullanıcısı Metal hızlandırmasına güvenebilirken, bir Linux masaüstü kullanıcısı CUDA veya Vulkan kullanabilir. Yalnızca CPU kullanan bir kullanıcı yine de daha küçük quantize edilmiş modelleri çalıştırabilir, ancak üretim hızı daha yavaş olacaktır.

Geniş ekosistem desteği

GGUF birçok yerel çıkarım aracı tarafından desteklenir. Örneklere şunlar dahildir:

• Komut satırı ve sunucu çıkarımı için llama.cpp
• CLI öncelikli model yönetimi ve API erişimi için Ollama
• Masaüstü arayüzü için LM Studio
• Gizlilik odaklı yerel sohbet için GPT4All
• Yerel rol yapma ve metin üretimi iş akışları için KoboldCpp
• Yerel yapay zekâ arayüzleri için Jan ve Open WebUI

Bu önemlidir çünkü kullanıcılar tek bir arayüze kilitlenmez. Aynı genel model formatı farklı iş akışlarında kullanılabilir.

Bir geliştirici bir modeli llama.cpp ile kıyaslayabilir, LM Studio'da onunla sohbet edebilir, Ollama üzerinden servisleyebilir ve Open WebUI aracılığıyla bir tarayıcı arayüzüne bağlayabilir.

Hugging Face dağıtımı

Hugging Face, GGUF modelleri için büyük bir dağıtım merkezi haline geldi.

Kaynak: Hugging Face

Birçok popüler açık ağırlıklı model, yayınlandıktan kısa süre sonra topluluk tarafından yüklenen GGUF varyantları alır. Bu depolar genellikle, kullanıcıların donanımlarına uyan bir modeli seçebilmesi için birkaç quantization seçeneğini içerir.

Yaygın yükleme varyantları şunlardır:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0
• IQ4_XS
• IQ3_M
• IQ2_XXS

Bu, manuel dönüştürmenin çoğu zaman gereksiz olduğu anlamına gelir. En popüler modeller için, topluluktan biri yaygın quantization seviyeleri için GGUF dosyaları zaten oluşturmuştur.

Ayrıntılı boyut-kalite kontrolü

GGUF, kullanıcılara boyut-kalite dengesi üzerinde ince ayar imkânı verir. Şunları seçebilirsiniz:

• Düşük bellekli makineler için daha küçük quantization'lar
• Günlük kullanım için dengeli orta seviye quantization'lar
• Kodlama, akıl yürütme veya yapılandırılmış çıktı için daha yüksek bitli quantization'lar
• Bellek kısıtı olmadığında tam veya tama yakın hassasiyet

Bu esneklik, formatın en büyük avantajlarından biridir. Sabit tek bir dağıtım hedefi yerine, GGUF aynı model ailesini birçok donanım katmanına uyarlamanıza olanak tanır.

GGUF Nasıl Çalışır?

Bir GGUF dosyası üç ana bölümden oluşur:

1. Başlık (header)
2. Üstveri ve tensör bilgileri
3. Tensör verisi

Tam yapı GGUF spesifikasyonu tarafından tanımlanır. Önemli olan, üstveri ve tensör bilgilerinin ham tensör verilerinden önce gelmesidir; bu sayede çalışma zamanı ne yükleyeceğini önceden anlayabilir.

Başlık

Başlık, dosyanın GGUF olduğunu belirtir ve çalışma zamanına geri kalanını nasıl ayrıştıracağını söyler. Şunları içerir:

• GGUF için sihirli sayı (magic number)
• Format sürümü
• Tensör sayısı
• Üstveri anahtar-değer çifti sayısı

Modern GGUF dosyaları yaygın olarak GGUF sürüm 3'ü kullanır.

Çıkarım motorları önce sihirli sayıyı kontrol eder. Dosya beklenen GGUF tanımlayıcısıyla başlamıyorsa, çalışma zamanı tensörleri ayrıştırmayı ya da bellek ayırmayı denemeden önce onu reddedebilir.

Bu, basit ama önemli bir güvenlik ve güvenilirlik adımıdır. Çalışma zamanının ilgisiz bir ikili dosyayı yanlışlıkla model olarak ele almasını engeller.

Üstveri anahtar-değer çiftleri

GGUF üstverisi türlendirilmiş bir anahtar-değer deposudur. Bu üstveri şunları tanımlayabilir:

• Genel model bilgileri
• Mimari ailesi
• Bağlam uzunluğu
• Gömme (embedding) boyutu
• Katman sayısı
• Dikkat başı sayısı
• RoPE parametreleri
• Tokenizer söz varlığı
• Özel tokenlar
• Quantization bilgisi

Anahtarlar genellikle ad alanlarına ayrılır. Örneğin:

• general.architecture
• general.alignment
• llama.context_length
• tokenizer.ggml.tokens

Ad alanları önemlidir çünkü GGUF'un tüm dosya formatını değiştirmeden birçok mimariyi desteklemesine olanak tanır. LLaMA ailesinden bir model llama.* anahtarlarını kullanabilirken, diğer model aileleri kendilerine özgü mimari üstverilerini kullanabilir.

Bu, GGUF'un orijinal LLaMA ailesinin ötesindeki Qwen, Mistral, Gemma, DeepSeek, Phi ve diğerleri gibi mimarilere iyi uyum sağlamasının nedenlerinden biridir.

Tensör bilgileri ve tensör verisi

Üstveriden sonra dosya tensör bilgilerini ve tensör verisini saklar.

Tensör bilgileri şunları açıklar:

• Tensör adı
• Şekli
• Veri türü
• Tensör verisi bölümündeki ofset

Tensör verisi bölümü gerçek model ağırlıklarını içerir. Bu ağırlıklar tam hassasiyette veya GGUF'un desteklediği quantize tensör türlerinden birinde saklanabilir.

GGUF, üstveride tanımlanan bir hizalama değeri kullanır; genellikle general.alignment. Birçok GGUF dosyası 32 bayt hizalama kullanır, ancak doğru tanım, hizalamanın kalıcı olarak sabit kodlanmak yerine üstveri tarafından kontrol edildiğidir.

Hizalama önemlidir çünkü çalışma zamanlarının tensör bloklarına verimli şekilde erişmesini sağlar.

Bellek eşleme

GGUF'un pratik avantajlarından biri bellek eşlemedir; sıklıkla mmap olarak adlandırılır.

Bellek eşleme ile, işletim sistemi, çalışma zamanını dosyanın tamamını RAM'e baştan kopyalamaya zorlamak yerine model dosyasını sanal belleğe eşleyebilir.

Bu, özellikle SSD'lerde model başlangıcını çok daha hızlı hissettirebilir. Ayrıca işletim sisteminin model verisini gerektiğinde içeri/dışarı sayfalamasına olanak tanır.

Ancak bellek eşleme sihirli bir çözüm değildir. Modelin yine de yeterli pratik bellek bant genişliğine ve mevcut RAM veya VRAM'e ihtiyacı vardır. Sisteminiz sürekli diskten sayfalama yapıyorsa, çıkarım yavaşlayabilir.

mmap için daha iyi bir düşünme şekli şudur:

• Yükleme verimliliğini artırır
• Gereksiz kopyalamayı azaltır
• Sayfalamayı işletim sistemine bırakır
• Çıkarımın bellek gereksinimlerini ortadan kaldırmaz

GGUF Quantization Türlerini Anlamak

Quantization, model ağırlıklarını daha düşük hassasiyetli temsillere sıkıştırır.

Her ağırlığı 16 bit kayan noktalı değer olarak saklamak yerine, quantize edilmiş bir model yaklaşık değerleri daha az bit kullanarak saklar. Bu da disk boyutunu, RAM ve VRAM kullanımını ve bellek bant genişliği baskısını azaltır.

Temel içgörü, birçok sinir ağı ağırlığının çıkarım sırasında tam kayan nokta hassasiyetine ihtiyaç duymamasıdır. Özenle quantize edilmiş bir model, özgün modelin davranışının çoğunu korurken dramatik biçimde küçülebilir.

GGUF quantization adlandırması

GGUF quantization adları genellikle şu deseni izler:

• Q quantize edilmiş anlamına gelir
• Sayı, ağırlık başına yaklaşık bit sayısını ifade eder
• K, k-quant ailesine işaret eder
• S, M ve L genellikle küçük, orta ve büyük varyantları ifade eder

Örnekler:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0

Ad yararlı bir rehberdir, ancak her zaman toplam dosya boyutunun tam ifadesi değildir. Gerçek dosya boyutu, tensör karması, mimari, üstveri, tokenizer boyutu ve bazı tensörlerin daha yüksek hassasiyette kalıp kalmadığına bağlıdır.

Yaygın GGUF quantization türleri

Bu sayılar 7B sınıfı yoğun (dense) modeller için yaklaşık değerlerdir. Daha yeni mimariler, uzman karışımı (MoE) modeller, daha büyük tokenizer'lar ve farklı tensör düzenleri gerçek dosya boyutunu değiştirebilir.

Pratikte, Q4_K_M boyut ve kalite arasında güçlü bir denge sunduğu için popüler bir varsayılan haline geldi. Birçok kullanıcı, genel sohbet, özetleme, yeniden yazma ve keşif amaçlı yerel yapay zekâ çalışmaları için yeterli buluyor.

Q5_K_M ve Q6_K, genellikle kodlama veya çok adımlı yönerge takibi gibi daha talepkâr iş yükleri için daha iyi seçimlerdir

Nedeni basittir: Bu görevler küçük kalite bozulmalarına daha hassastır.

K-quant'lar vs. I-quant'lar

K-quant'lar, Q4_K_M, Q5_K_M ve Q6_K gibi formatların arkasındaki yaygın quantization ailesidir.

Model davranışını korumaya yardımcı olan ölçekleme bilgisiyle gruplanmış quantization şemaları kullanırlar ve bellek gereksinimlerini azaltırlar. Güvenilir, geniş çapta desteklenen ve topluluk GGUF sürümlerinde kolayca bulunabildikleri için popülerdirler.

I-quant'lar, genellikle IQ formatları olarak yazılır ve şunlar gibi daha yeni quantization türleridir:

• IQ4_XS
• IQ3_M
• IQ2_XXS
• IQ1_S

I-quant'lar, çok küçük boyutlarda daha iyi kalite elde etmek için tasarlanmıştır. Önem farkındalıklı quantization ve doğrusal olmayan quantization kod kitapları gibi teknikler kullanabilirler. Bazı iş akışları, quantization sırasında daha önemli ağırlıkları korumaya yardımcı olmak için sıklıkla imatrix olarak adlandırılan bir önem matrisinden yararlanır.

Takas noktası karmaşıklıktır. I-quant'lar özellikle çok düşük bit hızlarında mükemmel boyut-kalite sonuçları üretebilir, ancak daha dikkatli quantization iş akışları ve çalışma zamanı desteği gerektirebilirler.

Çoğu yeni başlayan için K-quant'lar en kolay başlangıç noktası olmaya devam eder.

Donanımınız için bir quantization seviyesi seçme

Aşağıdaki tablo pratik başlangıç noktaları verir. Bunları katı garantiler değil, yaklaşık kurallar olarak düşünün. Bağlam uzunluğu, işletim sistemi ek yükü, GPU offload, KV önbellek boyutu ve belirli model mimarisi bellek gereksinimlerini değiştirebilir.

Genel yaklaşık kurallar:

• Çoğu yerel çıkarım için güvenli varsayılan olarak Q4_K_M kullanın.
• Her gigabaytı kısmaktan ziyade kalite önemliyse Q5_K_M kullanın.
• Bellek müsaitse ve daha iyi sadakat istiyorsanız Q6_K veya Q8_0 kullanın.
• Aşırı bellek kısıtlı senaryoları test etmiyorsanız ciddi işler için Q2_K'den kaçının.
• Özellikle uzun bağlam pencereleri kullanırken KV önbelleği için ekstra bellek bırakın.

KV önbelleği gözden kaçırması kolaydır. Bir model kısa bağlam uzunluğunda RAM'e sığabilir, ancak önbellek dizi uzunluğuyla birlikte büyüdüğü için çok daha uzun bir bağlamda başarısız olabilir veya yavaşlayabilir.

GGUF Ekosistemi

GGUF'un benimsenmesi, formatın kendisi kadar araçlardan da güç alır.

Bir format, kullanıcılar kolayca model indirip çalıştırabildiğinde, inceleyebildiğinde, dönüştürebildiğinde ve servisleyebildiğinde işe yarar hale gelir. GGUF, komut satırı araçları, masaüstü uygulamaları, API'ler ve barındırılan model depoları genelinde güçlü bir ekosistemin faydasını görür.

1. llama.cpp

llama.cpp, özgün ve en önemli GGUF çalışma zamanıdır. Georgi Gerganov tarafından oluşturulan ve GGML topluluğu tarafından sürdürülen hafif bir C/C++ çıkarım motorudur. Ana hedefi, birçok donanım platformunda minimum kurulumla verimli LLM çıkarımı sağlamaktır.

Modern llama.cpp şu arka uçları destekler:

• CPU
• NVIDIA GPU'lar için CUDA
• Apple cihazları için Metal
• Vulkan
• ROCm üzerinden AMD GPU'lar için HIP
• Intel GPU'lar için SYCL
• Seçili ortamlarda OpenCL
• Platform desteğine bağlı olarak CANN, OpenVINO ve WebGPU gibi diğer özel arka uçlar

Ayrıca dönüştürme, quantization, servisleme, kıyaslama ve komut satırı çıkarımı için araçlar içerir. Yaygın araçlar şunlardır:

• convert_hf_to_gguf.py
• llama-quantize
• llama-cli
• llama-server
• llama-bench

Temel bir CPU CMake derlemesi oluşturmak için komutlar şunlardır:

cmake -B build
cmake --build build --config Release

Bazı yapılandırmalarda, bu iki komuttan ilkinin sonuna belirli bayraklar eklemek gerekir:

• macOS'te Apple Metal'ı devre dışı bırakın (varsayılan olarak etkindir): -DGGML_METAL=OFF
• Vulkan derlemesi: -DGGML_VULKAN=1
• NVIDIA GPU'lar için CUDA derlemesi: -DGGML_CUDA=ON

Mevcut derlemelerin GGML_* CMake seçeneklerini, ör. GGML_CUDA, GGML_VULKAN ve GGML_HIP kullandığına dikkat edin.

2. Ollama

Ollama, yerel modelleri çalıştırmanın en kolay yollarından biridir. Şunları sağlar:

• Basit bir CLI
• Model indirme ve yönetimi
• Yerel bir REST API
• Resmi Python ve JavaScript kütüphaneleri
• Birçok yerel yapay zekâ ön yüzüyle entegrasyon

Ollama modelleri sizin için depolar ve yönetir; bu nedenle kullanıcı genellikle .gguf dosyalarıyla doğrudan etkileşime girmez. Ancak Ollama, llama.cpp uyumlu yerel çıkarım etrafında inşa edilmiştir ve bir Modelfile iş akışıyla GGUF dosyalarını içe aktarabilir.

Ollama yerel bir API'yi şurada sunar:

http://localhost:11434/api

Sık kullanılan iki uç nokta şunlardır:

• İstem tamamlama için /api/generate
• Sohbet tarzı mesajlar için /api/chat

Yeni başlayanlar için Ollama genellikle sıfırdan yerel çıkarıma en hızlı yoldur.

3. LM Studio

Kaynak: LM Studio

LM Studio, yerel modelleri keşfetmek, indirmek ve onlarla sohbet etmek için bir masaüstü uygulamasıdır. Komut satırı araçları yerine görsel bir arayüzü tercih eden kullanıcılar için kullanışlıdır.

4. GPT4All

Kaynak: GPT4All

GPT4All, özel ve yerel sohbet botu iş akışlarına odaklanan başka bir çapraz platform yerel yapay zekâ uygulamasıdır. GGUF modellerini destekler ve yerel çıkarım için yeni başlayanlara uygun bir ortam sağlar.

Bu araçlar GGUF'u uzman olmayanlar için erişilebilir kılar. Kullanıcıların yerel bir modeli denemek için CMake'i, tensör düzenlerini veya quantization iç detaylarını anlaması gerekmez.

GGUF Modelleriyle Nasıl Başlanır

Başlamak için iki pratik yol vardır:

1. En basit deneyim için Ollama kullanın.
2. Daha fazla kontrol için doğrudan llama.cpp kullanın.

Ollama ile bir model çalıştırma

En basit iş akışı modeli indirmek ve etkileşimli bir sohbet oturumu başlatmaktır:

ollama pull llama3.3
ollama run llama3.3

REST API kullanarak modeli Python'dan çağırmak için:

import requests

payload = {
    "model": "llama3.3",
    "prompt": "Give me three practical use cases for GGUF.",
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/generate",
    json=payload
)

print(response.json()["response"])

Sohbet tarzı uygulamalar için /api/chat kullanın:

import requests

payload = {
    "model": "llama3.3",
    "messages": [
        {"role": "user", "content": "What is GGUF used for?"}
    ],
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/chat",
    json=payload
)

print(response.json()["message"]["content"])

stream: false alanı basit betikler için önemlidir. Bu olmadan, Ollama tek bir nihai JSON yanıtı yerine bir JSON nesneleri akışı döndürür.

Ayrıca Ollama'nın resmi Python kütüphanesini kullanabilirsiniz:

from ollama import chat

response = chat(
    model="llama3.3",
    messages=[
        {"role": "user", "content": "Explain GGUF quantization simply."}
    ]
)

print(response.message.content)

Bir GGUF dosyasını llama.cpp ile çalıştırma

Zaten bir .gguf dosyanız varsa, projeyi derledikten sonra doğrudan llama.cpp ile çalıştırabilirsiniz.

Örnek:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Explain the difference between GGUF and GPTQ." \
  -n 256

GPU desteğiniz etkinse, katmanları GPU'ya offload edebilirsiniz:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Summarize GGUF in five bullet points." \
  -n 256 \
  -ngl 99

-ngl bayrağı GPU'ya offload edilen katman sayısını kontrol eder. 99 gibi yüksek bir değer, modelin VRAM'e sığdığı varsayılarak mümkün olduğunca çok offload etmek için yaygın olarak kullanılır.

API servisleme için llama-server kullanın:

./build/bin/llama-server \
  -m models/model.Q4_K_M.gguf \
  -ngl 99 \
  --host 127.0.0.1 \
  --port 8080

Bu, llama.cpp'yi uygulamalara entegre etmek için yerel bir sunucu arayüzü sağlar.

Bir Hugging Face modelini GGUF'a dönüştürme

Çoğu kullanıcı, topluluk GGUF sürümleri yaygın olarak mevcut olduğundan, modelleri manuel olarak dönüştürmek zorunda değildir.

Ancak şu durumlarda manuel dönüştürme yararlıdır:

• Kendi modelinizi ince ayarladınız
• Henüz bir GGUF sürümü yok
• Quantization sürecini kendiniz kontrol etmek istiyorsunuz
• Belirli bir quantization türüne ihtiyacınız var

Tipik bir iş akışı şöyledir:

1. Bir Hugging Face modeli indirin.
2. GGUF'a dönüştürün.
3. GGUF dosyasını quantize edin.

Örnek:

huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3 \
  --local-dir mistral-7b

Ardından GGUF'a dönüştürün:

python convert_hf_to_gguf.py mistral-7b \
  --outfile mistral-f16.gguf \
  --outtype f16

Sonra quantize edin:

./build/bin/llama-quantize \
  mistral-f16.gguf \
  mistral-q4_k_m.gguf \
  Q4_K_M

Güncel llama.cpp iş akışlarında convert_hf_to_gguf.py ve llama-quantize ilgili araçlardır. Eski eğitimler kullanım dışı bırakılmış dönüştürme betiklerine veya eski ikili adlara atıfta bulunabilir.

GGUF Formatının Avantajları ve Sınırlamaları

GGUF, pratik yerel çıkarım için optimize edilmiştir. Her model formatı veya servis yığını için evrensel bir yedek değildir.

Şu senaryolar için CPU öncelikli, Apple Silicon, karma donanım ve gizlilik odaklı çıkarımda GGUF çoğunlukla mükemmel bir seçimdir.

Yüksek verimli NVIDIA sunucu dağıtımı için, modele, yığın boyutuna, quantization yöntemine ve servis çerçevesine bağlı olarak diğer formatlar ve motorlar daha hızlı olabilir.

Son Düşünceler

GGUF, çalışma zamanının ihtiyaç duyduğu her şeyi (ağırlıklar, tokenizer, üstveri, quantization bilgisi) tek bir taşınabilir dosyada paketleyerek yerel LLM çıkarımını pratik hale getirir. Asıl gücü etrafındaki ekosistemdedir: llama.cpp, Ollama, LM Studio ve Hugging Face, onu yerel yapay zekâ dağıtımının varsayılan formatı haline getirdi.

Çoğu kullanıcı için yol basittir: Ollama'yı kurun, bir model çekin ve çalıştırın. Q4_K_M sağlam bir varsayılandır; daha iyi akıl yürütme veya kodlama çıktısı gerektiğinde ve belleğiniz elverdiğinde Q5_K_M veya Q6_K'ya geçin.

Daha derine inmek isterseniz LLM dağıtımı, model optimizasyonu ve yerel çıkarım iş akışları hakkında Veri Bilimciler için Yardımcı Yapay Zekâ Mühendisi veya Geliştiriciler için Yardımcı Yapay Zekâ Mühendisi kariyer yolunu keşfetmelisiniz.