Karaniwang isinusulat ang Arabic nang walang maiikling patinig. Pinupunan ito ng mambabasa mula sa konteksto; kadalasang hindi ito kaya ng software. Ang pagbabalik ng mga ito, na tinatawag na diacritization o tashkeel, ay ginagawang كَتَبَ (sumulat siya), كُتُبٌ (mga aklat) o كُتِبَ (isinulat ito) ang كتب, depende sa pangungusap. Ipinapakita ng post na ito kung paano ito gawin gamit ang LLM sa isang OpenAI-compatible API, paano pigilan ang model na tahimik na baguhin ang text mo, at paano sukatin ang resulta laban sa isang dedicated na diacritizer.
Kailan mo kailangan ng diacritics?
- Text-to-speech. Kailangan ng boses ang mga patinig para mabigkas ang salita. Inililista ng CATT paper ang text-to-speech at machine translation bilang mga application na napapahusay ng diacritics. Walang text-to-speech endpoint ang BroadNet Inference, kaya sa isang TTS pipeline, sa hiwalay na TTS service napupunta ang text na may diacritics.
- Mga nag-aaral at materyales pambata. Umaasa sa mga marka ang mga mambabasang natututo pa lang.
- Malalabong pangalan at termino. Mga proper noun, bihirang salita at teknikal na termino kung saan nag-iiba ang kahulugan dahil sa maling patinig.
- Relihiyoso at classical na text. Dito, bahagi ng text ang mga marka, at dapat pumuno lang ng puwang ang automatic na tool sa ilalim ng review ng tao.
Kadalasang ayaw mo ng diacritics sa search o retrieval. Doon, tinatanggal mo ang mga ito, gaya sa Arabic text normalization para sa search. Ginagawa ng libreng Arabic text normalizer ang pagtanggal na iyon sa browser. Kabaligtarang operasyon ang diacritization, at mas mahirap: lookup lang ang pagtanggal ng marka, habang kailangan ng grammar at konteksto ang pagdagdag.
Gaano kahusay ang mga LLM sa diacritization?
Dalawang nailathalang numero, na dapat basahin nang maingat:
| System | CATT benchmark, DER na may case ending | DER na wala | WER na may case ending | WER na wala |
|---|---|---|---|---|
| CATT encoder-decoder | 8.624% | 6.989% | 34.191% | 28.477% |
| CATT encoder-only | 8.762% | 7.088% | 35.508% | 29.714% |
| GPT-4 (GPT-4-turbo ayon sa text ng paper) | 9.515% | 8.113% | 38.311% | 33.505% |
| Command R+ | 13.169% | 11.329% | 48.518% | 44.158% |
| Shakkala | 13.494% | 10.386% | 50.387% | 40.643% |
| Mishkal | 16.482% | 10.796% | 60.844% | 40.215% |
Source: Table 4 ng CATT paper (2024). Mas mababa, mas mahusay. Ang benchmark ay 742 news sentence na na-scrape noong 2023, nilagyan ng diacritics ng dalawang native-speaker na eksperto at sinuri ng ikatlo.
Sa ikalawang test set ng paper, ang WikiNews (400 pangungusap), mas mahusay nang malayo ang GPT-4 kaysa sa lahat: 0.551% DER. Minarkahan ng mga author ang row na iyon at sinabing baka nakita na ng model ang WikiNews sa training. Iyan ang pangkalahatang babala sa mga LLM benchmark: puwedeng nasa training data ang pampublikong test text. Ganoon din ang alalahanin ng mga author ng CATT tungkol sa Tashkeela, na ang mga aklat ay maraming sipi mula sa Quran at hadith.
Isang hiwalay na 2024 paper nina Skiredj at Berrada ang nag-uulat ng mga 20% DER at 30% WER para sa GPT-4 sa Fadel et al. benchmark, nang walang detalyeng kakailanganin namin para ikumpara ito sa table sa itaas.
Kaya puwedeng lumapit ang mga model na kauri ng GPT-4 sa isang dedicated na diacritizer, at puwede ring mahuli. Mas luma ang dalawang paper kaysa sa mga open model na matatawag mo ngayon. Sukatin sa sarili mong text.
Anong mga test set ang mayroon?
| Dataset | Ano ito |
|---|---|
| Tashkeela | 75,629,921 salitang buo ang vocalization mula sa 97 aklat; 98.85% classical Arabic mula sa Shamela library, 1.15% modern Standard Arabic |
| Fadel et al. benchmark | Mga 2.3M salita na kinuha mula sa Tashkeela; 50,000 training, 2,500 validation at 2,500 test na linya |
| CATT benchmark | 742 news sentence na mano-manong nilagyan ng diacritics, inilabas kasama ng mga CATT model |
| WikiNews | 400 MSA news sentence na mano-manong nilagyan ng diacritics |
Karamihan ay classical ang Tashkeela at ang Fadel set. Kung modernong business o news Arabic ang text mo, mas malapit ang CATT at WikiNews set, at pinakamalapit ang sample ng sarili mong text.
Anong prompt ang hindi gumagalaw sa mga letra?
Ang trabaho ng model ay magdagdag ng marka at wala nang iba pang galawin. Mahilig tumulong ang mga LLM, at aayusin nila ang الى para maging إلى, papalitan ng ي ang huling ى o magdadagdag ng nawawalang hamza. Puwedeng tamang Arabic ang bawat isa, pero spelling correction iyon, hindi diacritization. Binabago nito ang text mo nang hindi sinasabi.
Kaya isinasaad ng prompt ang patakaran, at ipinapatupad ito ng code: tanggalin ang diacritics sa sagot at ikumpara sa input na tinanggalan din. Kapag may isang letra, space o bantas na naiiba, tatanggihan ang sagot.
import difflib, os, re, unicodedata
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
MARKS = re.compile("[ً-ْٰ]") # tanween, harakat, shadda, sukun, dagger alef
SYSTEM = """Add full Arabic diacritics (tashkeel) to the user's text, including case endings.
Reply with the diacritized text only. Do not add, remove, reorder or replace any letter,
space, digit or punctuation mark. Do not fix spelling. Keep any diacritics already present."""
def skeleton(s: str) -> str:
"""The text with every diacritic removed: what the model is not allowed to change."""
return MARKS.sub("", unicodedata.normalize("NFC", s))
def diacritize(text: str, model: str = "broadnet/qwen3.8-27b", tries: int = 2) -> str | None:
for attempt in range(tries):
r = client.chat.completions.create(
model=model, max_tokens=4000, temperature=0,
messages=[{"role": "system", "content": SYSTEM}, {"role": "user", "content": text}])
out = unicodedata.normalize("NFC", (r.choices[0].message.content or "").strip())
if skeleton(out) == skeleton(text):
return out
diff = [d for d in difflib.ndiff(skeleton(text).split(), skeleton(out).split()) if d[0] in "+-"]
print(f"attempt {attempt + 1}: letters changed {diff}")
return None # keep the undiacritized text; never ship a changed sentence
for line in ["ذهب الطالب الى المدرسة", "قرأ محمد الكتاب"]:
print(diacritize(line))
Pinatakbo namin ito laban sa isang local mock server, hindi sa live API. “Inayos” ng nakahandang sagot nito para sa unang pangungusap ang الى para maging إلى sa parehong attempt, at malinis ang sagot para sa ikalawa. Ito ang output:
attempt 1: letters changed ['- الى', '+ إلى']
attempt 2: letters changed ['- الى', '+ إلى']
None
قَرَأَ مُحَمَّدٌ الْكِتَابَ
Mga tala sa code:
- Unicode NFC muna. Puwedeng dumating ang hamza bilang isang precomposed na character (أ) o bilang letra kasama ang combining mark. Ginagawang pareho ng NFC ang dalawang panig bago ikumpara. Detalyadong tinatalakay ng post tungkol sa normalization ang bitag na ito.
max_tokens=4000. Ayon sa docs ng BroadNet, nagre-reason muna ang DeepSeek V4.1 Flash, GLM 5.3 at Qwen3.8 27B bago sumagot, at kasama ang reasoning samax_tokens. Kapag masyadong maliit ang limit, walang laman ang sagot, at tatanggihan ito ng check. Mag-iwan ng puwang, o itakda sa low angreasoning_effort; tingnan ang walang lamang sagot mula sa mga reasoning model at ang reasoning token budget calculator.- Hindi tine-test ng check ang “keep existing diacritics”. Kung may diacritics na ang bahagi ng input mo, ikumpara rin ang mga markang iyon.
- Hiwalay na desisyon ang spelling. Kung gusto mong maitama ang الى, magpatakbo muna ng correction step, saka lagyan ng diacritics ang naitamang text. Kapag pinagsama ang dalawa, imposibleng ma-check ang alinman.
- Hatiin ang mahabang text. Magpadala ng isang pangungusap o talata kada request. Nililimitahan mismo ng CATT ang input sa 1,024 character at hinahati ang mahahabang pangungusap sa bantas; ang parehong ugali ay nagpapanatiling maikli ng mga sagot ng LLM at mura ang mga retry.
Para sa pangkalahatang payo sa pagsulat ng Arabic na prompt, kasama kung kailan sasabihan ang model na huwag magdagdag ng diacritics, tingnan ang Arabic prompt engineering.
Paano i-score ang diacritization: DER at WER?
Ang diacritic error rate (DER) ay ang bahagi ng mga letra na iba ang diacritics sa reference. Ang word error rate (WER) dito ay ang bahagi ng mga salita na may kahit isang maling diacritic. Hindi ito ang speech-recognition WER sa aming ASR post; binibilang nito ang mga salitang may maling marka, hindi ang mga idinagdag o nawalang salita.
Dalawang setting ang malaki ang epekto sa mga numero:
- May o walang case ending. Dala ng huling letra ng salita ang grammatical case nito (i’rab), na nakadepende sa syntax. Ini-report ng mga paper ang dalawang setting, dahil maraming error ang galing sa case ending.
- Pagbibilang ng mga letrang walang diacritic. May mga script na binibilang ang bare na letra (gaya ng alef sa الطالب) bilang tamang “walang diacritic” na prediksyon; may mga nilalaktawan ito. May flag para dito ang scoring script ng Fadel.
Magkakaiba ang mga nailathalang script sa mga pagpipiliang ito, kaya ikumpara lang ang mga numerong galing sa iisang script. Sapat na maikli ang script na ito para basahin:
import re, unicodedata
MARK = re.compile("[ً-ْٰ]")
LETTER = re.compile("[ء-غف-ي]")
def letters(word: str) -> list[tuple[str, str]]:
"""(letter, its diacritics in a fixed order) for each Arabic letter in a word."""
out = []
for ch in unicodedata.normalize("NFC", word):
if LETTER.match(ch):
out.append([ch, ""])
elif MARK.match(ch) and out:
out[-1][1] += ch
return [(c, "".join(sorted(d))) for c, d in out]
def der_wer(gold: list[str], pred: list[str], case_ending=True, count_bare=True) -> dict:
"""DER: share of scored letters with the wrong diacritics. WER: share of words with any such letter.
case_ending=False skips each word's last letter. count_bare=False skips letters with no gold diacritic."""
errs = total = werr = words = 0
for g_line, p_line in zip(gold, pred):
for g, p in zip(g_line.split(), p_line.split()):
G, P = letters(g), letters(p)
if [c for c, _ in G] != [c for c, _ in P]:
raise ValueError(f"letters differ: {g} / {p}") # score only same-skeleton output
scored = [(gd, pd) for i, ((_, gd), (_, pd)) in enumerate(zip(G, P))
if (case_ending or i < len(G) - 1) and (count_bare or gd)]
if not scored:
continue
bad = sum(gd != pd for gd, pd in scored)
errs += bad; total += len(scored); werr += bad > 0; words += 1
return {"DER": round(100 * errs / total, 2), "WER": round(100 * werr / words, 2)}
gold = ["ذَهَبَ الطَّالِبُ إِلَى المَدْرَسَةِ", "قَرَأَ مُحَمَّدٌ الكِتَابَ"]
pred = ["ذَهَبَ الطَّالِبَ إِلَى المَدْرِسَةِ", "قَرَأَ مُحَمَّدٌ الكِتَابُ"]
for ce in (True, False):
print("with case endings" if ce else "without case endings", der_wer(gold, pred, case_ending=ce))
May dalawang maling case ending at isang maling patinig sa loob ng salita ang toy na prediksyon, sa kabuuang 32 letra at 7 salita. Nagpi-print ito ng DER 9.38 at WER 42.86 na may case ending, at DER 4.0 at WER 14.29 na wala. Pansinin kung paano pinalalaki ng WER ang iilang error: isang maling marka lang, sira na ang buong salita.
Tumatanggi ang script na i-score ang salitang nagbago ang mga letra. Sinadya iyon. Bigo na sa gawain ang diacritizer na nag-e-edit ng letra, at walang kahulugan ang DER nito.
Bilang ikalawang check, pinatakbo namin ang Mishkal 0.4.1, isang rule-based na diacritizer, sa isang 16-salitang pangungusap na mano-mano naming nilagyan ng diacritics. Case ending lahat ng apat nitong error, gaya ng مُحَمَّدُ sa halip na مُحَمَّدٌ. Nakakuha ito ng DER 5.88 na may case ending at 0.0 na wala. Walang napapatunayan ang isang pangungusap tungkol sa Mishkal; ipinapakita lang nito kung bakit dapat i-report ang dalawang setting.
Para bumuo ng test set, kumuha ng 100 hanggang 200 pangungusap mula sa sarili mong text, ipalagay sa isang native speaker ang diacritics, tanggalin ang mga marka, at patakbuhin ang bawat kandidato. Itago ang bersyon ng tao bilang gold.
Kailan mas mahusay ang dedicated na diacritizer kaysa sa LLM?
| Piliin | Kailan |
|---|---|
| Dedicated na model (CATT, libtashkeel, Mishkal) | Mataas na volume, iisang uri ng text, mahigpit na latency, offline o on-device na paggamit, o pangangailangan ng letter-for-letter na output by design |
| LLM sa pamamagitan ng API | Mababa o pabago-bagong volume, halo-halo o magulong input, team na walang ML ops, o pipeline na tumatawag na sa LLM para sa ibang hakbang |
Isang marka kada letra ang hinuhulaan ng mga dedicated na model, kaya hindi nila kayang isulat muli ang text mo. Apache 2.0 ang CATT at ini-install gamit ang pip install catt-tashkeel; inirerekomenda ng README nito ang encoder-only na model para sa bilis at ang encoder-decoder para sa katumpakan. MIT ang libtashkeel at sinanay pangunahin sa MSA. Rule-based at GPL ang Mishkal, na mahalaga kung isasama mo ito sa loob ng isang produkto.
Mas mabilis simulan ang LLM at kaya nito ang input na hindi pa nakikita ng isang trained model: dialect, halong Arabic at English, kakaibang bantas. Kailangan nito ang skeleton check sa itaas sa bawat sagot, at may bayad ito kada token.
Magkano ang LLM diacritization?
Dagdag na character ang diacritics, at hinahati ito ng mga tokenizer sa dagdag na token. Binilang namin ang 2,500-line na Fadel test set (125,098 salita) gamit ang sariling tokenizer ng bawat model, bare text laban sa text na buo ang diacritics:
| Tokenizer | Bare text | May diacritics | Ratio |
|---|---|---|---|
| Qwen3.8 27B | 196,987 | 407,144 | 2.07× |
| DeepSeek V4.1 Flash | 222,555 | 540,454 | 2.43× |
| Gemma 4 VL 26B | 208,769 | 508,758 | 2.44× |
| GLM 5.3 | 239,753 | 770,361 | 3.21× |
Nagbabayad ka ng input token para sa bare text at output token para sa sagot na may diacritics, kasama ang anumang reasoning. Output ang mahal na bahagi: $2.17 kada milyong token sa Qwen3.8 27B, $0.52 sa DeepSeek V4.1 Flash, $3.46 sa GLM 5.3 at $0.22 sa Gemma 4 VL 26B, mula sa pricing page ng BroadNet. Dagdag pa ang mga retry pagkatapos ng bigong check. I-paste ang sarili mong text sa Arabic token counter para ma-check ang ratio sa data mo, at tingnan ang token kada salita sa Arabic at English para malaman kung bakit mas maraming token ang Arabic sa simula pa lang.
Para sa isang one-off na trabaho sa malaking archive, pinapalitan ng mga DeepSeek V4.1 Flash plan ang metro ng flat na presyo kada session ($15 kada linggo o $1 kada oras); isang request lang sa isang pagkakataon ang tumatakbo sa bawat session, kaya planuhin ang run gaya sa batch processing nang walang batch API.
Saan pumapasok ang BroadNet Inference
Ang BroadRouter ay sariling website ng BroadNet. Inihahain ng BroadNet Inference ang apat na chat model sa itaas sa iisang OpenAI-compatible endpoint, kaya tumatakbo ang code gamit ang OpenAI Python SDK kapag naitakda na ang base URL at key. Tumatakbo ang Gemma 4 VL 26B sa $5 na panimulang credit; kailangan ng top-up ang DeepSeek, GLM at Qwen. Walang diacritization endpoint ang BroadNet, wala itong inilathalang sariling diacritization benchmark at wala itong text-to-speech. Hindi pa nasusukat kung alin sa mga model nito ang pinakamahusay maglagay ng diacritics sa text mo: i-score ang mga ito sa sarili mong sample bago pumili. Tingnan ang API reference para sa detalye ng request.
