CoolFace
Modelpublic

hoheyto/JokerCoder

sourceHugging Facemitupdated 18d agoView on Hugging Face
1likes72downloads
Model Card

Türkçe Kod Açıklama Asistanı

Base model: Qwen3-8B (Unsloth, unsloth-bnb-4bit)

Yöntem: QLoRA (4-bit quantization + LoRA)

Dil: Türkçe

Görev: Python fonksiyonlarını, junior geliştiricilere yönelik, teknik olarak doğru + hafif mizahi bir tonda açıklama

Model Açıklaması

Bu model, genel amaçlı bir kod-anlama modelinin, Türkçe konuşan junior geliştiricilere yönelik erişilebilir kod açıklamaları üretmesi için fine-tune edilmiş halidir. Çıktı formatı bilinçli olarak iki cümleye bölünmüştür:

  1. 1.Teknik cümle — fonksiyonun girdi/işlem/çıktısını doğru ve net şekilde anlatır.
  2. 2.Mizah cümlesi — kodun kendi mantığından türeyen, kısa bir gözlem/benzetme (dekoratif metafor değil).

Bu ayrım, veri kürasyonu sürecinde karşılaşılan bir soruna doğrudan çözüm olarak tasarlandı (bkz. "Veri Kürasyonu Süreci").

Kullanım Amacı ve Sınırlamalar

Uygun kullanım: Türkçe kaynakla kod öğrenen/gözden geçiren junior geliştiriciler için hızlı, anlaşılır kod açıklamaları.

Uygun olmayan kullanım: Güvenlik-kritik kod incelemesi, üretim ortamı kod review süreci, ileri seviye algoritmik doğrulama (aşağıdaki sınırlamalara bakınız).

Veri Kürasyonu Süreci — Kısa Özet

Nihai eğitim veri seti (~900+ örnek, kod+açıklama çifti) 5 turluk bir üretim/doğrulama döngüsünden geçirildi:

  • —Kod kaynağı: Karışık — mevcut LeetCode-tarzı problemler + ast modülüyle programatik olarak üretilmiş, zorluk kotasına göre dağıtılmış (~%30 temel, ~%40 orta, ~%30 ileri) özgün algoritmalar (sıralama/arama varyasyonları, graf algoritmaları, DP, veri yapıları, sayı teorisi, geometri, ML-temel fonksiyonlar).
  • —Açıklama üretimi: Elle hazırlanmış altın örneklerden yararlanılan bir veri oluşturma (bootstrapping) süreciyle üretildi.

Karşılaşılan ve çözülen kalite sorunları: | Sorun | Teşhis yöntemi | Çözüm | |---|---|---| | Aşırı argo/küfür | Elle örnekleme | Golden örnekleri temizleme, yasaklı kelime filtresi | | Aşırı süslü/şiirsel dil | Kelime frekans analizi (kusursuz, zarif, ayna vb. taraması) | Prompt'a katı kelime sayısı sınırı + yasaklı kelime listesi | | Teknik halüsinasyon + "kelime salatası" (uydurma kelimeler, bozuk çekim) | Kontrollü test: greedy decoding (do_sample=False) ile bile hata sürdüğü için, sorunun generation ayarlarında değil base modelde olduğu kanıtlandı | Base model değişikliği: Qwen2.5-Coder-7B-Instruct → Qwen3-8B |

Bu son bulgu, projenin en önemli metodolojik kararıydı: hyperparameter ayarı (LoRA alpha/r oranı dahil) bu sorunu çözemedi, çünkü kök neden veri değil, base modelin Türkçe'deki temel sınırlamasıydı. Üç ana deneyin (hiperparametre ablation'ı, generation ayarları, base model karşılaştırması) detaylı kaydı için EXPERIMENTS.md dosyasına bakınız.

Eğitim Prosedürü

Yöntem: QLoRA — base model 4-bit quantized (bnb), LoRA adaptörleri 16-bit'te eğitildi.

Hiperparametreler (küçük ölçekli ablation ile belirlendi, 146 örneklik alt kümede test edildi):

  • —LoRA rank (r): 16
  • —LoRA alpha: yüksek (alpha/r oranı ~2-4 aralığında en iyi val loss'u verdi; oran=1 test edildi, veri kirliliğinden bağımsız bir iyileşme sağlamadığı doğrulandı)
  • —Learning rate: 2e-4, linear scheduler
  • —Effective batch size: 8 (perdevice=2, gradientaccumulation=4)
  • —Epoch: 2-3 (4 epoch'ta val loss'un 2. epoch sonrası yükselmeye başladığı, yani overfitting'in başladığı gözlemlendi)
  • —load_best_model_at_end=True, metric_for_best_model="eval_loss" ile en iyi checkpoint otomatik seçildi

Donanım: Kaggle T4 GPU (ücretsiz katman), Save & Run All (commit) modu ile idle-timeout'tan bağımsız eğitim.

Değerlendirme

Otomatik metrikler (eval_loss, kelime sayısı, yasaklı kelime taraması) tek başına yeterli görülmedi — elle, kategori bazlı okuma ana değerlendirme yöntemi oldu:

  • —23 örneklik held-out set (LeetCode-tarzı algoritmalar) üzerinde manuel rubric kontrolü: teknik doğruluk, mizahın koda bağlılığı, gramer/akıcılık.
  • —Ayrıca, veri setinde hiç bulunmayan konu başlıklarıyla (Heavy-Light Decomposition, Karatsuba çarpma, Reservoir Sampling, 0-1 BFS) genelleme testi yapıldı.

Sonuç: Base model değişikliği sonrası, 23 örneğin büyük çoğunluğunda (~%90+) teknik doğruluk ve akıcılık sağlandı; halüsinasyon/uydurma kelime oranı sıfıra yakın.

Bilinen Sınırlamalar

  • —Kelime ve kalıp tekrarı: Model, bazı sıfatları ve benzetme kalıplarını beklenenden sık kullanabiliyor. Bu durum mizahi çeşitliliği zaman zaman sınırlayabiliyor.
  • —Niş algoritmalarda yüzeysellik: Eğitim verisinde az temsil edilen ileri algoritmalarda açıklamalar teknik olarak doğru olsa da daha genel ve yüzeysel kalabiliyor.
  • —Mizah-kod bağlantısında tutarsızlık: Bazı açıklamalarda mizah kodun mantığıyla güçlü biçimde bütünleşirken, bazılarında daha yüzeysel veya zorlama kalabiliyor.
  • —CPU tabanlı demo: Demo, GGUF (Q4_K_M) formatında llama.cpp ile CPU üzerinde çalıştırılıyor. Bu nedenle yanıt üretimi yaklaşık 2-3 dakika sürebiliyor.

Veri Seti

Modelin eğitiminde kullanılan veri setine buradan ulaşabilirsiniz:

Veri Seti: hoheyto/turkce_kod_aciklama_dataset

Kullanım

python
from llama_cpp import Llama

llm = Llama(model_path="qwen3-8b.Q4_K_M.gguf", n_ctx=2048)

prompt = (
    "<|im_start|>user\n"
    "Bu kodu açıkla:\n\ndef topla(a, b):\n    return a + b<|im_end|>\n"
    "<|im_start|>assistant\n"
)
output = llm(prompt, max_tokens=120, temperature=0.0, repeat_penalty=1.03, stop=["<|im_end|>"])
print(output["choices"][0]["text"].strip())

Deployment

Model, FastAPI + Docker ile paketlenip Hugging Face Spaces'te (Docker SDK) barındırılıyor. Canlı demo: [JokerCoder Demo](https://hoheyto-jokercoder-demo.hf.space/docs)

Teşekkür / Notlar

Bu proje, Unsloth kütüphanesi ve Hugging Face ekosistemi (transformers, datasets, TRL, PEFT) kullanılarak, Kaggle'ın ücretsiz GPU kaynaklarıyla geliştirilmiştir.-