Un modello vision sa leggere una fattura, ma può anche leggere male una cifra, saltare una riga o inventare un campo che non c’è. La soluzione non è solo un prompt migliore. È un passaggio di revisione previsto fin dal primo giorno: regole che decidono quali documenti vede una persona, una coda che le spiega il perché e un log che ti permette di dimostrare il tasso di errore.
Questo articolo parla di quel passaggio. L’estrazione vera e propria (preparazione dell’immagine, prompt JSON, validazione dello schema e retry) è in estrarre dati dai documenti con un LLM vision, e la lettura specifica dell’arabo è in leggere fatture in arabo con la vision. Qui diamo per scontato che tu riceva già JSON e debba decidere di che cosa fidarti.
Che cosa dovrebbe decidere se una persona rivede un documento?
Regole che puoi testare nel codice, non una sensazione sul modello. Parti da queste, in ordine di utilità:
| Regola | Codice motivo di esempio | Perché conta |
|---|---|---|
| Manca un campo obbligatorio | missing:total |
Un null è onesto; un valore indovinato è peggio |
| Le somme non tornano | arithmetic:subtotal+tax!=total |
Una sola cifra letta male rompe quasi sempre una somma |
| Le righe non sommano | arithmetic:lines!=subtotal |
Intercetta righe saltate o duplicate |
| Data illeggibile o fuori intervallo | date:unparsed |
Intercetta giorno e mese invertiti e rumore dell’OCR |
| Partita IVA del fornitore sconosciuta | vendor:unknown |
Da qui partono sia i nuovi fornitori sia le frodi |
| Valuta inattesa | currency:unexpected |
Un simbolo letto male cambia l’importo |
| Il modello dice di non essere sicuro | model:not_confident |
Un indizio, mai l’unico filtro |
Due scelte di progetto rendono la coda utilizzabile. Primo, ogni regola produce un codice motivo breve e stabile: chi revisiona apre il documento sapendo che cosa controllare, e tu puoi contare quale regola scatta più spesso. Secondo, un documento o supera tutte le regole o va a una persona. Evita punteggi pesati che nessuno sa spiegare a un revisore contabile.
Ci si può fidare della confidenza del modello?
Trattala come un segnale debole. Puoi chiedere al modello di valutare ogni campo con confidenza alta, media o bassa, e lo farà. Ma Xiong et al. (ICLR 2024) hanno messo a confronto diversi modi per far dichiarare la confidenza agli LLM e hanno trovato che i modelli “tend to be overconfident” (traduzione: «tendono a essere troppo sicuri di sé») quando dicono quanto sono sicuri; prompting e campionamento migliori aiutavano, e nessun metodo batteva gli altri in modo costante. Su alcune API un’altra opzione sono le log-probabilità dei token. Il riferimento API di BroadNet non documenta logprobs, quindi lì non progettare in base a quelle.
La regola pratica: qualsiasi valore inferiore a «high» da parte del modello, o nessuna valutazione, manda il documento in revisione, ma un «high» non fa mai saltare i controlli nel codice. Dopo qualche centinaio di documenti revisionati, verifica se i campi «high» hanno davvero avuto meno correzioni. Se no, elimina il segnale.
Come si instradano i documenti verso una coda?
Questo router gira dopo estrazione e validazione. Normalizza le cifre arabo-indiche, applica le regole qui sopra e sceglie una di tre code: review, audit_sample o auto. È Python semplice, senza chiamate API, quindi puoi scriverci dei test unitari.
import hashlib, json, random, re, time
from datetime import date, datetime
from decimal import Decimal, InvalidOperation
REQUIRED = ["vendor_name", "invoice_number", "invoice_date", "currency", "subtotal", "tax", "total"]
CURRENCIES = {"SAR", "AED", "USD", "EUR"}
KNOWN_VENDORS = {"300000000000003": "Example Trading Co"} # your supplier master: tax ID -> name
AUTO_SAMPLE_RATE = 0.05 # share of clean documents a person still checks
DIGITS = str.maketrans("٠١٢٣٤٥٦٧٨٩۰۱۲۳۴۵۶۷۸۹٫٬", "01234567890123456789.,")
def money(v):
"""'١٬٢٥٠٫٥٠' or '1,250.50' -> Decimal('1250.50'); None if it is not a number."""
if v is None:
return None
s = str(v).translate(DIGITS).replace(",", "").strip()
try:
return Decimal(s)
except InvalidOperation:
return None
def check(doc: dict, today: date) -> list[str]:
"""Return the reasons this document needs a person. Empty list = may auto-approve."""
reasons = [f"missing:{f}" for f in REQUIRED if doc.get(f) in (None, "")]
sub, tax, tot = (money(doc.get(k)) for k in ("subtotal", "tax", "total"))
if None not in (sub, tax, tot) and abs(sub + tax - tot) > Decimal("0.01"):
reasons.append("arithmetic:subtotal+tax!=total")
lines = [money(l.get("amount")) for l in doc.get("lines", [])]
if lines and None not in lines and sub is not None and abs(sum(lines) - sub) > Decimal("0.01"):
reasons.append("arithmetic:lines!=subtotal")
try:
d = datetime.strptime(str(doc.get("invoice_date", "")).translate(DIGITS), "%Y-%m-%d").date()
if d > today or (today - d).days > 400:
reasons.append("date:out_of_range")
except ValueError:
reasons.append("date:unparsed")
if doc.get("currency") and doc["currency"] not in CURRENCIES:
reasons.append("currency:unexpected")
if doc.get("vendor_tax_id") not in KNOWN_VENDORS:
reasons.append("vendor:unknown")
if doc.get("model_confidence", "low") != "high": # a hint from the prompt, never the only gate
reasons.append("model:not_confident")
return reasons
def route(doc_id: str, doc: dict, today: date, rng=random.random) -> dict:
reasons = check(doc, today)
if reasons:
queue = "review"
elif rng() < AUTO_SAMPLE_RATE:
queue, reasons = "audit_sample", ["sample:random"]
else:
queue = "auto"
return {"doc": hashlib.sha256(doc_id.encode()).hexdigest()[:16], "queue": queue,
"reasons": reasons, "ts": int(time.time())}
L’abbiamo provato su tre fatture saudite inventate (fornitore e partita IVA sono fittizi). Una pulita, con data e imponibile scritti in cifre arabo-indiche (٢٠٢٦-١١-٠٢ e ١٬٠٠٠٫٠٠), è finita in auto. La stessa fattura con il totale letto male come 1,105.00 è andata in review con arithmetic:subtotal+tax!=total. Una con una partita IVA sconosciuta, un mese 13 e confidenza «medium» è andata in review con tre motivi: date:unparsed, vendor:unknown e model:not_confident. Forzando l’estrazione casuale sotto 0,05, la fattura pulita è finita in audit_sample.
Due limiti da conoscere. L’helper money() presuppone un punto o il separatore decimale arabo come separatore dei decimali; un importo europeo come “1.150,00” richiede un parser a parte, scelto in base al paese del fornitore. E la regola sulla data presuppone che il modello restituisca date ISO. Le date dell’Egira vanno prima convertite, come in estrazione di entità nominate in arabo.
Che cosa cambia con fatture in arabo e in inglese?
Nel Golfo le fatture bilingui sono comuni: etichette in arabo e in inglese affiancate, importi in cifre occidentali o arabo-indiche, nome del fornitore in due alfabeti. Alcune regole aiutano:
- Normalizza le cifre prima di qualsiasi controllo. Converti ٠–٩ e le cifre persiane ۰–۹ in 0–9, e i separatori arabi di decimali e migliaia (٫ e ٬) nelle loro forme ASCII. Poi confronta.
- Abbina i fornitori sulla partita IVA, non sul nome. I nomi in arabo e in inglese raramente coincidono carattere per carattere con la tua anagrafica. Il numero di registrazione sì.
- Mostra entrambi i nomi a chi revisiona. Affianca i nomi del fornitore estratti in arabo e in inglese al record dell’anagrafica, con l’arabo in un blocco isolato da destra a sinistra. L’articolo sul design di prodotti multilingue spiega la visualizzazione bidirezionale.
- Verifica se esiste una fattura strutturata. In Arabia Saudita la ZATCA gestisce la fatturazione elettronica (Fatoorah) in due fasi, dal 4 dicembre 2021 e dal 1º gennaio 2023, basata su fatture in un formato elettronico strutturato. Se un fornitore può mandarti quella, leggi quella invece della foto, e tieni la vision per la carta, le foto e la coda lunga.
OCR dell’arabo con un LLM vision copre la parte di lettura: segni diacritici, alfabeti misti e layout.
Che cosa deve vedere chi revisiona?
Una buona schermata di revisione risponde a una domanda per ogni codice motivo. Per arithmetic, mostra righe, imponibile, imposta e totale affiancati alla somma calcolata. Per vendor:unknown, mostra la partita IVA estratta e i record più vicini dell’anagrafica. Per date:unparsed, mostra il testo grezzo della data e il ritaglio dell’immagine da cui proviene.
Mostra l’immagine accanto ai campi, non in un’altra scheda. Permetti a chi revisiona di correggere un campo, approvare o rifiutare il documento come illeggibile. Registra quale azione ha scelto. «Illeggibile» è un dato utile: se il 10% dei documenti di un fornitore è illeggibile, chiedi i PDF a quel fornitore, non un miracolo al modello.
Perché campionare documenti che hanno superato tutte le regole?
Perché le regole intercettano solo gli errori a cui hai pensato. Se un modello legge male una riga, l’imponibile e il totale della stessa quantità (un 7 sbavato letto come 1 in tutti e tre i punti), le somme tornano comunque e nessuna regola scatta. L’unico modo per trovare questi errori è guardare documenti che nessuno ha segnalato.
Campionali a caso, non a scelta, e conta quanti hanno richiesto una correzione. Un campione piccolo dà un intervallo ampio. Con l’intervallo di Wilson al 95%, che il manuale del NIST descrive per le proporzioni (citando le raccomandazioni di Agresti e Coull e di Brown, Cai e DasGupta), il nostro codice di metriche più sotto dà:
| Documenti controllati senza errori trovati | Il tasso di errore reale potrebbe arrivare fino a |
|---|---|
| 50 | circa 7,1% |
| 300 | circa 1,3% |
Quindi «ne abbiamo controllati 50 e non abbiamo trovato nulla» non significa che il tasso di errore sia sotto l’1%. Aumenta il campione dopo qualsiasi modifica al prompt, al modello o al tipo di documenti, e riducilo lentamente.
Come si tiene un audit trail?
Registra le correzioni nel tuo sistema. Ogni documento ha bisogno di una riga con:
- un hash SHA-256 del file sorgente (e dove è conservato il file stesso, secondo le tue regole di conservazione);
- l’ID del modello, la versione del prompt e il JSON grezzo restituito dal modello;
- l’ID della richiesta del provider (BroadNet lo restituisce nell’header
X-Request-ID) per le domande al supporto; - i risultati delle regole e la coda;
- il revisore, l’ora, l’azione e il valore prima e dopo di ogni campo corretto.
Questo conta ancora di più con un’API a zero conservazione. L’informativa sulla privacy di BroadNet dice che il suo gateway non conserva prompt, immagini, risposte né trascrizioni, e tiene solo registri di account, fatturazione, traffico e sicurezza privi di contenuto. È un bene per le fatture sensibili, ma significa che nessuno presso il provider potrà mostrarti che cosa ha visto o detto il modello il mese scorso. Il tuo log è l’unico registro. Tienilo libero da ciò che non ti serve; logging dell’uso delle API LLM spiega che cosa registrare e che cosa oscurare.
Come si misura il tasso di revisione?
Esegui questo ogni settimana sul log di instradamento, con le correzioni unite:
import math
from collections import Counter
def wilson(errors: int, n: int, z: float = 1.96) -> tuple[float, float]:
"""95% Wilson score interval for an error rate seen in a sample."""
if n == 0:
return (0.0, 1.0)
p = errors / n
centre = (p + z * z / (2 * n)) / (1 + z * z / n)
half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / (1 + z * z / n)
return (max(0.0, centre - half), min(1.0, centre + half))
def report(log: list[dict]) -> dict:
queues = Counter(r["queue"] for r in log)
reasons = Counter(x.split(":")[0] for r in log if r["queue"] == "review" for x in r["reasons"])
audited = [r for r in log if r["queue"] == "audit_sample"]
wrong = sum(1 for r in audited if r.get("corrected_fields"))
lo, hi = wilson(wrong, len(audited))
return {"documents": len(log),
"review_rate": round(queues["review"] / len(log), 3),
"top_reasons": reasons.most_common(3),
"audited": len(audited), "audited_with_errors": wrong,
"auto_error_rate_95ci": (round(lo, 4), round(hi, 4))}
Su una settimana sintetica di 1.000 documenti (760 auto, 190 in revisione, 50 controllati di cui 2 hanno richiesto una correzione), ha riportato un tasso di revisione di 0,19, vendor come motivo principale con 120 casi e un tasso di errore verificato tra l’1,1% e il 13,5%. Quest’ultimo intervallo è la risposta onesta a «quanto è accurata l’automazione?» con questa dimensione del campione.
Leggi i tre numeri insieme:
- Il tasso di revisione scende, gli errori verificati restano stabili: una regola era troppo severa, oppure il modello è migliorato. Bene.
- Il tasso di revisione scende, gli errori verificati salgono: una regola è troppo larga. Stringila prima che gli errori arrivino in contabilità.
- Un motivo domina: risolvi la causa. Se in testa c’è
vendor:unknown, aggiorna l’anagrafica fornitori; se c’èarithmetic, guarda la qualità delle immagini o prova un altro modello sugli stessi documenti con il metodo di valutare un LLM prima di cambiarlo.
Dove si colloca BroadNet Inference
BroadRouter è il sito di BroadNet. Secondo il suo feed dei prezzi, BroadNet Inference offre tre modelli di chat che accettano immagini: Qwen3.8 27B ($0.175 di input / $2.17 di output per 1M di token, con output strutturato documentato), Gemma 4 VL 26B ($0.10 / $0.22, utilizzabile con il credito iniziale di $5) e DeepSeek V4.1 Flash ($0.175 / $0.52). Con il pagamento a consumo, le immagini contano come token di input; il calcolatore di token per immagini aiuta a stimarli. Il contenuto dell’inferenza non viene conservato; i metadati necessari di account, fatturazione e sicurezza vengono conservati come descritto nell’informativa sulla privacy di BroadNet. BroadNet non fornisce una coda di revisione né un registro di audit, quindi l’instradamento e i registri descritti qui li devi costruire e conservare tu.
