AyoubChLin/unlimited-ocr-quran-uthmani

Unlimited-OCR Quran Uthmani OCR

AyoubChLin/unlimited-ocr-quran-uthmani is a Quran-focused OCR fine-tune of `baidu/Unlimited-OCR`. It is adapted for extracting Arabic Quran ayah text from images while preserving الرسم العثماني, diacritics, and Quranic symbols as closely as possible.

The model was trained with LoRA on Quran ayah images from `mohammed-almaamari/quran-dataset`, then merged into a standalone model for easier inference.

Intended Use

This model is intended for:

• —OCR of Quran ayah images.
• —Extracting Uthmani-script Arabic text from rendered ayah images.
• —Quran dataset preparation and cleaning workflows.
• —Educational and research workflows around Quranic OCR.

It is not intended to be treated as an authoritative Quran text source without verification. For religious, publishing, or production use, outputs should be checked against a trusted mushaf/Quran text database.

Training Dataset

Training used the train split of mohammed-almaamari/quran-dataset.

Dataset fields used during training included:

• —aya_image
• —aya_text
• —surah_number
• —aya_number
• —page
• —surah_name

The notebook cached all ayah images locally as JPEG files and produced:

The split was created with test_size=0.1 and seed 3407.

Fine-tuning Objective

The model was fine-tuned to answer the following image OCR instruction:

<image>
استخرج نص الآية القرآنية من الصورة كما هو بالضبط بالرسم العثماني، مع الحفاظ على التشكيل والرموز القرآنية، وأرجع النص فقط بدون شرح.

The target answer was the aya_text field from the dataset.

Training Setup

Base model:

baidu/Unlimited-OCR

Main configuration:

The notebook used base image mode at 1024x1024, without crop mode, for faster training and inference.

LoRA Configuration

The model was fine-tuned with LoRA while freezing the vision stack to preserve the base model's general OCR behavior.

LoRA was attached to selected language-decoder modules only:

• —Attention projections: q_proj, k_proj, v_proj, o_proj
• —Dense MLP projections: gate_proj, up_proj, down_proj
• —Shared-expert MLP projections

The per-token routed MoE experts were intentionally excluded to avoid inflating trainable parameters on a small dataset.

LoRA diagnostics from the notebook:

Training Results

Training was logged with Weights & Biases under the run name:

quran-uthmani-lora-r128

Final trainer metrics:

Loss logs:

Eval loss improved sharply early in training and reached its best value at step 150. Later eval loss stayed close but slightly increased, while train loss continued decreasing. This suggests the model learned the Quran ayah OCR task strongly, but the final checkpoint should still be validated with exact-match, CER, and WER before claiming production-level accuracy.

Qualitative Evaluation Notes

The notebook ran a small qualitative inference check on 3 eval samples. The model produced Arabic Quran-like Uthmani text and often preserved diacritics and symbols, but visible mistakes remained in some examples, especially longer ayahs.

Observed examples included:

• —Strong output on a long ayah, with a small word-level issue.
• —Minor OCR confusion in a short ayah.
• —More noticeable degradation on a very long ayah.

Because only qualitative examples and loss curves are available, this card does not claim exact OCR accuracy. A proper evaluation should compute:

• —Exact match
• —Character error rate
• —Word error rate
• —Diacritic-sensitive and diacritic-insensitive CER
• —Quran-symbol preservation accuracy

Inference

Load the model with trust_remote_code=True and use the model's built-in infer(...) method.

from transformers import AutoTokenizer, AutoModel
import torch

model_id = "AyoubChLin/unlimited-ocr-quran-uthmani"

tokenizer = AutoTokenizer.from_pretrained(
    model_id,
    trust_remote_code=True,
)

model = AutoModel.from_pretrained(
    model_id,
    trust_remote_code=True,
    use_safetensors=True,
    torch_dtype=torch.bfloat16,
    device_map="auto",
).eval()

prompt = """<image>
استخرج نص الآية القرآنية من الصورة كما هو بالضبط بالرسم العثماني، مع الحفاظ على التشكيل والرموز القرآنية، وأرجع النص فقط بدون شرح.
"""

result = model.infer(
    tokenizer,
    prompt=prompt,
    image_file="path/to/ayah_image.png",
    output_path="./ocr_output",
    base_size=1024,
    image_size=1024,
    crop_mode=False,
    max_length=2048,
    no_repeat_ngram_size=35,
    ngram_window=128,
    save_results=False,
    temperature=0.0,
)

print(result)

Depending on the upstream Unlimited-OCR implementation, inference may print generated text directly and may return None. Check stdout and the output directory behavior if needed.

Recommended Decoding Settings

For Quran OCR, deterministic decoding is recommended:

For long ayahs or difficult images, increase max_length carefully.

Limitations

• —The model was fine-tuned on a specific Quran ayah image dataset and may not generalize to all mushaf styles, scan qualities, fonts, or handwritten text.
• —The vision encoder was frozen, so improvements mainly come from adapting the language/OCR decoding behavior.
• —The available evaluation includes loss curves and a small qualitative check, not full OCR metrics.
• —The model can still make character-level, diacritic-level, word-level, and Quran-symbol mistakes.
• —Long ayahs may be more error-prone.
• —Outputs should be verified before religious, educational, or publishing use.

Ethical and Religious Use

Quran text must be handled carefully. This model should be used as an OCR assistant, not as a final source of truth. Always validate generated text against an authoritative Quran source before publication or distribution.

Training Notebook Summary

The training notebook performed the following steps:

1. 1.Checked GPU availability and required CUDA capability.
2. 2.Installed pinned dependencies compatible with baidu/Unlimited-OCR.
3. 3.Loaded baidu/Unlimited-OCR and mohammed-almaamari/quran-dataset.
4. 4.Cached all ayah images locally as JPEG.
5. 5.Split the dataset into train/eval sets.
6. 6.Loaded the model with torch.bfloat16 and device_map="auto".
7. 7.Froze the vision stack and projector.
8. 8.Attached LoRA to selected decoder modules.
9. 9.Used a custom multimodal collator for Unlimited-OCR base image mode.
10. 10.Trained for 12 epochs.
11. 11.Saved the LoRA adapter.
12. 12.Merged the adapter into the base model.
13. 13.Pushed the merged model to the Hugging Face Hub.

Citation

If you use this model, please cite the base model and dataset:

@misc{unlimited_ocr_quran_uthmani,
  title = {Unlimited-OCR Quran Uthmani Fine-tune},
  author = {AyoubChLin},
  year = {2026},
  base_model = {baidu/Unlimited-OCR},
  dataset = {mohammed-almaamari/quran-dataset}
}