BroadRouter

Extrair entidades nomeadas em árabe com LLM: JSON, datas e checagens

Pela equipe da BroadNet Inference · 7 min de leitura · Publicado em

Peça ao modelo que copie cada entidade exatamente como está escrita, com um tipo de uma lista fixa, em JSON. Verifique cada entidade no código: ela precisa aparecer no texto original depois de tirar os diacríticos e unificar as formas de alef. Converta datas hégira com uma biblioteca como a hijridate, não com o modelo. Avalie uma amostra rotulada à mão com precisão, recall e F1 por entidade.

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:

  1. 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.
  2. Uma lista fechada de tipos. PERSON, ORG, LOCATION, DATE, ou o seu próprio conjunto. Tipos livres não dão para avaliar.
  3. 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=2000 deixa 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 para max_tokens. Veja respostas vazias de modelos de raciocínio.
  • json.loads pode 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 em response_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.

Perguntas frequentes

Um LLM consegue fazer reconhecimento de entidades nomeadas em árabe?

Sim, com checagens. Os resultados zero-shot publicados para NER em árabe por token ficam bem atrás de modelos com fine-tuning, então valide cada entidade contra o texto original e avalie o modelo em uma amostra rotulada dos seus próprios dados antes de confiar.

Como comparo nomes árabes com e sem diacríticos?

Normalize os dois lados antes de comparar: remova o tashkeel (U+064B a U+065F), o alef sobrescrito e o tatweel, converta إ أ آ ٱ em ا e ى em ي, e junte os espaços repetidos. Guarde o texto original para exibição; use a forma normalizada só para comparar.

Como converto uma data hégira para gregoriana em Python?

Use a hijridate (antes hijri-converter): Hijri(1445, 6, 15).to_gregorian() retorna 2023-12-28. Ela segue o calendário Umm al-Qura, aceita de 1343 a 1500 AH e não se destina a datas religiosas definidas pela observação da lua.

Em quais datasets de NER em árabe posso testar?

ANERcorp (notícias, cerca de 150.000 tokens, quatro tipos), AQMAR (74.000 tokens da Wikipédia), Wojood (cerca de 550.000 tokens de MSA e dialeto com 21 tipos aninhados) e CANERCorpus (hadiths em árabe clássico, 20 tipos). Confira cada licença e mapeie os rótulos deles para os seus.

O modelo deve traduzir ou transliterar os nomes?

Não na etapa de extração. Peça o trecho exato do texto, para poder verificá-lo. Se precisar de uma grafia latina, acrescente um campo separado e trate-o como não verificado.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity