L’estrazione di entità nominate trasforma un paragrafo in record utilizzabili dal tuo codice: chi, quale organizzazione, dove e quando. L’arabo aggiunge quattro problemi che le pipeline per l’inglese incontrano di rado: diacritici facoltativi, più grafie per la stessa lettera, nomi scritti in caratteri latini (Arabizi) e date in due calendari. Questo articolo costruisce un passaggio di estrazione su un LLM compatibile con OpenAI che gestisce ciascuno di questi problemi nel codice, più uno script di valutazione che ti dice se funziona sul tuo testo.
Per classificare messaggi interi invece di estrarne degli span, vedi la classificazione di testi in arabo. Per le opzioni di richiesta JSON in sé, vedi JSON mode o json_schema.
Quanto sono bravi gli LLM nella NER in arabo?
La misura pubblica più pertinente che abbiamo trovato è LAraBench (Abdelali et al., EACL 2024), che ha eseguito GPT-3.5 e GPT-4 su set di NER in arabo come tagging token per token. Macro-F1, più alto è meglio:
| Dataset | GPT-3.5 zero-shot | GPT-4 zero-shot | GPT-4 3-shot | Sistema con fine-tuning citato |
|---|---|---|---|---|
| ANERcorp (notizie) | 0,210 | 0,355 | 0,420 | 0,886 |
| AQMAR (Wikipedia) | 0,230 | 0,365 | 0,390 | 0,690 |
| QASR (trascrizioni) | 0,208 | 0,504 | n/d | 0,698 |
Più esempi hanno aiutato: GPT-4 su ANERcorp è salito da 0,355 senza esempi a 0,451 con dieci. Gli autori hanno anche dovuto rimappare i tag che il modello scriveva nel suo formato, come PER-B al posto di B-PER.
Leggi questi dati con cautela. Sono modelli del 2023 alle prese con un compito di tagging rigido su set di etichette da benchmark. Un modello attuale a cui chiedi una breve lista di persone e aziende in un ticket di assistenza può fare molto meglio, oppure no. La tabella ti dice due cose che valgono ancora: un LLM non è automaticamente un buon sistema di NER, e ti serve una misura tua.
Quali dataset di NER in arabo esistono?
| Dataset | Testo | Dimensione ed etichette |
|---|---|---|
| ANERcorp | Notizie | Circa 150.000 token; persona, luogo, organizzazione, varie. CAMeL Lab pubblica uno split train/test standard |
| CLEANANERCorp | ANERcorp corretto | Corregge errori di annotazione, etichette mancanti e incoerenze trovati nell’originale |
| AQMAR | Wikipedia in arabo | 74.000 token da 28 articoli |
| Wojood | MSA e dialetto | Circa 550.000 token, 21 tipi di entità, annidati; usato nello shared task WojoodNER 2023 |
| CANERCorpus | Hadith in arabo classico | Oltre 7.000 hadith, 20 tipi su temi islamici |
Usali per una verifica di massima del prompt, non come test di accettazione. I tuoi tipi di entità (cliente, prodotto, filiale, numero di contratto) saranno diversi dai loro, e anche le licenze cambiano. Controllale una per una prima di un uso commerciale.
Cosa deve chiedere il prompt?
Tre regole rendono l’output verificabile:
- Copia lo span esattamente. Niente traduzione, niente traslitterazione, niente “completamento” di un nome proprio in un nome e cognome. Se ti serve una grafia inglese, chiedila in un campo separato e considerala non verificata.
- Una lista chiusa di tipi. PERSON, ORG, LOCATION, DATE, o un tuo set. I tipi liberi non si possono valutare.
- Le date in parti, non convertite. Chiedi anno, mese e giorno come sono scritti, più il calendario. Un هـ finale indica una data dell’Egira; م indica il gregoriano.
Scrivi le istruzioni in inglese o in arabo; il prompt engineering in arabo spiega i pro e i contro. Metti la struttura JSON nel system prompt e tienila identica tra le richieste, così può andare in cache.
Come si verificano le entità sul testo di partenza?
Il modello può restituire un nome che il testo non menziona mai, oppure copiare correttamente un nome ma senza diacritici. Un semplice test di sottostringa non distingue i due casi. Normalizza prima entrambi i lati: rimuovi tashkeel e tatweel, unifica le forme di alef e unisci عبد ال in modo che عبد الله corrisponda a عبدالله. Le regole sono le stesse della normalizzazione del testo arabo per la ricerca, applicate solo al confronto. Tieni lo span originale per la visualizzazione.
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))
Lo abbiamo eseguito su un server mock locale (nessuna chiamata all’API reale) la cui risposta preimpostata aggiungeva una persona inventata e una data impossibile (mese 13). L’output ha tenuto خالد بن سعيد (la risposta aveva perso i diacritici; il confronto normalizzato l’ha trovato comunque), شركة النخيل للتقنية e جدة. Ha convertito ١٥ جمادى الآخرة ١٤٤٥هـ in 2023-12-28 e ha elencato due problemi: il nome inventato era “not in source” e il mese 13 ha sollevato “month must be in 1-12”. Nomi e azienda sono di fantasia.
Note sul codice:
max_tokens=2000lascia spazio al ragionamento. La documentazione di BroadNet dice che DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere e che quel ragionamento conta inmax_tokens. Vedi risposte vuote dai modelli di ragionamento.json.loadspuò fallire. Racchiudilo in un try e, in caso di errore, rinvia una volta con l’errore, come nel ciclo di riparazione. Su GLM 5.3 e Qwen3.8 27B, per cui BroadNet documenta l’output strutturato, aggiungi anche uno schemaresponse_format. La validazione resta in ogni caso.- Il confronto per sottostringa è volutamente largo. Conferma che lo span esiste; non conferma il tipo. I tipi sono ciò che misura la fase di valutazione qui sotto.
Come si gestiscono le date dell’Egira?
Il testo arabo scrive le date in molti modi: ١٥/٦/١٤٤٥هـ, ١٥ جمادى الآخرة ١٤٤٥, oppure una data gregoriana con nomi di mesi che cambiano da regione a regione (نوفمبر in Egitto e nel Golfo, تشرين الثاني nel Levante). Di solito un modello sa scomporle in parti, e il codice controlla le parti. Convertire tra calendari è aritmetica su una tabella pubblicata, e non c’è motivo perché un modello lo faccia bene.
hijridate, ex hijri-converter, converte usando il calendario Umm al-Qura. L’intervallo documentato va dal 1343 al 1500 AH (dal 1° agosto 1924 al 16 novembre 2077 d.C.). Fuori intervallo solleva OverflowError; un mese o un giorno non validi sollevano ValueError, ed è per questo che il codice le intercetta entrambe. La sua documentazione dice che non è pensato per usi religiosi in cui si preferisce l’avvistamento della luna crescente, quindi una data fissata con l’avvistamento può differire dal valore convertito. Salva la data come è scritta accanto a quella convertita.
Qui le cifre arabo-orientali non richiedono una gestione speciale: il modello restituisce interi. Se analizzi tu le date, converti prima ٠١٢٣٤٥٦٧٨٩ (e le persiane ۰–۹) in 0–9.
E i nomi in Arabizi e nel testo misto?
I messaggi dei clienti spesso scrivono i nomi in caratteri latini: “ana 7a2ool la Mo7ammad bokra”. La regola dello span esatto funziona ancora: il testo dell’entità è “Mo7ammad” e il controllo di sottostringa passa. Quello che non funziona è collegare quel record a محمد nel tuo CRM. Fallo in un secondo passaggio: converti lo span in caratteri arabi, come nella gestione dell’Arabizi, poi confrontalo con i tuoi record usando la stessa normalizzazione. Tieni un indicatore di affidabilità su ogni record passato per una conversione.
Lo stesso vale per i nomi di aziende inglesi dentro frasi arabe e per le grafie latine dei nomi arabi (Mohammed, Muhammad, Mohamed). Non chiedere alla fase di estrazione di sceglierne una.
Come si valuta l’estrattore?
Etichetta a mano da 100 a 200 campioni reali, con la stessa lista di tipi. Poi confronta le previsioni con una corrispondenza esatta a livello di entità su testo normalizzato e tipo, e riporta precisione, recall e F1 per 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
Su un set giocattolo di due frasi (tre entità di riferimento; la previsione classificava جدة come ORG invece di LOCATION e aggiungeva un luogo in più), ha stampato precisione micro 0,5, recall 0,667 e F1 0,571, e F1 di LOCATION pari a 0. La vista per tipo ti mostra dove investire: un punteggio ORG debole di solito significa che le definizioni dei tipi hanno bisogno di esempi, non di un modello più grande.
Decidi in anticipo cosa conta come corrispondenza. La corrispondenza esatta è severa: “شركة النخيل” contro un riferimento “شركة النخيل للتقنية” conta come un falso positivo e un falso negativo. Se per il tuo uso gli span parziali sono accettabili, riporta un secondo punteggio basato sulla sovrapposizione, ma tieni quello severo come numero principale.
Quale modello BroadNet usare?
Tutti i prezzi sono per 1M di token, dalla pagina prezzi di BroadNet.
| Modello | Perché | Input / output |
|---|---|---|
| Qwen3.8 27B | Output strutturato documentato; BroadNet dichiara di averlo testato in arabo, compresa la comprensione dei dialetti del Golfo ed egiziano; legge immagini | $0.175 / $2.17 |
| GLM 5.3 | Output strutturato documentato; contesto di 1.048.576 token per documenti molto lunghi | $0.78 / $3.46 |
| Gemma 4 VL 26B | Funziona con il credito iniziale $5; nessun output strutturato documentato, quindi valida il JSON ottenuto solo dal prompt; contesto di 32.768 token | $0.10 / $0.22 |
Esegui lo script di valutazione sul tuo campione con ogni candidato e scegli in base all’F1 per tipo e al costo, non alla descrizione del fornitore. Per lo stesso contenuto l’arabo di solito richiede più token dell’inglese; token per parola in arabo riporta i rapporti misurati. Per entità dentro moduli scansionati o foto, estrai direttamente dall’immagine, come nella lettura di fatture arabe con un modello di visione.
Dove si colloca BroadNet Inference
BroadRouter è il sito di BroadNet. BroadNet Inference ti dà accesso compatibile con OpenAI ai modelli qui sopra con una sola chiave, quindi il codice funziona con l’SDK Python di OpenAI cambiando il base URL. La sua documentazione dice che prompt e risposte non vengono conservati dopo la richiesta, il che conta quando il testo è pieno di nomi di persone. Non ha un endpoint dedicato alla NER e non pubblica un proprio benchmark di NER in arabo, quindi misura sui tuoi dati. Se ti serve un tagger self-hosted per grandi volumi, un modello con fine-tuning addestrato su Wojood o sulle tue etichette può costare meno ed essere più coerente di qualsiasi LLM; il divario pubblicato qui sopra è il motivo per verificarlo.
