Haber Sınıflandırması İçin QLoRA ile Qwen3.5 Small İnce Ayarı

Qwen3.5 Small, prototipleme, göreve özel uyarlama ve araştırma iş akışları için tasarlandığından hafif ince ayar için pratik bir modeldir. QLoRA ile eşleştirildiğinde, donmuş 4 bit nicemlenmiş bir temel modelin üzerine ince ayar yapabiliriz; bu da süreci çok daha bellek verimli hale getirir ve sınırlı donanımlarda erişilebilir kılar.

Bu eğitimde ortamı kuracak, modeli ve AG News veri setini yükleyecek, temel modeli değerlendirecek ve ardından Qwen3.5 small’u haber sınıflandırması için ince ayar yapacağız. Eğitimden önce ve sonra sonuçları karşılaştırarak bitirecek, ardından LoRA adaptörünü yeniden kullanım için Hugging Face’e kaydedip yayımlayacağız. 

Eğer nasıl çalıştığına hâlihazırda aşina değilseniz Hugging Face Fundamentals beceri yolunu almanızı öneririm.

Qwen3.5 Small nedir?

Koda dalmadan önce, üzerinde çalıştığımız modeli anlamak faydalıdır. Qwen3.5 bir temel model ailesidir ve "Small" serisi, özellikle 10 milyar parametrenin altındaki hafif modelleri ifade eder. Bu eğitimde 0.8B sürümünü kullanacağız.

Sadece 800 milyon parametreye sahip olmasına rağmen Qwen3.5-0.8B oldukça yetenekli ve son derece verimlidir. 4 bit hassasiyetle yüklendiğinde 2 GB’tan az VRAM gerektirir. Bu da onu tüketici dizüstü bilgisayarları, Kaggle gibi ücretsiz bulut ortamları ve hafif edge dağıtımları için harika bir seçenek yapar.

Ayrıca Qwen3.5 mimarisi 262K gibi büyük bir bağlam penceresini ve yerel çok kipli (multimodal) desteği sunar. Bu rehberde yalnızca metin sınıflandırmaya odaklansak da, ele aldığımız temel kavramlar daha sonra kolayca görsel görevlere genişletilebilir. Model, hibrit akıl yürütme moduna da sahiptir; ancak basit etiketleme görevimizde çıkarım hızını en üst düzeye çıkarmak için bunu devre dışı bırakacağız.

Genel olarak Qwen3.5-0.8B, prototipleme için son derece pratik bir seçenektir. İnce ayar iş akışlarını hızlı ve düşük maliyetle test etmemizi sağlarken güçlü aşağı akış sonuçları sunar.

1. Kaggle Ortamını Kurun

Bu eğitimde, eğitim ortamı olarak bir Kaggle defteri kullanacağız. Kaggle bize GPU erişimi sağlar ve modeli eğitmek, ince ayar yapmak ve değerlendirmek için uygun bir platformdur. Defteri çalıştırmadan önce yeni bir Kaggle defteri başlatın, Oturum ayarlarını açın ve hızlandırıcı olarak GPU P100 seçeneğini belirleyin. 

Sonraki adımda ortamı kuracak, bir Hugging Face belirtecini (token) Kaggle’a ekleyecek ve eğitim boyunca kullanılan Python kütüphanelerini içe aktaracağız.

Hugging Face erişim belirteci oluşturun

Defteri çalıştırmadan önce hesabınızın ayarlar kısmından bir Hugging Face erişim belirteci oluşturun. Ayarlar’a gidin, Erişim Belirteçleri bölümünü açın ve yeni bir belirteç oluşturun. Eğitimin sonunda ince ayarlı LoRA adaptörünü Hugging Face Hub’a yayımlamak istiyorsanız, belirtecin yazma iznine sahip olduğundan emin olun.

Belirteci Kaggle secrets’a ekleyin

Belirteci oluşturduktan sonra Kaggle defterinizi açın ve onu bir gizli bilgi (secret) olarak ekleyin. Defter düzenleyicisinde Eklentiler, ardından Secrets bölümüne gidin ve HUGGINGFACE_TOKEN adında yeni bir gizli bilgi oluşturun. Belirteç değerini buraya yapıştırın; böylece defter, kodda açığa çıkarmadan güvenli bir şekilde erişebilir.

Gerekli kütüphaneleri yükleyin

Şimdi bu iş akışı için gereken temel kütüphaneleri yükleyebiliriz. Bu paketler; model yükleme, nicemleme, parametre verimli ince ayar, veri seti işleme ve değerlendirmeyi kapsar.

!pip install -q -U transformers accelerate
!pip install -q peft trl bitsandbytes datasets scikit-learnAltyapı:

Hugging Face ile kimlik doğrulayın

Sonraki adımda Hugging Face belirtecini Kaggle secrets’tan yükleyip kimlik doğrulamada kullanacağız. Bu, deftere modele erişim izni verir ve daha sonra eğitimli adaptörü göndermemize olanak tanır.

from huggingface_hub import login
from kaggle_secrets import UserSecretsClient

user_secrets = UserSecretsClient()
login(token=user_secrets.get_secret("HUGGINGFACE_TOKEN"))Altyapı:

Python kütüphanelerini içe aktarın

Son olarak, model yükleme, eğitim, veri seti işleme ve değerlendirme için eğitim boyunca kullanılan Python kütüphanelerini içe aktarıyoruz.

import torch
from datasets import load_dataset
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model
from trl import SFTTrainer, SFTConfig
from transformers import TrainingArguments
from sklearn.metrics import accuracy_score, f1_score
from tqdm.notebook import tqdmAltyapı:

2. Qwen3.5 Modelini ve AG News Veri Setini Yükleyin

Artık ortam hazır olduğuna göre, temel modeli yükleyebilir ve veri setini ince ayara hazırlayabiliriz. 

Bu bölümde, eğitimi daha bellek verimli kılmak için Qwen3.5-0.8B’yi 4 bit hassasiyetle yükleyecek, belirteçleyiciyi (tokenizer) kuracak ve eğitim ile değerlendirme için AG News veri setinin küçük bir alt kümesini yükleyeceğiz.

Qwen3.5-0.8B’yi 4 bit nicemleme ile yükleyin

BitsAndBytes kullanarak Qwen3.5-0.8B’yi 4 bit nicemleme ile yüklayarak başlıyoruz. Bu, bellek kullanımını azaltır ve modeli Kaggle defteri ortamında çalışmak için daha pratik hale getirir.

model_id = "Qwen/Qwen3.5-0.8B"

bnb_config = BitsAndBytesConfig(
  load_in_4bit=True,
  bnb_4bit_quant_type="nf4",
  bnb_4bit_compute_dtype=torch.bfloat16
)

model = AutoModelForCausalLM.from_pretrained(
  model_id,
  quantization_config=bnb_config,
  device_map="auto",
  dtype=torch.bfloat16
)Altyapı:

Belirteçleyiciyi yükleyin

Sonraki adımda aynı model için belirteçleyiciyi yüklüyoruz. Ayrıca, modelin eğitim ve üretim sırasında doldurulmuş girdileri doğru şekilde işleyebilmesi için dolgu (padding) belirtecini dizi sonu belirtecine ayarlıyoruz.

tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token

model.config.pad_token_id = tokenizer.eos_token_id
model.generation_config.pad_token_id = tokenizer.eos_token_idAltyapı:

AG News veri setini yükleyin

Son olarak, AG News veri setini yüklüyor ve bu eğitim için daha küçük eğitim ve test bölümleri oluşturuyoruz. Bir alt küme kullanmak iş akışını hızlandırırken, ince ayarın etkisini değerlendirmek için yeterli veri sağlar.

dataset = load_dataset("ag_news")

train_dataset = dataset["train"].select(range(2500))
test_dataset = dataset["test"].select(range(200))Altyapı:

3. İstem Biçimlendirme ve Başlangıç Değerlendirmesi

İnce ayardan önce, modelin görevi nasıl göreceğini tanımlamamız ve orijinal hâliyle ne kadar iyi performans gösterdiğini ölçmemiz gerekir. 

Bu bölümde, haber sınıflandırması için yönerge tarzında bir istem oluşturacak, model çıktısından tahminleri çıkaracak, örnek bir çıkarım çalıştıracak ve eğitimden önce temel modeli test kümesinde değerlendireceğiz.

Yönerge istemini oluşturun

Etiket adlarını tanımlayıp modelden bir haber makalesini sınıflandırmasını isteyen bir istem oluşturarak başlıyoruz. İstem, modelin yalnızca sayısal etiketi döndüreceği şekilde yazılmıştır; bu da değerlendirme sırasında çıktının ayrıştırılmasını kolaylaştırır.

labels = ['World','Sports','Business','Sci/Tech']

def build_prompt(text):

    return f"""
Classify the news article.

Article:
{text}

Return ONLY the number of the correct label.

0 = World
1 = Sports
2 = Business
3 = Sci/Tech

Answer:
"""Altyapı:

Model çıktısından tahminleri çıkarın

Sonraki adımda, üretilen metinden tahmin edilen etiketi çıkarmak için küçük bir yardımcı işlev oluşturuyoruz. Bu işlev, fazladan akıl yürütme belirteçlerini kaldırır ve son sınıf etiketini bir tamsayı olarak döndürür.

import re

def extract_label(text):

   text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL)
   matches = re.findall(r"[0-3]", text)

   if matches:
       return int(matches[-1])

   return -1Altyapı:

Örnek bir çıkarım çalıştırın

Modeli tüm test kümesinde değerlendirmeden önce, önce tek bir örnek üzerinde deneriz. Bu, makaleyi incelememize, doğru etiketi kontrol etmemize ve ince ayardan önce modelin ne tahmin ettiğini görmemize yardımcı olur.

sample = train_dataset[10]

sample_text = sample["text"]
sample_label = sample["label"]

print("Ground truth label:", sample_label)
print("Sample text:")
print(sample_text[:300])Altyapı:

Çıktı, gerçek etiketin 2 olduğunu ve bunun Business etiketine karşılık geldiğini gösteriyor.

Ground truth label: 2
Sample text:
Oil and Economy Cloud Stocks' Outlook  NEW YORK (Reuters) - Soaring crude prices plus worries  about the economy 
and the outlook for earnings are expected to  hang over the stock market next week during the depth of the  summer doldrums.Altyapı:

Şimdi istemi biçimlendiriyor, modele iletiyor ve bir tahmin üretiyoruz.

prompt = build_prompt(sample_text)

inputs = tokenizer(prompt, return_tensors="pt").to("cuda")

with torch.inference_mode():
    outputs = model.generate(
        **inputs,
        max_new_tokens=5,
        do_sample=False,
        pad_token_id=tokenizer.eos_token_id
    )

prediction = tokenizer.decode(outputs[0], skip_special_tokens=True)

print("Model prediction (before training):")
print(extract_label(prediction))Altyapı:

Model de 2 tahmin ediyor; yani bu örneği doğru sınıflandırıyor. Bu da istem biçiminin ve tahmin hattının beklendiği gibi çalıştığını hızlıca doğrular.

Model prediction (before training):
2Altyapı:

İnce ayardan önce temel modeli değerlendirin

Şimdi bir başlangıç düzeyi oluşturmak için temel modeli test kümesinde değerlendiriyoruz. Bu, ince ayardan önce ve sonra performansı karşılaştırmak için bir referans noktası sağlar.

def evaluate_model(dataset):

    preds = []
    refs = []

    model.eval()

    for example in tqdm(dataset):

        text = example["text"]
        label = example["label"]

        prompt = build_prompt(text)

        inputs = tokenizer(prompt, return_tensors="pt", truncation=True)
        inputs = {k: v.to("cuda") for k, v in inputs.items()}

        with torch.inference_mode():

            outputs = model.generate(
                **inputs,
                max_new_tokens=5,
                do_sample=False,
                pad_token_id=tokenizer.eos_token_id
            )

        prediction = tokenizer.decode(outputs[0], skip_special_tokens=True)

        pred_label = extract_label(prediction)

        preds.append(pred_label)
        refs.append(label)

    acc = accuracy_score(refs, preds)
    f1 = f1_score(refs, preds, average="weighted")

    print("Accuracy:", acc)
    print("F1:", f1)


print('Pre-fine-tuning evaluation')
evaluate_model(test_dataset)Altyapı:

Çıktı, doğruluğun 0.52 ve ağırlıklı F1 skorunun 0.4589 olduğunu bildiriyor. Bu başlangıç sonuçları, modelin görevi bir ölçüde yapabildiğini ancak ince ayarla iyileştirme için açık bir alan kaldığını gösteriyor.

Pre-fine-tuning evaluation
Accuracy: 0.52
F1: 0.45889163289429247Altyapı:

4. QLoRA ile Qwen3.5’i İnce Ayarlayın

Artık bir başlangıç düzeyi oluşturduğumuza göre modeli haber sınıflandırma görevi üzerinde ince ayarlayabiliriz. Bu bölümde, eğitim verilerini biçimlendirecek, LoRA adaptörlerini yapılandıracak, eğitim ayarlarını tanımlayacak, modeli eğitecek ve son adaptörü daha sonra kullanmak üzere kaydedeceğiz.

Eğitim verilerini hazırlayın

İlk olarak, her eğitim örneğini çıkarım sırasında kullanılan aynı istem yapısına uyacak şekilde biçimlendiriyoruz. Doğru etiketi istemin sonuna ekliyoruz; böylece model ince ayar sırasında doğru cevabı üretmeyi öğrenebilir.

def format_train(example):
    prompt = build_prompt(example['text'])
    answer = str(example['label'])
    return {'text': prompt + ' ' + answer}

train_dataset = train_dataset.map(format_train)Altyapı:

LoRA adaptörlerini yapılandırın

Sonraki adımda LoRA yapılandırmasını tanımlıyoruz. Bu, ince ayar sırasında hangi katmanların uyarlanacağını modele bildirir; böylece tüm modeli güncellemek yerine küçük bir ek parametre kümesi eğitilir.

lora_config = LoraConfig(
    r=16,
    lora_alpha=16,
    lora_dropout=0,
    bias='none',
    task_type='CAUSAL_LM',
    target_modules=[
        'q_proj','k_proj','v_proj','o_proj',
        'gate_proj','up_proj','down_proj'
    ]
)Altyapı:

Eğitim yapılandırmasını tanımlayın

Daha sonra denetimli ince ayar için eğitim argümanlarını ayarlıyoruz. Bu ayarlar, aynı anda kaç örneğin işleneceğini, gradyanların nasıl biriktirileceğini, eğitimin ne kadar süreceğini ve çıktı dosyalarının nereye kaydedileceğini belirler.

training_args = SFTConfig(
    output_dir="./qwen35-lora",
    per_device_train_batch_size=8,
    gradient_accumulation_steps=2,
    learning_rate=2e-4,
    num_train_epochs=1,
    logging_steps=10,
    bf16=True,
    dataset_text_field="text",
    packing=False,
)Altyapı:

Modeli eğitin

Şimdi eğitmeni; model, veri seti, LoRA yapılandırması, eğitim ayarları ve belirteçleyici ile başlatıyoruz. Ardından biçimlendirilmiş AG News eğitim kümesi üzerinde modele ince ayar yapmaya başlıyoruz.

trainer = SFTTrainer(
    model=model,
    train_dataset=train_dataset,
    peft_config=lora_config,
    args=training_args,
    processing_class=tokenizer
)
trainer.train()Altyapı:

Çıktı: 

TrainOutput(global_step=157, training_loss=1.9094241804378047, metrics={'train_runtime': 616.477, 'train_samples_per_second': 4.055, 'train_steps_per_second': 0.255, 'total_flos': 1041693973114368.0, 'train_loss': 1.9094241804378047})Altyapı:

Eğitilmiş adaptörü kaydedin

Eğitim tamamlandıktan sonra LoRA adaptörünü ve belirteçleyiciyi kaydediyoruz. Bu, ince ayarlı adaptörü daha sonra değerlendirme, paylaşma veya Hugging Face’e yayımlama için yeniden yüklememize olanak tanır.

trainer.model.save_pretrained("qwen35-small-news-class")
tokenizer.save_pretrained("qwen35-small-news-class")Altyapı:

5. İnce Ayarlı Modeli Değerlendirin

Eğitimden sonra temel modeli yeniden yükleyip kaydedilen LoRA adaptörünü ekliyoruz. Bu sayede ince ayarlı ağırlıkları kullanarak değerlendirmeyi çalıştırabilir ve sonuçları önceki başlangıç düzeyiyle karşılaştırabiliriz.

Temel modeli yeniden yükleyin ve LoRA adaptörünü ekleyin

Önce temel Qwen3.5 modelini tekrar yüklüyor, sonra Kaggle çalışma dizininde kaydedilen ince ayarlı LoRA adaptörünü ekliyoruz. Ardından modeli değerlendirme moduna alıp eğitilebilir parametre özetini inceliyoruz.

from transformers import AutoModelForCausalLM
base_model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    dtype=torch.bfloat16
)


from peft import PeftModel

model = PeftModel.from_pretrained(
    base_model,
    "/kaggle/working/qwen35-small-news-class"
)

model.eval()
model.print_trainable_parameters()Altyapı:

Çıktı, bu aşamada eğitilebilir parametre olmadığını gösteriyor; çünkü eğitim tamamlandı ve artık kaydedilen adaptörü çıkarım ve değerlendirme için kullanıyoruz.

trainable params: 0 || all params: 758,782,784 || trainable%: 0.0000Altyapı:

İnce ayarlı modeli değerlendirin

Şimdi aynı değerlendirme işlevini test kümesinde tekrar çalıştırıyoruz. Bu, ince ayardan sonra modelin ne kadar iyileştiğini ölçmemizi sağlar.

print('Post-fine-tuning evaluation')
evaluate_model(test_dataset)Altyapı:

Çıktı, doğruluğun 0.865 ve ağırlıklı F1 skorunun 0.8661 olduğunu bildiriyor. Başlangıç sonuçlarıyla karşılaştırıldığında, ince ayardan sonra büyük bir iyileşme olduğunu gösteriyor.

Post-fine-tuning evaluation
Accuracy: 0.865
F1: 0.8660926258753361Altyapı:

Sonuçları karşılaştırın

Artık modelin performansını ince ayardan önce ve sonra karşılaştırabiliriz. Hem doğruluk hem de F1 skoru önemli ölçüde artıyor; bu da QLoRA ile ince ayarın modelin haber sınıflandırma görevine iyi uyum sağlamasına yardımcı olduğunu gösteriyor.

Görüldüğü gibi, QLoRA ile Qwen3.5 Small’un ince ayarı sınıflandırma performansını önemli ölçüde artırıyor.

6. Modeli Hugging Face’e Yayımlayın

Değerlendirme tamamlandıktan sonra, ince ayarlı adaptörü ve belirteçleyiciyi Hugging Face’e yükleyebiliriz. Bu, modeli gelecekte tam eğitim sürecini tekrarlamadan yeniden kullanmayı, paylaşmayı ve projelere yüklemeyi kolaylaştırır.

model.push_to_hub("kingabzpro/qwen35-small-news-class")
tokenizer.push_to_hub("kingabzpro/qwen35-small-news-class")Altyapı:

Yükleme tamamlandıktan sonra model şu adreste erişilebilir olacaktır:

Model:
https://huggingface.co/kingabzpro/qwen35-small-news-classAltyapı:

Kaynak: kingabzpro/qwen35-small-news-class

Bu eğitime ait Kaggle defteri de mevcuttur. Yukarıdaki adımları yeniden üretirken sorun yaşarsanız kullanmanızı öneririm. Ayrıca defteri klonlayıp kendi sisteminizde çalıştırabilirsiniz; ancak Hugging Face kullanıcı adını ve belirtecini kendi hesabınıza uyacak şekilde güncellemeyi unutmayın.

7. Sonuç

Bu eğitimde, Qwen3.5-0.8B modeline QLoRA ile haber sınıflandırması için ince ayar yaptık ve çok hafif bir kurulumla güçlü bir sonuç elde ettik. Yalnızca bir epoch ve küçük bir veri alt kümesiyle doğruluk 0.52’den 0.865’e yükseldi; ağırlıklı F1 ise 0.4589’dan 0.8661’e çıktı. 

Bu kadar küçük bir model için en şaşırtıcı olan, güçlü aşağı akış sonuçları elde etmek için devasa bir model, büyük bir veri seti veya uzun bir eğitim koşusuna ihtiyaç duymamamız.

Bunu daha da kullanışlı kılan şey, kurulumun ne kadar pratik olduğudur. Qwen, 0.8B modeli prototipleme ve göreve özel ince ayar için iyi bir uyum olarak tanımlar ve QLoRA, donmuş 4 bit temel modelin üstünde adaptörleri eğiterek bellek kullanımını düşük tutar. Bu da bunun sadece bir bulut defteri iş akışı olmadığını gösterir. Daha küçük tüketici ve dizüstü GPU’larda test etmek için de gerçekçidir.

Bu modeli heyecan verici bulmamın bir diğer nedeni, Qwen3.5 ailesinin hem metin hem görsel ince ayarı desteklemesidir. Dolayısıyla burada metin sınıflandırma için kullansak da aynı fikir; görüntü sınıflandırma, görüntüden metne ve metinden metne görevlere de genişletilebilir. Bu da fikirleri hızlıca test etmek, ucuza ince ayar yapmak ve dağıtımı hafif tutmak istediğinizde bu kadar küçük bir modeli gerçekten pratik bir seçenek haline getirir.

Ayrıca diğer kaynaklarımıza da göz atmanızı öneririm: Qwen3.5 rehberimiz ve Qwen3.5’i tek bir GPU’da yerel olarak nasıl çalıştıracağınıza dair eğitim.