HukukcuApp/tr-legal-embedding-gemma-2

HukukcuApp TR Legal Embedding Gemma-2 ⚖️🇹🇷

HukukcuApp TR Legal Embedding Gemma-2, Yargıtay emsal kararlarında hukuki uyuşmazlık ➔ emsal gerekçe eşleştirmesi ve içtihat arama görevleri için özelleştirilmiş dikey bir semantik arama modelidir.

Google'ın EmbeddingGemma-2 mimarisi üzerinde, kararlardaki uyuşmazlık tanımları, hukuki ilkeler ve gerekçe blokları arasındaki anlamsal bağı kurmak amacıyla 118.078 adet içtihadi üçlü (triplet) ile fine-tune edilmiştir.

---

📋 Model Özellikleri

• Model Türü: Yoğun Vektörel Semantik Arama
• Temel Mimari: google/embeddinggemma-2 (embedding_gemma2_text mimarisi)
• Parametre Sayısı & Boyut: 271 Milyon parametre. Yalnızca metin katmanlarını içeren 516 MB hafif modeldir.
• Embedding Vektör Boyutu: 768
• Bağlam Uzunluğu (Token Bütçesi):
  • Eğitim: Sorgu: 256 / Doküman: ≤ 512 token
  • Önerilen Kullanım (Arama): Sorgu: 256 / Doküman: ≤ 1024 token
• Vektör Havuzlama: Ortalama Havuzlama (Mean Pooling) + L2 Birim Normalizasyonu
• Benzerlik Ölçümü: Kosinüs Benzerliği (Cosine Similarity) / İç Çarpım (Dot Product)
• Gereksinimler: Güncel transformers, sentence-transformers ve torch kütüphaneleri gereklidir.

---

🎯 Modelin Odak Alanı ve Sınırları

Temel Yetkinlik (Birincil Görev)

• Uyuşmazlık ➔ Emsal Karar Erişimi: Somut bir hukuki uyuşmazlık veya dava konusu metni verildiğinde, geniş karar külliyatı içerisinden ilgili konuyu çözen emsal kararın ilke ve gerekçesini en üst sıralarda bulup getirmek.

Potansiyel Kullanım Alanları (Doğrudan Ölçülmemiş)

• Dava dilekçelerindeki vakıa anlatımlarına uygun emsal karar önerileri,
• Külliyat içerisindeki paralel veya zıt yönlü içtihatların taranması.

⚠️ Önemli Sınırlar

• Üretken Model (LLM) Değildir: Model hukuki bir mütalaa yazmaz, soru cevaplamaz veya yeni bir karar metni üretmez; yalnızca yüksek hassasiyetli vektörel benzerlik ve içtihat erişim motorudur.

---

🏋️ Eğitim Detayları ve Metodoloji

• Taban Model: google/embeddinggemma-2
• Veri Kaynağı: Yargıtay'ın kamuya açık emsal kararları ve içtihatları.
• Eğitim Verisi: 118.078 adet içtihadi üçlü (task: search query | query: ➔ title: none | text: olumlu karar ➔ zorlayıcı negatif karar).
• Veri Hazırlama Boru Hattı: Eğitim öncesi veri üretim aşamasında BM25 tabanlı zor negatif madenciliği yapılmış; pozitif kararla kosinüs benzerliği $\ge 0,88$ olan emsal ikiz kararlar negatif havuzundan elenerek yanlış negatif (false-negative) oluşumu engellenmiştir.
• Sızıntı Önleme ve Sınırlılık: Test kararları eğitim kümesinden ayrı tutulmuştur (külliyat hunisi, mükerrer ayıklama, semantik ikiz dışlama). Ancak Yargıtay içtihadının kalıplı yapısı nedeniyle test sorularıyla eğitim kümesi arasında konu düzeyinde benzerlik bulunabilir. Bu nedenle sonuçlar, eğitim dağılımıyla aynı külliyatta arama performansını yansıtır; tamamen yeni hukuki konulara genelleme garantisi vermez.
• Kayıp Fonksiyonu: MultipleNegativesRankingLoss (scale = 20.0).
• Optimizasyon: AdamW (öğrenme oranı = 2e-5, weight decay = 0.01), 100 adım ısınma (warmup).
• Eğitim Süresi ve Checkpoint Seçimi: Eğitim 3.0 epoch için planlanmış, ara ağırlıklar her 0,5 epoch'ta kaydedilip doğrulama metrikleriyle (NDCG@5, MRR, Top-1) değerlendirilmiştir. En iyi sonuç Epoch 2.0'da elde edilmiş ve yayınlanan checkpoint olarak seçilmiştir.

Eğitim Dinamikleri ve Doğrulama Günlüğü

Not: Model her 0,5 epoch'ta ara doğrulama setleriyle değerlendirilmiştir. Tablodaki Val NDCG@5 metriği 2.529 soruluk doğrulama havuzunda (999 karar); Top-1, Hukuk ve Ceza başarıları ise 320 kararlık sabit doğrulama kümesinde ölçülmüştür:

Eğitim Aşaması	Eğitim Kaybı (Loss)	Val NDCG@5	Sabit Doğrulama Top-1 (320 Karar)	Hukuk Başarısı	Ceza Başarısı	Durum
Başlangıç (Sıfır-Shot)	—	0,6295	224 / 320 (%70,0)	154 / 200	70 / 120	Ham Taban Model
Epoch 0.5	0,5120	0,7679	244 / 320 (%76,3)	168 / 200	76 / 120	Hızlı Adaptasyon
Epoch 1.0	0,3845	0,7719	245 / 320 (%76,6)	167 / 200	78 / 120	Dengeleme
Epoch 1.5	0,3012	0,7831	248 / 320 (%77,5)	168 / 200	80 / 120	İlerleme
Epoch 2.0 (Seçilen Checkpoint) 🏆	0,2536	0,7858	254 / 320 (%79,4)	173 / 200	81 / 120	Optimum Genelleme

---

🏆 Test ve Değerlendirme Sonuçları

Ayrı Tutulan 10.000 Kararlık Test Seti

Ayrı tutulan 10.000 karar (5.000 Hukuk + 5.000 Ceza) üzerinde yapılan $10.000 \times 10.000$ sıralama testi sonuçları:

Model	Model Türü	Top-1 (1. Sırada)	Top-5 (İlk 5'te)	Top-10 (İlk 10'da)	Hukuk Top-1	Ceza Top-1	MRR
Gemma-2 Base	Ham Taban (Sıfır-Shot)	%46,21	%64,62	%71,82	%58,04	%34,38	0,5503
Mürşit Base TR	Referans Taban Model	%46,87	%65,41	%72,43	%60,32	%33,42	0,5552
HukukcuApp Gemma-2	Fine-Tuned (Epoch 2.0)	%53,75	%71,01	%77,11	%65,44	%42,06	0,6178
Net Gelişim (Tabana Göre)	—	+7,54 puan	+6,39 puan	+5,29 puan	+7,40 puan	+7,68 puan	+0,0675

• 10.000 Aday Karar Arasında Tek Atış (Top-1): Uyuşmazlık sorgularının %53,75'inde doğru emsal karar, 9.999 alternatif karar arasından doğrudan 1. sırada getirilmiştir.
• Top-10 Kapsamı: Doğru emsal karar %77,11 oranında ilk 10 sonuç içerisinde yer almaktadır. Hukuk dairesi kararlarında ilk 5'te doğru kararı yakalama oranı %82,6'dır.

---

Hızlı Başlangıç

pip install --upgrade transformers sentence-transformers torch

Yöntem 1: Sentence-Transformers ile (Önerilen)

from sentence_transformers import SentenceTransformer

# Modeli yukle
model = SentenceTransformer("HukukcuApp/tr-legal-embedding-gemma-2")

# 1. Sorgu ve Emsal Karar Dokumanlari
queries = ["Taşınmaz satış vaadi sözleşmesinde zamanaşımı ve zilyetlik defi"]
documents = [
    "Hukuki İlkeler: Satış vaadi sözleşmelerinde zamanaşımı 10 yıldır. Zilyetlik devredilmişse zamanaşımı defi dinlenmez.",
    "Hukuki İlkeler: Karşılıksız çek keşide etme suçunda adli para cezası ve çek düzenleme yasağı."
]

# 2. Kodlama (Otomatik prompt ve normalizasyon)
q_emb = model.encode(queries, prompt_name="query", normalize_embeddings=True)
doc_embs = model.encode(documents, prompt_name="document", normalize_embeddings=True)

# 3. Benzerlik Hesabi
similarities = model.similarity(q_emb, doc_embs)
print("Benzerlik Skoru:", similarities[0].tolist())

---

Yöntem 2: Transformers ile

import torch
import torch.nn.functional as F
from transformers import AutoTokenizer, AutoModel

model_id = "HukukcuApp/tr-legal-embedding-gemma-2"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModel.from_pretrained(model_id).to("cuda" if torch.cuda.is_available() else "cpu")
model.eval()

def get_embedding(texts, prefix="", max_length=512):
    prefixed = [f"{prefix}{t}" for t in texts]
    inputs = tokenizer(prefixed, padding=True, truncation=True, max_length=max_length, return_tensors="pt").to(model.device)
    with torch.no_grad():
        out = model(**inputs)
        mask = inputs["attention_mask"].unsqueeze(-1)
        emb = torch.sum(out.last_hidden_state * mask, dim=1) / mask.sum(dim=1).clamp(min=1e-9)
        return F.normalize(emb, p=2, dim=1)

# Sorgu: max_length=256
q_emb = get_embedding(
    ["Taşınmaz satış vaadinde zamanaşımı"], 
    prefix="task: search query | query: ", 
    max_length=256
)

# Dokuman: max_length=1024
doc_emb = get_embedding(
    ["Hukuki İlkeler: Satış vaadinde zamanaşımı 10 yıldır. Zilyetlik devrinde defi dinlenmez."], 
    prefix="title: none | text: ", 
    max_length=1024
)

score = torch.mm(q_emb, doc_emb.T)
print("Kosinüs Benzerliği:", score.item())

---

🔒 Veri Gizliliği ve Fikri Mülkiyet Bildirimi

Bu model "Açık Ağırlıklı" olarak sunulmaktadır. Modelin eğitildiği 118.078 adet içtihadi veri kümesi ile test verileri; kişisel verilerin korunması (KVKK), gizlilik ilkeleri ve modelin tescilli veri boru hattı mimarisinin korunması amacıyla kamuya açık bir veri seti olarak paylaşılmamaktadır.

---

⚖️ Hukuki Sorumluluk Reddi

Bu model bir hukuk danışmanı veya nihai hukuki mütalaa organı değildir. Yalnızca emsal içtihat tespitini ve doktrinel araştırmayı hızlandırmak üzere tasarlanmış teknik bir semantik erişim aracıdır. Somut uyuşmazlıklarda nihai hukuki değerlendirme ve sorumluluk uygulayıcıya aittir.

---

📜 Lisans

Bu model, Google Gemma lisansı altındadır. Kullanım, dağıtım ve türev çalışmalar Google'ın resmi koşullarına tabidir:

• Google Gemma Terms of Use