HakHukuk-4B-GGUF

HakHukuk-4B

Summary

HakHukuk-4B is a 4B-parameter Turkish legal assistant that runs on a consumer laptop GPU (Q4_K_M, about 3 GiB VRAM). Given a question and the text of the relevant statutes, it either answers and cites the article it relied on, or says that the provided sources do not cover the question. It is built on Qwen/Qwen3.5-4B from two LoRA branches (grounding and abstention) merged as task vectors with TIES. Scope: Turkish statutes in force (a 2026-08-06 snapshot). The reported numbers require the retrieval layer that ships with it; without sources the model produces confident but wrong legal content. It is not legal advice. Weights, code, data and the full research record are released under Apache-2.0.

Özet

HakHukuk-4B, tüketici sınıfı bir dizüstü GPU'sunda (Q4_K_M, yaklaşık 3 GiB VRAM) çalışan 4B parametreli bir Türkçe hukuk asistanıdır. Bir soru ve ilgili mevzuat metni verildiğinde ya cevaplar ve dayandığı maddeyi belirtir, ya da verilen kaynakların soruyu kapsamadığını söyler. Qwen/Qwen3.5-4B üzerine iki LoRA kolunun (temellendirme ve çekinme) görev vektörü olarak TIES ile birleştirilmesiyle elde edilmiştir. Kapsam: yürürlükteki Türkiye Cumhuriyeti kanunları (2026-08-06 anlık görüntüsü). Ağırlık, kod, veri ve araştırma kaydının tamamı Apache-2.0 lisansıyla açıktır.

Kullanmadan önce.

1. Hukuki tavsiye değildir. Ürettiği her madde numarası mevzuat.gov.tr üzerinden doğrulanması gereken bir iddiadır. Gerçek bir hukuki mesele için avukata danışılmalıdır. Bu ibarenin nihai metni hukukçu görüşü beklemektedir (açık karar S10).
2. Model tek başına bildirilen sonucu üretmez. Aşağıdaki sayılar, bir arama katmanının ilgili maddeleri bulup modele verdiği koşulda ölçülmüştür. Kaynaksız kullanımda model yüksek güvenle yanlış hukuki içerik üretir (§5.6).

Kütle tek bir sayı olarak değil, aralık olarak bildirilir: aynı 80 cevabı iki bağımsız hakem ailesi puanlamış, gpt-4o-mini 0,8011, claude-sonnet-5 0,6940 vermiştir (ADR-0084).

---

1. Model nedir

Modele bir soru ve kaynak madde metinleri verilir. Model ya cevaplar ve dayandığı maddeyi belirtir, ya da kaynakların soruyu kapsamadığını söyler. İkinci davranış bu projenin varlık sebebidir: hukukta kendinden emin bir yanlış madde numarası, "bilmiyorum" demekten daha zararlıdır. Model iki beceri için ayrı ayrı eğitilmiştir: verilen metne dayanmak ve metin yetmediğinde susmak.

Sade dil bir eğitim hedefi değildir. Sade ve kısa cevaba doğru eğitmek önceki hatta denenmiş, isabeti düşürmüş ve çekinmeyi çökertmiştir (ADR-0010). Eğitim doğruluk ve çekinmeyi hedefler; sadeleştirme istem katmanında yapılır.

Sürüm numaraları (ADR-0065; 2026-10-10'dan beri dosya adı ürün sürümünü taşır):

v1 adı bir sonraki eğitim turunun sonundaki sürüme ayrıldı. v0.5 modelin iyileştiği anlamına gelmez. Ağırlıklar v0.3'ten beri bayt bayt aynıdır; değişen, sürüm kapısının ikinci ve bağımsız bir hakem ailesi altında da geçmiş olmasıdır.

Kapsam. Yalnız yürürlükteki Türkiye Cumhuriyeti kanunları: 892 kanun, 40.496 madde, 2026-08-06 anlık görüntüsü. Yönetmelik, tüzük, KHK ve tebliğ kapsam dışıdır. Mevzuat değişir, ağırlıklar değişmez: güncellik arama katmanının sorumluluğundadır, modelin belleğinin değil.

2. Eğitim hattı ve yöntemler

Qwen3.5-4B (ham) ──┬── LoRA SFT   (temellendirme) ──► τ_g
                   └── LoRA ORPO  (çekinme)       ──► τ_a
                                                       │
            eşzamanlı 2-yollu TIES, norm dengeleme kapalı ◄┘
            trim_k 0,2 · λ 1,0 · 224/224 tensör · bf16
                                                       │
            llama.cpp ile Q4_K_M kuantizasyonu ──► GGUF

İki kolda ortak: QLoRA (NF4), r=16, α=32, tüm doğrusal katmanlar, dropout 0,05, seed 3407. τ_g'nin eğitim koşusu künye disiplininden önce yapıldığı için veri dizini doğrudan kayıtlı değildir; raft_scrubbed davranışsal kanıtla desteklenen okumadır. Ayrıntılı künye: docs/record/kollar.md.

Neden iki kol ayrı eğitildi. Görev vektörü τ = θ_ft − θ_base olarak tanımlanır; bu tanım iki kolun aynı θ_base'den çıkmasını şart koşar. Bir kolu diğerinin üstüne eğitmek ardışık SFT olurdu. Aynı sebeple birleştirme eşzamanlıdır: TIES kırpma, işaret seçimi ve ortalamayı bütün vektörler üzerinde birlikte yapar (ADR-0027).

Neden ham TIES. Kolların ölçeği çok farklıdır (‖τ_g‖ 10,47 ↔ ‖τ_a‖ 1,18, oran 8,87×). Başta, dengelenmezse küçük kolun silineceği varsayılmış ve norm dengeleme ana ayar olarak ön-kayıtlanmıştı. Ölçüm bunu tersine çevirdi (ADR-0052):

Ham TIES çekinme kolunu silmemiş, temellendirme kolunun M2b'deki düşüşünü kısmen onarmıştır (0,506 → 0,766). Bu tablo arama katmanı kapalı, eski soru setiyle ölçülmüştür; §5'teki sayılarla karşılaştırılamaz.

Arama katmanı. BM25 ve BAAI/bge-m3 yoğun arama sonuçları RRF ile birleştirilir (RRF_K=10), ilk 10 madde modele verilir, yürürlükten kalkmış maddeler elenir. Gömücü CPU'da, indeks CPU belleğinde ve diskte çalışır; GPU'ya yalnız model girer. İstemde önsöz yoktur. Üretim bütçesi 1024 düşünce + 512 cevap belirtecidir.

3. Benchmarklarımız

Ölçümler kendi kümemizde yapılmıştır. LegalBench, BigLaw-Bench ve MMLU gibi dış ölçütler koşulmamıştır: bunlar İngilizce ve common-law temellidir, bir Türk hukuku modelinde düşük not modelin mi sınavın mı kusuru olduğunu ayırmaz (ADR-0016). Bunun bedeli, üçüncü taraf bir çıpa üzerinde koşulmuş bir sayının olmamasıdır.

Altı mod (CANON, ADR-0011). Bu karttaki sayıların çoğu h1 ve M5'ten gelir.

Kümeler. Geliştirme kümesi (DEV) data/eval/dev/core_hard.jsonl, 80 soru; bütün seçimler burada yapılır. Donmuş test kümesi (TEST) data/eval/canon/; seçim için kullanılmaz, yalnız sürüm kabulünde ve insan onayıyla bir kez açılır.

Metrikler.

Rakipler. gemini-3.1-flash-lite, gemini-3.5-flash-lite, gemini-3.5-flash, claude-sonnet-5. Sınav eşittir ve bu ölçülmüştür: beş özne aynı 80 soruyu, bayt bayt aynı kaynaklarla ve aynı bütçeyle almıştır (ADR-0057). Bizim kolumuz yerelde llama-server ile, rakipler kendi API'leri üzerinden koşmuştur.

Puanlama. Çekinme tespiti ve atıf doğrulaması hakemsizdir (düzenli ifade ve korpusa karşı deterministik kontrol). Sadakat gibi yargı gerektiren eksenleri LLM hakemler puanlar: bağlayıcı hakem gpt-4o-mini, ikinci aile claude-sonnet-5. Bildirilen sayılarda hiçbir özne kendi ailesinin hakemiyle puanlanmamıştır. Her sayım adımında kalemler ayrıca gözle okunur.

4. Testler

4.1 Ölçüm kapıları

Sürüm kapısı (v0.5; ön-kayıttaki adı v1.0). Üç madde, hiçbir rakip sayısı görülmeden 2026-09-06'da ön-kayıtlanmıştır (ADR-0064):

1. Kütle, çıpanın (gemini-3.5-flash) kütlesinin en fazla 2 puan altında olabilir.
2. Yanlış maddeye dayanma gerilemez.
3. Ezber kütlesi (M5) temel modele göre yükselmez.
4. Her sayım adımında gözle okuma zorunludur.

Kapı önce gpt-4o-mini ile geçmiş, 2026-09-12'de claude-sonnet-5 altında yeniden okunmuş ve yine geçmiştir (ADR-0084). Sonuçlar §5.2'de.

Geçerlilik kapıları. Bir koşu bunları geçmeden puanlanmaz:

• Kesik cevap oranı en fazla %5 (ADR-0040).
• recall@10 bilinen değerden sapmaz; sapma arama katmanının değiştiğini gösterir.

Çekinme dedektörünün kalibrasyonu. Her rakip ailede çekinme sayılan bütün kalemler gözle okunmuştur. Dedektör hem Gemini hem Anthropic cevaplarında fazla çekinme saymış (doğru ve atıflı cevapları şerh cümlesi yüzünden çekinme saymış), bizim kolumuzda ise yanlış pozitif bulunmamıştır. Karttaki değerler bu düzeltmeden sonraki değerlerdir; ham araç okumaları docs/OLCUM.md §3.5'tedir.

Donmuş test kabul testi. TEST 2026-09-09'da insan onayıyla, bir kez açılmıştır. Rejim geliştirme koşusuyla aynıdır.

Ürün yolu ölçümü. Kullanıcının fiilen kuracağı yol (konteynerin HTTP API'si) 80 soruyla ayrıca ölçülmüş ve ölçüm hattının hakemiyle puanlanmıştır.

4.2 Yazılım testleri

pytest paketinde 337 test vardır: 335 geçer, 2'si bilinen ve işaretlenmiş başarısızlıktır (xfail). Testler yalnız kodu değil ölçüm rejimini de kapıya çevirir:

• docker/compose.yaml ayrıştırılır ve llama-server bayraklarının ölçüldükleri değerde olduğu sınanır (test_konteyner.py).
• Atıf doğrulayıcı, çekinme dedektörü ve dört durumlu sınıflandırıcı kendi testleriyle korunur (test_atif_dogrula.py, test_score_abstention.py, test_terazi.py).
• Bulunan her kusur bir regresyon testine dönüştürülmüştür (test_kusurlar.py).
• Belgelerdeki bütün göreli bağlantılar ve bu kartın Hugging Face sürümünün üretimi sınanır (test_belgeler.py, test_hf_kart.py).

5. Sonuçlar

Aksi belirtilmedikçe: DEV, n=80, arama katmanı açık, k=10, önsözsüz istem, seed 3407, bütçe 1536 belirteç, bağlayıcı hakem gpt-4o-mini, KV önbelleği q8_0.

5.1 Skor kartı

• claude-sonnet-5 kütlede, A1'de, gereksiz çekinmede ve yanlış maddeye dayanmada öndedir. HakHukuk cevaplama oranında, uydurulmuş madde numarasında, ezber kütlesinde ve maliyette öndedir.
• Rakip sütunları tek hakemlidir; HakHukuk sütunundaki kütle iki hakem ailesinin aralığıdır. Rakip değerleri üç okumanın rakip lehine olanıdır (docs/OLCUM.md §3.5).
• Yanlış maddeye dayanma sayıları gözle tam taramadır ve alt sınırdır.
• Maliyet OpenRouter fiyatlarıyla ölçülmüştür (2026-09-07); bizim kolumuz yerelde koştuğu için çıkarım bedeli sıfırdır. Hakem bedeli dahil değildir.
• Temel model (Qwen3.5-4B) tabloda yoktur: geçerlilik kapısından kalmıştır (kesik cevap 16/80 = %20, eşik %5). Kaynaklar eklendiğinde uzun, alıntı yapan cevaplar yazıp bütçeye sığmamaktadır; aynı model kaynaksız modda yalnız 2/80 kesik verir.

Kaynak: KALIBRASYON_ve_OZET.md · MALIYET.json · BULGU.md.

5.2 Sürüm kapısı

İkinci hakem altında kendi kütlemiz 10,71 puan, çıpanınki 12,42 puan düşmüştür; kapı çıpaya göre tanımlandığı için marj genişlemiştir. Mutlak bir eşik bu okumada kapıyı düşürürdü.

5.3 Hakem duyarlılığı

• Fark tamamen sadakat puanından gelir; coverage hakemden bağımsızdır.
• Kayma tek yönlüdür: ikinci hakem 24/80 kalemde daha düşük, 8/80 kalemde daha yüksek not vermiştir. Bu rastgele gürültü değil, sistematik katılıktır.
• Uyum zayıftır: Cohen κ 0,534 (tam sadakat) / 0,409 (atıf temizliği), aracın 0,6 eşiğinin altında; Pearson r 0,705.
• Hakemin yeniden koşma gürültüsü yaklaşık 0,3 A1 puanıdır; bundan küçük farklar yorumlanmaz.

Kaynak: KAPPA.md.

5.4 Geliştirme kümesi ve donmuş test

Düşüş 22,07 puandır. Bunun 16,87 puanı (%76) arama tavanının düşüklüğüyle açıklanır: iki küme kanuna göre katmanlıdır ama madde uzunluğuna göre değildir; en uzun madde diliminin payı DEV'de %12, TEST'te %50'dir ve arama uzun maddelerde zayıflar. Kalan 5,20 puan (%24) açıklanmaz; model görmediği veride tavanını da daha az kullanmaktadır. Koşunun kesiklik oranı %2,5'tir.

Kaynak: OZET.md · ADR-0069 · ADR-0077.

5.5 Ürün yolu

Fark −2,19 puandır (n=80'de bir adım 1,25 puan). Kaynak: outputs/eval/gorev/g24-urun-yolu-kutle-6.3b/.

5.6 Kaynaksız kullanım (M5)

M5 bir anti-hedeftir; çıpası rakipler değil temel modeldir. Sorulan, eğitimin modeli ezberden konuşmaya itip itmediğidir; itmemiştir (gözle okuma da aynı yönde: 0,4057 ↔ 0,4739). Bu tablodan "rakipleri yendik" sonucu çıkmaz: rakipler Türk hukukunu kaynaksızken bizden iyi bilmektedir. Bu bilgi arama ıskaladığında bir emniyet ağı da olmamaktadır: HakHukuk ve üç Gemini kolu altın maddenin gelmediği aynı 4 soruyu kaçırır ve bu sorularda rakiplerin sadakati 0,13-0,20'dir; ezberden bildikleri hukuku yanlış kanuna bağlarlar. Kör mod llama.cpp'nin DRY örnekleyicisiyle koşulduğu için hüküm yalnız HakHukuk ile temel model arasında kurulur (ADR-0073).

5.7 Kuantizasyon

Eğri monoton değildir ve mekanizması ölçülmemiştir; bu yüzden yayımlanan taşıyıcı değiştirilmemiştir. Kaynak: OZET.md.

5.8 Donanım

llama-server, Q4_K_M, KV önbelleği q8_0, tek slot:

Kaynak: vram_stack_tgta_v1.json.

6. Sınırlar

Bilinen kusurlar.

Davranış özellikleri. Model cevaptan önce düşünür (ortalama 782,5 belirteç). Çekinmesi kısa ve kalıplıdır (medyan 58 karakter). Soruların 4/80'i 1536 belirteçlik bütçeye sığmaz. Cevapların 7/80'i atıf taşımaz; bunlar doğru olabilir ama denetlenemez. Sadakat tek bir altın maddeye göre puanlanır; başka gerçek bir maddeden doğru cevap vermek ölçümde sadakatsiz sayılır.

Hakem. Yargı eksenlerindeki bütün değerler LLM hakem puanıdır. İki hakem ailesi aynı yönde hükmeder ama uyumları zayıftır (κ < 0,6), panel hedeflenen üç aile yerine iki ailedir ve öz-tercih genel olarak ölçülmemiştir. Bu sayılar mutlak doğruluk değil, modeller arası sıralama olarak okunmalıdır.

Tek boyut noktası. Yalnız ~4B ölçülmüştür. Bulguların bu temel modele özgü olup olmadığı ve kapasite büyüdükçe nasıl değiştiği açık sorudur.

Bu karttan kurulmayan cümleler.

1. "TEST'te de aynı başarım." Ölçüm DEV'dedir; TEST'te kütle 0,5804'tür (§5.4).
2. "Üç aileli bir hakem panelinden geçmiş hüküm." Panel iki ailelidir ve κ eşiğin altındadır.
3. "v0.5 modelin iyileştiği anlamına gelir." Ağırlıklar değişmemiştir.
4. "Maliyete göre normalize edilmiş eşdeğerlik." Maliyet ölçülmüştür, ama eşdeğerlik bir maliyet satırından değil, bir başarım-maliyet eğrisinden kurulur.
5. "Kaynaksız da iyi çalışır." Tersi ölçülmüştür (§5.6).
6. "M5'te rakipleri yendik." M5'in çıpası temel modeldir (§5.6).
7. "Rakip havuzu sektörü temsil eder." Rakipler iki sağlayıcıdandır (Google, Anthropic).

7. Çalıştırma

7.1 Konteyner (önerilen)

git clone https://github.com/Rfetha/HakHukuk && cd HakHukuk
docker compose -f docker/compose.yaml up

indir kutusu GGUF'u ve arama indeksini sabitlenmiş bir revizyondan indirir, bayt sayısı ve sha256 ile doğrular; doğrulama tutmazsa iki servis de başlamaz (ADR-0078). Konteyner aşağıdaki bayrakları zorunlu kılar; elle kurulumda bunları kullanıcı yazmak zorundadır.

Servisler yalnız 127.0.0.1 arayüzüne açılır; kimlik doğrulama ve hız sınırı yoktur (açık karar S9).

7.2 Sunucu bayrakları sonucu değiştirir

Bildirilen değerler şu yapılandırmayla üretilmiştir:

llama-server -m HakHukuk-4B-v0.5-Q4_K_M.gguf \
  -ngl 99 -fa on --no-context-shift \
  --cache-type-k q8_0 --cache-type-v q8_0 \
  -c 8192 --host 127.0.0.1 --port 8080

Bayraklar belgelendirme ayrıntısı değildir. Aynı soru, aynı seed ve sıcaklık 0 ile yalnız KV önbelleği q8_0'dan varsayılan fp16'ya alındığında 80 cevabın 65'i değişmiş, kütle 0,8011'den 0,7932'ye inmiş ve yanlış atıf oranı 0,0769'dan 0,1553'e çıkmıştır. Varsayılan KV ile bildirilen başarımın korunacağı iddia edilmez (KARSILASTIRMA.md). Konteyner bunlara --reasoning-format deepseek ekler. Bu bayrak, ölçüm sırasında varsayılan olan auto'nun davranışını değiştirmez, sabitler (ikisinin aynı çıktıyı verdiği ölçülmüştür); paketin düşünce kanalını ikinci geçişte kapatması bu biçime dayanır (ADR-0080). Elle kurulumda da eklenmelidir.

7.3 Python paketi

Paket llama-server'ı 127.0.0.1:8080'de bekler (§7.2) ve arama indeksini depo kökünden data/index/mevzuat_bge_m3_s2/ olarak okur; ikisi de HAKHUKUK_SUNUCU ve HAKHUKUK_INDEKS ortam değişkenleriyle değiştirilebilir.

pip install -e .
hakhukuk "Askerlik nedeniyle iş sözleşmesi ne olur?"   # komut satırı
hakhukuk-tui                                           # tek ekran arayüz
pip install -e ".[api]" && hakhukuk-api                # HTTP API

from hakhukuk.cekirdek import servis

cevap = servis.answer("Kat malikleri kurulu hangi çoğunlukla karar alır?")
cevap.durum      # Durum.CEVAP | CEKINCELI | SUSKUNLUK | KESIK
cevap.atiflar    # her atıf için: getirilen kaynakta doğrulandı mı
cevap.kaynaklar  # modele verilen maddeler

Paket her durumda şunları garanti eder:

• Doğrulanamayan atıf gizlenmez, uyarıyla gösterilir.
• Bütçeye sığmayan cevap KESIK durumuyla işaretlenir.
• Arama hiç kaynak bulamazsa model çağrılmaz.
• Yürürlükten kalkmış maddeler modele verilmez.
• Sorumluluk ibaresi her cevapta basılır.

8. Yeniden üretim, lisans, atıf

Yeniden üretim. bash scripts/yeniden_uret.sh bildirilen tek-hakem okumasını (kütle 0,8011) üretir: ön koşul denetimi, üretim, iki geçerlilik kapısı, puanlama ve çıpadan sapma kontrolü. Ayrıntı: docs/YENIDEN_URETIM.md. Değişmezler:

seed 3407 · parça kırpma 900 karakter · düşünce açık · bütçe 1024 + 512 · n 80
soru seti data/eval/dev/core_hard.jsonl · indeks mevzuat_bge_m3_s2 · k 10 · RRF_K 10 · önsözsüz

Bu değerlerden biri değişirse koşu hata vermez, yalnız karşılaştırma geçersiz olur.

Birleştirme:

python scripts/egitim/merge_ties.py --base Qwen/Qwen3.5-4B \
       --adapter tg=outputs/tg_v1 --adapter ta=outputs/ta_v1 \
       --no-norm-balance --out models/merged/tgta_v1

LoRA adaptörleri git'te değildir (GitHub'ın 100 MB sınırı) ve yedeklenmez; veri, reçete ve seed sabit olduğu için yeniden üretilebilirler.

Veri ve lisans. Lisans Apache-2.0'dır ve ağırlıkları, kodu, veriyi ve araştırma kaydını kapsar; temel model Qwen/Qwen3.5-4B de Apache-2.0'dır. Yalnız kamuya açık ve lisansı uygun kaynaklar kullanılmıştır (Mevzuat.gov.tr, Resmî Gazete, Yargıtay açık portalı, açık lisanslı veri setleri); ticari hukuk veritabanları kullanılmamıştır. Her veri seti kullanılmadan önce örneklenip gözle denetlenir. Eğitim verisinde kişisel veriler maskelenmiştir. Örnek cevaplar ağırlık deposundaki ORNEK_CEVAPLAR.md dosyasındadır.

Daha fazlası. Ayrıntılı ölçüm tabloları: docs/OLCUM.md · kararlar ve elenen seçenekler: docs/adr/ · kronolojik ölçüm kaydı: docs/record/.

@software{hakhukuk2026,
  title   = {HakHukuk-4B: A Turkish legal assistant built by task-vector merging},
  year    = {2026},
  url     = {https://github.com/Rfetha/HakHukuk},
  license = {Apache-2.0}
}