BroadRouter

Aggiungere i diacritici all’arabo con un LLM: prompt, controlli, DER

A cura del team di BroadNet Inference · 8 min di lettura · Pubblicato · Aggiornato

Chiedi al modello il tashkeel completo e nient’altro, poi togli i diacritici dalla risposta e confrontala con il tuo input. Se cambia anche una lettera, scarta e riprova. Valuta un campione controllato a mano con il diacritic error rate (DER) e il word error rate (WER), con e senza desinenze di caso. I risultati pubblicati mettono GPT-4 vicino ai migliori diacritizzatori dedicati, ma dietro.

L’arabo si scrive di norma senza vocali brevi. Chi legge le ricava dal contesto; il software spesso no. Ripristinarle, la cosiddetta diacritizzazione o tashkeel, trasforma كتب in كَتَبَ (ha scritto), كُتُبٌ (libri) o كُتِبَ (è stato scritto), a seconda della frase. Questo articolo mostra come farlo con un LLM tramite un’API compatibile con OpenAI, come impedire al modello di modificare il tuo testo di nascosto e come misurare il risultato rispetto a un diacritizzatore dedicato.

Quando servono i diacritici?

  • Sintesi vocale (text-to-speech). Una voce ha bisogno delle vocali per pronunciare una parola. Il paper CATT indica sintesi vocale e traduzione automatica tra le applicazioni che i diacritici migliorano. BroadNet Inference non ha un endpoint di sintesi vocale, quindi in una pipeline TTS il testo con diacritici va a un servizio TTS separato.
  • Studenti e materiale per bambini. Chi sta ancora imparando a leggere si affida ai segni.
  • Nomi e termini ambigui. Nomi propri, parole rare e termini tecnici, dove una vocale sbagliata cambia il significato.
  • Testi religiosi e classici. Qui i segni fanno parte del testo, e uno strumento automatico dovrebbe solo colmare le lacune, sotto revisione umana.

Per la ricerca o il retrieval, di solito i diacritici non li vuoi. Lì si tolgono, come in normalizzazione del testo arabo per la ricerca. Il normalizzatore di testo arabo gratuito li toglie direttamente nel browser. La diacritizzazione è l’operazione opposta, e molto più difficile: togliere i segni è una ricerca in tabella, aggiungerli richiede grammatica e contesto.

Quanto sono bravi gli LLM nella diacritizzazione?

Due numeri pubblicati, da leggere con attenzione:

Sistema Benchmark CATT, DER con desinenze di caso DER senza WER con desinenze di caso WER senza
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 secondo il testo del 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%

Fonte: tabella 4 del paper CATT (2024). Più basso è meglio. Il benchmark è composto da 742 frasi di notizie raccolte nel 2023, diacritizzate da due esperti madrelingua e verificate da un terzo.

Sul secondo test set del paper, WikiNews (400 frasi), GPT-4 ha fatto molto meglio di tutti gli altri: 0,551% di DER. Gli autori segnalano quella riga e ipotizzano che il modello abbia visto WikiNews durante l’addestramento. È l’avvertenza generale per i benchmark sugli LLM: il testo di test pubblico può essere nei dati di addestramento. Gli autori di CATT sollevano lo stesso dubbio su Tashkeela, i cui libri contengono molte citazioni dal Corano e dagli hadith.

Un altro paper del 2024, di Skiredj e Berrada, riporta per GPT-4 circa il 20% di DER e il 30% di WER sul benchmark di Fadel et al., senza i dettagli che servirebbero per confrontarlo con la tabella qui sopra.

Quindi i modelli della classe di GPT-4 possono avvicinarsi a un diacritizzatore dedicato, ma possono anche restare indietro. Entrambi i paper precedono i modelli open che puoi chiamare oggi. Misura sul tuo testo.

Quali test set esistono?

Dataset Cos’è
Tashkeela 75.629.921 parole completamente vocalizzate da 97 libri; 98,85% arabo classico dalla biblioteca Shamela, 1,15% arabo standard moderno
Benchmark di Fadel et al. Circa 2,3 milioni di parole estratte da Tashkeela; 50.000 righe di addestramento, 2.500 di validazione e 2.500 di test
Benchmark CATT 742 frasi di notizie diacritizzate a mano, rilasciate con i modelli CATT
WikiNews 400 frasi di notizie in MSA diacritizzate a mano

Tashkeela e il set di Fadel sono soprattutto arabo classico. Se il tuo testo è arabo moderno commerciale o giornalistico, i set CATT e WikiNews sono più vicini, e un campione del tuo testo lo è ancora di più.

Quale prompt lascia intatte le lettere?

Il compito del modello è aggiungere segni e non toccare nient’altro. Gli LLM amano rendersi utili: correggono الى in إلى, cambiano una ى finale in ي o aggiungono una hamza mancante. Ognuna di queste modifiche può essere arabo corretto, ma è una correzione ortografica, non una diacritizzazione. Cambia il tuo testo senza dirtelo.

Per questo il prompt enuncia la regola e il codice la fa rispettare: togli i diacritici dalla risposta e confrontala con l’input, anch’esso senza diacritici. Se differisce anche solo una lettera, uno spazio o un segno di punteggiatura, la risposta viene scartata.

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))

Abbiamo eseguito il codice contro un server mock locale, non contro l’API reale. La sua risposta preimpostata per la prima frase «correggeva» الى in إلى in entrambi i tentativi, mentre la risposta per la seconda era pulita. L’output è stato:

attempt 1: letters changed ['- الى', '+ إلى']
attempt 2: letters changed ['- الى', '+ إلى']
None
قَرَأَ مُحَمَّدٌ الْكِتَابَ

Note sul codice:

  • Prima la normalizzazione Unicode NFC. Una hamza può arrivare come un unico carattere precomposto (أ) o come lettera più segno combinante. NFC rende uguali i due lati prima del confronto. L’articolo sulla normalizzazione tratta questa trappola nel dettaglio.
  • max_tokens=4000. Secondo la documentazione di BroadNet, DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il ragionamento conta in max_tokens. Un limite troppo basso restituisce una risposta vuota, che il controllo scarta. Lascia margine, oppure imposta reasoning_effort su low; vedi risposte vuote dai modelli di ragionamento e il calcolatore del budget di token di ragionamento.
  • Il controllo non verifica «mantieni i diacritici già presenti». Se il tuo input è in parte già diacritizzato, confronta anche quei segni.
  • L’ortografia è una decisione a parte. Se vuoi che الى venga corretto, esegui prima un passaggio di correzione e poi diacritizza il testo corretto. Mescolare le due cose le rende entrambe impossibili da verificare.
  • Dividi i testi lunghi. Manda una frase o un paragrafo per richiesta. CATT stesso limita l’input a 1.024 caratteri e spezza le frasi lunghe sulla punteggiatura; la stessa abitudine mantiene brevi le risposte dell’LLM ed economici i nuovi tentativi.

Per consigli generali su come scrivere prompt in arabo, incluso quando dire a un modello di non aggiungere diacritici, vedi prompt engineering in arabo.

Come si valuta la diacritizzazione: DER e WER?

Il diacritic error rate (DER) è la quota di lettere i cui diacritici differiscono dal riferimento. Il word error rate (WER), qui, è la quota di parole con almeno un diacritico sbagliato. Non è il WER del riconoscimento vocale di il nostro articolo sull’ASR: conta le parole con un segno sbagliato, non le parole inserite o cancellate.

Due impostazioni cambiano molto i numeri:

  • Con o senza desinenze di caso. L’ultima lettera di una parola porta il suo caso grammaticale (i‘rab), che dipende dalla sintassi. I paper riportano entrambe le impostazioni, perché le desinenze di caso causano molti degli errori.
  • Contare o no le lettere senza diacritico. Alcuni script contano una lettera nuda (come l’alef in الطالب) come previsione corretta di «nessun diacritico», altri la saltano. Lo script di valutazione di Fadel ha un flag apposta.

Gli script pubblicati fanno scelte diverse su questi punti, quindi confronta solo numeri prodotti dallo stesso script. Questo è abbastanza breve da leggerlo tutto:

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))

La previsione giocattolo ha due desinenze di caso sbagliate e una vocale interna sbagliata, su 32 lettere e 7 parole. Stampa DER 9.38 e WER 42.86 con desinenze di caso, e DER 4.0 e WER 14.29 senza. Nota come il WER ingigantisce pochi errori: un solo segno sbagliato rovina un’intera parola.

Lo script si rifiuta di valutare una parola le cui lettere sono cambiate. È voluto. Un diacritizzatore che modifica le lettere ha fallito il compito, e il suo DER non avrebbe senso.

Come seconda verifica abbiamo eseguito Mishkal 0.4.1, un diacritizzatore a regole, su una frase di 16 parole che avevamo diacritizzato a mano. Tutti e quattro i suoi errori erano desinenze di caso, come مُحَمَّدُ al posto di مُحَمَّدٌ. Ha ottenuto DER 5,88 con desinenze di caso e 0,0 senza. Una frase non dimostra nulla su Mishkal; mostra perché vanno riportate entrambe le impostazioni.

Per costruire un test set, prendi da 100 a 200 frasi del tuo testo, falle diacritizzare a un madrelingua, togli i segni ed esegui ogni candidato. Tieni la versione umana come riferimento (gold).

Quando un diacritizzatore dedicato batte un LLM?

Scegli Quando
Un modello dedicato (CATT, libtashkeel, Mishkal) Grandi volumi, tipo di testo fisso, latenza stringente, uso offline o on-device, oppure serve un output che per costruzione non cambi nessuna lettera
Un LLM tramite API Volumi bassi o irregolari, input misto o disordinato, un team senza MLOps, oppure una pipeline che chiama già un LLM per altri passaggi

I modelli dedicati prevedono un segno per lettera, quindi non possono riscrivere il tuo testo. CATT è Apache 2.0 e si installa con pip install catt-tashkeel; il suo README consiglia il modello encoder-only per la velocità e l’encoder-decoder per l’accuratezza. libtashkeel è MIT ed è addestrato soprattutto su MSA. Mishkal è basato su regole e GPL, e questo conta se lo distribuisci dentro un prodotto.

Un LLM è il modo più rapido per partire e se la cava con input che un modello addestrato non ha mai visto: dialetto, arabo e inglese mescolati, punteggiatura strana. Richiede il controllo dello scheletro visto sopra su ogni risposta, e si paga a token.

Quanto costa diacritizzare con un LLM?

I diacritici sono caratteri in più, e i tokenizer li spezzano in token in più. Abbiamo contato il test set di Fadel da 2.500 righe (125.098 parole) con il tokenizer di ciascun modello, testo nudo contro testo completamente diacritizzato:

Tokenizer Testo nudo Con diacritici Rapporto
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×

Paghi token di input per il testo nudo e token di output per la risposta diacritizzata, più l’eventuale ragionamento. L’output è la parte costosa: $2.17 per milione di token su Qwen3.8 27B, $0.52 su DeepSeek V4.1 Flash, $3.46 su GLM 5.3 e $0.22 su Gemma 4 VL 26B, secondo la pagina prezzi di BroadNet. I nuovi tentativi dopo un controllo fallito aggiungono altro. Incolla il tuo testo nel contatore di token per l’arabo per verificare il rapporto sui tuoi dati, e vedi token per parola in arabo e in inglese per capire perché l’arabo costa più token già in partenza.

Per un lavoro una tantum su un grande archivio, i piani DeepSeek V4.1 Flash sostituiscono il contatore con un prezzo fisso per sessione ($15 a settimana o $1 all’ora); ogni sessione esegue una richiesta alla volta, quindi pianifica l’elaborazione come in elaborazione in batch senza una batch API.

Dove si colloca BroadNet Inference

BroadRouter è il sito di BroadNet. BroadNet Inference serve i quattro modelli di chat qui sopra tramite un unico endpoint compatibile con OpenAI, quindi il codice funziona con l’SDK Python di OpenAI una volta impostati base URL e chiave. Gemma 4 VL 26B funziona con il credito iniziale di $5; DeepSeek, GLM e Qwen richiedono una ricarica. BroadNet non ha un endpoint di diacritizzazione, non pubblica un proprio benchmark di diacritizzazione e non offre sintesi vocale. Quale dei suoi modelli diacritizzi meglio il tuo testo non è stato misurato: valutali su un tuo campione prima di scegliere. Vedi il riferimento API per i dettagli delle richieste.

Domande frequenti

Come si aggiungono i diacritici a un testo arabo in Python?

Due strade. Installi un diacritizzatore dedicato come catt-tashkeel (Apache 2.0) o mishkal (GPL) e lo chiami in locale, oppure mandi il testo a un LLM con un prompt che chiede solo il tashkeel. Con un LLM, controlla sempre che la risposta senza diacritici sia uguale al tuo input.

ChatGPT o GPT-4 sono bravi a mettere i diacritici in arabo?

Vicini ai migliori sistemi dedicati in alcuni test, dietro in altri. Il paper CATT ha misurato GPT-4 a 9,515% di DER con desinenze di caso sul suo benchmark di notizie, contro 8,624% del proprio modello. Un altro paper del 2024 riporta per GPT-4 circa il 20% di DER sul benchmark di Fadel. Fai la prova sul tuo testo.

Che differenza c’è tra DER e WER nella diacritizzazione?

Il DER è la quota di lettere con i diacritici sbagliati. Il WER è la quota di parole con almeno un diacritico sbagliato, quindi è sempre più alto. Entrambi si riportano con le desinenze di caso (l’ultima lettera di ogni parola) e senza.

Perché il mio LLM cambia le lettere quando aggiunge il tashkeel?

Perché corregge anche l’ortografia: الى diventa إلى, una ى diventa ي, compare una hamza mancante. Può essere giusto, ma è una correzione, non una diacritizzazione, e rompe la valutazione lettera per lettera. Chiedigli di non farlo, controlla ogni risposta e, se vuoi la correzione, falla in un passaggio separato.

BroadNet può leggere ad alta voce il testo con diacritici?

No. BroadNet Inference non ha un endpoint di sintesi vocale (text-to-speech). Offre modelli di chat e speech-to-text. Se la diacritizzazione è il primo stadio di una pipeline TTS, manda il risultato a un servizio TTS separato.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity