PersianHTR-7K
A pretrained Persian Handwritten Word Retrieval Model for fast handwritten word recognition using Embedding + FAISS.
Unlike traditional OCR models that directly classify an image into one of thousands of classes, PersianHTR-7K converts each handwritten word image into a compact embedding vector and retrieves the most similar words from a FAISS index.
This model is designed to work together with Korosh-HTR-Engine, providing fast, scalable, and CPU-friendly handwritten word recognition.
Features
- Persian handwritten word-level recognition
- Retrieval-based recognition (Embedding + FAISS)
- CPU-only inference
- Portable model package
- Fast similarity search
- Easily scalable vocabulary
- Top-K candidate retrieval
- Designed for integration with downstream language models (LLMs)
Model Overview
| Property | Value |
|---|
| Language | Persian (Farsi) |
| Recognition Level | Word |
| Recognition Method | Embedding + FAISS Retrieval |
| Encoder | MobileNetV3-Small |
| Embedding Dimension | 256 |
| Index | FAISS |
| Inference | CPU |
| Output | Top-K Candidate Words |
Training Dataset
The model was trained using a Persian handwritten word dataset.
| Property | Value |
|---|
| Total Images | 403,881 |
| Unique Words | 7,391 |
| Average Samples per Word | ~55 |
| Dataset Type | Persian Handwritten Word Images |
Dataset structure:
1dataset/
2
3 کتاب/
4 00001.png
5 00002.png
6 ...
7
8 مدرسه/
9 ...
10
11 ماهی/
12 ...
Training Configuration
| Parameter | Value |
|---|
| Backbone | MobileNetV3-Small |
| Epochs | 20 |
| Embedding Size | 256 |
| Batch Size | Auto (864 on Tesla T4) |
| Mixed Precision | Enabled |
| FAISS | Enabled |
Training optimizations:
- Automatic Batch Size Tuning
- Automatic Checkpointing
- Automatic Resume
- GPU Image Augmentation
- Optimized Disk Cache
- AMP
- TF32
- channels_last
Training Summary
| Metric | Value |
|---|
| Images | 403,881 |
| Classes | 7,391 |
| Epochs | 20 |
| Final Training Accuracy | 68.2% |
| Final Training Loss | 5.4345 |
| Generated Embeddings | 403,881 |
| Embedding Dimension | 256 |
Generated FAISS Index:
1Vectors : 403,881
2Dimension : 256
About the Reported Accuracy
The reported 68.2% training accuracy is NOT the final capability of this model.
This training run was intentionally performed as an initial proof-of-concept under limited computational resources and limited available training time.
Training was stopped after only 20 epochs, even though the optimization process was still improving.
The model did not show any sign of convergence or saturation before training stopped.
During all training epochs:
- Training accuracy continuously increased.
- Training loss continuously decreased.
- No accuracy plateau was observed.
- No loss plateau was observed.
Training progression:
| Epoch | Accuracy | Loss |
|---|
| 1 | 0.2% | 8.7655 |
| 5 | 22.2% | 7.3786 |
| 10 | 53.4% | 6.1466 |
| 15 | 65.5% | 5.5627 |
| 20 | 68.2% | 5.4345 |
The training curves indicate that the network was still learning when training ended.
With additional training epochs, more computational resources, and further hyperparameter tuning, higher training accuracy and improved retrieval performance are expected.
Important: PersianHTR-7K is intended to be used as a retrieval model, not as a conventional classifier. The classifier accuracy shown above is mainly used to learn a discriminative embedding space. For the intended application, retrieval metrics such as Top-1 Accuracy, Top-K Accuracy, and Recall@K are considerably more meaningful than classifier accuracy alone.
Model Package
The exported model directory contains everything required for inference.
1output_model/
2
3 model.pt
4
5 faiss.index
6
7 labels.json
8
9 config.json
10
11 metadata.json
Simply loading this directory is sufficient to perform inference.
Example Output
1[
2 {
3 "word":"کتاب",
4 "probability":0.83
5 },
6 {
7 "word":"کباب",
8 "probability":0.11
9 },
10 {
11 "word":"حساب",
12 "probability":0.06
13 }
14]
Instead of returning only one prediction, the model always returns the Top-K most similar candidate words, allowing downstream systems (such as LLMs) to make more informed decisions using contextual information.
Recognition Pipeline
1Handwritten Word Image
2
3 │
4
5 ▼
6
7Preprocessing
8
9 │
10
11 ▼
12
13CNN Encoder
14
15 │
16
17 ▼
18
19256-D Embedding
20
21 │
22
23 ▼
24
25FAISS Search
26
27 │
28
29 ▼
30
31Top-K Candidate Words
32
33 │
34
35 ▼
36
37Probability Estimation
38
39 │
40
41 ▼
42
43JSON Output
Intended Workflow
1Handwritten Answer Sheet
2
3 │
4
5 ▼
6
7Word Segmentation
8
9 │
10
11 ▼
12
13PersianHTR-7K
14
15 │
16
17 ▼
18
19Top-K Candidate Words
20
21 │
22
23 ▼
24
25(Optional)
26
27Large Language Model
28
29 │
30
31 ▼
32
33Final Correct Word
Limitations
Current version supports:
- Persian language only
- Word-level recognition only
- Offline inference
- CPU-only inference
Current version does not perform:
- Line segmentation
- Page layout analysis
- Text detection
- Full-page OCR
- Context-aware correction (handled by downstream systems)
Future Work
Future versions may include:
- Larger Persian vocabulary
- Improved embedding models
- Retrieval-specific fine-tuning
- Better probability calibration
- Larger public evaluation benchmarks
- Better ranking algorithms
- Hard-negative mining
- More robust embeddings
- Improved retrieval accuracy
Related Projects
Engine:
Korosh-HTR-Engine
Dataset:
Persian Word Handwritten Dataset
License
Please refer to the LICENSE file included in this repository.
Citation
If you use this model in academic research, publications, or commercial projects, please cite this repository.
