TR Dizin Metadata Extraction — Qwen2.5-14B Fine-Tuning Raporu

Proje: Akademik makale PDF'lerinden (markdown'a çevrilmiş) yapılandırılmış metadata çıkarımı. Base Model: Qwen/Qwen2.5-14B-Instruct Eğitim Yöntemi: LoRA fine-tuning (Unsloth) Inference Motoru: vLLM (değerlendirme) Tarih Aralığı: Nisan 2026 — boyunca iteratif deneyler Donanım: TRUBA, 1x NVIDIA H100

H1. Amaç ve Problem Tanımı

1.1 Hedef

TR Dizin akademik makalelerinden aşağıdaki alanları eksiksiz ve doğru JSON formatında çıkaran bir LLM elde etmek:

• title.tr, title.en
• abstracts[] (dil + metin + anahtar kelimeler)
• authors[] (ad, ORCID, affiliation)
• doi, language, publicationType, docType
• journal.name, startPage, endPage
• references[] — en zorlu alan, 200'e kadar çıkabiliyor

1.2 Kullanım Senaryosu

• Marker ile markdown'a çevrilmiş PDF → Marker → LLM → structured metadata (JSON). Marker seçim gerekçesi ve üretim profili: 50_Operasyon/PDF-Cikarim-Araclari.md, benchmark: Deney 06.
• Referanslar citation graph oluşturmak için tam ve sıralı olmalı

1.3 Başlangıç Noktası

• TR Dizin'den 703,183 publication ID çekildi
• Marker ile PDF → Markdown çevirisi: ~96,695 dosya
• Hedef: bu 96k dosyayla 90k+ fine-tuning örneği üretmek

2. Veri Hazırlama

2.1 Sayısal Durum

2.2 Akış

prepare_data.py şu pipeline'ı uyguladı:

1. Paralel S3 fetch: ThreadPoolExecutor ile num_workers=32 işçi, boto3 client'ta max_pool_connections=64 + retries.
2. Dinamik truncation: Markdown token sayısına göre akıllı kırpma.
3. %25 baş + %70 son + %5 buffer
4. Amaç: başlık/özet/yazarları koru (baş), referansları koru (son).
5. Hedef JSON oluşturma: metadata dict'ten target JSON.
6. Yetersiz bütçe örnekleri atla: ~596 örnek output > 16K tokens olduğu için eğitim dışında tutuldu.

2.3 Referans Sayısı Dağılımı (train, n=90,573)

Dağılım sağlıklı: 20+ ref olan örnekler %81, 50+ ref %22.8. Eğitim sırasında modelin her boyda referans listesi görmesi sağlandı.

2.4 Sorun Noktası 1 — Uzun Markdown Truncation

Sorun: Uzun markdown'lar (50K+ token) modelin max_seq_length=16384'üne sığmıyordu.

Çözüm: dynamic_smart_truncate_md — input token budget'ını output JSON tahminine göre dinamik hesapladı. Training sırasında output tam korundu, input orantılı kırpıldı.

2.5 Sorun Noktası 2 — Metadata Fetch Bug'ı (Title'lar Null Geldi)

Sorun: İlk veri hazırlama koşusunda metadata JSON'larını çekerken kullanılan kayıt sözlüğünde yanlış alan eşlemesi yapıldı. Bu hatanın somut yansıması:

• TR Dizin kayıtlarındaki title.tr ve title.en alanları, tezin gerçek başlığı yerine boş / null değerlerle hedef JSON'a yazıldı.
• Sonuç olarak eğitim ve doğrulama setinin önemli bir kısmında "ground truth title" alanı boş olarak görüldü.
• Eğitim çalıştı, ama model "title alanını üretsem bile GT'de null var" sinyaliyle bu alanı sistematik olarak boş üretmeye eğilimli hale geldi.

Bu hatanın değerlendirme aşamasındaki yansıması:

• 100-örneklik validasyonda fuzzy_title.tr = 0.03, fuzzy_title.en = 0.07.
• İlk teşhiste bu skorlar "modelin başlık çıkaramadığı" şeklinde yorumlandı.
• Daha sonra örneklerin expected_title alanı doğrudan kontrol edilince GT'de null geldiği anlaşıldı → kök sebep veri hazırlama pipeline'ında bulundu.

Çözüm:

1. prepare_data.py içinde metadata fetcher düzeltildi (doğru alan adı ve fallback sırası: title.tr yoksa title["tr"], yoksa metadata'daki ana başlık).
2. Veri yeniden üretildi; train/val/test split tekrar oluşturuldu.
3. Doğrulama: 100 örnek üzerinde fuzzy_title.tr ve fuzzy_title.en her ikisi de 0.03 / 0.07 → 1.00 seviyesine çıktı.
4. Tam test setindeki (n=2384) son skorlar: fuzzy_title.tr = 1.00, fuzzy_title.en = 1.00 (Bölüm 6.2).

Çıkarılan ders: Metrik düşük geldiğinde modeli suçlamadan önce GT'yi doğrula. "Model bu alanı üretemiyor" hipotezi ile "GT'de bu alan zaten yok" hipotezi farklı yerlere bakar; tek satırlık bir sanity-check (örneklerden 5–10 tanesini gözle kontrol) bu yolu kısaltır.

3. Model Seçimi

3.1 Karşılaştırma

Kısa bir compare_models.py ile Qwen2.5-14B, Qwen3-8B, Qwen3.5-9B zero-shot değerlendirildi.

3.2 Karar: Qwen2.5-14B

Gerekçeler:

1. Zero-shot taban JSON üretiminde en tutarlı.
2. Türkçe desteği daha güçlü.
3. 32K context akademik makaleler için yeterli (ortalama ~15K token).
4. Fine-tuning sonrası çok daha büyük kazanç potansiyeli.
5. 90k örnekle eğitim için parametre/veri oranı optimal.

4. Eğitim

4.1 Konfigürasyon (config.yaml)

model:
  base_model: unsloth/Qwen2.5-14B-Instruct-bnb-4bit
  max_seq_length: 16384
  dtype: bfloat16
  load_in_4bit: true

lora:
  r: 32
  alpha: 32
  target_modules:
    - q_proj, k_proj, v_proj, o_proj
    - gate_proj, up_proj, down_proj

training:
  num_train_epochs: 1
  per_device_train_batch_size: 1
  gradient_accumulation_steps: 8
  learning_rate: 2e-4
  warmup_ratio: 0.03
  lr_scheduler_type: cosine
  logging_steps: 500
  save_steps: 500
  eval_steps: 500

data:
  total_samples: 100000
  train_ratio: 0.95
  val_ratio: 0.025
  test_ratio: 0.025

4.2 Eğitim Süresi

• 1 epoch, ~90K örnek, H100 GPU
• Toplam süre: ~6 saat

4.3 Checkpoint Birleştirme

Eğitim sonrası LoRA adapter → base model merge → checkpoints/merged (vLLM standart HF formatında yükleyebilsin diye).

5. Değerlendirme Yolculuğu

Değerlendirme süreci 5+ iterasyon aldı, her biri yeni bir darboğaz ortaya çıkardı ve düzeltildi.

5.1 İterasyon 1: İlk evaluate.py (transformers-native)

Komut: python scripts/evaluate.py --num-samples 5

Sorun: ~10 dakika/örnek. Akıl almaz yavaş.

Teşhis:

• Flash Attention 2 BROKEN (CUDA 13.0 vs PyTorch 12.8 uyumsuzluğu)
• XFormers fallback devrede
• do_sample=True (gereksiz stochastic decode)
• max_new_tokens=4096
• attention_mask verilmiyor

Düzeltmeler:

• tokenizer() ile explicit attention_mask
• temperature=0.0 (greedy decode)
• torch.inference_mode()
• use_cache=True, pad_token_id=tokenizer.eos_token_id
• Verbose HTTP/future warnings susturuldu

Sonuç: ~3 dk/örnek. Hâlâ çok yavaş.

5.2 İterasyon 2: Flash Attention 2 Kurulumu

Teşebbüs: pip install flash-attn --no-build-isolation

Hata: CUDA version (13.0) mismatches PyTorch (12.8)

Karar: FA2'yi tek başına yeniden kurmak yerine vLLM'e geç.

5.3 İterasyon 3: vLLM Geçişi (evaluate_vllm.py)

vLLM içinde FA2 + continuous batching built-in. Ayrıca conda create -n vllm ile izole env kuruldu.

Yeni darboğaz: libstdc++ çakışması

ImportError: /lib64/libstdc++.so.6: version `CXXABI_1.3.15' not found

Çözüm:

export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"

Sonuç: ~20 sn/örnek. 30x hızlanma.

5.4 İterasyon 4: Referans Recall Krizi

İlk test: 5 örnek, vLLM + 2-pass (genel metadata + ref-only)

Beklenmeyen sonuç:

• avg_ref_recall = 0.18 (77 ref'li örnekte 15 ref yakalandı)
• avg_ref_precision bazı örneklerde 0.14'e düştü

Hatalı hipotez 1: "Training'de 77+ refli örnek görmedi"

• Yanlış! Dağılıma bakınca 50+ refli 20k örnek eğitimde vardı.

Hatalı hipotez 2: "Context yetersiz, 32K'ya çıkaralım"

• 24K → 32K denedik, recall hiç iyileşmedi. Bu da sorun değilmiş.

Gerçek teşhis (dönüm noktası):

• 2-pass'te kullanılan REF_ONLY_PROMPT modeli eğitimde hiç görmedi
• Model SYSTEM_PROMPT ile tam JSON üretmeye koşullandı
• Ref-only prompt → zero-shot → bozuk çıktı
• Main pass'te max_new_tokens=2048 → JSON yarıda kesildi

Düzeltme: 2-pass'i kaldır, tek pass'te büyük output budget:

--max-new-tokens 10240
--no-two-pass-refs

Sonuç (5 örnek):

• avg_ref_recall = 0.938
• avg_ref_f1 = 0.933
• Sample 2 (77 ref): 77/77 predicted, 76 matched, recall 0.987

5.5 İterasyon 5: 100-Örneklik Doğrulama

Komut:

python scripts/evaluate_vllm.py \
  --max-model-len 24576 \
  --max-new-tokens 10240 \
  --no-two-pass-refs \
  --num-samples 100

Sonuç:

• json_validity_rate = 0.89 ← 11 parse hatası çıktı
• Diğer metrikler 5-örneklik ile tutarlı

11 Hatanın Analizi: Hepsinin finish_reason="stop" olması kritik ipucu. Model üretimi tamamlıyordu, JSON yapısı da sağlam görünüyordu.

5.6 İterasyon 6: JSON Escape Kökeni

Tail'lerde tekrar eden pattern:

[\[CrossRef\]]        # idx 43, 65, 85
[\[Link\]]            # idx 65
[\[pubMed\]]          # idx 65
[\[pMC\]]             # idx 65

Kök sebep: Model markdown'dan \[ ve \] escape sequence'larını JSON string'inin içine alıyor. Ama JSON spec'te sadece şu escape'ler geçerli: \" \\ \/ \b \f \n \r \t \uXXXX.

Yani \[, \], \_, \-, \(, \), \* hepsi invalid JSON.

Düzeltme: _sanitize_json_escapes() fonksiyonu yazıldı. Karakter karakter gezip geçersiz backslash'leri atıyor:

• \[ → [
• \] → ]
• \_ → _
• \" ve \n korunuyor (geçerli escape)

Sonuç: 11 hatadan 10'u kurtarıldı → json_validity_rate = 0.99. Kalan 1 hata (#17) farklı bir sorun (muhtemelen orta yerde farklı karakter sorunu).

5.7 İterasyon 7: Metrik Normalizasyonu ve Title Sorununun Kök Sebebi

Metrikleri dikkatle okuyunca şu yapay düşüklükler fark edildi:

Title metrikleri düşük görünüyordu:

• fuzzy_title.tr = 0.03, fuzzy_title.en = 0.07
• İlk yorumda bunun nedeni "modelin title üretemediği" şeklinde varsayıldı.
• 5–10 örneğin expected_title alanı doğrudan kontrol edildi → GT'nin kendisi null geliyordu.

Kök sebep — veri hazırlama bug'ı (bkz. Bölüm 2.5):

• prepare_data.py içindeki metadata fetcher, kayıt sözlüğünde yanlış alan eşlemesi nedeniyle title.tr / title.en alanlarını null olarak hedef JSON'a yazıyordu.
• Yani model bu alanı eğitim setinde de sistematik olarak boş gördü; düşük skor "model üretmiyor" değil "GT zaten boş" sinyaliydi.

Düzeltme:

1. Metadata fetcher düzeltildi, dataset yeniden üretildi (Bölüm 2.5).
2. Modelle yeniden değerlendirme: fuzzy_title.tr ve fuzzy_title.en her ikisi de 1.00. Bu skor 100-örneklik doğrulamada ve 2384'lük tam test setinde ayrı ayrı tekrar üretildi (Bölüm 6.2).

DOI format farkları:

• #16: 'DOI: 10.5505/ejm.2020.71676' — GT'de DOI: prefix var
• Tip varyasyonları: https://doi.org/..., doi:..., DOI: ...

Fix: _normalize_doi() — prefix listesi + iteratif strip + lowercase + trailing noktalama.

Page format farkları:

• Leading zero ("01" vs "1")
• Tip varyasyonları

Fix: _normalize_page() — leading zero strip, lowercase.

100-örneklik doğrulama sonrası:

DOI/Page'deki marjinal artış, title tarafındaki ana problemin veri eksikliği değil; önceki aşamada parse/okuma kaynaklı yanlış değerlendirme olduğunu gösterdi.

6. Final Tam Test Sonuçları

6.1 Komut (SLURM)

sbatch run_eval_vllm.slurm
# Tüm test seti (2384 örnek), 32K context, 14K output, single-pass

6.2 Sonuç Tablosu

Konfigürasyon:

• max_model_len = 32768
• max_new_tokens = 14336
• dtype = bfloat16, gpu_memory_utilization = 0.9
• temperature = 0.0 (greedy)
• Single-pass (no 2-pass refs)

Metrikler (n = 2384):

6.3 Güçlü Yönler

1. Yapısal doğruluk yüksek: docType, authors, abstract_lang > %90
2. Referanslar üretim seviyesinde: F1 0.84, hiçbirinin eğitilmemiş modelde erişemeyeceği seviye
3. Hız: 6.46s/örnek → production'da elverişli
4. Ölçeklenebilir: 2384 örnekte kararlı metrikler, 5-örneklik teste uygun ± davranış

6.4 Zayıf Yönler

1. 46 parse hatası: finish=stop olduğu için token limit problemi değil. Muhtemelen hâlâ yakalanamayan özel karakter kombinasyonları var.
2. DOI/Page düşük (~0.63-0.67): Format normalizasyonu yaptık ama temel sorun model çıktısında. Olası sebepler:
3. PDF'te bu alanlar net değildi → model tahmin etti
4. Training örneklerinde bu alanlar bazen null
5. İki farklı kaynakta (başlık sayfası vs makale içi) farklı değerler
6. Journal name fuzzy düşük (0.65): Kısaltma vs tam ad farkı olabilir.
7. Reference count match sadece 0.62: Model bazen 1-2 ref eksik çıkarıyor. ref_count_tol2 = 0.78 → %78'inde ±2 içinde, yani çoğu durum kabul edilebilir.

7. Kalan Sorunlar ve Öneriler

7.1 Öncelikli Düzeltmeler

A) Parse hatalarını 0'a indir (2384'te 46 → 5'ten az hedef)

• error_examples'daki 46 hatanın tail'lerini analiz et
• Sanitizer'a yeni kurallar ekle (muhtemelen: unescaped newline, tab, kontrol karakterleri, bozuk unicode)
• Beklenen etki: json_validity 0.98 → 0.995+

B) DOI/Page tarafında model çıktısını net gör

• evaluate_vllm.py'ye predicted_doi, predicted_startPage, predicted_endPage alanlarını kaydet
• Sistematik pattern var mı (hep None mı? hep yakın rakam mı?) gör
• Gerekirse GT'yi de kalite kontrolünden geçir (çift sayfa nümerasyonu)

C) Referansları daha tamamlayıcı yap

• Model avg_ref_count_diff = 7.39 ile ortalama 7 ref eksik/fazla veriyor
• Olasılıklar:
• Çok uzun markdown'da referanslar input'tan kırpıldı
• Model "özetleyici" davranış gösteriyor (5-10 atladı)
• Çözüm önerisi: Chunked inference → input çok uzunsa markdown'ı 2'ye böl, ikinci ref pass yap, merge et

7.2 Orta Vadeli İyileştirmeler

D) Veri hazırlama sanity-check'i (metadata fetch bug'ının tekrarını önle)

• Title alanı düşüklüğü, sürecin başında metadata fetch bug'ı yüzünden GT title.tr / title.en alanlarının null gelmesinden kaynaklandı (Bölüm 2.5). Düzeltildikten sonra skor 1.00'a çıktı.
• Yapılacak: prepare_data.py koşusunun sonunda alan-bazlı null-rate raporu üret (title.tr null %, doi null %, journal null %...). Bir alan beklenenden çok daha boş geliyorsa pipeline crash etsin / uyarı versin.
• Eğitim öncesi 50 örnekte gözle expected_* doğrulaması zorunlu adım olsun.
• evaluate_vllm.py çıktısına predicted_title ve expected_title örnekleri yazılsın; metrik düşükse hızlıca GT mi model mi sorusu cevaplanabilsin.

E) ORCID recall (0.61) iyileştirme

• ORCID'ler markdown'da çok nadir yer alır
• Model çıkaramadıysa bu aslında bir veri sorunu

F) Journal name fuzzy için alias tablosu

• "Tıp Dergisi" vs "Journal of Medicine" gibi Türkçe/İngilizce varyantları eşleştirmek için eval aşamasında bir alias tablosu kurulabilir

7.3 Uzun Vadeli

G) Aktif öğrenme ile zor örnekleri retraining

• ref_count_diff > 15 veya json_valid=False olan test örneklerini topla
• Bu "hard negatives" ile micro-training pass yap
• Modeli baştan eğitmek yerine sadece bu pattern'lere ince ayar

H) Ensembling / self-consistency

• Aynı girdiyi 3 kere temperature=0.3 ile çalıştır, majority vote
• Referans count için özellikle etkili olabilir
• Ama 3x inference maliyeti — kullanım senaryosuna göre değerlendir

I) Chunked ref extraction

• 200+ refli makaleler için markdown'ı "references" bölümüne göre chunkla
• Her chunk için ref çıkar, merge et
• Uzun kuyruk örnekler için özel path

8. Mühendislik Öğrenimleri

8.1 Teknik

1. vLLM cost-effective inference için vazgeçilmez (30x hızlanma)
2. Training-inference prompt uyumu kritik: 2-pass ref-only prompt modelin hiç görmediği bir formattı, zero-shot'a düşürdü
3. JSON spec katı: Model markdown escape üretebilir, bunları sanitize etmeden parse etmek mümkün değil
4. max_new_tokens vs max_model_len trade-off: input bütçesi = model_len − new_tokens − overhead; dikkatli ayarlamak lazım
5. HPC env'de LD_LIBRARY_PATH sistem vs conda çakışması sık yaşanır

8.2 Metodolojik

1. Küçük hızlı iterasyon (5 örnek) + büyük validasyon (100+ örnek) en verimli akış
2. Metriği yorumlamadan önce GT'yi doğrula: Title alanında düşük skor "modelin başaramadığı" değil veri hazırlamada metadata'nın yanlış çekilip null yazılması kaynaklıydı (Bölüm 2.5). Birkaç örneğin expected_* alanına gözle bakmak bu yolu çok kısaltıyor.
3. finish_reason her inference sonucunda kontrol edilmeli (length vs stop ayrımı çok şey söylüyor)
4. Her hata örneğinin tail'ine bakmak HEAD'den daha değerli

8.3 Veri

1. Veri hazırlama pipeline'ı tek başına bir sistemdir; bug'ları model performansını taklit eder. İlk koşuda metadata fetcher'da yanlış alan eşlemesi yüzünden title.tr / title.en alanları null geldi; bu durum eğitim sinyalini kirletti ve değerlendirmede de yanıltıcı düşük skor üretti (Bölüm 2.5). Düzeltme sonrası başlık skorları 1.00'a çıktı.
2. TR Dizin metadata'sında gerçekten de boş/null alanlar var (ORCID, bazı abstract alanları vb.), ancak başlık için önceki "çoğu null" yorumu bu fetch bug'ı kaynaklıydı; veri kaynağı kaynaklı değildi.
3. Marker PDF→MD çevirisinde bazen kaynakça başlığı kayıyor, bu da model performansına doğrudan etki ediyor.
4. Dağılımın kuyruk kısmını bilmek önemli: 100+ refli örnek %1.8 olduğundan model onları nadir gördü, ama eğitime dahil edildiği için genelleştirebildi.

9. Reprodüksiyon Talimatları

9.1 Veri Hazırlama

cd /arf/scratch/alisahin7/Qwen_Fine_Tune
conda activate qwen_ft
python scripts/prepare_data.py --config config/config.yaml

9.2 Eğitim

sbatch --export=ALL,STAGE=train run_qwen_finetune.slurm

9.3 Model Merge

# Training sonrası otomatik, ya da manuel:
python scripts/merge_lora.py \
  --base-model unsloth/Qwen2.5-14B-Instruct \
  --lora-path checkpoints/lora_final \
  --output checkpoints/merged

9.4 Değerlendirme (vLLM)

conda activate vllm
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"

# Tüm test seti
sbatch run_eval_vllm.slurm

# Veya sadece N örnek
sbatch --export=ALL,NUM_SAMPLES=500 run_eval_vllm.slurm

9.5 Tek Dosyada Inference

python scripts/inference.py \
  --model-path checkpoints/merged \
  --input some_paper.md \
  --output result.json

10. Özet Değerlendirme

Qwen2.5-14B tabanlı fine-tuned model, TR Dizin metadata extraction için production-ready bir seviyede. Özellikle:

• Yapısal doğruluk (JSON validity, docType, authors, abstract) %90+
• Referans çıkarımı (F1 0.84) — en zorlu alan, başarılı
• Hız (6.5 sn/örnek) — tüm 96K veriyi ~7 günde işleyebilir
• Geliştirme potansiyeli net: DOI/page + parse hataları hedefli düzeltmelerle +%5-10 overall artış mümkün

Son tavsiye: Mevcut model canlıya alınabilir. Paralelde:

1. Parse error'larını nokta atışı fix'le (kısa vadeli),
2. Hard-negative retraining pass'i yap (orta vadeli),
3. Chunked ref extraction opsiyonunu geliştir (sadece 200+ refli rare case'ler için).

Rapor Tarihi: 2026-04-22 Yazan: Ali Şahin + AI asistan Versiyon: 1.0