Downloads · 30 days
15
31% of all-time downloads
nizarun/HAT-Tashkeel-803M
HAT-Tashkeel-803M is a token classification model from nizarun. Use it when you need labels on individual words, such as names. It is set up for pytorch. The card lists the license as cc-by-nc-sa-4.0.
Downloads · 30 days
15
31% of all-time downloads
All-time downloads
49
Public
Parameters
803M
1.6 GB on disk
Likes
0
Public
Click a slice to open those files.
.safetensors1.6 GB · 100%
From the Hugging Face model README
<a id="english"></a>
English · العربية
Author: Nizar, independent AI researcher, Riyadh, Saudi Arabia. Designed, pretrained and fine-tuned by one person; no team, no open-weight base model.
Adds full diacritics (tashkeel) to Arabic text, including case endings (i'rab).
model.safetensors (1.6 GB).The Arabic version of this card (below) was diacritized by this model with no human intervention (only the opening note and the data-source thanks are left undiacritized).
Our base model is a character-level Hierarchical Attention Transformer (HAT). It has three parts: a character encoder turns each word's letters into one word vector, a word-level backbone processes the sequence of words, and a character decoder writes out the next word letter by letter. As a language model it is autoregressive: it only looks left and generates new text.
Diacritization is a different kind of problem. The output unit is the same as the input unit: a word goes in, and the same word comes out with marks. Nothing new has to be generated, but the right mark often depends on words that come after it (a case ending depends on the rest of the sentence). So we converted the language model:
The whole passage is labelled in one forward pass, which is why it is fast (see Speed).
| Part | Size |
|---|---|
| Character encoder | 5 layers, width 512, 8 learned pooling queries → word vector of 1792 |
| Word backbone (bidirectional) | 20 layers, width 1792, 14 heads, RoPE |
| Diacritic head | cross-attention to the word state + 2 character layers → 16 outputs |
| Context | up to 220 word slots per window (180 words used by default, see below) |
# pip install torch huggingface_hub safetensors
from modeling_tashkeel import TashkeelModel # file included in this repo
model = TashkeelModel.from_pretrained("nizarun/HAT-Tashkeel-803M").to("cuda").eval() # bf16
print(model.diacritize("كتب الطالب درسا جديدا وقرأ كتابا مفيدا"))
# كَتَبَ الطَّالِبُ دَرْسًا جَدِيدًا وَقَرَأَ كِتَابًا مُفِيدًا
outputs = model.diacritize(list_of_texts, batch_size=16) # batched
model.float().window_units= to change it).| Setting | Recommendation | Why (measured) |
|---|---|---|
| Words per window (chunk) | 180 (the default) | Best on both test sets. 100–200 words is fine; below 50 words accuracy drops (10 words: DER 4.68% on WikiNews), and filling all 220 slots raises DER from 3.01% to 4.03%. |
| Overlapping windows | Off | Overlap (stride 90) gave 2.99% vs 3.01% for twice the compute. |
| Decoding passes | One pass | We tested multi-pass iterative refinement (4 passes, where confident marks are fed back as input). It was worse than a single pass on both test sets we ran it on (unseen Fadel lines: DER 2.55% vs 2.47%; our validation sample: 6.60% vs 6.34%) and about twice as slow, so it is not recommended and not included. |
| Input | Plain text, hamzas written | Existing marks are removed anyway; missing hamzas (اله instead of إله) cause errors. |
| Batch size (GPU) | 8–32 | Throughput stops increasing above 8. |
| Precision | bf16 on GPU; fp32 or int8 on CPU | See Speed. |
We report DER (diacritic error rate): the share of letters whose diacritic differs from the reference. It is given with the case ending (last letter of each word) and without it. Letters that should carry no mark are included. Scoring uses the official script of the Fadel et al. (2019) benchmark.
The WikiNews test set (Darwish et al., 2017): 428 lines, 17,001 words of Modern Standard Arabic news. None of its lines share even 10% of their 8-word spans with our training data.
| DER | With case ending | Without case ending |
|---|---|---|
| Each line decoded on its own (standard protocol) | 3.27% | 2.12% |
| Whole articles decoded as continuous text | 3.01% | — |
Style differences are not errors. Our training text is mostly Classical Arabic, while WikiNews is news-style Modern Standard Arabic, and some differences from the reference are two correct ways of writing the same word:
Counting these (symmetric, fixed rules) as correct gives DER 2.68% with case endings. Many of the remaining differences are foreign names (ويكيبيديا, ستيفن, ليدز), which have no single correct vocalization.
This benchmark is built from Tashkeela, which is also part of our training data, and 84% of its test lines appear almost word for word in our training data. A full-test-set score would therefore overstate accuracy, so we report only the 156 lines (1,833 words) not found in training. It is a small sample; treat it as approximate.
| DER, unseen lines only | With case ending | Without case ending |
|---|---|---|
| 2.47% | 1.98% |
The model was trained on 220-word windows, but on unseen text it is most accurate when about 180 words of text are used and the remaining slots are left as padding. DER with passages decoded as continuous text:
| Words per window | 50 | 100 | 150 | 180 | 200 | 220 |
|---|---|---|---|---|---|---|
| WikiNews | 3.44% | 3.14% | 3.09% | 3.01% | 3.05% | 4.03% |
| Fadel unseen lines (stacked) | — | 2.41% | 2.38% | 2.02% | 2.14% | 2.24% |
180 is the default (DEFAULT_WINDOW_WORDS in modeling_tashkeel.py).
GPU (RTX 4090, bf16, PyTorch 2.9, no torch.compile):
| Latency, one request of 10–200 words | ~30 ms |
| Throughput, batched short texts | ~5,800 words/s |
| Throughput, long documents | ~10,000+ words/s |
| GPU memory | 1.7 GB (batch 1), 2.4 GB (batch 8), 4.8 GB (batch 32) |
CPU (Intel i9-10850K, 10 threads):
| fp32 | int8 dynamic quantization | |
|---|---|---|
| Latency, one request | 1.45 s | 0.86 s |
| Throughput, long document | 125 words/s | 195 words/s |
| DER on 60 WikiNews lines (GPU bf16: 2.90%) | 2.87% | 2.97% |
int8: torch.ao.quantization.quantize_dynamic(model.float(), {torch.nn.Linear}, dtype=torch.qint8). Avoid bf16 on CPUs without native bf16 support (4× slower than fp32 on the CPU above).
CC BY-NC-SA 4.0 (Attribution, NonCommercial, ShareAlike):
Built in Riyadh, Saudi Arabia, for the Arabic language.
<a id="arabic"></a>
بِالْعَرَبِيَّةِ
<!-- no-tashkeel --><!-- /no-tashkeel -->أضيف التشكيل إلى النص أدناه بواسطة النموذج دون أي تدخل بشري.
السَّلَامُ عَلَيْكُمْ وَرَحْمَةُ اللَّهِ وَبَرَكَاتُهُ،
صَاحِبُ النَّمُوذَجِ: نِزَار، بَاحِثٌ مُسْتَقِلٌّ فِي الذَّكَاءِ الِاصْطِنَاعِيِّ، الرِّيَاضُ، الْمَمْلَكَةُ الْعَرَبِيَّةُ السُّعُودِيَّةُ. صَمَّمَهُ وَدَرَّبَهُ شَخْصٌ وَاحِدٌ.
نَمُوذَجٌ يَضَعُ التَّشْكِيلَ الْكَامِلَ عَلَى النَّصِّ الْعَرَبِيِّ، وَمَعَهُ الْإِعْرَابَ فِي أَوَاخِرِ الْكَلِمَاتِ.
بَنَيْنَا النَّمُوذَجَ الْأَسَاسِيَّ عَلَى طَرِيقَةٍ هَرَمِيَّةٍ تَبْدَأُ مِنَ الْحُرُوفِ، وَفِيهِ ثَلَاثَةُ أَجْزَاءٍ:
وَهَذَا النَّمُوذَجُ اللُّغَوِيُّ لَا يَرَى إِلَّا مَا قَبْلَ الْكَلِمَةِ، وَيَكْتُبُ نَصًّا جَدِيدًا كَلِمَةً بَعْدَ كَلِمَةٍ.
أَمَّا التَّشْكِيلُ فَأَمْرٌ آخَرُ: الْكَلِمَةُ الَّتِي تَدْخُلُ هِيَ الْكَلِمَةُ الَّتِي تَعُودُ، وَلَكِنْ بِحَرَكَاتِهَا. فَلَا حَاجَةَ إِلَى كِتَابَةِ شَيْءٍ جَدِيدٍ. غَيْرَ أَنَّ الْحَرَكَةَ الصَّحِيحَةَ تَعْتَمِدُ كَثِيرًا عَلَى كَلِمَاتٍ تَأْتِي بَعْدَ الْكَلِمَةِ، فَالْإِعْرَابُ مَثَلًا يَتَحَدَّدُ بِبَاقِي الْجُمْلَةِ. وَلِهَذَا غَيَّرْنَا النَّمُوذَجَ اللُّغَوِيَّ عَلَى هَذَا النَّحْوِ:
وَيَعُودُ النَّصُّ كُلُّهُ مَشْكُولًا فِي خُطْوَةٍ وَاحِدَةٍ، وَهَذَا سِرُّ سُرْعَتِهِ.
| الْجُزْءُ | الْحَجْمُ |
|---|---|
| قَارِئُ الْحُرُوفِ | فِيهِ خَمْسُ طَبَقَاتٍ بِعَرْضِ 512، وَيُعْطِي صُورَةً لِلْكَلِمَةِ بِعَرْضِ 1792 |
| الْعَمُودُ الْفِقْرِيُّ | فِيهِ عِشْرُونَ طَبَقَةً بِعَرْضِ 1792، فِي كُلِّ طَبَقَةٍ 14 رَأْسًا |
| جُزْءُ التَّشْكِيلِ | فِيهِ طَبَقَتَانِ عَلَى الْحُرُوفِ، ثُمَّ يَخْتَارُ وَاحِدًا مِنْ 16 |
| طُولُ النَّصِّ | حَتَّى 220 كَلِمَةً فِي كُلِّ مَرَّةٍ، وَالأَفْضَلُ 180 كَلِمَةً |
from modeling_tashkeel import TashkeelModel
model = TashkeelModel.from_pretrained("nizarun/HAT-Tashkeel-803M").to("cuda").eval()
print(model.diacritize("كتب الطالب درسا جديدا وقرأ كتابا مفيدا"))
outputs = model.diacritize(list_of_texts, batch_size=16)
وَهَذِهِ نَتِيجَةُ الْمِثَالِ:
كَتَبَ الطَّالِبُ دَرْسًا جَدِيدًا وَقَرَأَ كِتَابًا مُفِيدًا
window_units
وَعَلَى الْمُعَالِجِ الْمَرْكَزِيِّ نَسْتَخْدِمُ الدِّقَّةَ الْكَامِلَةَ بِهَذَا الْأَمْرِ:
model.float()
| مَا نَضْبِطُهُ | مَا نَنْصَحُ بِهِ | لِمَاذَا |
|---|---|---|
| عَدَدُ الْكَلِمَاتِ فِي كُلِّ جُزْءٍ | 180 كَلِمَةً | أَفْضَلُ نَتِيجَةٍ فِي الِاخْتِبَارَيْنِ. وَكُلُّ عَدَدٍ بَيْنَ 100 وَ200 مَقْبُولٌ، أَمَّا عَشْرُ كَلِمَاتٍ فَتَزِيدُ الخَطَأَ إِلَى 4.68%. وَإِذَا مَلَأْنَا الْأَمَاكِنَ كُلَّهَا زَادَ الْخَطَأُ مِنْ 3.01% إِلَى 4.03%. |
| أَجْزَاءٌ مُتَدَاخِلَةٌ | لَا | التَّدَاخُلُ أَعْطَى 2.99% بَدَلًا مِنْ 3.01%، وَالْحِسَابُ صَارَ ضِعْفَيْنِ. |
| عَدَدُ مَرَّاتِ الْقِرَاءَةِ | مَرَّةً وَاحِدَةً | جَرَّبْنَا أَنْ يَقْرَأَ النَّمُوذَجُ النَّصَّ أَرْبَعَ مَرَّاتٍ، وَيَسْتَفِيدَ فِي كُلِّ مَرَّةٍ مِنَ الْحَرَكَاتِ الَّتِي وَثِقَ بِهَا فِي الْمَرَّةِ السَّابِقَةِ، فَكَانَتِ النَّتِيجَةُ أَسْوَأَ مِنَ الْقِرَاءَةِ الْوَاحِدَةِ: 2.55% بَدَلًا مِنْ 2.47% فِي اخْتِبَارٍ، وَ6.60% بَدَلًا مِنْ 6.34% فِي اخْتِبَارٍ آخَرَ، مَعَ بُطْءٍ بِنَحْوِ الضِّعْفِ. لِذَلِكَ لَا نَنْصَحُ بِهِ، وَلَمْ نَضَعْهُ فِي الْبَرْنَامَجِ. |
| النَّصُّ | نَصٌّ عَادِيٌّ بِهَمَزَاتٍ صَحِيحَةٍ | نَحْذِفُ التَّشْكِيلَ القَدِيمَ عَلَى كُلِّ حَالٍ، أَمَّا الْهَمْزَةُ النَّاقِصَةُ فَتُسَبِّبُ الخَطَأَ. |
| عَدَدُ النُّصُوصِ مَعًا عَلَى الْمُعَالِجِ الرُّسُومِيِّ | مِنْ 8 إِلَى 32 | السُّرْعَةُ لَا تَزِيدُ بَعْدَ 8. |
نَقِيسُ نِسْبَةَ الْحُرُوفِ الَّتِي أَخْطَأَ النَّمُوذَجُ فِي حَرَكَتِهَا، مُقَارَنَةً بِنَصٍّ مَشْكُولٍ بِأَيْدِي الْمُخْتَصِّينَ. وَنَحْسُبُهَا مَرَّةً مَعَ حَرَكَةِ آخِرِ الْكَلِمَةِ، وَمَرَّةً بِدُونِهَا، وَتَدْخُلُ فِي الْحِسَابِ الْحُرُوفُ الَّتِي يَجِبُ أَنْ تَبْقَى بِلَا حَرَكَةٍ. وَاسْتَخْدَمْنَا فِي الْحِسَابِ الْبَرْنَامَجَ الَّذِي نَشَرَهُ الْبَاحِثُ عَلِيُّ فَاضِل وَزُمَلَاؤُهُ سَنَةَ 2019، وَهَذَا رَابِطُهُ.
نَشَرَ الْبَاحِثُ كَرِيم دَرْوِيش وَزُمَلَاؤُهُ اخْتِبَارَ الْأَخْبَارِ سَنَةَ 2017، وَهَذَا رَابِطُهُ. وَفِيهِ 428 سَطْرًا وَ17,001 كَلِمَةً مِنَ الْأَخْبَارِ بِالعَرَبِيَّةِ الْفُصْحَى الْمُعَاصِرَةِ. وَقَدْ بَحَثْنَا فِي كُلِّ بَيَانَاتِ التَّدْرِيبِ، فَلَمْ نَجِدْ سَطْرًا وَاحِدًا يَشْتَرِكُ مَعَهَا حَتَّى فِي عَشَرَةٍ بِالْمِئَةِ مِنْ عِبَارَاتِهِ.
| طَرِيقَةُ الْقِرَاءَةِ | مَعَ حَرَكَةِ آخِرِ الْكَلِمَةِ | بِدُونِهَا |
|---|---|---|
| نُشَكِّلُ كُلَّ سَطْرٍ وَحْدَهُ، كَمَا فِي أَكْثَرِ الْأَبْحَاثِ | 3.27% | 2.12% |
| نُشَكِّلُ الْمَقَالَةَ كُلَّهَا نَصًّا وَاحِدًا | 3.01% | — |
اخْتِلَافُ الْأُسْلُوبِ لَيْسَ خَطَأً. النَّمُوذَجُ تَعَلَّمَ مِنْ كُتُبِ التُّرَاثِ فِي أَكْثَرِ تَدْرِيبِهِ، أَمَّا الْأَخْبَارُ فَأُسْلُوبُهَا صَحَفِيٌّ مُعَاصِرٌ. وَبَعْضُ الْفُرُوقِ بَيْنَ النَّمُوذَجِ وَالنَّصِّ الْمَشْكُولِ هِيَ طَرِيقَتَانِ صَحِيحَتَانِ لِكِتَابَةِ الْكَلِمَةِ نَفْسِهَا:
وَإِذَا عَدَدْنَا هَذِهِ الْحَالَاتِ صَحِيحَةً، بِقَوَاعِدَ ثَابِتَةٍ لَا تَمِيلُ إِلَى النَّمُوذَجِ وَلَا إِلَى النَّصِّ الْمَشْكُولِ، صَارَ الْخَطَأُ 2.68% مَعَ حَرَكَةِ آخِرِ الْكَلِمَةِ.
وَمِنَ الْفُرُوقِ الْبَاقِيَةِ أَسْمَاءٌ أَجْنَبِيَّةٌ كَثِيرَةٌ، مِثْلَ أَسْمَاءِ الْمُدُنِ وَالْأَشْخَاصِ، وَهَذِهِ لَيْسَ لَهَا تَشْكِيلٌ وَاحِدٌ صَحِيحٌ.
أَمَّا الِاخْتِبَارُ الثَّانِي فَنَشَرَهُ الْبَاحِثُ عَلِيُّ فَاضِلٍ وَزُمَلَاؤُهُ، وَهُوَ مَأْخُوذٌ مِنْ مُدَوَّنَةِ تَشْكِيلَةٍ، وَهِيَ أَيْضًا مِنْ مَصَادِرِ بَيَانَاتِ تَدْرِيبِنَا. كَمَا أَنَّ أَكْثَرَ مِنْ ثَمَانِينَ بِالْمِئَةِ مِنْ أَسْطُرِهِ مَوْجُودَةٌ فِي بَيَانَاتِ التَّدْرِيبِ تَقْرِيبًا بِحُرُوفِهَا. فَنَتِيجَةُ الِاخْتِبَارِ كَامِلًا سَتَكُونُ أَحْسَنَ مِنَ الْوَاقِعِ، وَلِذَلِكَ لَا نَنْشُرُهَا. وَنَنْشُرُ فَقَطْ نَتِيجَةَ 156 سَطْرًا (1,833 كَلِمَةً) لَمْ نَجِدْهَا فِي التَّدْرِيبِ. وَالْعَدَدُ صَغِيرٌ، فَالرَّقْمُ تَقْرِيبِيٌّ.
| الْأَسْطُرُ الَّتِي لَمْ يَرَهَا النَّمُوذَجُ | مَعَ حَرَكَةِ آخِرِ الْكَلِمَةِ | بِدُونِهَا |
|---|---|---|
| نِسْبَةُ الخَطَأِ | 2.47% | 1.98% |
كَانَ التَّدْرِيبُ عَلَى 220 كَلِمَةً فِي كُلِّ مَرَّةٍ، لَكِنَّ أَفْضَلَ نَتِيجَةٍ عَلَى النُّصُوصِ الْجَدِيدَةِ كَانَتْ عِنْدَ 180 كَلِمَةً، وَتَبْقَى الْأَمَاكِنُ الْأُخْرَى فَارِغَةً. وَهَذِهِ نِسَبُ الْخَطَأِ حِينَ نُشَكِّلُ النُّصُوصَ نَصًّا مُتَّصِلًا:
| عَدَدُ الْكَلِمَاتِ فِي كُلِّ مَرَّةٍ | 50 | 100 | 150 | 180 | 200 | 220 |
|---|---|---|---|---|---|---|
| اِخْتِبَارُ الأَخْبَارِ | 3.44% | 3.14% | 3.09% | 3.01% | 3.05% | 4.03% |
| الِاخْتِبَارُ الثَّانِي، الْأَسْطُرُ الَّتِي لَمْ يَرَهَا النَّمُوذَجُ | — | 2.41% | 2.38% | 2.02% | 2.14% | 2.24% |
DEFAULT_WINDOW_WORDS
عَلَى الْمُعَالِجِ الرُّسُومِيِّ بِالدِّقَّةِ النِّصْفِيَّةِ، وَاسْتَخْدَمْنَا هَذَا الْجِهَازَ:
RTX 4090
| الْقِيَاسُ | النَّتِيجَةُ |
|---|---|
| وَقْتُ الطَّلَبِ الْوَاحِدِ، مِنْ عَشْرِ كَلِمَاتٍ إِلَى مِئَتَيْ كَلِمَةٍ | 0.03 ثَانِيَةٍ تَقْرِيبًا |
| السُّرْعَةُ مَعَ نُصُوصٍ قَصِيرَةٍ كَثِيرَةٍ مَعًا | 5,800 كَلِمَةً فِي الثَّانِيَةِ تَقْرِيبًا |
| السُّرْعَةُ مَعَ نُصُوصٍ طَوِيلَةٍ | تَزِيدُ عَلَى 10,000 كَلِمَةٍ فِي الثَّانِيَةِ |
| الذَّاكِرَةُ | 1.7 غِيغَابَايْت لِنَصٍّ وَاحِدٍ، وَ2.4 لِثَمَانِيَةِ نُصُوصٍ، وَ4.8 لِاثْنَيْنِ وَثَلَاثِينَ نَصًّا |
عَلَى الْمُعَالِجِ الْمَرْكَزِيِّ مَعَ 10 خُيُوطٍ، وَاسْتَخْدَمْنَا هَذَا الْجِهَازَ:
Intel i9-10850K
| الْقِيَاسُ | الدِّقَّةُ الْكَامِلَةُ | الدِّقَّةُ الْمُنْخَفِضَةُ |
|---|---|---|
| وَقْتُ طَلَبٍ وَاحِدٍ | 1.45 ثَانِيَةٍ | 0.86 ثَانِيَةٍ |
| السُّرْعَةُ مَعَ نَصٍّ طَوِيلٍ | 125 كَلِمَةً فِي الثَّانِيَةِ | 195 كَلِمَةً فِي الثَّانِيَةِ |
| نِسْبَةُ الخَطَأِ عَلَى سِتِّينَ سَطْرًا مِنَ الأَخْبَارِ، وَكَانَتْ عَلَى المُعَالِجِ الرُّسُومِيِّ 2.90% | 2.87% | 2.97% |
torch.ao.quantization.quantize_dynamic(model.float(), {torch.nn.Linear}, dtype=torch.qint8)
النَّمُوذَجُ مَنْشُورٌ بِرُخْصَةِ الْمُشَاعِ الْإِبْدَاعِيِّ، وَلَهَا ثَلَاثَةُ شُرُوطٍ:
جاء جزء من بيانات التدريب من نسخة معالجة لمدونة تشكيلة، وهذا رابطها. فنشكر من أعدها:
Hamza Abbad
ونشكر الجامع الأصلي لمدونة تشكيلة:
Taha Zerrouki
كما تدرب النموذج أيضا على نصوص شكلناها بأنفسنا.
<!-- /no-tashkeel -->وَنَشْكُرُ الْبَاحِثَ عَلِيَّ فَاضِلٍ وَزُمَلَاءَهُ، وَالْبَاحِثَ كَرِيمَ دَرْوِيش وَزُمَلَاءَهُ، فَقَدْ قَامَتْ عَلَى أَعْمَالِهِمْ بَيَانَاتُ الِاخْتِبَارِ. وَنَشْكُرُ كُلَّ مَنْ شَارَكَ فِي الْمَصَادِرِ الْمَفْتُوحَةِ لِلُّغَةِ الْعَرَبِيَّةِ.
بَنَيْنَا هَذَا النَّمُوذَجَ فِي الرِّيَاضِ بِالْمَمْلَكَةِ الْعَرَبِيَّةِ السُّعُودِيَّةِ، خِدْمَةً لِلُّغَةِ الْعَرَبِيَّةِ.