Tesseract model for Karakalpak (Cyrillic) — v0.2
Tesseract 5 LSTM model for printed Karakalpak in the Cyrillic alphabet, including Ó˜ Ò’ Òš Ò¢ Ó¨ Ò® ÐŽ Ò². For Latin-script Karakalpak use kaa-ml/tesseract-kaa-latn.
The Kazakh model (kaz), the usual stand-in, has no ў and ҳ and silently writes у and х — the text looks right but is misspelled. The Russian model loses all eight Karakalpak letters.
This repository ships the training checkpoints as well, so the fine-tuning can be continued (see Continue fine-tuning).
Files
| Path | What it is |
|---|---|
best/kaa_cyrl.traineddata |
float model, most accurate — use this |
fast/kaa_cyrl.traineddata |
integer model, smaller and faster (v0.1 measured 0.62 s vs 0.73 s per page), slightly less accurate |
checkpoints/r6b/kaa_cyrl6b_66900.checkpoint |
training checkpoint the best/ model was exported from |
checkpoints/r6b/kaa_cyrl6b.traineddata |
matching proto model (unicharset + recoder) required to resume from the checkpoint |
checkpoints/r6a/… |
sibling run started from kaz instead of v0.1 (near-identical quality) |
training/finetune.sh |
resume fine-tuning from a checkpoint on your own line images |
training/make_lstmf.py, training/prepare_lists.py |
data preparation used by finetune.sh |
training/eval_ocr.py |
page-level CER and Karakalpak-letter recall |
skills/ |
step-by-step instructions for AI coding agents (usage and fine-tuning) |
checkpoints/r6b → best/ is reproducible bit-for-bit (sha256 3195c74f…a244).
Benchmark
10 scanned pages of an old printed Karakalpak book, never used in training, --psm 4, Tesseract 5.5.1. CER = character error rate (lower is better). Letter recall = share of Ó™ Ò“ Ò› Ò£ Ó© Ò¯ Ñž Ò³ in the reference that the output contains.
The original reference transcripts were partly wrong in the same way kaz is wrong: pages print ў, ҳ, —, while the reference had у, х, --, plus a few lines of OCR junk. We proofread a copy against the page images (333 of 7,928 characters, 4.2%) and report both.
| Model | CER (original ref) | Letter recall (original ref) | CER (proofread ref) | Letter recall (proofread ref) | CER, held-out book |
|---|---|---|---|---|---|
v0.2 best/ |
13.44% | 93.9% | 10.56% | 92.7% | 2.75% |
v0.2 fast/ |
13.84% | 92.9% | 10.97% | 92.0% | – |
v0.1 best/ |
12.87% | 92.3% | 10.97% | 88.6% | 4.52% |
Tesseract kaz (tessdata_best) |
12.64% | 88.8% | 12.87% | 78.3% | 8.49% |
Honest summary: against the corrected reference v0.2 is the best model on every metric (−2.3 CER points and +14 letter-recall points vs kaz). Against the original reference its CER is ~0.8 points worse than kaz, because that reference rewards kaz's substitutions. The proofreading was done by one reviewer; treat the corrected numbers accordingly. About 6% of reference characters sit in lines Tesseract's layout analysis misses or garbles entirely — more training data will not fix those; better page segmentation/preprocessing will.
Usage
mkdir -p tessdata
huggingface-cli download kaa-ml/tesseract-kaa-cyrl best/kaa_cyrl.traineddata --local-dir .
mv best/kaa_cyrl.traineddata tessdata/
tesseract page.png out -l kaa_cyrl --tessdata-dir ./tessdata --psm 4
Mixed Karakalpak/Russian documents: -l kaa_cyrl+rus (put rus.traineddata in the same folder). Scan at 300 DPI.
import os
import pytesseract
from huggingface_hub import hf_hub_download
from PIL import Image
path = hf_hub_download("kaa-ml/tesseract-kaa-cyrl", "best/kaa_cyrl.traineddata")
text = pytesseract.image_to_string(
Image.open("page.png"),
lang="kaa_cyrl",
config=f"--tessdata-dir {os.path.dirname(path)} --psm 4",
)
Continue fine-tuning
Needs Tesseract ≥ 5.3 with training tools (lstmtraining, combine_tessdata), Python 3 with Pillow.
huggingface-cli download kaa-ml/tesseract-kaa-cyrl --local-dir tesseract-kaa-cyrl
cd tesseract-kaa-cyrl
GT_DIR=/path/to/lines OUT_DIR=/path/to/run ITERS=10000 training/finetune.sh
GT_DIR holds single-line images name.png with the exact transcription in name.gt.txt (one line, UTF-8, NFC). The script builds .lstmf files, checks every character exists in the model's unicharset, splits 95/5 train/eval, resumes from checkpoints/r6b at LR=5e-5 and writes OUT_DIR/best/kaa_cyrl.traineddata and OUT_DIR/fast/kaa_cyrl.traineddata. Always compare the result with training/eval_ocr.py against v0.2 and kaz before using it. Full procedure, pitfalls and the rebuild path for new characters: skills/tesseract-kaa-cyrl-finetune/SKILL.md.
Training (v0.2)
- Start: v0.1 (itself fine-tuned from
kaz, tessdata_best, Apache-2.0); LR 5e-5, 80,000 iterations, checkpoint chosen by held-out-book error (iteration 66,900), MacBook CPU, ~1 hour. - Data: 158,050 line images — 26,518 unique lines cropped from the text layers of three digitally typeset Karakalpak books (each once clean and four times degraded: blur, noise, JPEG, binarisation, small rotation, 28–64 px height), 182 real scanned lines (×30 augmented), 20,000 synthetic lines (
kaa-ml/kaa-cyrl-ocr-synthetic, kknews.uz text, CC-BY-4.0). Validation: a fourth book held out entirely. The book-derived lines are not redistributed. - Did not help in earlier rounds: oversampling lines with rare letters (hallucinated
Ñž), a news-text word dictionary, Augraphy scan simulation with old serif fonts.
Versions
v0.2— real book typography from PDF text layers; checkpoints and fine-tuning scripts published.v0.1— synthetic lines + 182 real scanned lines.
License
Apache-2.0 (same as Tesseract's traineddata). Synthetic training text comes from kknews.uz under CC-BY-4.0.