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:

Split	Samples
Train	5,612
Eval	624
Total usable records	6,236

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:

Setting	Value
Epochs	12
Learning rate	2e-4
Scheduler	cosine
Warmup ratio	0.05
Weight decay	0.01
Train batch size per device	16
Eval batch size per device	16
Gradient accumulation	16
Precision	bf16
Optimizer	adamw_torch_fused
Image size	1024
Crop mode	disabled
Max text tokens	1400
Seed	3407
GPU used	NVIDIA H200

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 setting	Value
Rank r	128
Alpha	256
Dropout	0.03
Trainable parameters	31,825,920
Total parameters	3,367,932,160
Trainable percentage	0.945%

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:

Target group	Wrapped modules
Attention projections	48
Shared-expert MLP	33
Dense-layer MLP	3
Routed experts	0
Total LoRA-wrapped modules	84

Training Results

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

quran-uthmani-lora-r128

Final trainer metrics:

Metric	Value
Train runtime	6,385.08 sec
Train samples / sec	10.547
Train steps / sec	0.041
Final average train loss	0.1368
Epoch	12.0

Loss logs:

Metric	Start	Best	Final
Train loss	2.0129	0.0043 @ step 260	0.0043
Eval loss	0.1909	0.1274 @ step 150	0.1319

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:

Setting	Recommended value
temperature	0.0
base_size	1024
image_size	1024
crop_mode	False
max_length	2048

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