sam4rano/yoruba_ocr_research

This contains all the research, experiment and results of the yoruba ocr research project # Yorùbá OCR Research Repository for experiments, analysis, and paper writing for Yorùbá OCR. The project studies line-level OCR for tone-marked Yorùbá text. The central question is not only "which model reads the line correctly?" but also "which model preserves the diacritics that carry tone and vowel quality?" For that reason the benchmark reports standard OCR metrics, CER and WER, plus DER (Diacritic Error Rate). ## Current Experiment Plan The active experiment uses one frozen `data/processed` split and separates three kinds of evidence: baselines, supervised fine-tuning, and ablations. ### 1. Baselines Baselines measure what works before training on this dataset. | Model key | How it runs | Purpose | | --- | --- | --- | | `paddleocr_en_pretrained` | `scripts/evaluate_paddleocr_en_pretrained.py` via `scripts/shell/phase_05_eval_paddleocr_recognition.sh` | Classical OCR control. Evaluates English-pretrained PP-OCR on Yorùbá while loading its matching English CTC head, so the row is not a random-head phantom. | | `paddleocrvl16_zero_shot` | `scripts/eval_paddleocrvl16.py` via `scripts/shell/phase_15_eval_paddleocrvl16_zero_shot.sh` | Zero-shot OCR-oriented VLM baseline using PaddleOCR-VL-1.6. | | `glm_ocr_zero_shot` | `scripts/eval_glm_ocr.py` via `scripts/shell/phase_18_eval_glm_ocr_zero_shot.sh` | Second zero-shot VLM baseline from a different model family. | The zero-shot rows are prompt-fixed and deterministic. They should not be described as fine-tuned models. ### 2. Fine-Tuned Models The main supervised adaptation is: | Model key | How it runs | Purpose | | --- | --- | --- | | `paddleocrvl16_sft` | Export with `scripts/export_paddleocrvl16_sft.py`, train with `scripts/train_paddleocrvl16_sft.py`, evaluate with `scripts/eval_paddleocrvl16.py` | Uses assistant-only supervised OCR loss. The default `lm_head` scope adapts only the output head for T4/L4 memory safety; `non_vision` adapts the language-side parameters on larger GPUs, while `all` also upda …