BroadRouter

Diacríticos no árabe com um LLM: prompt, checagens e DER

Pela equipe da BroadNet Inference · 8 min de leitura · Publicado em · Atualizado em

Peça ao modelo o tashkeel completo e nada mais, depois remova os diacríticos da resposta e compare com a sua entrada. Se qualquer letra mudou, rejeite e tente de novo. Avalie uma amostra revisada à mão com diacritic error rate (DER) e word error rate (WER), com e sem as terminações de caso. Os resultados publicados colocam o GPT-4 perto dos melhores diacritizadores dedicados, mas atrás deles.

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 para max_tokens. Um limite pequeno demais devolve uma resposta vazia, que a checagem rejeita. Deixe folga ou defina reasoning_effort como 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.

Perguntas frequentes

Como adicionar diacríticos a um texto em árabe com Python?

Há dois caminhos. Instale um diacritizador dedicado, como catt-tashkeel (Apache 2.0) ou mishkal (GPL), e rode localmente, ou envie o texto a um LLM com um prompt que peça só o tashkeel. Com um LLM, sempre confira se a resposta sem diacríticos é igual à sua entrada.

O ChatGPT ou o GPT-4 são bons em diacritizar árabe?

Ficam perto dos melhores sistemas dedicados em alguns testes e atrás deles em outros. O artigo do CATT mediu o GPT-4 com 9,515% de DER com terminações de caso no seu benchmark de notícias, contra 8,624% do próprio modelo. Outro artigo de 2024 informa cerca de 20% de DER para o GPT-4 no benchmark de Fadel. Teste no seu próprio texto.

Qual a diferença entre DER e WER na diacritização?

O DER é a proporção de letras com diacríticos errados. O WER é a proporção de palavras com pelo menos um diacrítico errado, por isso é sempre maior. Os dois são informados com as terminações de caso (a última letra de cada palavra) e sem elas.

Por que meu LLM muda letras quando adiciona o tashkeel?

Porque ele também corrige a ortografia: الى vira إلى, um ى vira ي, aparece uma hamza que faltava. Pode até estar certo, mas é correção, não diacritização, e quebra a avaliação letra a letra. Peça para não fazer isso, confira cada resposta e, se quiser a correção, rode-a como etapa separada.

A BroadNet consegue ler em voz alta o texto com diacríticos?

Não. A BroadNet Inference não tem endpoint de texto para fala (text-to-speech). Ela oferece modelos de chat e fala para texto. Se a diacritização é a primeira etapa de um pipeline de TTS, envie o resultado para um serviço de TTS separado.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity