Unsloth

#Unsloth #LLM #FineTuning #QLoRA

LLM ince ayarını 2-5× hızlandıran ve %70 VRAM tasarrufu sağlayan açık kaynaklı Python kütüphanesi.

Unsloth, büyük dil modellerinin (LLM) ince ayarını standart yöntemlere kıyasla 2-5× daha hızlı ve yaklaşık %70 daha az GPU belleği (VRAM) kullanarak gerçekleştiren açık kaynaklı bir Python kütüphanesidir. Daniel Han tarafından 2023 yılında geliştirilen Unsloth, HuggingFace'in TRL (Transformer Reinforcement Learning) kütüphanesiyle tam uyumlu çalışır; mevcut eğitim betiklerine minimum kod değişikliğiyle entegre edilebilir. Kütüphanenin temel performans kazanımı, dikkat (attention) hesabı ve geri yayılım (backpropagation) için el ile yazılmış Triton/CUDA kernel'larından kaynaklanır. PyTorch'un genel amaçlı operatörleri yerine bellek bant genişliğini optimize eden bu özel çekirdekler, QLoRA (4-bit Quantized Low-Rank Adaptation) ve tam ince ayar (SFT) senaryolarında belirgin hız ve verimlilik artışı sunar. Flash Attention 2 entegrasyonu, aktivasyon yeniden hesaplama (gradient checkpointing) ve bellek havuzu optimizasyonları da ek tasarruf katkısı sağlar. Bu katmanlı yaklaşımla aynı model, çok daha küçük bir GPU üzerinde veya çok daha büyük bir batch boyutuyla eğitilebilir hale gelir. Desteklenen model aileleri arasında Llama 3.x, Mistral, Gemma, Phi-3/4, Qwen 2/3 ve DeepSeek yer alır. Tüketici sınıfı GPU'lar (RTX 3090, 4090, L4) üzerinde 7-70 milyar parametreli modellerin ince ayarını mümkün kılan Unsloth, ücretsiz Colab ve Kaggle ortamlarıyla da sorunsuz çalışır. DPO (Direct Preference Optimization), ORPO ve SFT gibi hizalama odaklı eğitim yöntemleri de tam desteklenir. Unsloth, kurumsal GPU altyapısına sahip olmayan araştırmacıların ve küçük ekiplerin alan spesifik modeller geliştirmesini demokratikleştirir. Apache 2.0 lisansıyla dağıtılan kütüphane, aktif bir açık kaynak topluluğu tarafından geliştirilmeye devam etmektedir. Eğitim sonrası modeller GGUF formatına (llama.cpp uyumu için) veya vLLM'e uyumlu biçimde dışa aktarılabilir. DeepSpeed, Axolotl ve LLaMA Factory gibi alternatif çerçeveler benzer yetenekler sunarken, Unsloth'un TRL uyumluluğu ve düşük kurulum eşiği hızlı deneme döngüleri için onu öne çıkarır.

Unsloth Nasıl Hızlandırır?

Unsloth, attention hesaplama ve backpropagation için özel Triton/CUDA kernel'ları yeniden yazar. Flash Attention 2'yi entegre eder; gradient checkpointing'i bellek-hız dengesi için optimize eder. Quantization (4-bit, 8-bit) ve aktivasyon yeniden hesaplama stratejileri birleştirilerek GPU bellek tükenmesi (OOM) olmadan daha büyük batch'ler işlenir. Sonuç: aynı donanımda daha hızlı epoch, daha az VRAM, daha düşük maliyet.

Desteklenen Senaryolar

model_training QLoRA Fine-tuning

4-bit quantized modeli LoRA adaptörleriyle ince ayar. En az VRAM ile en yüksek verimlilik. Tüketici GPU için ideal.

thumbs_up_down DPO / ORPO

Tercih tabanlı eğitim yöntemleri TRL entegrasyonuyla desteklenir. Hizalama odaklı fine-tuning.

laptop_chromebook Colab / Kaggle

Ücretsiz GPU ile çalışan hazır notebook'lar. A100 olmadan 7B fine-tuning mümkün.

Unsloth'un Temel Özellikleri

  • check_circle El Yazımı CUDA Çekirdekleri: PyTorch'un jenerik operatörleri yerine dikkat hesabı ve geri yayılım için optimize edilmiş özel CUDA çekirdekleri. Bellek bant genişliğini minimuma indirir.
  • check_circle 2× Hızlanma: QLoRA ince ayarında standart Hugging Face + PEFT'e kıyasla yaklaşık 2× eğitim hızlanması. Flash Attention 2 ile entegrasyon.
  • check_circle %60-70 Daha Az VRAM: Aktivasyon yeniden hesaplama ve bellek verimliliği optimizasyonlarıyla aynı modeli çok daha az GPU belleğiyle ince ayar yapma imkânı.
  • check_circle TRL Uyumluluğu: HuggingFace TRL ile tam uyumlu API. Mevcut betiklerde from transformers import satırını from unsloth import ile değiştirmek yeterli.
  • check_circle Çoklu Model Desteği: Llama 3.x, Mistral, Gemma, Phi-3/4, Qwen 2/3, DeepSeek ve diğerleri. Yeni modeller sürekli eklenir.
  • check_circle GGUF ve vLLM Export: Eğitim sonrası modeli GGUF formatına (llama.cpp uyumu) veya vLLM ile sunuma hazır hale dönüştürme desteği.

Unsloth ile Pratik LLM İnce Ayarı

Unsloth, tüketici donanımında LLM ince ayarının önündeki temel engelleri —bellek ve hız— kaldıran açık kaynaklı bir kütüphanedir. Tipik kullanım senaryosu: 16GB VRAM'li tek bir NVIDIA RTX 3090 veya 4090 ile 7B parametreli bir Llama 3 modelini domain-spesifik veri kümesiyle QLoRA yöntemiyle ince ayarlamak. Kurulum pip install unsloth ile tamamlanır; FastLanguageModel.from_pretrained() mevcut HuggingFace model yükleme akışıyla örtüşür. Eğitim döngüsü (SFTTrainer, DPOTrainer) TRL üzerinde çalışmaya devam eder; Unsloth yalnızca altta yatan kernel'ları optimize eder.

Ekosistem ve Alternatifler

  • check_circle Axolotl: YAML tabanlı yapılandırma dosyalarıyla QLoRA, DPO ve çoklu GPU eğitimini destekleyen kapsamlı fine-tuning çerçevesi. Unsloth backend olarak entegre edilebilir.
  • check_circle LLaMA Factory: 100+ modeli destekleyen tek arayüzde SFT, DPO ve RLHF eğitimine olanak tanıyan kapsamlı açık kaynaklı çerçeve; web UI seçeneği mevcuttur.
  • check_circle DeepSpeed: Microsoft'un çok GPU ve çok düğümlü dağıtık eğitim optimizasyon kütüphanesi. ZeRO-3 optimizasyonuyla çok büyük modeller için tercih edilir.
  • check_circle PEFT (HuggingFace): LoRA, prefix-tuning ve IA3 gibi parametre verimli ince ayar yöntemlerini kapsayan resmi HuggingFace kütüphanesi; Unsloth'un üzerine inşa edildiği ekosistem bileşeni.

terminal Kurulum ve Çalışan Bir QLoRA Betiği

Kurulum tek satır: pip install unsloth. CUDA sürücüsü hazır bir makinede bu paket torch, bitsandbytes, triton ve unsloth_zoo bağımlılıklarını da çeker. Colab veya Kaggle kullanıyorsanız çalışma zamanını T4 ya da L4 GPU'ya almak yeterli.

Sürüm çakışması yaşarsanız temiz kurulum komutu şu: pip install --upgrade --force-reinstall --no-cache-dir unsloth unsloth_zoo

8B bir modeli 4 bit QLoRA ile ince ayarlayan en kısa betik şöyle görünür:

from unsloth import FastLanguageModel from trl import SFTTrainer, SFTConfig

model, tokenizer = FastLanguageModel.from_pretrained( model_name = "unsloth/llama-3.1-8b-bnb-4bit", max_seq_length = 2048, load_in_4bit = True, )

model = FastLanguageModel.get_peft_model( model, r = 16, lora_alpha = 16, lora_dropout = 0, bias = "none", target_modules = ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"], use_gradient_checkpointing = "unsloth", random_state = 3407, )

trainer = SFTTrainer( model = model, tokenizer = tokenizer, train_dataset = dataset, args = SFTConfig( per_device_train_batch_size = 2, gradient_accumulation_steps = 4, warmup_steps = 5, max_steps = 60, learning_rate = 2e-4, optim = "adamw_8bit", logging_steps = 1, output_dir = "outputs", ), ) trainer.train()

Buradaki tek Unsloth'a özgü ayar, use_gradient_checkpointing değerinin "unsloth" olması. Kütüphanenin kendi gradient checkpointing uygulamasını devreye sokar ve uzun bağlamda yaklaşık %30 ek VRAM kazandırır. Gerisi standart TRL kodu, bu yüzden mevcut eğitim betiklerine taşımak kolaydır.

Eğitim bitince model.save_pretrained("lora_model") yalnızca adaptör ağırlıklarını diske yazar; dosya boyutu genellikle birkaç yüz MB kalır. Birleştirilmiş tam model için model.save_pretrained_merged("merged", tokenizer, save_method = "merged_16bit") kullanılır. Çıkarım tarafında FastLanguageModel.for_inference(model) çağrısı modeli hızlı üretim moduna alır.

speed Model Boyutuna Göre VRAM İhtiyacı

  • check_circle 1B ile 3B modeller: 4 bit QLoRA, max_seq_length 2048 ve batch 2 ayarında yaklaşık 5 ile 6 GB VRAM yeter. Colab'ın ücretsiz T4 kartı (16 GB) bu sınıfta rahat çalışır, batch boyutunu 8'e kadar çıkarabilirsiniz.
  • check_circle 7B ve 8B modeller: Llama 3.1 8B veya Mistral 7B için tipik ihtiyaç 8 ile 12 GB arasında. Ücretsiz T4 üzerinde eğitilebilir. RTX 3090 ya da 4090 sahipleri 24 GB ile batch boyutunu 4'e, bağlamı 4096'ya çıkarabilir.
  • check_circle 12B ile 14B modeller: Gemma 3 12B veya Qwen 2.5 14B sınıfı 16 ile 20 GB ister. Tek 24 GB kart yeterlidir, ancak max_seq_length 4096'nın üzerine çıkıldığında bellek hızla artar; ilk kısıtlanacak ayar dizi uzunluğudur.
  • check_circle 30B ile 34B modeller: 24 GB kartlarda ancak kısa bağlam ve LoRA rank 8 ile 16 aralığında mümkün. Rahat çalışma için 40 veya 48 GB (A100 40GB, RTX A6000) gerekir.
  • check_circle 70B modeller: 4 bit QLoRA ile tek 48 GB kartta eğitilebildiği raporlanıyor, fakat uzun örnekli veri setlerinde 80 GB (A100 80GB, H100) daha güvenli. Bu boyutta batch 1 ile çalışıp kaybı gradient_accumulation_steps ile kapatmak normaldir.
  • check_circle Sayıların bağlamı: Değerler Unsloth'un yayımladığı ölçümlere ve topluluk raporlarına dayanır. Gerçek tüketim LoRA rank'i, target_modules listesinin uzunluğu, batch boyutu ve dizi uzunluğuyla değişir. Kendi rakamınızı görmek için ilk 10 adım boyunca nvidia-smi çıktısını izleyin.

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

  • check_circle torch.OutOfMemoryError alıyorum: Önce per_device_train_batch_size değerini 1'e indirin ve kaybı gradient_accumulation_steps ile telafi edin. Ardından max_seq_length'i düşürün ve use_gradient_checkpointing ayarının "unsloth" olduğunu doğrulayın. Aynı not defteri oturumunda önceki model nesnesi bellekte kaldıysa çekirdeği yeniden başlatmak gerekir.
  • check_circle Model desteklenmiyor hatası: Kütüphane modelin mimarisini tanıyamıyor demektir. unsloth/ ön ekli hazır 4 bit depolarından birini seçmek veya pip ile en güncel sürüme geçmek çoğu durumda çözer. Çok yeni mimarilerde destek birkaç hafta gecikebilir.
  • check_circle ImportError ve beklenmedik AttributeError: Genellikle unsloth ile unsloth_zoo sürümlerinin uyuşmamasından kaynaklanır. pip install --upgrade --force-reinstall --no-cache-dir unsloth unsloth_zoo komutu paket çiftini aynı sürüme hizalar.
  • check_circle CUDA capability uyarısı: Unsloth, CUDA hesaplama yeteneği 7.0 ve üzeri kartlar ister. GTX 1080 gibi Pascal kartlar (6.1) desteklenmez. T4, RTX 20xx, 30xx, 40xx ve A serisi kartlar çalışır.
  • check_circle Eğitilen model cümleyi bitirmiyor: Eğitim verisindeki örneklerin sonunda EOS token'ı yoksa üretim durmaz ve model kendi kendine konuşmaya devam eder. Metin sonuna tokenizer.eos_token eklemek ya da unsloth.chat_templates içindeki get_chat_template ve train_on_responses_only yardımcılarını kullanmak sorunu giderir.
  • check_circle GGUF dışa aktarımı başarısız oluyor: save_pretrained_gguf çağrısı llama.cpp'yi kaynaktan derler; cmake veya C derleyicisi eksikse işlem yarıda kalır. Sistem paketlerini kurmak istemiyorsanız önce merged_16bit olarak kaydedip dönüşümü ayrı bir makinede yapın.
  • check_circle İkinci GPU kullanılmıyor: Açık kaynak sürüm uzun süre tek GPU odaklı çalıştı ve çoklu kart desteği hâlâ olgunlaşıyor. Makinede birden fazla kart varsa CUDA_VISIBLE_DEVICES=0 ile tek karta sabitlemek beklenmedik davranışları önler.

Sık Sorulan Sorular

  • check_circle TRL ile farkı nedir? TRL resmi HuggingFace kütüphanesidir; Unsloth onun üzerine inşa edilir. Unsloth kernel optimizasyonları ekler; API uyumlu, geçiş kolaydır.
  • check_circle Nasıl kurulur? pip install unsloth ardından from unsloth import FastLanguageModel ile başlanır. Colab için hazır notebook'lar GitHub'da mevcuttur.
  • check_circle Hangi modeller desteklenir? Llama 3.x, Mistral, Gemma, Phi-3/4, Qwen2/3, DeepSeek ve diğerleri. Model listesi düzenli güncellenir.
  • check_circle Standart PEFT/QLoRA'ya kıyasla ne kadar hızlı? Yaklaşık 2× daha hızlı eğitim ve %60-70 daha az VRAM kullanımı raporlanmaktadır. Gerçek kazanım modele, batch boyutuna ve donanıma göre değişir.
  • check_circle Apple Silicon'da çalışır mı? Hayır, Unsloth yalnızca CUDA uyumlu NVIDIA GPU'larda çalışır. Apple Silicon için MLX tabanlı çerçeveler veya llama.cpp daha uygun alternatiflerdir.
  • check_circle Unsloth için minimum VRAM ne kadar? 4 bit QLoRA ile 3B sınıfı bir model yaklaşık 5 ile 6 GB, 8B sınıfı bir model 8 ile 12 GB VRAM ister. Colab'ın ücretsiz T4 kartı (16 GB) 8B modelleri 2048 token bağlamda eğitmeye yeter. Bellek yetmezse önce batch boyutunu 1'e indirip gradient_accumulation_steps değerini artırın.
  • check_circle Unsloth ücretsiz mi? Açık kaynak sürüm Apache 2.0 lisansıyla ücretsizdir ve hız ile bellek kazancının büyük bölümünü içerir. Ekip ayrıca çoklu GPU ve kurumsal destek içeren ticari bir sürüm sunuyor. Tek kartla çalışan kullanıcıların neredeyse tamamı için ücretsiz sürüm yeterli.
  • check_circle Unsloth ile eğitilen model Ollama'da nasıl çalıştırılır? Eğitim sonrası model.save_pretrained_gguf("model", tokenizer, quantization_method = "q4_k_m") çağrısı llama.cpp uyumlu tek bir dosya üretir. Ardından FROM ./model/unsloth.Q4_K_M.gguf satırını içeren bir Modelfile yazıp ollama create modelim -f Modelfile komutunu çalıştırmak yeterli.
  • check_circle Unsloth Windows'ta çalışır mı? Çalışır, ancak en sorunsuz yol WSL2 içinde Ubuntu kurup NVIDIA sürücüsünü Windows tarafında bırakmaktır. Yerel Windows kurulumunda triton'un Windows derlemesi ve bitsandbytes uyumu ek adım ister. Apple Silicon ise desteklenmiyor; orada MLX veya llama.cpp tabanlı araçlara yönelmek gerekir.