A extração de entidades nomeadas transforma um parágrafo em registros que seu código pode usar: quem, qual organização, onde e quando. O árabe acrescenta quatro problemas que pipelines em inglês raramente encontram: diacríticos opcionais, várias grafias para a mesma letra, nomes escritos em letras latinas (Arabizi) e datas em dois calendários. Este post monta uma etapa de extração em um LLM compatível com a OpenAI que trata cada um desses problemas no código, e um script de avaliação que diz se ela funciona no seu texto.
Para classificar mensagens inteiras em vez de extrair trechos delas, veja classificação de texto em árabe. Para as opções de requisição JSON em si, veja JSON mode vs json_schema.
Os LLMs são bons em NER em árabe?
A medição pública mais relevante que encontramos é o LAraBench (Abdelali et al., EACL 2024), que rodou o GPT-3.5 e o GPT-4 em conjuntos de NER em árabe como marcação token a token. Macro-F1, quanto maior, melhor:
| Dataset | GPT-3.5 zero-shot | GPT-4 zero-shot | GPT-4 3-shot | Sistema com fine-tuning citado |
|---|---|---|---|---|
| ANERcorp (notícias) | 0,210 | 0,355 | 0,420 | 0,886 |
| AQMAR (Wikipédia) | 0,230 | 0,365 | 0,390 | 0,690 |
| QASR (transcrições) | 0,208 | 0,504 | n/d | 0,698 |
Mais exemplos ajudaram: o GPT-4 no ANERcorp subiu de 0,355 sem exemplos para 0,451 com dez. Os autores também tiveram de remapear as tags que o modelo escrevia no próprio formato, como PER-B em vez de B-PER.
Leia com cuidado. São modelos de 2023 fazendo uma tarefa rígida de marcação em conjuntos de rótulos de benchmark. Um modelo atual a quem você pede uma lista curta de pessoas e empresas em um ticket de suporte pode se sair muito melhor, ou não. A tabela diz duas coisas que continuam valendo: um LLM não é automaticamente um bom sistema de NER, e você precisa da sua própria medição.
Quais datasets de NER em árabe existem?
| Dataset | Texto | Tamanho e rótulos |
|---|---|---|
| ANERcorp | Notícias | Cerca de 150.000 tokens; pessoa, local, organização, diversos. O CAMeL Lab publica uma divisão treino/teste padrão |
| CLEANANERCorp | ANERcorp corrigido | Corrige erros de anotação, rótulos faltantes e inconsistências encontrados no original |
| AQMAR | Wikipédia em árabe | 74.000 tokens de 28 artigos |
| Wojood | MSA e dialeto | Cerca de 550.000 tokens, 21 tipos de entidade, aninhados; usado na shared task WojoodNER 2023 |
| CANERCorpus | Hadiths em árabe clássico | Mais de 7.000 hadiths, 20 tipos sobre temas islâmicos |
Use-os para uma checagem rápida do prompt, não como teste de aceitação. Seus tipos de entidade (cliente, produto, filial, número de contrato) vão ser diferentes dos deles, e as licenças também variam. Confira cada uma antes de uso comercial.
O que o prompt deve pedir?
Três regras tornam a saída verificável:
- Copie o trecho exatamente. Sem tradução, sem transliteração, sem “completar” um primeiro nome para o nome completo. Se precisar de uma grafia em inglês, peça em um campo separado e trate como não verificada.
- Uma lista fechada de tipos. PERSON, ORG, LOCATION, DATE, ou o seu próprio conjunto. Tipos livres não dão para avaliar.
- Datas em partes, não convertidas. Peça ano, mês e dia como estão escritos, mais o calendário. Um هـ no final indica data hégira; م indica gregoriana.
Escreva as instruções em inglês ou em árabe; engenharia de prompt em árabe discute os prós e contras. Coloque o formato JSON no system prompt e mantenha-o idêntico entre as requisições, para que possa ir para o cache.
Como checar as entidades contra o texto original?
O modelo pode retornar um nome que o texto nunca menciona, ou copiar um nome certo, mas sem os diacríticos. Um simples teste de substring não diferencia os dois casos. Normalize os dois lados antes: remova tashkeel e tatweel, unifique as formas de alef e junte عبد ال para que عبد الله corresponda a عبدالله. As regras são as mesmas da normalização de texto em árabe para busca, aplicadas só à comparação. Guarde o trecho original para exibição.
import json, os, re
from hijridate import Hijri
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
TYPES = {"PERSON", "ORG", "LOCATION", "DATE"}
SYSTEM = """Extract named entities from the Arabic text. Reply with JSON only:
{"entities": [{"text": "...", "type": "PERSON|ORG|LOCATION|DATE"}],
"dates": [{"text": "...", "calendar": "hijri|gregorian", "year": 0, "month": 0, "day": 0}]}
Rules: copy "text" exactly as it appears in the input, including any diacritics.
Do not translate, transliterate or complete names. A date followed by هـ is Hijri.
If there are no entities, return empty lists."""
DIACRITICS = re.compile(r"[ً-ٰٟـ]") # tashkeel, dagger alef, tatweel
def norm(s: str) -> str:
s = DIACRITICS.sub("", s)
s = re.sub("[إأآٱ]", "ا", s).replace("ى", "ي").replace("عبد ال", "عبدال")
return " ".join(s.split())
def validate(source: str, data: dict) -> tuple[list, list]:
"""Keep entities that really occur in the source; report everything else."""
src, kept, problems = norm(source), [], []
for e in data.get("entities", []):
if e.get("type") not in TYPES:
problems.append(f"unknown type: {e}")
elif norm(e.get("text", "")) not in src:
problems.append(f"not in source: {e['text']}")
else:
kept.append(e)
for d in data.get("dates", []):
if d.get("calendar") == "hijri":
try:
d["iso"] = Hijri(d["year"], d["month"], d["day"]).to_gregorian().isoformat()
except (ValueError, OverflowError) as err:
problems.append(f"bad Hijri date {d['text']}: {err}")
return kept, problems
def extract(text: str, model="broadnet/qwen3.8-27b") -> dict:
r = client.chat.completions.create(
model=model, max_tokens=2000,
messages=[{"role": "system", "content": SYSTEM}, {"role": "user", "content": text}])
data = json.loads(r.choices[0].message.content)
data["entities"], data["problems"] = validate(text, data)
return data
text = "التقى خالِد بن سَعِيد مديرةَ شركة النخيل للتقنية في جدة يوم ١٥ جمادى الآخرة ١٤٤٥هـ."
print(json.dumps(extract(text), ensure_ascii=False, indent=1))
Rodamos isso contra um servidor mock local (sem chamada à API real) cuja resposta pronta acrescentava uma pessoa inventada e uma data impossível (mês 13). A saída manteve خالد بن سعيد (a resposta tinha perdido os diacríticos; a comparação normalizada achou mesmo assim), شركة النخيل للتقنية e جدة. Converteu ١٥ جمادى الآخرة ١٤٤٥هـ em 2023-12-28 e listou dois problemas: o nome inventado estava “not in source” e o mês 13 gerou “month must be in 1-12”. Os nomes e a empresa são fictícios.
Observações sobre o código:
max_tokens=2000deixa espaço para o raciocínio. A documentação da BroadNet diz que DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder e que esse raciocínio conta paramax_tokens. Veja respostas vazias de modelos de raciocínio.json.loadspode falhar. Envolva em um try e, em caso de falha, reenvie uma vez com o erro, como no loop de correção. No GLM 5.3 e no Qwen3.8 27B, que a BroadNet documenta com saída estruturada, acrescente também um schema emresponse_format. A validação continua de qualquer forma.- A comparação por substring é propositalmente frouxa. Ela confirma que o trecho existe; não confirma o tipo. Os tipos são o que a etapa de avaliação abaixo mede.
Como lidar com datas hégira?
O texto em árabe escreve datas de muitas formas: ١٥/٦/١٤٤٥هـ, ١٥ جمادى الآخرة ١٤٤٥, ou uma data gregoriana com nomes de meses que mudam por região (نوفمبر no Egito e no Golfo, تشرين الثاني no Levante). Um modelo normalmente consegue separá-las em partes, e o código confere as partes. Converter entre calendários é aritmética sobre uma tabela publicada, e não há motivo para um modelo acertar isso.
A hijridate, antes hijri-converter, converte usando o calendário Umm al-Qura. O intervalo documentado vai de 1343 a 1500 AH (1º de agosto de 1924 a 16 de novembro de 2077 d.C.). Fora do intervalo ela lança OverflowError; um mês ou dia inválido lança ValueError, por isso o código captura os dois. A documentação diz que ela não se destina a fins religiosos em que se prefere a observação da lua crescente, então uma data definida por observação pode diferir do valor convertido. Guarde a data como está escrita ao lado da convertida.
Os dígitos arábicos orientais não precisam de tratamento especial aqui: o modelo retorna inteiros. Se você mesmo fizer o parsing das datas, converta antes ٠١٢٣٤٥٦٧٨٩ (e os persas ۰–۹) para 0–9.
E nomes em Arabizi e texto misturado?
Mensagens de clientes muitas vezes escrevem nomes em letras latinas: “ana 7a2ool la Mo7ammad bokra”. A regra do trecho exato continua funcionando: o texto da entidade é “Mo7ammad”, e a checagem de substring passa. O que falha é associar esse registro a محمد no seu CRM. Faça isso em uma segunda etapa: converta o trecho para o alfabeto árabe, como em lidar com Arabizi, e compare com seus registros usando a mesma normalização. Mantenha um indicador de confiança em todo registro que passou por uma conversão.
O mesmo vale para nomes de empresas em inglês dentro de frases em árabe e para grafias latinas de nomes árabes (Mohammed, Muhammad, Mohamed). Não peça à etapa de extração que escolha uma grafia.
Como avaliar o extrator?
Rotule à mão de 100 a 200 amostras reais, com a mesma lista de tipos. Depois compare as previsões com correspondência exata por entidade sobre o texto normalizado e o tipo, e informe precisão, recall e F1 por tipo:
from collections import Counter
def score(gold: list[list[dict]], pred: list[list[dict]]) -> dict:
"""Entity-level exact match on (normalised text, type), micro-averaged, plus per type."""
tp, fp, fn = Counter(), Counter(), Counter()
for g, p in zip(gold, pred):
G = Counter((norm(e["text"]), e["type"]) for e in g)
P = Counter((norm(e["text"]), e["type"]) for e in p)
for (t, ty), n in (G | P).items():
hit = min(G[(t, ty)], P[(t, ty)])
tp[ty] += hit; fp[ty] += P[(t, ty)] - hit; fn[ty] += G[(t, ty)] - hit
def prf(a, b, c):
p = a / (a + b) if a + b else 0.0
r = a / (a + c) if a + c else 0.0
return {"p": round(p, 3), "r": round(r, 3), "f1": round(2 * p * r / (p + r), 3) if p + r else 0.0}
out = {ty: prf(tp[ty], fp[ty], fn[ty]) for ty in sorted(tp | fp | fn)}
out["micro"] = prf(sum(tp.values()), sum(fp.values()), sum(fn.values()))
return out
Em um conjunto de brinquedo de duas frases (três entidades de referência; a previsão classificou جدة como ORG em vez de LOCATION e acrescentou um lugar a mais), ele imprimiu precisão micro 0,5, recall 0,667 e F1 0,571, e F1 de LOCATION igual a 0. A visão por tipo mostra onde investir esforço: uma pontuação fraca em ORG normalmente significa que as definições dos tipos precisam de exemplos, não de um modelo maior.
Decida antes o que conta como acerto. A correspondência exata é rígida: “شركة النخيل” contra uma referência “شركة النخيل للتقنية” conta como um falso positivo e um falso negativo. Se trechos parciais forem aceitáveis no seu uso, informe uma segunda pontuação baseada em sobreposição, mas mantenha a rígida como número principal.
Qual modelo da BroadNet usar?
Todos os preços são por 1M de tokens, da página de preços da BroadNet.
| Modelo | Por quê | Input / output |
|---|---|---|
| Qwen3.8 27B | Saída estruturada documentada; a BroadNet informa que foi testado em árabe, incluindo compreensão dos dialetos do Golfo e egípcio; lê imagens | $0.175 / $2.17 |
| GLM 5.3 | Saída estruturada documentada; contexto de 1.048.576 tokens para documentos muito longos | $0.78 / $3.46 |
| Gemma 4 VL 26B | Roda com o crédito inicial de $5; sem saída estruturada documentada, então valide o JSON obtido só pelo prompt; contexto de 32.768 tokens | $0.10 / $0.22 |
Rode o script de avaliação na sua amostra com cada candidato e escolha pelo F1 por tipo e pelo custo, não pela descrição do fornecedor. Para o mesmo conteúdo, o árabe costuma usar mais tokens que o inglês; tokens por palavra em árabe traz as proporções medidas. Para entidades dentro de formulários digitalizados ou fotos, extraia direto da imagem, como em ler notas fiscais em árabe com visão.
Onde a BroadNet Inference entra
O BroadRouter é o site da própria BroadNet. A BroadNet Inference dá acesso compatível com a OpenAI aos modelos acima com uma única chave, então o código roda com o SDK Python da OpenAI depois de trocar a base URL. A documentação dela diz que prompts e respostas não são retidos após a requisição, o que importa quando o texto está cheio de nomes de pessoas. Ela não tem um endpoint dedicado a NER e não publica um benchmark próprio de NER em árabe, então meça nos seus dados. Se você precisa de um marcador self-hosted para grande volume, um modelo com fine-tuning treinado no Wojood ou nos seus próprios rótulos pode sair mais barato e ser mais consistente que qualquer LLM; a diferença publicada acima é o motivo para verificar.
