README_TR.md

---
license: apache-2.0
language:
- ott
- tr
- ar
pipeline_tag: image-to-text
tags:
- ocr
- ottoman
- qwen
- vllm
- vision-language
metrics:
- accuracy
- cer
---

# Azra 1-Mini (0.8B) — Osmanlıca OCR Modeli

<p align="center">
  <img src="banner.png" alt="Azra 1-Mini Banner" width="45%">
</p>


**Azra 1-Mini 0.8b**, Osmanlıca metinlerin transkripsiyonu için **Nesih** (matbu/hat) ve **Rika** (el yazısı) yazı stillerinde özel olarak eğitilmiş, hafif ve yüksek performanslı bir Görsel-Dil (Vision-Language) OCR modelidir.

Sadece **0.8 milyar parametreye** sahip olmasına rağmen Azra 1-Mini, kapalı kaynaklı dev modelleri geride bırakarak Osmanlıca OCR alanında State-of-the-Art (SOTA) başarı oranlarına ulaşmıştır.

> ⚠️ **Önemli Kullanım Notu (Satır Bazlı Görseller):**
> Bu model özellikle **satır bazlı (line-level) kırpılmış görseller** üzerinde eğitilmiş ve optimize edilmiştir. Tam sayfa (page-level) görseller satırlara bölünmeden doğrudan verildiğinde model beklenen yüksek başarıyı gösteremeyebilir.

---

## 📊 Benchmark ve Performans Karşılaştırması

Model, standart Osmanlıca test setlerinde dikey bazlı karakter başarı yüzdeleri (`100% - CER`) üzerinden önde gelen modellerle karşılaştırılmıştır.

### 1. Nesih Test Seti (Matbu / Hat Sanatı)

| Model | Başarı Yüzdesi (%) | Derece |
| :--- | :---: | :---: |
| **Gemini 3.1 Pro** | **%82.82** | 👑 1. Sıra |
| **Azra 1-Mini 0.8b** | **%80.23** | 🥈 2. Sıra |
| **Qwen 3.8 Max** | %74.26 | 🥉 3. Sıra |

### 2. Rika Test Seti (El Yazısı)

| Model | Başarı Yüzdesi (%) | Derece |
| :--- | :---: | :---: |
| **Azra 1-Mini 0.8b** | **%67.08** | 👑 **1. Sıra (Kazanan)** |
| **Gemini 3.1 Pro** | %58.46 | 🥈 2. Sıra |
| **Qwen 3.8 Max** | %54.99 | 🥉 3. Sıra |

> 🌟 **Öne Çıkan Başarı:** Azra 1-Mini 0.8b, zorlu **Rika el yazısı test setinde %67.08 başarı oranıyla 1. sıraya yerleşmiş**, hem Gemini 3.1 Pro hem de Qwen 3.8 Max modellerine belirgin bir fark atmıştır.

---

## 📷 Örnek Transkripsiyonlar ve Görsel Çıktılar

Aşağıda **Azra 1-Mini 0.8b** modelinin test setlerinden elde ettiği yüksek başarımlı örnek transkripsiyonlar verilmiştir:

### 1. Nesih Yazı Stili Örnekleri (Matbu / Hat Sanatı)

| Satır Görseli | Gerçek Metin (Ground Truth) | Model Tahmini (Azra 1-Mini) | CER |
| :---: | :--- | :--- | :---: |
| <img src="assets/samples/nesih_3263_759633_eSc_line_f5695a2d.png" height="35"> | `امّا اری وابدار ونازک اولور هر اعجک زمان غرسی` | `امّا اری وابدار ونازک اولور هر اعجک زمان غرسی` | **%0.00** |
| <img src="assets/samples/nesih_3263_759704_eSc_line_211ddfad.png" height="35"> | `هلاک ایدر ازایسه علاج ایله خلاص اولور` | `هلاک ایدر ازایسه علاج ایله خلاص اولور` | **%0.00** |
| <img src="assets/samples/nesih_3263_759800_eSc_line_83cb8596.png" height="35"> | `یافوجی ایچنه دوشرلر اوّل التنه وافرد وکلمش خردل` | `یافوجی ایچنه دوشرلر اوّل التنه وافرد وکلمش خردل` | **%0.00** |
| <img src="assets/samples/nesih_3263_759772_eSc_line_21130720.png" height="35"> | `اغزی محکم باغلنوب اول بوداق اکلوب یره کوملسه وقت` | `اغزی محکمه باغلنوب اول بوداق اکلوب یره کوملسه وقت` | **%2.08** |
| <img src="assets/samples/nesih_3263_759629_eSc_line_e9d59dc1.png" height="35"> | `دکمک زماندر دیمش یعنی آیک نقصانی زمانی که اوّل` | `دکک زماندر دیمش یعنی آیک نقصانی زمانی که اوّل` | **%2.17** |

### 2. Rika Yazı Stili Örnekleri (El Yazısı)

| Satır Görseli | Gerçek Metin (Ground Truth) | Model Tahmini (Azra 1-Mini) | CER |
| :---: | :--- | :--- | :---: |
| <img src="assets/samples/riqa_dfc88259-fa14-4ae1-b772-f5ea65db8b6c-001.png" height="35"> | `دیمک طلب و دیانت بزدن، دین، شریعت، هدایت اللهدندر و بو هدایت ایکی` | `دیک طلب و دیانت بزدن، دین، شریعت، هدایت اللهدندر۔ و بوهدایت ایکی` | **%4.62** |
| <img src="assets/samples/riqa_dfc88259-fa14-4ae1-b772-f5ea65db8b6c-015.png" height="35"> | `ایتمک دون بنی تنویر ایدن کونشک یارین تنویر ایدهمیهجکنی ادعا ایتمک کبی قانون استقرایی انکاردر۔` | `ایتمک دوند بنی تنویر ایدن کونشک یارین تنویر ایدرمهجیکنی ادعا ایتمک کبی قانون استقرالی انکاردر۔` | **%5.38** |
| <img src="assets/samples/riqa_c25bfa03-dbf2-41e2-8164-d639b87fbede-015.png" height="35"> | `ایمانده نه قدر بیوک بر سعادت و نعمت؛ و نه قدر بیوک بر لذت و راحت بولوندیغنی اڭلامق` | `ایمانده نه قدر یوک بر سعادت ونعمت و نه قدر یوک بر لذت و راحت بولوندیغی اشلامم` | **%8.54** |
| <img src="assets/samples/riqa_e2da2c9f-5dc9-4ffa-8241-d13cffc1caef-020.png" height="35"> | `”الله تعالی ابراهیم علیه السلامه وحی ایدوب دیدی که: اسماعیل حقندهکی دعاکی قبول ایتدم و اونی` | `"الله تعالی ابراهیم علمه السلام دحی ایدوب دیدی کی: اسماعیل حقندهکی دعاک قبول ایتدم واولی` | **%8.79** |
| <img src="assets/samples/riqa_81f5dd07-3ee3-4b26-a02a-a589e289f11c-003.png" height="35"> | `بوراده مطلوب اولمامق لازم کلیر، فی الواقع "الصراط المستقیم" نظم جلیلی بزه علی الاطلاق` | `بوراده مطلوب اولاسون لازم کلیر۔ فی الواقع "الصراط المستقیم" نظام جلیلی بزه علی الاطام` | **%9.41** |

---

## 🚀 Kullanım Rehberi (`transformers`)

Modeli yerel makinenizde PyTorch ve Hugging Face `transformers` kütüphanesi kullanarak çalıştırmak için aşağıdaki standart kod bloğunu kullanabilirsiniz:

```python
import os
import torch
from PIL import Image
from transformers import AutoProcessor, Qwen3_5ForConditionalGeneration
from qwen_vl_utils import process_vision_info

# Cihaz ve Veri Tipi Ayarları
device = "cuda" if torch.cuda.is_available() else "cpu"
dtype = torch.float16 if device == "cuda" else torch.float32

model_id = "OttomanNLP/Azra-1-Mini-0.8b"

print("[INFO] Model ve processor yükleniyor...")
processor = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)
model = Qwen3_5ForConditionalGeneration.from_pretrained(
    model_id,
    torch_dtype=dtype,
    device_map="auto" if device == "cuda" else None,
    trust_remote_code=True
)
model.eval()
print("[INFO] Model başarıyla yüklendi!")

def extract_text(image_path: str, prompt: str = "Görseldeki Osmanlıca metni transkribe et:") -> str:
    """Satır bazlı görselden Osmanlıca metni transkribe eder"""
    if not os.path.exists(image_path):
        return f"Dosya bulunamadı: {image_path}"
        
    image = Image.open(image_path).convert("RGB")
    
    # Boyutları 64'ün katlarına ayarlama
    w, h = image.size
    new_w = ((w + 63) // 64) * 64
    new_h = ((h + 63) // 64) * 64
    if (new_w, new_h) != (w, h):
        image = image.resize((new_w, new_h), Image.Resampling.LANCZOS)
    
    messages = [{
        "role": "user",
        "content": [
            {"type": "image", "image": image},
            {"type": "text", "text": prompt}
        ]
    }]
    
    text_input = processor.apply_chat_template(
        messages, tokenize=False, add_generation_prompt=True
    )
    image_inputs, _ = process_vision_info(messages)
    
    inputs = processor(
        text=[text_input],
        images=image_inputs,
        padding=True,
        return_tensors="pt"
    ).to(device)
    
    with torch.inference_mode():
        generated_ids = model.generate(
            **inputs,
            max_new_tokens=512,
            do_sample=False,
            repetition_penalty=1.2,
            no_repeat_ngram_size=3,
            pad_token_id=processor.tokenizer.pad_token_id,
            eos_token_id=processor.tokenizer.eos_token_id,
        )
    
    input_len = inputs.input_ids.shape[1]
    output_text = processor.batch_decode(
        generated_ids[:, input_len:],
        skip_special_tokens=True,
        clean_up_tokenization_spaces=False
    )[0]
    
    return output_text.strip()

if __name__ == "__main__":
    image_path = "osmanlica_satir_ornek.png"  # Satır bazlı görsel yolu
    metin = extract_text(image_path)
    print("📝 Okunan Osmanlıca Metin:\n", metin)
```

---

## 🏷️ Model Detayları

- **Geliştiren:** OttomanNLP
- **Yazarlar:** Gökhan Usta, Oğuz Alpoğlu, Fatih Günaydın
- **Model Tipi:** Osmanlıca OCR için Görsel Dil Modeli (VLM)
- **Desteklenen Diller:** Osmanlı Türkçesi (Osmanlıca)
- **Mimari:** Qwen3.5-Vision
- **Parametre Sayısı:** ~0.8B (800 Milyon)
- **Lisans:** Apache-2.0

---

## 📚 Atıf (Citation)

Bu modeli veya çalışmamızı akademik araştırmalarınızda kullanıyorsanız, lütfen aşağıdaki makalemize atıfta bulununuz:

```bibtex
@article{usta2026cross,
  title={Cross-Lingual Transfer Learning and Autonomous Data Bootstrapping for VLM-Based Ottoman Turkish Handwritten Text Recognition},
  author={Usta, G{\"o}khan and Alpo{\u{g}}lu, O{\u{g}}uz and G{\"u}nayd{\i}n, Fatih},
  journal={Research Square (Preprint)},
  year={2026},
  doi={10.21203/rs.3.rs-10418926/v1},
  note={Under Review at International Journal on Document Analysis and Recognition (IJDAR)}
}
```

**APA Formatı:**
> Usta, G., Alpoğlu, O., & Günaydın, F. (2026). *Cross-Lingual Transfer Learning and Autonomous Data Bootstrapping for VLM-Based Ottoman Turkish Handwritten Text Recognition*. Research Square Preprint. DOI: [10.21203/rs.3.rs-10418926/v1](https://doi.org/10.21203/rs.3.rs-10418926/v1)

---

## 📄 Lisans

Bu model **Apache 2.0 Lisansı** ile sunulmaktadır. Ticari ve akademik kullanıma tamamen açıktır.