msbayindir/tr-ocr-markdown-deepseek-ocr2-lora-v0.2

TR-OCR-Markdown v0.2 — DeepSeek-OCR-2 için Türkçe belge → Markdown LoRA adaptörü

Türkçe basılı belge sayfası görüntüsünü (duyuru, form, sözleşme, tablo, kanun/mevzuat sayfası, kadro cetveli…) başlık hiyerarşisi, paragraf, liste ve boru tablolarıyla yapılandırılmış Markdown'a çeviren LoRA adaptörü. Taban model unsloth/DeepSeek-OCR-2 (Apache-2.0); adaptör tamamen sentetik, kurmaca Türkçe belgelerle eğitildi, gerçek kanun sayfalarında ölçüldü. Proje: veri üreteci, kalite kontrol, ölçüm araçları, demo ve tam rapor ayrı bir git deposundadır.

Sonuçlar (sabit test kümeleri, eğitimde kullanılmadı)

Test kümesi	Taban model	v0.1	v0.2 (E1)	v0.2-r32 (E2)
Gerçek kanun sayfaları (born-digital PDF, 55 sayfa)	%87,3	%8,2	%4,7	%8,7
test_v02 — yeni türler: mevzuat, kadro cetveli, değişiklik tablosu, iki sütun (198 sayfa)	—	%9,3	%3,3	%1,8
test_v01 — duyuru, form, sözleşme, tablo vb. (199 sayfa)	%98,2	%2,5	%2,7	%0,7

CER = karakter hata oranı (düşük iyi). v0.2-r32 gerçek testte neredeyse boş bir sayfada tarih döngüsüne girdi; o sayfa hariç CER %5,2. Gerçek sayfalarda ek ölçüler: başlık seviyesi doğruluğu v0.1 %26 → v0.2 %80, tablo hücre doğruluğu %46 → %81. Tüm farklar eşleştirilmiş bootstrap (%95) ile docs/report.md §6'da.

Bu depodaki metrics/ klasöründe her kümenin ayrıntılı raporu (*_report.json, *_summary.md) ve sürümler arası eşleştirilmiş karşılaştırmalar (compare_*) bulunur.

Kullanım

# transformers==4.57.6, peft==0.20.0 ile doğrulandı (bf16 destekli GPU'da bf16, aksi hâlde fp16)
import torch
from transformers import AutoModel, AutoTokenizer
from peft import PeftModel

BASE, REPO = "unsloth/DeepSeek-OCR-2", "msbayindir/tr-ocr-markdown-deepseek-ocr2-lora-v0.2"
tok = AutoTokenizer.from_pretrained(BASE, trust_remote_code=True)
base = AutoModel.from_pretrained(BASE, trust_remote_code=True, use_safetensors=True, _attn_implementation="eager",
                                 torch_dtype=torch.bfloat16).eval().cuda()
model = PeftModel.from_pretrained(base, REPO).eval()
model = model.merge_and_unload()   # isteğe bağlı: 2× hız, çıktı birebir aynı
# v0.2-r32 (E2) seçeneği: aynı depoda `variants/v0.2-r32` alt klasörü
# model = PeftModel.from_pretrained(base, REPO, subfolder="variants/v0.2-r32")

md = model.infer(tok, prompt="<image>\nFree OCR. ", image_file="sayfa.png", output_path="/tmp/out",
                 base_size=1024, image_size=768, crop_mode=True, save_results=False, test_compress=False, eval_mode=True)
print(md)

Decoding (eğitim ve ölçümle aynı): temperature 0, no_repeat_ngram_size=35, max_new_tokens=2048. Ham çıktıdaki grounding etiketleri için trocr/postprocess.py (proje deposu) kullanılabilir. Çıktı biçimi: output_standard.md (bu depoda).

---

Model Kartı — TR-OCR-Markdown v0.2 (LoRA adaptörleri)

Durum (24.10.2026): v0.2 adaptörleri Colab A100 (bf16) üzerinde eğitildi ve sabit test kümelerinde ölçüldü. Varsayılan adaptör v0.2 = E1 (r=16, 1 epoch, v01+v02 verisi); v0.2-r32 = E2 (r=32, 2 epoch) seçenek olarak pakettedir. v0.1 ile kıyas: gerçek kanun sayfaları (n=55) CER %8,2 → %4,7, başlık F1 %59 → %75, başlık seviyesi doğruluğu %26 → %80, tablo hücre %46 → %81; yeni belge türleri (test_v02, n=198) CER %9,3 → %3,3; eski türler (test_v01, n=199) CER %2,5 → %2,7 (fark yok), tablo/başlık/liste anlamlı iyileşme. Ayrıntı ve güven aralıkları: docs/report.md §6.

Özet

• Tür: Görüntü → metin (belge OCR + Markdown yapılandırma) için LoRA adaptörü.
• Taban model: unsloth/DeepSeek-OCR-2 (Apache-2.0), deepseek-ai/DeepSeek-OCR-2 türevi; 3,5 milyar parametre (DeepEncoder V2 + MoE dil modeli). Taban model revision'ı her çalıştırmanın env_*.json dosyasına yazılır (results/train_v2_E1/, results/train_v2_E2/).
• Bu adaptörler sıfırdan eğitilmiş model değildir; dil modeli projeksiyon katmanlarına (q/k/v/o/gate/up/down) eklenen LoRA ağırlıklarıdır. Görüntü kodlayıcıları eğitilmez.
• Görev: Türkçe basılı tek sayfa belge görüntüsünü docs/output_standard.md biçiminde Markdown'a çevirmek (başlık hiyerarşisi, paragraflar, listeler, boru tabloları, form alanları; v0.2 ile mevzuat madde/bent/dipnot kuralları ve kenarlıksız tablolar).
• Dil: Türkçe.

Sürümler

Adaptör	r / α	Epoch	Veri	Eğitilebilir param.	Boyut	Eğitim	Gerçek test CER	test_v01 CER	test_v02 CER
v0.1	16 / 16	1	train_v01 (1.995)	86 M	356 MB	Kaggle T4 fp16, 2 s	%8,2	%2,5	%9,3
v0.2 (E1)	16 / 16	1	train_v01 + train_v02 (3.989)	86 M	356 MB	Colab A100 bf16, ~2,3 s	%4,7	%2,7	%3,3
v0.2-r32 (E2)	32 / 32	2	train_v01 + train_v02 (3.989)	173 M	701 MB	Colab A100 bf16, 3,5 s	%8,7 (dejenere sayfa hariç %5,2)	%0,7	%1,8

Seçim gerekçesi: hedef gerçek belgeler. Gerçek testte E1 ile E2 istatistiksel olarak başa baş (medyan eşit; sayfa bazında E2 15 daha iyi / 21 daha kötü / 19 eşit), E2 neredeyse boş bir sayfada kontrolsüz tarih döngüsü üretti (CER ≥ 1), E1 döngü üretmedi. E2 sentetik kümelerde ve gerçek tablolarda (hücre doğruluğu %98 vs %81) daha iyidir; tablo ağırlıklı, temiz belgelerde tercih edilebilir.

Eğitim (v0.2)

• Veri: docs/dataset_card.md — train_v01 (1.995) + train_v02 (1.994; mevzuat, kadro cetveli, değişiklik tablosu, iki sütunlu düzenler); doğrulama v01 + v02 karışık 40 sayfa (yalnız loss); test ve gerçek test eğitimde kullanılmaz.
• Yöntem: Unsloth FastVisionModel + PEFT LoRA (dropout 0, seed 3407), bf16, Unsloth gradient checkpointing, adamw_8bit, lr 1e-4 doğrusal (warmup 10), bs 2 × grad. accum. 4 (8 örnek/adım), 1 epoch = 499 adım (E1), 2 epoch = 998 adım (E2); uzunluk politikası: sıra 4.096 / hedef 2.048 token üstü örnekler elenir (0 örnek elendi; seq p50 1.741, maks 3.138).
• Sonuç (eğitim): E1 doğrulama loss 0,0139 → 0,0055 (adım 100 → 400); E2 0,0114 → 0,0029 (adım 100 → 900). E1 eğitimi bir kesinti nedeniyle checkpoint-300'den --resume-from ile devam ettirildi (optimizer/scheduler/RNG dâhil). Adım süresi 15–17 s (E1), 12,6 s (E2); tepe VRAM 17,4 / 18,5 GB. Eğitim ve çıkarım bu modelde GPU'ya değil CPU/Python yüküne bağlıdır (rapor §6.3).
• Prompt (eğitim = çıkarım): <image>\nFree OCR. ; görüntü ön işleme base_size 1024, image_size 768, crop_mode True.
• Kod: scripts/run_mode.py (ortamdan bağımsız), kaggle/kaggle_lib/train.py, collator kaggle/kaggle_lib/collator.py (Unsloth notebook'undan uyarlama, LGPL-3.0).

Çıkarım

Saf transformers (AutoModel, trust_remote_code=True, bf16 destekli GPU'da bf16, aksi hâlde fp16) + peft.PeftModel.from_pretrained(base, adapter_dir); isteğe bağlı merge_and_unload() (ölçümlerde kullanıldı: çıktı PEFT ile birebir aynı, hız 2×). model.infer(..., eval_mode=True); decoding: temperature 0, no_repeat_ngram_size=35, max_new_tokens=2048. Hız: A100'de de T4'te de ~14 token/s (tek süreç, CPU-bağlı); aynı GPU'da paralel süreçler toplam hızı düşürür. Ham çıktı trocr/postprocess.py ile deterministik temizlenir (grounding etiketleri, HTML tablo → GFM); ham çıktı her zaman saklanır.

Değerlendirme

trocr/evaluate.py + trocr/compare.py (eşleştirilmiş bootstrap) ile sabit test manifestlerinde: CER/WER (mikro, %95 bootstrap), Türkçe karakter yanlış okuma, sayısal alan tam eşleşme, tablo hücre doğruluğu, başlık/liste F1, başlık seviyesi, okuma sırası τ, blok eşleşme, erken bitiş/döngü sayfa payı. v0.1 ve v0.2 aynı sayfalarda kıyaslanır; v0.1'in test_v01/gerçek tahminleri Kaggle T4 fp16 koşusundan, test_v02 tahminleri A100'den alınmıştır. Sonuçlar: docs/report.md §6, results/metrics/.

Kullanım amacı ve sınırlamalar

• Araştırma/demo amaçlı; üretim servisi değildir.
• Kapsam dışı: el yazısı, karmaşık matematik, birleşik hücreli tablolar, görsel betimleme, çok sayfalı bağlam.
• Eğitim verisi sentetiktir; gerçek başarı 55 sayfalık born-digital kanun kümesiyle ölçülmüştür; taranmış/fotoğraflanmış belgelerde doğrulanmamıştır (sentetik bozulmalar eğitimde vardır).
• Bilinen zayıflıklar (v0.2): kenarlıksız tablolarda sayıların satırlar arasında kayması; yoğun mevzuat sayfasında nadiren sayfanın bir kısmının atlanması (erken bitiş: gerçek testte 2/55); neredeyse boş sayfalarda kontrolsüz üretim riski (E2'de 1/55, E1'de 0); imza bloğu gibi tekrarlı alanlarda döngü (sentetik testte ≤1/199); başlık seviyeleri gerçek belgede standarttan sapabilir (seviye doğruluğu %80).
• Model özetlemez, düzeltmez, tamamlamaz; yine de taban modelin halüsinasyon/atlama davranışı tamamen giderilmiş değildir.

Lisans ve paket

• Adaptör ağırlıkları: taban modelle uyumlu olarak Apache-2.0 niyetiyle paylaşılabilir; bu depo yayın yapmaz (kullanıcı istemedikçe Hugging Face'e yüklenmez).
• Paket düzeni (scripts/package_hf.py): kök = varsayılan adaptör (E1) dosyaları + bu kart (README.md) + output_standard.md + metrics/; variants/v0.2-r32/ = E2 adaptörü; env.json eğitim ortamı.