Türkçe Akademik Embedding Veri Kümesi — Tasarım Raporu

Doküman Türü: Tasarım Raporu (Design Document)
Durum: Taslak — uygulama öncesi kavramsal çerçeve
Son Güncelleme: Nisan 2026
Wiki Konumu: Anlamsal-Arama/Veri-Kumesi-Tasarimi/ → bu sayfa.
Karar kartı için önce ./README.md okunmalı.

Önemli Uyarılar

Bu doküman bir tasarım raporudur; kesinleşmiş bir uygulama spesifikasyonu değildir. Aşağıdaki hususlar göz önünde bulundurulmalıdır:

Mevcut veriye dayalı tahminlerdir. Bu rapordaki tüm hacim hesaplamaları, oran önerileri ve compute tahminleri, elimizdeki yaklaşık 300 bin .md dosyası ve bunlara ait metadata yapısı baz alınarak üretilmiştir. Gerçek uygulama sürecinde bu rakamlar farklılık gösterebilir. Örneğin kalite filtreleri uygulandığında temiz belge sayısı tahmin edilenden düşük veya yüksek çıkabilir; chunk üretim oranları makale uzunluğuna ve alan dağılımına göre değişebilir; pozitif çift sayıları belge başına bölüm ve paragraf yoğunluğuna bağlıdır.

Veri kümesi özellikleri değişkenlik gösterebilir. Akademik makalelerin alan dağılımı (tıp, mühendislik, sosyal bilimler vb.), dil dağılımı (tamamen Türkçe, tamamen İngilizce, iki dilli), yapısal kalitesi (iyi segmentlenmiş vs. bozuk layout) ve metadata tutarlılığı homojen değildir. Bu heterojenlik, burada önerilen eşik değerlerinin, filtreleme kurallarının ve örnekleme oranlarının pilot çalışma sonuçlarına göre revize edilmesini gerektirebilir.

Öneriler referans çalışmalara dayanır ancak doğrudan aktarım garantisi yoktur. SPECTER, SciDocs, SciRepEval, BEIR, MTEB ve TR-MTEB gibi referans çalışmalardan çıkarılan ilkeler ve oranlar, ağırlıklı olarak İngilizce akademik veri kümeleri üzerinde doğrulanmıştır. Türkçe akademik yazının kendine özgü özellikleri (çift dilli özet yapısı, Türkçe tokenizasyon farklılıkları, alan terminolojisi vb.) bu oranların ayarlanmasını gerektirebilir.

Yol haritası ve zaman tahminleri koşullara bağlıdır. Ekip büyüklüğü, donanım erişimi, annotator mevcudiyeti ve ara sonuçlara göre yöntem değişiklikleri zamanlamayı doğrudan etkiler. Bu rapordaki haftalık plan, tam zamanlı çalışan küçük bir teknik ekip varsayımına dayanır.

Bu doküman yaşayan bir dokümandır. Pipeline'ın her aşamasında elde edilen bulgulara göre güncellenmelidir. Özellikle pilot aşama sonuçları, buradaki birçok varsayımı doğrulayacak veya revize edecek birincil veri kaynağı olacaktır.

1. Amaç ve Vizyon

Bu rapor, yaklaşık 300 bin Marker kaynaklı .md akademik makale dosyasından iki ayrı ürün oluşturma planını tanımlar:

  1. Eğitim Korpusu — Milyonlarca zayıf gözetimli örnek içeren büyük ölçekli contrastive learning veri seti
  2. Altın Standart Benchmark — Küçük ama dikkatle etiketlenmiş, sürüm kontrollü, Türkçe akademik retrieval ve embedding değerlendirme paketi

Bu ayrım tesadüfi değildir. SciDocs, BEIR ve MTEB gibi referans çalışmalar, eğitim verisi ile değerlendirme benchmarkının kesinlikle ayrı tutulması gerektiğini; tek görevde yüksek skor alan modellerin genel olarak en iyi model olmadığını göstermiştir. TR-MTEB de Türkçe embedding değerlendirmesinde dil ve kültür bağlamına uyarlanan benchmarkların farklı içgörüler verdiğini ortaya koymuştur.

Wiki bağlamı: Marker kaynaklı .md üretimi için bkz. PDF Çıkarım Araçları ve Deney 06 — Marker Performans. Bu raporun çıktısı (eğitim korpusu + altın benchmark) doğrudan Embedding Modelleri ve MTEB Değerlendirme sayfalarındaki seçim kararlarını besleyecektir.

2. Temel Tasarım İlkeleri

Başlık + Özet omurgadır. SPECTER'in temel bulgusu, bilimsel belge embeddinglerinde başlık+özet birleşiminin güçlü bir temel sunduğunu; yazar/dergi gibi ek alanların belirgin kazanım getirmediğini gösterir. Tam metin ise doğrudan girdi yerine, chunk tabanlı ek eğitim sinyali üretmek için kullanılmalıdır.

Belge temsili ile chunk temsili karıştırılmamalıdır. Belge düzeyinde başlık+özet ile "doc encoder", paragraf/bölüm düzeyinde ise "chunk encoder" davranışı ayrı ayrı öğretilir. Bu, hem belge retrieval hem de RAG/passage retrieval için çift katmanlı bir yetenek sağlar.

Görev çeşitliliği şarttır. Benchmark yalnızca retrieval'dan ibaretse, modelin zayıf olduğu alanlar gizlenir. Retrieval, similarity, classification ve recommendation görevleri birlikte ele alınmalıdır.

Split sızıntısı önlenmelidir. Train/dev/test ayrımı belge ailesi (family_id) düzeyinde yapılmalıdır; asla çift düzeyinde değil. Aynı çalışmanın tez/makale/kongre sürümleri aynı aile altında tutulmalıdır.

3. Veri Şeması

3.1 Belge Kaydı (documents.jsonl)

Her belge kaydında şu alanlar bulunur:

Alan Açıklama
doc_id Benzersiz belge kimliği
family_id Near-duplicate / aynı çalışmanın sürümlerini gruplayan aile kimliği
source_type thesis, article, conference_paper vb.
lang Belgenin ana dili
title Başlık
abstract_tr Türkçe özet (çekirdek veri için zorunlu)
abstract_en İngilizce özet
sections Bölüm listesi (id, başlık, metin)
keywords Anahtar kelimeler
references Kaynakça (ham metin, DOI, normalize başlık)
quality_flags Kalite bayrakları (Türkçe özet var mı, dedupe durumu, artifact skoru)
split train / dev / test — aile düzeyinde atanır

3.2 Chunk Kaydı (chunks.jsonl)

Alan Açıklama
chunk_id {doc_id}_{section_id}_{chunk_no}
doc_id Bağlı belge
section_title Bölüm başlığı
chunk_text Parça metni
token_len Token uzunluğu
position Bölüm içi sıra
is_table_heavy Tablo/formül ağırlıklı mı
is_reference_zone Kaynakça bölgesi mi
quality_score 0–1 arası kalite puanı

3.3 Eğitim Örnekleri

Pair formatı (pairs_train.jsonl): anchor_text + positive_text + görev etiketi + kalite skoru.

Triplet formatı (triplets_train.jsonl): anchor + positive + negative(s) + zorluk skoru.

3.4 Benchmark Dosyaları

Dosya İçerik
queries.jsonl Sorgu metinleri, türleri, dilleri
qrels.tsv Sorgu-belge ilişkilendirme etiketleri (0/1/2)
sts.jsonl Benzerlik çiftleri (0–5 ölçeği, çoklu annotator)
classification.jsonl Alan sınıflandırma etiketleri
recommendation.jsonl İlgili belge önerileri

4. Ön İşleme ve Chunking

4.1 Pipeline Akışı

Marker .md dosyaları
    → Markdown parser + bölüm tanıma
    → Dil tespiti + kalite filtreleri
    → documents.jsonl
        → Yapısal chunking (paragraf sınırları korunur)
        → Kayan pencere fallback (çok uzun paragraflar için)
        → chunks.jsonl

4.2 Temizlik Kuralları

Kural Uygulama Amaç
Unicode normalizasyonu NFKC + tek boşluk Yazım tutarlılığı
Özet çıkarımı "Öz/Abstract" başlık eşleme Belge omurgası
Kaynakça ayıklama Heading + regex + satır biçimi Gürültü azaltma
Tablo/formül filtresi Non-letter oranı > %35 → bayrak Paragraf kalitesi
Dil filtresi lang=tr + güven > 0.80 Türkçe odak
Dedupe Title+abstract MinHash + family_id Split sızıntısını önleme
Kısa parça düşürme < 60 token veya düşük kalite Zayıf sinyal temizliği

4.3 Kalite Eşikleri

Başlık en az 5 token, Türkçe özet en az 80 token, chunk başına en az 60 token, alfabetik karakter oranı en az %60, tekrarlanan satır oranı en fazla %20.

4.4 Chunking Reçetesi

Paragraf Uzunluğu Strateji
80–320 token Olduğu gibi al, overlap yok
320–900 token 220 token pencere, 40 token overlap
900+ token Alt başlık/cümle sonu ara, bulamazsan 256 token pencere, 48 overlap

Hedef chunk boyutu 180–300 token, tavan 384 token. Overlap yalnızca kayan pencere fallback'inde uygulanır.

5. Pozitif Örnek Üretimi

5.1 Dört Çekirdek Pair Tipi

Tip Oran Açıklama Belge Başına
title ↔ abstract %25 En güvenilir sinyal, SPECTER omurgası 1 çift
abstract ↔ paragraph %35 Retrieval/RAG için kritik, hibrit skorlama ile seçilir 3 paragraf
section ↔ paragraph %20 Yapısal semantik öğretir, anchor = "bölüm başlığı | belge başlığı" 2 çift
intra_doc paragraphs %20 Belge içi bağlam sürekliliği 2 çift

5.2 Beklenen Hacim (220K temiz belgeden)

Tip Tahmini Çift Sayısı
title ↔ abstract ~220K
abstract ↔ paragraph ~660K
section ↔ paragraph ~440K
intra_doc ~440K
Toplam ~1.76M pozitif çift

5.3 Abstract–Paragraph Eşleştirme Skoru

skor = 0.55 × teacher_cosine + 0.25 × bm25_norm + 0.20 × keyword_overlap

Her belge için üç farklı bölgeden birer paragraf seçilir (giriş, yöntem, bulgu/sonuç) — özetin sadece girişle hizalanması engellenir.

6. Negatif Örnek Üretimi

6.1 Üç Katmanlı Negatif Mimarisi

Katman 1 — In-batch negatives: InfoNCE/MNRL tabanlı eğitimde varsayılan ve en ucuz kaynak. CachedMultipleNegativesRankingLoss ile büyük efektif batch'lere çıkılır.

Katman 2 — Random negatives: Belgeler arası alan farkı yüksek örneklerden seçilir (ör. bilgisayar bilimi özeti için tarım alanından). Yardımcı sinyal — tek başına yetersiz.

Katman 3 — Hard negatives: Benchmarkı gerçekten değerli kılan katman. Üç otomatik strateji:

Strateji Yöntem
Küme tabanlı Öğretmen model embeddinglari → 2K–4K küme → aynı/komşu kümedeki non-positive belgeler
Bibliyografik Ortak 2+ kaynak paylaşan ama aynı çalışma olmayan belgeler
Anahtar kelime Aynı 2+ normalize anahtar kelimeyi paylaşan farklı yönelimdeki belgeler

6.2 Hard Negative Seçim Kuralları

Aday belge şu koşulları karşılamalıdır: aynı family_id içinde olmamalı, teacher cosine 0.55–0.82 aralığında olmalı, BM25 ilk 50'de veya aynı kümede bulunmalı, title trigram overlap 0.80'i aşmamalı, near-duplicate skoru 0.90'dan düşük olmalı.

6.3 Eğitim Batch Dağılımı

Oran İçerik
%60 Yalnız pozitif çift + in-batch negatives
%25 Bir hard negative içeren genişletilmiş çift
%10 Bir hard + bir random negative triplet
%5 Yalnız explicit random negative

İlk epoch'ta hard-negative oranı düşük tutulur, ikinci epoch'ta artırılır (curriculum etkisi).

7. Altın Benchmark Paketi

7.1 Görev Yapısı

Görev Ölçek Birincil Metrik İkincil Metrikler
Retrieval 1500–2000 sorgu × 20 aday nDCG@10 MRR@10, MAP@100, Recall@100
Similarity (STS) 3000 çift, 0–5 ölçek Spearman korelasyon Pearson korelasyon
Classification 20K belge, 12–20 üst sınıf Macro-F1 Accuracy
Recommendation Yardımcı görev nDCG@10 MAP@10, Recall@20

Wiki bağlamı: Görev türlerinin MTEB içindeki rolleri için bkz. Görev Türleri ve Görev Türleri (detaylı).

7.2 Retrieval Sorgu Aileleri

Dört farklı sorgu türü: kısa başlık-benzeri sorgular, doğal dil bilgi ihtiyacı cümleleri, anahtar kelime yoğun sorgular ve section-aware sorgular. Sorgular başlığın doğrudan kopyası olmamalı, paraphrase edilmelidir.

Candidate pool üç kaynaktan birleşir: BM25 üst sonuçları + dense baseline üst sonuçları + rastgele hard distractor havuzu.

7.3 Manuel Etiketleme Bütçesi

Aşama İçerik İş Yükü
Pilot 150–200 retrieval sorgusu, 300 STS çifti, 100 recommendation seed Yönerge netleştirme
Ana 1500 sorgu × 20 aday × 2 annotator = 60K yargı; 3K STS × 3 annotator = 9K puan ~500–650 annotator-saat
Kalite Cohen's kappa ≥ 0.70 (retrieval), Spearman ≥ 0.75 (STS) Düşük uyumlu örnekler çıkarılır

2 araştırma görevlisi + 1 uzlaştırıcı ile 4–6 haftada tamamlanabilir.

8. Eğitim Reçetesi

8.1 Base Modeller

Model Güçlü Yanı Kullanım
multilingual-e5-large 512 token, olgun, retrieval odaklı, query:/passage: prefix Birincil baseline — doc-level ve chunk-level
bge-m3 8192 token, dense+sparse+multi-vector, 100+ dil Uzun doküman ve hibrit retrieval deneyleri

8.2 Eğitim Konfigürasyonu

Parametre Değer
Loss CachedMultipleNegativesRankingLoss
Learning rate 2e-5
Warmup %10
Decay Cosine
Epoch 2–3
Efektif batch 2048–8192 (cached loss ile)
Max token (doc) 512
Max token (chunk) 320–384

8.3 İki Fazlı Eğitim

Faz 1: Cached-MNRL ile tüm pozitif çiftler + in-batch negatives üzerinde contrastive pretraining.

Faz 2: Hard-negative miner çıktısından 200–400K örneklik subset üzerinde kısa triplet fine-tune (SPECTER tarzı, margin=1, 2 epoch).

8.4 Erken Durdurma Kriteri (Çok Görevli)

composite = 0.50 × nDCG@10 + 0.20 × MRR@10 + 0.15 × STS_Spearman + 0.15 × MacroF1

9. Altyapı ve Compute Tahmini

9.1 Veri Boyutu

300K ham belge → ~220K temiz belge → 15–25 chunk/belge → 3.3–5.5M chunk. 1024 boyutlu float16 dense embeddingler yalnız vektör tarafında 7–11 GB; ANN indeksleri ile 30–80 GB.

9.2 Donanım

Bileşen Minimum
Depolama 1 TB NVMe
RAM 128–256 GB
GPU (ilk model) 1× A100 80GB
GPU (full varyant) 2–4× A100 80GB
ANN mining Faiss

9.3 Compute Bütçesi

Varyant Çift Sayısı GPU-Saat
Prototype 300–500K 10–30
Standard 0.9–1.3M 40–120
Full/SOTA 2–3M 150–400

10. Proje Varyantları

Lite Standard (Önerilen) Full
Temiz belge 35–40K 120–150K 220–260K
Pozitif çift 250–350K 0.9–1.3M 2.0–3.0M
Gold retrieval 400–500 sorgu 1200–1500 sorgu 1800–2000 sorgu
Gold STS 800–1000 çift ~3000 çift 4000–5000 çift
Hard negative Lexical + teacher NN Cluster + keyword + bibliographic İteratif üç katmanlı
Süre 2–4 hafta 6–10 hafta 3–6 ay

Öneri: Doğrudan Standard varyantla başlanmalıdır. Lite hızlı doğrulama sağlar ama referans değeri taşımaz. Full ancak standard stabil çalıştıktan sonra anlamlıdır.

11. Yol Haritası

Hafta 1 — Pipeline doğrulama

5–10K .md dosyasında md → documents/chunks JSONL hattını doğrula. Kalite filtreleri ve family_id dedupe mantığını oturt.

Hafta 2 — İlk çiftler ve baseline

Yalnız title↔abstract ve abstract↔paragraph ile ilk 100–150K çifti üret. Seed encoder ile hard-negative miner'ı kur. multilingual-e5-large baseline'ı küçük dev set üzerinde eğit.

Hafta 3 — Pilot benchmark

Retrieval ve STS için pilot gold annotation turunu başlat. Pilot sonuçları tutarlıysa standard varyanta genişle.

Hafta 4–10 — Standard varyant

Dört çekirdek pair tipinin tamamını üret. Üç katmanlı hard-negative mining'i çalıştır. İki fazlı eğitimi tamamla. Benchmark'ı sürümlendirip raporla.

Wiki bağlamı: Bu yol haritasının kısa kart özeti 90_Roadmap/Embedding-Veri-Kumesi-MVP.md sayfasında tutulur.

12. Gerekli Script Seti

Script Görev Öncelik
md_to_jsonl.py Marker .md → documents.jsonl + chunks.jsonl 1
build_pairs.py Dört çekirdek pair tipini üretir 2
train_embedding_baseline.py Cached-MNRL ile ilk baseline eğitimi 3
mine_hard_negatives.py Teacher + BM25 + keyword + bibliographic mining 4
build_gold_benchmark.py Retrieval query havuzu + candidate pooling + annotation export 5
eval_beir_mteb_style.py Retrieval, STS, classification, recommendation metrikleri 6
package_hf_dataset.py Hugging Face dataset formatında paketleme 7

İlk üç script çıkmadan hard-negative mining ve gold benchmark adımlarına geçmek verimsizdir. Doğru sıra: pipeline → çiftler → baseline → mining → benchmark.

Son Not

Bu raporda sunulan tüm rakamlar, oranlar ve mimari kararlar mevcut ~300K veri tabanı üzerinde yapılmış bir düşünce egzersizinin ürünüdür. Gerçek uygulama sürecinde veri profili netleştikçe (alan dağılımı, kalite oranları, chunk istatistikleri) bu doküman güncellenmelidir. Raporun değeri kesin reçeteler sunmasında değil, karar noktalarını ve trade-off'ları görünür kılmasındadır. Pilot aşamadan çıkacak somut metrikler, buradaki tasarım kararlarının nihai doğrulayıcısı olacaktır.

İlgili Wiki Sayfaları