O árabe normalmente é escrito sem as vogais curtas. Quem lê as deduz pelo contexto; o software muitas vezes não consegue. Restaurá-las, o que se chama diacritização ou tashkeel, transforma كتب em كَتَبَ (ele escreveu), كُتُبٌ (livros) ou كُتِبَ (foi escrito), dependendo da frase. Este post mostra como fazer isso com um LLM por meio de uma API compatível com a OpenAI, como impedir que o modelo altere seu texto sem avisar e como medir o resultado contra um diacritizador dedicado.
Quando você precisa de diacríticos?
- Texto para fala (text-to-speech). Uma voz precisa das vogais para pronunciar a palavra. O artigo do CATT cita texto para fala e tradução automática entre as aplicações que os diacríticos melhoram. A BroadNet Inference não tem endpoint de texto para fala, então, num pipeline de TTS, o texto com diacríticos vai para um serviço de TTS separado.
- Estudantes e material infantil. Quem ainda está aprendendo a ler depende das marcas.
- Nomes e termos ambíguos. Nomes próprios, palavras raras e termos técnicos, em que uma vogal errada muda o sentido.
- Textos religiosos e clássicos. Aqui as marcas fazem parte do texto, e uma ferramenta automática só deve preencher lacunas, com revisão humana.
Para busca ou recuperação, em geral você não quer diacríticos. Lá eles são removidos, como em normalização de texto em árabe para busca. O normalizador de texto em árabe gratuito faz essa remoção no navegador. A diacritização é a operação inversa, e bem mais difícil: remover marcas é uma consulta a uma tabela, enquanto adicioná-las exige gramática e contexto.
Quão bons são os LLMs em diacritização?
Dois números publicados, para ler com cuidado:
| Sistema | Benchmark do CATT, DER com terminações de caso | DER sem | WER com terminações de caso | WER sem |
|---|---|---|---|---|
| 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, segundo o texto do artigo) | 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: Tabela 4 do artigo do CATT (2024). Quanto menor, melhor. O benchmark tem 742 frases de notícias coletadas em 2023, diacritizadas por dois especialistas nativos e conferidas por um terceiro.
No segundo conjunto de teste do artigo, o WikiNews (400 frases), o GPT-4 foi muito melhor que todos os outros: 0,551% de DER. Os autores destacam essa linha e sugerem que o modelo pode ter visto o WikiNews no treinamento. Esse é o alerta geral para benchmarks de LLM: textos de teste públicos podem estar nos dados de treinamento. Os autores do CATT levantam a mesma suspeita sobre o Tashkeela, cujos livros contêm muitas citações do Alcorão e de hadiths.
Um outro artigo de 2024, de Skiredj e Berrada, informa cerca de 20% de DER e 30% de WER para o GPT-4 no benchmark de Fadel et al., sem os detalhes de que precisaríamos para compará-lo com a tabela acima.
Ou seja: modelos da classe do GPT-4 podem chegar perto de um diacritizador dedicado, mas também podem ficar atrás. Os dois artigos são anteriores aos modelos abertos que você consegue chamar hoje. Meça no seu próprio texto.
Quais conjuntos de teste existem?
| Dataset | O que é |
|---|---|
| Tashkeela | 75.629.921 palavras totalmente vocalizadas de 97 livros; 98,85% árabe clássico da biblioteca Shamela, 1,15% árabe padrão moderno |
| Benchmark de Fadel et al. | Cerca de 2,3 milhões de palavras extraídas do Tashkeela; 50.000 linhas de treino, 2.500 de validação e 2.500 de teste |
| Benchmark do CATT | 742 frases de notícias diacritizadas à mão, publicadas junto com os modelos do CATT |
| WikiNews | 400 frases de notícias em MSA diacritizadas à mão |
O Tashkeela e o conjunto de Fadel são majoritariamente clássicos. Se o seu texto é árabe moderno de negócios ou de notícias, os conjuntos do CATT e do WikiNews estão mais próximos, e uma amostra do seu próprio texto está mais próxima ainda.
Que prompt preserva as letras?
A tarefa do modelo é adicionar marcas e não mexer em mais nada. LLMs gostam de ajudar: corrigem الى para إلى, trocam um ى final por ي ou adicionam uma hamza que faltava. Cada uma dessas mudanças pode ser árabe correto, mas é correção ortográfica, não diacritização. Ela altera seu texto sem avisar.
Por isso o prompt declara a regra e o código a garante: remova os diacríticos da resposta e compare com a entrada, também sem diacríticos. Se uma única letra, espaço ou sinal de pontuação for diferente, a resposta é rejeitada.
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))
Rodamos isso contra um servidor mock local, não contra a API real. A resposta pronta para a primeira frase “corrigia” الى para إلى nas duas tentativas, e a resposta para a segunda veio limpa. A saída foi:
attempt 1: letters changed ['- الى', '+ إلى']
attempt 2: letters changed ['- الى', '+ إلى']
None
قَرَأَ مُحَمَّدٌ الْكِتَابَ
Observações sobre o código:
- Primeiro, Unicode NFC. Uma hamza pode chegar como um único caractere pré-composto (أ) ou como letra mais uma marca combinante. O NFC deixa os dois lados iguais antes da comparação. O post sobre normalização trata dessa armadilha em detalhe.
max_tokens=4000. A documentação da BroadNet diz que DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e que o raciocínio conta paramax_tokens. Um limite pequeno demais devolve uma resposta vazia, que a checagem rejeita. Deixe folga ou definareasoning_effortcomo low; veja respostas vazias de modelos de raciocínio e a calculadora de orçamento de tokens de raciocínio.- A checagem não testa “mantenha os diacríticos existentes”. Se a sua entrada já vem parcialmente diacritizada, compare também essas marcas.
- Ortografia é uma decisão à parte. Se você quer الى corrigido, rode antes uma etapa de correção e depois diacritize o texto corrigido. Misturar as duas coisas torna ambas impossíveis de verificar.
- Divida textos longos. Envie uma frase ou um parágrafo por requisição. O próprio CATT limita a entrada a 1.024 caracteres e quebra frases longas na pontuação; o mesmo hábito mantém curtas as respostas do LLM e baratas as novas tentativas.
Para dicas gerais sobre prompts em árabe, inclusive quando dizer a um modelo para não adicionar diacríticos, veja engenharia de prompt em árabe.
Como avaliar a diacritização: DER e WER?
O diacritic error rate (DER) é a proporção de letras cujos diacríticos diferem da referência. O word error rate (WER), aqui, é a proporção de palavras com pelo menos um diacrítico errado. Não é o WER de reconhecimento de fala do nosso post sobre ASR: ele conta palavras com uma marca errada, não palavras inseridas ou apagadas.
Duas configurações mudam muito os números:
- Com ou sem terminações de caso. A última letra de uma palavra carrega o caso gramatical (i‘rab), que depende da sintaxe. Os artigos informam as duas configurações, porque as terminações de caso respondem por muitos dos erros.
- Contar ou não letras sem diacrítico. Alguns scripts contam uma letra sem marca (como o alef em الطالب) como previsão correta de “nenhum diacrítico”; outros a ignoram. O script de avaliação de Fadel tem uma flag para isso.
Os scripts publicados fazem escolhas diferentes nesses pontos, então só compare números produzidos pelo mesmo script. Este é curto o bastante para ler inteiro:
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))
A previsão de brinquedo tem duas terminações de caso erradas e uma vogal interna errada, em 32 letras e 7 palavras. Ela imprime DER 9.38 e WER 42.86 com terminações de caso, e DER 4.0 e WER 14.29 sem. Note como o WER amplia poucos erros: uma única marca errada estraga a palavra inteira.
O script se recusa a avaliar uma palavra cujas letras mudaram. Isso é proposital. Um diacritizador que edita letras falhou na tarefa, e o DER dele não teria sentido.
Como segunda checagem, rodamos o Mishkal 0.4.1, um diacritizador baseado em regras, numa frase de 16 palavras que diacritizamos à mão. Todos os seus quatro erros foram terminações de caso, como مُحَمَّدُ no lugar de مُحَمَّدٌ. Ele marcou DER 5,88 com terminações de caso e 0,0 sem. Uma frase não prova nada sobre o Mishkal; mostra por que você deve informar as duas configurações.
Para montar um conjunto de teste, pegue de 100 a 200 frases do seu próprio texto, peça a um falante nativo que as diacritize, remova as marcas e rode cada candidato. Guarde a versão humana como referência (gold).
Quando um diacritizador dedicado ganha de um LLM?
| Escolha | Quando |
|---|---|
| Um modelo dedicado (CATT, libtashkeel, Mishkal) | Alto volume, tipo de texto fixo, latência rígida, uso offline ou no dispositivo, ou necessidade de uma saída que, por construção, não mude nenhuma letra |
| Um LLM via API | Volume baixo ou irregular, entrada mista ou bagunçada, um time sem MLOps, ou um pipeline que já chama um LLM em outras etapas |
Modelos dedicados preveem uma marca por letra, então não conseguem reescrever seu texto. O CATT é Apache 2.0 e se instala com pip install catt-tashkeel; o README recomenda o modelo encoder-only pela velocidade e o encoder-decoder pela precisão. O libtashkeel é MIT e treinado principalmente em MSA. O Mishkal é baseado em regras e GPL, o que importa se você o distribuir dentro de um produto.
Um LLM é o começo mais rápido e lida com entradas que um modelo treinado nunca viu: dialeto, árabe misturado com inglês, pontuação estranha. Ele exige a checagem de esqueleto acima em toda resposta, e cobra por token.
Quanto custa diacritizar com um LLM?
Diacríticos são caracteres extras, e os tokenizadores os quebram em tokens extras. Contamos o conjunto de teste de Fadel, com 2.500 linhas (125.098 palavras), com o tokenizador de cada modelo, texto sem marcas contra texto totalmente diacritizado:
| Tokenizador | Sem marcas | Com diacríticos | Proporção |
|---|---|---|---|
| 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× |
Você paga tokens de entrada pelo texto sem marcas e tokens de saída pela resposta diacritizada, mais o raciocínio, se houver. A saída é o lado caro: $2.17 por milhão de tokens no Qwen3.8 27B, $0.52 no DeepSeek V4.1 Flash, $3.46 no GLM 5.3 e $0.22 no Gemma 4 VL 26B, segundo a página de preços da BroadNet. Novas tentativas após uma checagem que falhou somam mais. Cole seu próprio texto no contador de tokens para árabe para conferir a proporção nos seus dados, e veja tokens por palavra em árabe e inglês para entender por que o árabe já parte custando mais tokens.
Para um trabalho pontual sobre um grande acervo, os planos do DeepSeek V4.1 Flash trocam o medidor por um preço fixo por sessão ($15 por semana ou $1 por hora); cada sessão executa uma requisição por vez, então planeje a execução como em processamento em lote sem uma batch API.
Onde a BroadNet Inference entra
O BroadRouter é o site da própria BroadNet. A BroadNet Inference serve os quatro modelos de chat acima por um único endpoint compatível com a OpenAI, então o código roda com o SDK Python da OpenAI depois de configurar a base URL e a chave. O Gemma 4 VL 26B roda com o crédito inicial de $5; DeepSeek, GLM e Qwen exigem uma recarga. A BroadNet não tem endpoint de diacritização, não publica benchmark próprio de diacritização e não tem texto para fala. Qual dos seus modelos diacritiza melhor o seu texto não foi medido: avalie-os numa amostra sua antes de escolher. Veja a referência da API para os detalhes das requisições.
