El árabe se escribe normalmente sin vocales cortas. El lector las deduce del contexto; el software a menudo no puede. Restaurarlas, lo que se llama diacritización o tashkeel, convierte كتب en كَتَبَ (escribió), كُتُبٌ (libros) o كُتِبَ (fue escrito), según la oración. Este artículo muestra cómo hacerlo con un LLM a través de una API compatible con OpenAI, cómo impedir que el modelo cambie su texto sin avisar y cómo medir el resultado frente a un diacritizador dedicado.
¿Cuándo necesita diacríticos?
- Texto a voz. Una voz necesita las vocales para pronunciar una palabra. El artículo de CATT cita el texto a voz y la traducción automática entre las aplicaciones que mejoran con diacríticos. BroadNet Inference no tiene endpoint de texto a voz, así que en un pipeline de TTS el texto diacritizado va a un servicio de TTS aparte.
- Estudiantes y material infantil. Quienes aún están aprendiendo a leer dependen de las marcas.
- Nombres y términos ambiguos. Nombres propios, palabras raras y términos técnicos en los que una vocal equivocada cambia el significado.
- Textos religiosos y clásicos. Aquí las marcas forman parte del texto, y una herramienta automática solo debería rellenar huecos, con revisión humana.
Para búsqueda o recuperación, normalmente no le conviene usar diacríticos. Allí se eliminan, como en normalización de texto árabe para búsqueda. El normalizador de texto árabe gratuito hace esa eliminación en el navegador. La diacritización es la operación contraria y mucho más difícil: quitar marcas es una consulta en una tabla, mientras que añadirlas requiere gramática y contexto.
¿Qué tan buenos son los LLM diacritizando?
Dos cifras publicadas, que conviene leer con cuidado:
| Sistema | Benchmark de CATT, DER con terminaciones de caso | DER sin ellas | WER con terminaciones de caso | WER sin ellas |
|---|---|---|---|---|
| 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 según el texto del artículo) | 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% |
Fuente: tabla 4 del artículo de CATT (2024). Menos es mejor. El benchmark son 742 oraciones de noticias recopiladas en 2023, diacritizadas por dos expertos nativos y revisadas por un tercero.
En el segundo conjunto de prueba del artículo, WikiNews (400 oraciones), GPT-4 obtuvo un resultado muy superior al de todos los demás: 0.551% de DER. Los autores marcan esa fila y sugieren que el modelo pudo haber visto WikiNews durante el entrenamiento. Es la advertencia general de los benchmarks de LLM: el texto de prueba público puede estar en los datos de entrenamiento. Los autores de CATT plantean la misma duda sobre Tashkeela, cuyos libros contienen muchas citas del Corán y de hadices.
Un artículo distinto de 2024, de Skiredj y Berrada, reporta para GPT-4 cerca de un 20% de DER y un 30% de WER en el benchmark de Fadel et al., sin el detalle que haría falta para compararlo con la tabla anterior.
Así que los modelos de la clase de GPT-4 pueden acercarse a un diacritizador dedicado, y también pueden quedar por detrás. Ambos artículos son anteriores a los modelos abiertos que puede llamar hoy. Mida con su propio texto.
¿Qué conjuntos de prueba existen?
| Conjunto de datos | Qué es |
|---|---|
| Tashkeela | 75,629,921 palabras totalmente vocalizadas de 97 libros; 98.85% árabe clásico de la biblioteca Shamela y 1.15% árabe estándar moderno |
| Benchmark de Fadel et al. | Unos 2.3M de palabras extraídas de Tashkeela; 50,000 líneas de entrenamiento, 2,500 de validación y 2,500 de prueba |
| Benchmark de CATT | 742 oraciones de noticias diacritizadas a mano, publicadas con los modelos de CATT |
| WikiNews | 400 oraciones de noticias en MSA diacritizadas a mano |
Tashkeela y el conjunto de Fadel son mayoritariamente clásicos. Si su texto es árabe moderno de negocios o de noticias, los conjuntos de CATT y WikiNews se parecen más, y una muestra de su propio texto es lo más cercano.
¿Qué prompt mantiene intactas las letras?
El trabajo del modelo es añadir marcas y no tocar nada más. A los LLM les gusta ayudar: corregirán الى a إلى, cambiarán una ى final por ي o añadirán una hamza que falta. Cada cambio puede ser árabe correcto, pero es una corrección ortográfica, no una diacritización. Cambia su texto sin decírselo.
Por eso el prompt enuncia la regla y el código la hace cumplir: elimine los diacríticos de la respuesta y compárela con la entrada también sin diacríticos. Si difiere una sola letra, espacio o signo de puntuación, la respuesta se rechaza.
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))
Lo ejecutamos contra un servidor simulado local, no contra la API real. Su respuesta predefinida para la primera oración “corrigió” الى a إلى en ambos intentos, y la respuesta para la segunda fue limpia. La salida fue:
attempt 1: letters changed ['- الى', '+ إلى']
attempt 2: letters changed ['- الى', '+ إلى']
None
قَرَأَ مُحَمَّدٌ الْكِتَابَ
Notas sobre el código:
- Primero, Unicode NFC. Una hamza puede llegar como un único carácter precompuesto (أ) o como una letra más una marca combinante. NFC deja ambos lados iguales antes de comparar. El artículo sobre normalización trata esta trampa en detalle.
max_tokens=4000. La documentación de BroadNet indica que DeepSeek V4.1 Flash, GLM 5.3 y Qwen3.8 27B razonan antes de responder, y que el razonamiento cuenta paramax_tokens. Un límite demasiado bajo devuelve una respuesta vacía, que el control rechaza. Deje margen o configurereasoning_efforten low; consulte respuestas vacías de los modelos de razonamiento y la calculadora de presupuesto de tokens de razonamiento.- El control no verifica “conservar los diacríticos existentes”. Si su entrada está parcialmente diacritizada, compare también esas marcas.
- La ortografía es una decisión aparte. Si quiere que se corrija الى, ejecute primero un paso de corrección y luego diacritice el texto corregido. Mezclar ambos hace imposible verificar cualquiera de los dos.
- Divida el texto largo. Envíe una oración o un párrafo por solicitud. CATT limita la entrada a 1,024 caracteres y divide las oraciones largas en los signos de puntuación; el mismo hábito mantiene cortas las respuestas del LLM y baratos los reintentos.
Para consejos generales sobre prompts en árabe, incluido cuándo indicar al modelo que no añada diacríticos, consulte ingeniería de prompts para árabe.
¿Cómo se evalúa la diacritización: DER y WER?
La tasa de error de diacríticos (DER) es la proporción de letras cuyos diacríticos difieren de la referencia. La tasa de error de palabras (WER), aquí, es la proporción de palabras con al menos un diacrítico incorrecto. No es el WER del reconocimiento de voz de nuestro artículo sobre ASR: cuenta palabras con una marca incorrecta, no palabras insertadas o eliminadas.
Dos ajustes cambian mucho las cifras:
- Con o sin terminaciones de caso. La última letra de una palabra lleva su caso gramatical (i’rab), que depende de la sintaxis. Los artículos reportan ambos ajustes, porque las terminaciones de caso causan muchos de los errores.
- Contar las letras sin diacrítico. Algunos scripts cuentan una letra sin marca (como el alef de الطالب) como una predicción correcta de “sin diacrítico”; otros la omiten. El script de evaluación de Fadel tiene una opción para esto.
Los scripts publicados difieren en estas decisiones, así que compare solo cifras producidas por el mismo script. Este es lo bastante corto para leerlo:
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 predicción de juguete tiene dos terminaciones de caso incorrectas y una vocal interna incorrecta en 32 letras y 7 palabras. Imprime DER 9.38 y WER 42.86 con terminaciones de caso, y DER 4.0 y WER 14.29 sin ellas. Observe cómo el WER magnifica unos pocos errores: una sola marca equivocada estropea una palabra entera.
El script se niega a evaluar una palabra cuyas letras cambiaron. Es deliberado. Un diacritizador que edita letras ha fallado en la tarea, y su DER no significaría nada.
Como segunda comprobación, ejecutamos Mishkal 0.4.1, un diacritizador basado en reglas, sobre una oración de 16 palabras que diacritizamos a mano. Sus cuatro errores fueron todos terminaciones de caso, como مُحَمَّدُ en lugar de مُحَمَّدٌ. Obtuvo DER 5.88 con terminaciones de caso y 0.0 sin ellas. Una oración no demuestra nada sobre Mishkal; muestra por qué conviene reportar ambos ajustes.
Para crear un conjunto de prueba, tome de 100 a 200 oraciones de su propio texto, pida a un hablante nativo que las diacritice, elimine las marcas y ejecute cada candidato. Conserve la versión humana como referencia.
¿Cuándo supera un diacritizador dedicado a un LLM?
| Elija | Cuando |
|---|---|
| Un modelo dedicado (CATT, libtashkeel, Mishkal) | Volumen alto, tipo de texto fijo, latencia estricta, uso sin conexión o en el dispositivo, o necesidad de una salida letra por letra por diseño |
| Un LLM a través de una API | Volumen bajo o irregular, entrada mixta o desordenada, un equipo sin MLOps, o un pipeline que ya llama a un LLM para otros pasos |
Los modelos dedicados predicen una marca por letra, así que no pueden reescribir su texto. CATT tiene licencia Apache 2.0 y se instala con pip install catt-tashkeel; su README recomienda el modelo encoder-only por velocidad y el encoder-decoder por precisión. libtashkeel tiene licencia MIT y se entrenó principalmente con MSA. Mishkal se basa en reglas y tiene licencia GPL, lo que importa si lo incluye dentro de un producto.
Un LLM permite empezar más rápido y se las arregla con entradas que un modelo entrenado nunca vio: dialecto, árabe mezclado con inglés, puntuación extraña. Necesita el control de esqueleto anterior en cada respuesta, y cobra por token.
¿Cuánto cuesta diacritizar con un LLM?
Los diacríticos son caracteres adicionales, y los tokenizadores los dividen en tokens adicionales. Contamos el conjunto de prueba de Fadel, de 2,500 líneas (125,098 palabras), con el tokenizador de cada modelo, texto sin marcas frente a texto totalmente diacritizado:
| Tokenizador | Texto sin marcas | Diacritizado | Proporción |
|---|---|---|---|
| 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× |
Usted paga tokens de entrada por el texto sin marcas y tokens de salida por la respuesta diacritizada, más el razonamiento que haya. La salida es la parte cara: $2.17 por millón de tokens en Qwen3.8 27B, $0.52 en DeepSeek V4.1 Flash, $3.46 en GLM 5.3 y $0.22 en Gemma 4 VL 26B, según la página de precios de BroadNet. Los reintentos tras un control fallido suman más. Pegue su propio texto en el contador de tokens en árabe para comprobar la proporción con sus datos, y consulte tokens por palabra en árabe e inglés para saber por qué el árabe cuesta más tokens de partida.
Para un trabajo puntual sobre un archivo grande, los planes de DeepSeek V4.1 Flash sustituyen el medidor por un precio fijo por sesión ($15 a la semana o $1 la hora); cada sesión ejecuta una solicitud a la vez, así que planifique la ejecución como en procesamiento por lotes sin una Batch API.
Dónde encaja BroadNet Inference
BroadRouter es el sitio de la propia BroadNet. BroadNet Inference sirve los cuatro modelos de chat anteriores a través de un único endpoint compatible con OpenAI, así que el código funciona con el SDK de OpenAI para Python una vez configuradas la URL base y la clave. Gemma 4 VL 26B funciona con el crédito inicial de $5; DeepSeek, GLM y Qwen requieren una recarga. BroadNet no tiene endpoint de diacritización, no publica un benchmark propio de diacritización y no ofrece texto a voz. Cuál de sus modelos diacritiza mejor su texto no se ha medido: evalúelos con su propia muestra antes de elegir. Consulte la referencia de la API para los detalles de las solicitudes.
