Ollama ile GGUF dosyası nasıl çalıştırılır?

Bir GGUF modelini Ollama'ya aktarmanın iki yolu

Bir GGUF modelini Ollama'ya aktarmanın iki yolu vardır ve doğru yöntem, dosyanın şu anda nerede bulunduğuna bağlıdır. Eğer model bir Hugging Face deposunda yer alıyorsa, tek bir ollama run komutu onu çeker ve Modelfile gerektirmeden çalıştırır. Eğer .gguf dosyası halihazırda sunucunuzun diskindeyse, iki satırlık bir Modelfile yazıp ollama create komutunu çalıştırmanız gerekir.

Her iki yol da aynı noktada sonlanır: yerel Ollama kütüphanenizde, ollama run ve Ollama API'sinin sunabileceği isimlendirilmiş bir model. Dosyayı başkası yayınladıysa ilk yolu, modeli kendiniz kuantize ettiyseniz, dosya scp veya rsync üzerinden geldiyse ya da makine Hugging Face'e erişemiyorsa ikinci yolu kullanın.

GGUF dosyası; ağırlıkları, tokenizer'ı ve model meta verilerini bir arada tutan tek bir ikili dosyadır. Bu, llama.cpp'nin okuduğu formattır ve Ollama, llama.cpp üzerine inşa edildiğinden neredeyse her açık modelin topluluk tarafından oluşturulmuş bir GGUF dönüştürmesi mevcuttur. Ollama ayrıca bir .safetensors ağırlıkları dizinini de içe aktarabilir, ancak bu ayrı bir yoldur ve aşağıdaki --quantize bölümü bunun nerede kullanıldığını gösterir.

Aşağıdaki her şey, Ollama'nın halihazırda kurulu olduğunu ve servisinin çalıştığını varsayar. Eğer kurulu değilse, Ollama'nın bir VPS üzerine kurulumu ile başlayıp geri dönün. Önce ollama list komutunu çalıştırın. Eğer bir bağlantı hatası yerine, boş da olsa bir tablo döndürürse sunucu ayaktadır ve bu kılavuzun geri kalanı çalışacaktır.

Birinci yöntem: Modelfile olmadan Hugging Face üzerinden GGUF çalıştırma

Ollama, bir GGUF dosyasını doğrudan Hugging Face deposundan çekebilir. Komut, hf.co/ ön eki ile birlikte depo yoludur:

ollama run hf.co/{username}/{repository}

Hem hf.co hem de huggingface.co alan adı olarak çalışır. Hugging Face dokümantasyonundan gerçek bir örnek:

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

İlk çalıştırmada dosya indirilir, bu nedenle indirme tamamlanana kadar sohbet istemi görünmez. Daha sonra model yerel kütüphanenize kaydedilir ve hızlıca başlar. İkinci bir kabuk açın ve hangi isimle kaydedildiğini görmek için ollama list komutunu çalıştırın. Bu isim, etiketiyle birlikte tüm hf.co/... dizisidir ve her seferinde yazmak için uzundur. Ona kısa bir takma ad verin:

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

Bu yöntem yalnızca GGUF dosyaları içeren depolarda çalışır. Yalnızca .safetensors ağırlıkları yayınlayan bir depo bu yöntemle çekilecek bir içerik sunmaz; bu durumda aşağıda açıklanan yerel içe aktarma yöntemlerinden birine ihtiyacınız olur.

Ollama hangi kuantizasyonu seçer?

Hugging Face'in 10 Ekim 2026 tarihinde okunan Ollama dokümantasyonu, varsayılan ayar konusunda nettir: "Varsayılan olarak, model deposu içinde mevcut olduğunda Q4_K_M kuantizasyon şeması kullanılır. Eğer mevcut değilse, depo içindeki makul bir kuantizasyon türünü seçmek varsayılan davranışımızdır." On farklı kuantizasyon yayınlayan bir depo size Q4_K_M verir; Q4_K_M içermeyen bir depo ise Ollama'nın sizin adınıza yaptığı bir seçimi sunar. Bu sayfaya güvenmeden önce tekrar okuyun, çünkü varsayılanlar değişebilir.

Belirli bir kuantizasyonu etiket olarak ekleyerek talep edin:

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

Kuantizasyon ismi büyük/küçük harfe duyarlı değildir, bu nedenle :iq3_m ve :IQ3_M aynı anlama gelir. Ayrıca etiketi tam dosya ismi olarak da girebilirsiniz; bu, depodaki kısa isimlerin belirsiz olduğu durumlarda güvenli yöntemdir. Etiket, o depoda var olan bir dosyayı işaret etmelidir; bu nedenle bir isim yazmadan önce Files and versions sekmesini açın ve gerçek dosya isimlerini okuyun. Hangi kuantizasyonu istediğiniz bir bellek ve kalite meselesidir; Q4, Q8 ve FP16 arasındaki fark bu dengeyi doğru şekilde ele alır.

İkinci yol: kendi diskinizden bir .gguf dosyası içe aktarmak

Dosya zaten sunucuda bulunuyorsa bir Modelfile dosyasına ihtiyacınız vardır. Bu dosya tek satırdan oluşabilir. Bir dizin oluşturun, Modelfile dosyasını içine yerleştirin ve FROM komutunu dosyaya yönlendirin:

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

Bunu Modelfile olarak kaydedin ve ardından modeli oluşturun:

ollama create my-model

ollama create komutu varsayılan olarak mevcut dizindeki Modelfile adlı bir dosyayı okur. Dosyanızın farklı bir adı varsa veya başka bir yerdeyse, ollama create my-model -f /home/you/models/my-model/Modelfile örneğinde olduğu gibi -f kullanın. Bayrağı ve derleme üzerindeki varsayılan değerini görmek için ollama create --help komutunu çalıştırın. FROM içindeki yol mutlak veya Modelfile dosyasına göre göreli olabilir; bu nedenle her ikisi de aynı dizindeyse FROM ./my-model-Q4_K_M.gguf çalışır. Mutlak bir yol kullanmak bu belirsizliği tamamen ortadan kaldırır.

Güvenmeden önce sonucu kontrol edin:

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ollama list artık my-model içermelidir. ollama show my-model komutu, Ollama'nın dosyanın kendi meta verilerinden okuduğu mimariyi, parametre sayısını, bağlam uzunluğunu ve nicemleme (quantization) değerini yazdırır. Dosya adına güvenmek yerine bu değerleri okuyun, çünkü dosya adı birisi tarafından elle yazılmış bir dizgidir. Model test isteminize normal bir dilde yanıt veriyorsa ve ardından duruyorsa, içe aktarma işlemi başarılı olmuştur. Aksi takdirde aşağıdaki şablon bölümüne gidin, çünkü sorun neredeyse her zaman bundan kaynaklanır.

Disk alanı hakkında bilinmesi gereken bir nokta: ollama create, GGUF dosyasını bulunduğu yerden referans göstermek yerine Ollama'nın kendi model deposuna kopyalar. Siz orijinali silene kadar ağırlıklar diskte iki kez yer kaplar. ollama run my-model çalıştığında kaynak dosyayı silin veya iki kez ödeme yapmadığınız bir yerde tutun. Ollama'nın modellerini diskte nerede tuttuğu bölümünde yerleşim düzeni ve bunun nasıl taşınacağı açıklanmıştır.

--quantize ne zaman uygulanır ve ne zaman uygulanmaz

ollama create bir --quantize bayrağına sahiptir ve günümüzde bu yalnızca bir durumda geçerlidir: .safetensors ağırlıklarından oluşan bir dizinden içe aktarılan bir model. 10 Ekim 2026 tarihinde kontrol edilen mevcut Ollama kaynak kodundaki yardım metni "Safetensors modelini bu seviyeye nicemle (örneğin nvfp4)" şeklindedir ve kabul ettiği değerler int4, int8, nvfp4, mxfp4 ve mxfp8 şeklindedir. q8_0 veya q4_K_M gibi GGUF nicemleme adları, desteklenmeyen türler olarak reddedilir. Ollama'nın içe aktarma belgeleri GGUF tarafında nettir: "Ollama, içe aktarma sırasında GGUF modellerini nicemlemez."

ollama create --quantize int8 my-model

Bu komut, FROM satırı .safetensors dosyalarını içeren dizini işaret eden bir Modelfile dosyasını varsayar.

FROM bir .gguf dosyasını işaret ettiğinde, hassasiyeti ne olursa olsun bu bayrağı geçmeyin. Bir FP16 veya FP32 GGUF dosyası, "create-time quantization is only supported for safetensors imports" (oluşturma anında nicemleme yalnızca safetensors içe aktarmaları için desteklenir) hatasıyla, Q4_K_M dosyasıyla aynı şekilde reddedilir. Adında Q4_K_M veya Q5_K_S geçen bir .gguf zaten nicemlenmiştir ve kaybettiği hassasiyet geri getirilemez. llama.cpp'nin llama-quantize aracı, --allow-requantize parametresini geçerseniz böyle bir dosyayı Q8_0 dahil başka bir tür olarak yeniden kodlayabilir; ancak kılavuzu, bunun "16bit veya 32bit'ten nicemlemeye kıyasla kaliteyi ciddi şekilde düşürebileceği" konusunda uyarır ve Q8 olarak yeniden yazılan bir Q4 dosyası daha iyi olmadan daha büyük hale gelir. Tam hassasiyetli bir GGUF dosyasını küçültmek için önce Ollama belgelerinin işaret ettiği araç olan llama-quantize komutunu çalıştırın, ardından yazdığı dosyayı içe aktarın. Kaynağınız .safetensors dosyalarından oluşan bir Hugging Face deposuysa, FROM parametresini o dizine yönlendirip ollama create aracının içe aktarmasına izin verebilir veya daha küçük olmasını istiyorsanız --quantize kullanabilir ya da llama.cpp deposundaki convert_hf_to_gguf.py ile dönüştürüp betiğin yazdığı GGUF dosyasını içe aktarabilirsiniz. Ollama ve llama.cpp arasındaki ilişki bu araçların neden diğer projeye ait olduğunu açıklar.

İçe aktarılan bir GGUF neden anlamsız yanıtlar veriyor veya neden durmuyor?

Bu, çoğu içe aktarma rehberinin atladığı ancak mutlaka karşılaşacağınız bir hata türüdür. Belirtiler bozuk bir model gibi görünür. Kontrol belirteçleri (tokens) yanıtta görünür metin olarak belirir; <|im_start|>assistant veya <|end|> gibi dizeler buna örnektir. Model yanıt verir, ardından yeni bir kullanıcı sorusu yazar ve onu da yanıtlar. Siz Ctrl+C tuşlarına basana kadar üretim devam eder.

Modelde bir sorun yoktur. Sorun, sohbet şablonunun (chat template) yanlış olmasıdır. Sohbet şablonu, mesajınızı modelin eğitildiği tam belirteç dizisine dönüştüren bir sarmalayıcıdır; sistem isteminin nerede bittiğini ve kullanıcı sırasının nerede başladığını belirten kendi işaretçilerine sahiptir. Ollama sizin için bir tane seçer: belgelerde, bir şablonun GGUF dosyası içinde saklanan yerleşik tokenizer.chat_template meta verilerine dayalı olarak "yaygın kullanılan şablonlar listesinden otomatik olarak seçileceği" belirtilir. Bu meta veri eksik olduğunda veya listedeki hiçbir şeyle eşleşmediğinde, genel bir sarmalayıcı elde edersiniz. Model, eğitiminde görmediği bir istem yapısıyla karşılaşır ve bu nedenle durması gerektiğini öğrendiği sıra sonu işaretçisini asla bulamaz.

Ollama'nın gerçekte neyi seçtiğini yazdırın:

ollama show --template my-model
ollama show --modelfile my-model

Boş veya bariz şekilde genel bir şablon bunu doğrular. Şablonu Modelfile içinde kendiniz yazın:

FROM /home/you/models/my-model-Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|system|>
{{ .System }}<|end|>
{{ end }}{{ if .Prompt }}<|user|>
{{ .Prompt }}<|end|>
{{ end }}<|assistant|>
{{ .Response }}<|end|>"""

PARAMETER stop "<|end|>"

ollama create my-model ile yeniden oluşturun ve aynı test istemini tekrar gönderin. stop parametresi güvenlik ağınızdır: bu dize göründüğünde Ollama'ya üretimi kesmesini söyler; bu, siz şablonun kendisini ayarlarken bile "asla durmama" belirtisini sona erdirir. Yanıt, belirttiğiniz hiçbir işaretçi görünmediği için hala devam ediyorsa, bir num_predict üst sınırı şablonun ne ürettiğine bakılmaksızın üretimi sabit bir belirteç sayısında keser.

Şablon bir Jinja şablonu değil, bir Go şablonu olmalıdır. Hugging Face belgeleri bunu doğrudan belirtir ve bu önemlidir çünkü orijinal model deposundaki tokenizer.chat_template alanı Jinja içerir. Bunu değiştirmeden yapıştırmak çalışmaz. Ollama'nın sözdizimi üç değişken içerir: sistem istemi için {{ .System }}, kullanıcı mesajı için {{ .Prompt }} ve modelin yanıtı için {{ .Response }}. Modelin gerçek sıra işaretçilerini model kartında veya tokenizer_config.json dosyasında bulun, ardından bunları manuel olarak Go sözdizimine yeniden yazın.

Bir kısayol bu işin çoğunu kurtarır. Birçok model ortak bir istem biçimini paylaşır; bu nedenle kütüphanenizdeki başka bir model aynı biçimi kullanıyorsa, ona karşı ollama show --template komutunu çalıştırın ve yazdırdığı içeriği kopyalayın.

Hugging Face deposundaki template, system ve params dosyaları

Hugging Face rotası, Modelfile içindeki talimatlar yerine depodaki dosyalarla aynı kontrolleri sunar. Eğer deponun sahibiyseniz veya kendi kuantizasyonunuzu yayınlıyorsanız, bu dosyaları ekleyin; böylece her ollama run hf.co/... bunları otomatik olarak alır.

• template adlı bir dosya Go şablonunu tutar. Kural aynıdır: Jinja değil, Go kullanılmalıdır.
• system adlı bir dosya sistem istemini (system prompt) tutar.
• params adlı bir dosya örnekleme parametrelerini tutar ve bu dosya JSON formatında olmalıdır.

Minimal bir params dosyası:

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

Deponun sahibi olmadığınız durumlarda bu dosyaları ekleyemezsiniz. Modeli bir kez çekin, size verilenleri dışa aktarmak için ollama show --modelfile hf.co/... komutunu çalıştırın ve bu çıktıyı bir Modelfile olarak kaydedin. Bunun FROM satırı, Ollama'nın halihazırda indirdiği bloba işaret eder; bu nedenle TEMPLATE ve PARAMETER satırlarını düzenleyip, hiçbir şeyi yeniden indirmeden sabit bir yerel kopya oluşturmak için ollama create komutunu çalıştırın. Bu yöntem, başkasına ait hatalı bir kuantizasyonun onarılması için standart yoldur.

Özel bir GGUF deposunu içe aktarma

Özel bir depo, Hugging Face hesabınızda Ollama'nın SSH anahtarının tanımlı olmasını gerektirir. Bu yöntem için belgelenen yol, API belirteci yerine bir SSH anahtarı kullanır; bu nedenle halihazırda sahip olduğunuz bir belirteç, depoya erişim sağlamayacaktır.

Genel anahtarı ekrana yazdırın. Ollama'nın resmi betik ile kurulduğu bir Linux sunucusunda servis, ollama kullanıcısı olarak çalışır; bu nedenle anahtar, ilgili kullanıcının ev dizininde bulunur:

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

Eğer ollama serve servisini kendi kullanıcınızla manuel olarak başlatıyorsanız, yol bunun yerine ~/.ollama/id_ed25519.pub olacaktır. Satırın tamamını kopyalayın, https://huggingface.co/settings/keys adresinden Hugging Face hesap ayarlarınızı açın ve anahtarı yeni bir SSH anahtarı olarak ekleyin. Ardından standart komut, özel depolarınız üzerinde çalışacaktır:

ollama run hf.co/{username}/{repository}

Anahtarı eklemenize rağmen çekme işlemi hala başarısız oluyorsa, muhtemelen yanlış dosyayı yazdırdınız. İndirme işlemini sunucu gerçekleştirir ve kendi anahtarını sunar; systemd tarafından başlatılan bir sunucu, kullanıcınızın ~/.ollama dosyasını asla okumaz. Bu nedenle, ev dizininizdeki anahtar, Hugging Face'in gördüğü anahtar değildir.

Model VPS'nize sığacak mı?

Bunu belirleyen sayı, disk üzerindeki dosya boyutu ile bağlam pencerenizin (context window) ihtiyaç duyduğu bellek miktarıdır. Ağırlıklar, dosyadaki boyutlarına yakın bir miktarda belleğe yüklenir; bağlam tahsisi ise bunun üzerine eklenir ve izin verdiğiniz token sayısıyla birlikte büyür. Ollama'nın model için kaydettiği boyutu okumak için ollama list komutunu çalıştırın, bunu sunucudaki free -h ile karşılaştırın ve işletim sistemi ile sunucuda çalışan diğer her şey için bir miktar boşluk bırakın. Bu hesaplamanın gerçek bir model üzerinde nasıl yapıldığını görmek isterseniz, Nemotron 3.5 Lightning'i bir VPS üzerinde çalıştırma rehberi, çekilecek tam etiketi, ihtiyaç duyulan RAM miktarını ve yalnızca CPU içeren bir sunucunun yeterli olup olmadığını belirtir.

Bağlam, insanların unuttuğu kısımdır. Varsayılan pencere boyutunda yüklenen bir model, num_ctx değerini artırdığınızda başarısız olabilir; çünkü bu tahsis, talep ettiğiniz pencere boyutuyla ölçeklenir. num_ctx ayarı ve bellek maliyeti bölümünde boyutlandırma bilgileri yer almaktadır. Toplam miktar çok büyükse, çözüm genellikle aynı modelin daha küçük bir kuantizasyonunu kullanmaktır; bu takas Q4 ve Q8 karşılaştırması bölümünde ele alınmıştır.

Hata belirgin bir şekilde gerçekleşir. Yalnızca CPU içeren bir VPS'de, çekirdeğin bellek yetersizliği sonlandırıcısı (OOM killer) süreci durdurur ve journalctl -u ollama -n 50 ile birlikte dmesg bu sonlandırmayı gösterir. GPU'lu bir sunucuda ise ollama ps, yüklenen modelin GPU belleğine mi, sistem belleğine mi yoksa her ikisine birden mi dağıtıldığını gösteren bir PROCESSOR sütunu yazdırır. Sistem belleğine taşan bir model yanıt vermeye devam eder ancak yavaş çalışır. Saniyedeki token sayısını ölçme bölümü, "yavaş" ifadesini kuantizasyonlar arasında karşılaştırabileceğiniz bir sayıya dönüştürür.

İçe aktardığınız modeli kontrol edin

Her içe aktarma işleminden sonra bu dört komutu sırasıyla çalıştırın:

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

ollama list komutu, modelin var olduğunu doğrular ve Ollama tarafından kaydedilen boyutu gösterir. ollama show komutu, Ollama'nın GGUF dosyasından ihtiyaç duyduğu meta verileri okuduğunu kanıtlar. ollama show --modelfile komutu, modelin gerçekte hangi şablonu ve parametreleri kullanacağını gösterir; bu kontrol, kullanıcılarınız fark etmeden önce hatalı çıktı sorununu tespit etmenizi sağlar. Test istemi tüm süreci sınar, çünkü hatalı şablona sahip bir model en kısa istekte bile başarısız olur. Bu istemden temiz bir yanıt aldığınızda, modele verdiğiniz isim, kendi sunucunuza yönlendirilmiş bir kodlama aracı dahil olmak üzere Ollama API ile iletişim kuran diğer her yerde kullanacağınız isimle aynıdır. Hatalı bir içe aktarmayı ollama rm my-model ile kaldırın ve yeniden oluşturun. Bu komut, Ollama'nın kopyasını siler ve .gguf kaynak dosyanıza dokunmaz.

FAQ

Bir GGUF dosyasını Modelfile yazmadan Ollama'ya aktarabilir miyim?

Evet, dosya bir Hugging Face deposunda bulunuyorsa bu mümkündür. ollama run hf.co/{username}/{repository} komutu dosyayı doğrudan çeker ve çalıştırır, ollama run hf.co/{username}/{repository}:{quantization} ise belirli bir kuantizasyon türünü seçmenizi sağlar. Modelfile yalnızca diskinizde halihazırda bulunan bir .gguf için gereklidir; bu durumda dosya, FROM /path/to/file.gguf komutunu takiben ollama create my-model satırından oluşan tek satırlık bir içerik ile oluşturulabilir.

Bir kuantizasyon belirtmediğimde Ollama hangisini indirir?

10 Ekim 2026 tarihinde incelenen Hugging Face dokümantasyonuna göre, ilgili kuantizasyon depoda mevcutsa Q4_K_M kullanılır; aksi takdirde Ollama, depoda bulunan makul bir kuantizasyon türünü seçer. Kontrolü sağlamak için :Q8_0 gibi bir etiket ekleyin. Dosyanın adından ziyade meta verilerinden kuantizasyon bilgisini yazdıran ollama show <model> komutu ile gerçekte neyin indirildiğini doğrulayın.

İçe aktardığım model neden kendini tekrar ediyor veya üretimi durdurmuyor?

Sohbet şablonu (chat template) model ile uyumlu değildir. Ollama, GGUF içindeki tokenizer.chat_template meta verilerinden otomatik bir şablon seçer; bu meta veriler eksik veya tanımsız olduğunda genel bir sarmalayıcı kullanılır ve model, eğitildiği sıra sonu işaretçisini göremez. Mevcut şablonu ollama show --template <model> ile yazdırın, ardından Modelfile içerisine bir TEMPLATE bloğu ve PARAMETER stop satırı ekleyerek ollama create komutunu tekrar çalıştırın. Şablonu Go şablonu formatında yazın; orijinal depodaki Jinja şablonu çalışmayacaktır.

İndirdiğim bir GGUF üzerinde --quantize kullanmalı mıyım?

Hayır. --quantize yalnızca ollama create sırasındaki safetensors içe aktarma işlemlerinde çalışır ve FP16 veya FP32 dahil tüm GGUF kaynaklarını reddederek, GGUF modellerini içe aktarmadan önce kuantize etmeniz gerektiğini belirten bir hata verir. Adında Q4_K_M gibi bir kuantizasyon ifadesi bulunan dosya zaten dönüştürülmüştür; bunu tekrar kuantize etmek kaybedilen hassasiyeti geri getirmez. llama-quantize --allow-requantize ile dosya Q8_0 olarak yeniden yazılabilir ancak sonuç, kalite artışı olmaksızın daha büyük bir dosya boyutu doğurur. Tam hassasiyetli bir GGUF dosyasından daha küçük bir dosya elde etmek için, dosya üzerinde llama.cpp'nin llama-quantize aracını çalıştırın ve elde edilen sonucu içe aktarın.

Özel (private) bir GGUF deposunu nasıl çekerim?

Ollama'nın SSH genel anahtarını Hugging Face hesabınıza ekleyin. Standart bir Linux kurulumunda anahtarı sudo cat /usr/share/ollama/.ollama/id_ed25519.pub ile, sunucuyu kendi kullanıcınızla çalıştırıyorsanız ~/.ollama/id_ed25519.pub üzerinden yazdırın ve ardından hesap ayarlarınızdaki SSH anahtarları sayfasına ekleyin. Bu işlemden sonra ollama run hf.co/{username}/{repository} komutu, kendi özel depolarınızda ve üyesi olduğunuz organizasyonlara ait depolarda çalışacaktır.