Arapça normalde kısa ünlüler olmadan yazılır. Okuyucu bunları bağlamdan tamamlar; yazılım ise çoğu zaman tamamlayamaz. Bunları geri getirmek (hareke ekleme ya da teşkil), cümleye göre كتب’yi كَتَبَ (yazdı), كُتُبٌ (kitaplar) veya كُتِبَ (yazıldı) yapar. Bu yazı, bunu OpenAI uyumlu bir API üzerinden bir LLM ile nasıl yapacağınızı, modelin metninizi sessizce değiştirmesini nasıl önleyeceğinizi ve sonucu özel bir hareke aracıyla nasıl karşılaştıracağınızı gösteriyor.
Harekelere ne zaman ihtiyaç duyarsınız?
- Metinden sese (TTS). Bir sesin kelimeyi telaffuz edebilmesi için ünlülere ihtiyacı vardır. CATT makalesi metinden sese ve makine çevirisini harekelerin iyileştirdiği uygulamalar arasında sayıyor. BroadNet Inference’ın metinden sese uç noktası yok; bu yüzden bir TTS hattında harekeli metin ayrı bir TTS hizmetine gider.
- Öğrenciler ve çocuk materyalleri. Okumayı hâlâ öğrenen okuyucular bu işaretlere dayanır.
- Belirsiz adlar ve terimler. Yanlış bir ünlünün anlamı değiştirdiği özel adlar, nadir kelimeler ve teknik terimler.
- Dinî ve klasik metinler. Burada işaretler metnin parçasıdır; otomatik bir araç yalnızca insan denetiminde boşlukları doldurmalıdır.
Arama ya da erişim (retrieval) için genellikle hareke istemezsiniz. Orada onları silersiniz; bkz. arama için Arapça metin normalleştirme. Ücretsiz Arapça metin normalleştirici bu silme işini tarayıcıda yapar. Hareke ekleme bunun tersidir ve çok daha zordur: işaretleri silmek bir tablo aramasıdır, eklemek ise dil bilgisi ve bağlam ister.
LLM’ler hareke eklemede ne kadar iyi?
Dikkatle okunması gereken iki yayımlanmış sonuç:
| Sistem | CATT kıyaslaması, i’rab dahil DER | Hariç DER | i’rab dahil WER | Hariç WER |
|---|---|---|---|---|
| CATT kodlayıcı-kod çözücü | %8,624 | %6,989 | %34,191 | %28,477 |
| CATT yalnızca kodlayıcı | %8,762 | %7,088 | %35,508 | %29,714 |
| GPT-4 (makale metnine göre GPT-4-turbo) | %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 |
Kaynak: CATT makalesi, Tablo 4 (2024). Düşük olan daha iyidir. Kıyaslama, 2023’te toplanmış, anadili Arapça olan iki uzman tarafından harekelenmiş ve üçüncü bir uzman tarafından kontrol edilmiş 742 haber cümlesinden oluşuyor.
Makalenin ikinci test setinde, WikiNews’te (400 cümle), GPT-4 diğer her şeyden çok daha iyi sonuç aldı: %0,551 DER. Yazarlar bu satırı işaretliyor ve modelin WikiNews’ü eğitimde görmüş olabileceğini öne sürüyor. LLM kıyaslamaları için genel uyarı da bu: herkese açık test metni eğitim verisinde olabilir. CATT yazarları aynı kaygıyı, kitaplarında çok sayıda Kur’an ve hadis alıntısı bulunan Tashkeela için de dile getiriyor.
Skiredj ve Berrada’nın 2024 tarihli ayrı bir makalesi, Fadel vd. kıyaslamasında GPT-4 için yaklaşık %20 DER ve %30 WER bildiriyor; ancak yukarıdaki tabloyla karşılaştırmamız için gereken ayrıntıyı vermiyor.
Yani GPT-4 sınıfı modeller özel bir hareke aracına yaklaşabilir, ama gerisinde de kalabilir. İki makale de bugün çağırabileceğiniz açık modellerden önce yazıldı. Kendi metninizde ölçün.
Hangi test setleri var?
| Veri seti | Nedir |
|---|---|
| Tashkeela | 97 kitaptan 75.629.921 tam harekeli kelime; %98,85’i Shamela kütüphanesinden klasik Arapça, %1,15’i Modern Standart Arapça |
| Fadel vd. kıyaslaması | Tashkeela’dan çıkarılmış yaklaşık 2,3 milyon kelime; 50.000 eğitim, 2.500 doğrulama ve 2.500 test satırı |
| CATT kıyaslaması | Elle harekelenmiş 742 haber cümlesi, CATT modelleriyle birlikte yayımlandı |
| WikiNews | Elle harekelenmiş 400 MSA haber cümlesi |
Tashkeela ve Fadel seti ağırlıklı olarak klasik. Metniniz modern iş ya da haber Arapçasıysa CATT ve WikiNews setleri daha yakındır; kendi metninizden bir örneklem ise en yakınıdır.
Hangi istem harfleri olduğu gibi korur?
Modelin işi işaret eklemek ve başka hiçbir şeye dokunmamak. LLM’ler yardım etmeyi sever: الى’yı إلى’ya düzeltir, sondaki ى’yı ي yapar ya da eksik bir hemze ekler. Bunların her biri doğru Arapça olabilir, ama bu hareke ekleme değil, yazım düzeltmesidir. Metninizi size haber vermeden değiştirir.
Bu yüzden istem kuralı söyler, kod da uygular: yanıttaki harekeleri silin ve harekeleri silinmiş girdiyle karşılaştırın. Tek bir harf, boşluk ya da noktalama işareti farklıysa yanıt reddedilir.
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))
Bunu canlı API’ye karşı değil, yerel bir sahte (mock) sunucuya karşı çalıştırdık. Sunucunun ilk cümle için hazır yanıtı iki denemede de الى’yı إلى’ya “düzeltti”; ikinci cümlenin yanıtı ise temizdi. Çıktı şöyleydi:
attempt 1: letters changed ['- الى', '+ إلى']
attempt 2: letters changed ['- الى', '+ إلى']
None
قَرَأَ مُحَمَّدٌ الْكِتَابَ
Kodla ilgili notlar:
- Önce Unicode NFC. Bir hemze tek bir hazır karakter (أ) olarak da, bir harf artı birleşen bir işaret olarak da gelebilir. NFC, karşılaştırmadan önce iki tarafı aynı hâle getirir. Normalleştirme yazısı bu tuzağı ayrıntılı anlatıyor.
max_tokens=4000. BroadNet’in dokümantasyonuna göre DeepSeek V4.1 Flash, GLM 5.3 ve Qwen3.8 27B yanıt vermeden önce akıl yürütür ve akıl yürütmemax_tokens’a sayılır. Çok küçük bir sınır boş bir yanıt döndürür, kontrol de onu reddeder. Pay bırakın ya dareasoning_effortdeğerini low yapın; bkz. akıl yürütme modellerinden boş yanıtlar ve akıl yürütme token bütçesi hesaplayıcısı.- Kontrol “mevcut harekeleri koru” kuralını test etmez. Girdiniz kısmen harekeliyse bu işaretleri de karşılaştırın.
- Yazım ayrı bir karardır. الى’nın düzeltilmesini istiyorsanız önce bir düzeltme adımı çalıştırın, sonra düzeltilmiş metne hareke ekleyin. İkisini karıştırmak, ikisinin de kontrol edilmesini imkânsız kılar.
- Uzun metni parçalayın. İstek başına bir cümle ya da bir paragraf gönderin. CATT’in kendisi girdiyi 1.024 karakterle sınırlar ve uzun cümleleri noktalama işaretlerinden böler; aynı alışkanlık LLM yanıtlarını kısa, yeniden denemeleri de ucuz tutar.
Bir modele hareke eklememesini ne zaman söyleyeceğiniz dahil, Arapça istem yazımıyla ilgili genel öneriler için bkz. Arapça istem mühendisliği.
Hareke ekleme nasıl puanlanır: DER ve WER
Hareke hata oranı (DER), harekeleri referanstan farklı olan harflerin oranıdır. Kelime hata oranı (WER) burada en az bir yanlış harekesi olan kelimelerin oranıdır. Bu, ASR yazımızdaki konuşma tanıma WER’i değildir; eklenen ya da silinen kelimeleri değil, yanlış işareti olan kelimeleri sayar.
İki ayar sayıları çok değiştirir:
- i’rab harekeleri dahil ya da hariç. Bir kelimenin son harfi, sözdizimine bağlı olan dil bilgisel durumunu (i’rab) taşır. Makaleler iki ayarı da raporlar, çünkü hataların çoğu bu son harekelerden gelir.
- Harekesiz harflerin sayılması. Bazı betikler harekesiz bir harfi (الطالب’deki elif gibi) doğru bir “hareke yok” tahmini olarak sayar, bazıları atlar. Fadel puanlama betiğinde bunun için bir bayrak var.
Yayımlanmış betikler bu seçimlerde farklılaşır; bu yüzden yalnızca aynı betiğin ürettiği sayıları karşılaştırın. Bu betik okunacak kadar kısa:
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))
Örnek tahminde 32 harf ve 7 kelime içinde iki yanlış i’rab harekesi ve bir yanlış iç ünlü var. i’rab dahil DER 9.38 ve WER 42.86, hariç DER 4.0 ve WER 14.29 yazdırıyor. WER’in birkaç hatayı nasıl büyüttüğüne dikkat edin: tek bir yanlış işaret bütün bir kelimeyi bozar.
Betik, harfleri değişmiş bir kelimeyi puanlamayı reddeder. Bu bilinçli bir tercih. Harfleri düzenleyen bir hareke aracı görevi başaramamıştır ve DER değeri anlamsız olur.
İkinci bir kontrol olarak kural tabanlı bir hareke aracı olan Mishkal 0.4.1’i elle harekelediğimiz 16 kelimelik tek bir cümlede çalıştırdık. Dört hatasının dördü de i’rab harekesiydi; örneğin مُحَمَّدٌ yerine مُحَمَّدُ. i’rab dahil DER 5.88, hariç 0.0 aldı. Tek bir cümle Mishkal hakkında hiçbir şey kanıtlamaz; iki ayarı da neden raporlamanız gerektiğini gösterir.
Bir test seti oluşturmak için kendi metninizden 100 ila 200 cümle alın, anadili Arapça olan birine harekeletin, işaretleri silin ve her adayı çalıştırın. İnsan sürümünü altın standart (gold) olarak saklayın.
Özel bir hareke aracı LLM’i ne zaman geçer?
| Seçin | Ne zaman |
|---|---|
| Özel bir model (CATT, libtashkeel, Mishkal) | Yüksek hacim, sabit metin türü, katı gecikme şartı, çevrimdışı ya da cihaz üzerinde kullanım veya tasarımı gereği harfi harfine çıktı ihtiyacı |
| API üzerinden bir LLM | Düşük ya da düzensiz hacim, karışık veya dağınık girdi, ML operasyonu olmayan bir ekip ya da diğer adımlar için zaten LLM çağıran bir hat |
Özel modeller harf başına bir işaret tahmin eder; bu yüzden metninizi yeniden yazamazlar. CATT Apache 2.0 lisanslıdır ve pip install catt-tashkeel ile kurulur; README’si hız için yalnızca kodlayıcı modeli, doğruluk için kodlayıcı-kod çözücüyü öneriyor. libtashkeel MIT lisanslıdır ve ağırlıklı olarak MSA ile eğitilmiştir. Mishkal kural tabanlıdır ve GPL lisanslıdır; bir ürünün içinde dağıtacaksanız bu önemlidir.
LLM ile başlamak daha hızlıdır ve eğitilmiş bir modelin hiç görmediği girdiyle de başa çıkar: lehçe, karışık Arapça ve İngilizce, alışılmadık noktalama. Her yanıtta yukarıdaki iskelet kontrolünü gerektirir ve token başına ücretlendirilir.
LLM ile hareke eklemenin maliyeti ne?
Harekeler ek karakterlerdir ve tokenizer’lar bunları ek token’lara böler. 2.500 satırlık Fadel test setini (125.098 kelime) her modelin kendi tokenizer’ıyla, çıplak metne karşı tam harekeli metin olarak saydık:
| Tokenizer | Çıplak metin | Harekeli | Oran |
|---|---|---|---|
| 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× |
Çıplak metin için girdi token’ı, harekeli yanıt için çıktı token’ı ve varsa akıl yürütme için ödersiniz. Pahalı taraf çıktıdır: BroadNet’in fiyatlar sayfasına göre milyon token başına Qwen3.8 27B için $2.17, DeepSeek V4.1 Flash için $0.52, GLM 5.3 için $3.46 ve Gemma 4 VL 26B için $0.22. Başarısız bir kontrolden sonraki yeniden denemeler buna eklenir. Oranı kendi verinizde kontrol etmek için metninizi Arapça token sayacına yapıştırın; Arapçanın neden en baştan daha fazla token tuttuğu için bkz. Arapça ve İngilizcede kelime başına token.
Büyük bir arşiv üzerinde tek seferlik bir iş için DeepSeek V4.1 Flash planları sayacı oturum başına sabit bir fiyatla değiştirir (haftada $15 veya saatte $1); her oturum aynı anda bir istek çalıştırır, bu yüzden işi batch API olmadan toplu işleme yazısındaki gibi planlayın.
BroadNet Inference nerede devreye girer?
BroadRouter, BroadNet’in kendi sitesidir. BroadNet Inference yukarıdaki dört sohbet modelini tek bir OpenAI uyumlu uç nokta üzerinden sunar; böylece base URL ve anahtar ayarlandığında kod OpenAI Python SDK ile çalışır. Gemma 4 VL 26B $5 başlangıç kredisiyle çalışır; DeepSeek, GLM ve Qwen bakiye yükleme gerektirir. BroadNet’in hareke ekleme uç noktası yok, kendine ait bir hareke ekleme kıyaslaması yayımlamıyor ve metinden sese hizmeti yok. Modellerinden hangisinin metninize en iyi hareke eklediği ölçülmüş değil: seçmeden önce onları kendi örnekleminizde puanlayın. İstek ayrıntıları için API başvurusuna bakın.
