README.md

---
base_model: unsloth/Qwen3-VL-2B-Instruct
library_name: peft
license: apache-2.0
pipeline_tag: image-text-to-text
tags:
- arabic
- ocr
- qwen3-vl
- lora
- unsloth
- document-ai
---

# Alhazen-OCR

QLoRA adapter on [`unsloth/Qwen3-VL-2B-Instruct`](https://huggingface.co/unsloth/Qwen3-VL-2B-Instruct) for Arabic institutional OCR: printed forms, invoices, and handwriting-heavy pages.

Named after Ibn al-Haytham (Alhazen), the 11th-century scholar who founded the science of optics.

- **Base:** Qwen3-VL-2B-Instruct (Apache-2.0)
- **Training data:** [`context212/context212-alhazen-ocr`](https://huggingface.co/datasets/context212/context212-alhazen-ocr) (khattmix rebuild)
- **Code:** [`github.com/context212/atlas-ocr`](https://github.com/context212/atlas-ocr)
- **Experiment sibling:** [`context212/alhazen-ocr-khattmix`](https://huggingface.co/context212/alhazen-ocr-khattmix)

## Results

CER / WER (lower is better), greedy decoding, **50 samples** each on the held-out eval split and on external [`ahmedheakl/arocrbench_khatt`](https://huggingface.co/datasets/ahmedheakl/arocrbench_khatt):

| Model | Eval CER ↓ | Eval WER ↓ | KHATT CER ↓ | KHATT WER ↓ |
|---|---:|---:|---:|---:|
| Qwen3-VL-2B-Instruct (base) | 0.792 | 0.947 | 1.893 | 1.801 |
| **Alhazen-OCR** | **0.328** | **0.504** | **0.841** | **1.193** |

Held-out character error: **0.79 → 0.33**. External KHATT handwriting: **1.89 → 0.84** CER.

This release (khattmix) adds line-level KHATT handwriting (~30% of the mix) on top of synthetic printed, invoices, and paragraph handwriting; KHATT-bench transcript overlap is removed from train.

## Training

- **Objective:** QLoRA SFT, one epoch
- **LR:** 2e-5 cosine, warmup 5%
- **Effective batch:** 16 (8 × grad accum 2) on A100 80GB
- **LoRA:** r=16, RSLoRA, vision + language layers
- **Mix:** ~30% loay synthetic / 15% invoices / 30% KHATT lines / 23% KHATT paragraphs / 2% historical (~18k train rows)

## Usage

Serve the base with the adapter attached (vLLM example):

```bash
vllm serve Qwen/Qwen3-VL-2B-Instruct \
  --enable-lora \
  --lora-modules alhazen=context212/alhazen-ocr \
  --limit-mm-per-prompt '{"image": 1}' \
  --mm-processor-cache-gb 0 \
  --no-enable-prefix-caching
```

Prompt:

> Extract all the text from this image, preserving the original reading order.

Keep `temperature=0` for transcription.

## Limitations

- Tuned for Arabic institutional paperwork; not a general multilingual OCR.
- KHATT remains harder than printed forms — scores above 1.0 CER mean many lines are still wrong.
- Eval above is capped at 50 samples per split; treat as directional until a full-split rerun.

## Citation

```bibtex
@misc{alhazen-ocr-2026,
  title        = {Alhazen-OCR},
  author       = {Context212},
  year         = {2026},
  howpublished = {\url{https://huggingface.co/context212/alhazen-ocr}}
}
```