Fatture, scontrini e moduli hanno tutti lo stesso problema: i dati stanno in un’immagine e a te servono in un database. L’OCR basato su template si rompe a ogni nuovo layout di fornitore. Un modello visione-linguaggio legge la pagina e restituisce direttamente i campi. Il rovescio della medaglia è che può sbagliare con grande sicurezza, quindi il lavoro sta nella pipeline che gli costruisci attorno. Questo articolo copre la pipeline generale, per qualsiasi lingua. Per i documenti in arabo, vedi leggere fatture in arabo con la vision per la configurazione e OCR arabo e LLM vision a confronto per capire quando l’OCR classico è lo strumento migliore.
Com’è fatta la pipeline?
- Prepara ogni pagina: converti i PDF in immagini, correggi la rotazione, ridimensiona.
- Estrai: una richiesta per documento con un prompt campo per campo, solo JSON.
- Valida: parsing, controllo dello schema, controllo aritmetico.
- Ripeti una volta con il messaggio d’errore se la validazione fallisce.
- Rivedi: ciò che continua a fallire va a una persona, con l’immagine e la bozza.
- Misura l’accuratezza per campo su un campione etichettato, e ripeti la misura ogni volta che cambi modello o prompt.
Come si preparano le immagini dei documenti?
Converti i PDF in immagini con PyMuPDF e mantieni nitido il testo più piccolo senza inviare più pixel del necessario:
# pip install pymupdf pillow
import base64, io
import pymupdf # older code imports it as fitz
from PIL import Image
def pdf_pages_as_data_urls(path, long_edge=1800):
urls = []
for page in pymupdf.open(path):
pix = page.get_pixmap(dpi=200)
img = Image.open(io.BytesIO(pix.tobytes("png"))).convert("RGB")
img.thumbnail((long_edge, long_edge))
buf = io.BytesIO()
img.save(buf, format="JPEG", quality=90)
urls.append("data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode())
return urls
Su BroadNet Inference, le immagini vanno nel messaggio come URL data: con un tipo MIME corretto, e con il pagamento a consumo si pagano come token di input; le immagini più grandi ne usano di più. Misura una volta i token per pagina con il blocco usage e dimensiona i batch di conseguenza; contare i token prima dell’invio spiega come, e costo per immagine degli LLM vision trasforma i token in costo per pagina. Per stimare i token per pagina prima di inviare qualsiasi cosa, carica una scansione di esempio nel calcolatore di token per immagini.
Come va scritto il prompt di estrazione?
Sii preciso su chiavi, tipi, formati e valori mancanti. Se ti serve anche uno JSON Schema per la validazione o per i provider che lo impongono, il generatore gratuito di JSON Schema lo costruisce a partire da una fattura di esempio:
PROMPT = """Extract this invoice. Reply with one JSON object only, no prose.
Keys:
- vendor_name: string, as printed
- vendor_tax_id: string or null
- invoice_number: string
- invoice_date: string, YYYY-MM-DD
- currency: ISO 4217 code, e.g. USD, EUR, SAR
- line_items: list of {description: string, quantity: number, unit_price: number, line_total: number}
- subtotal: number
- tax: number or null
- total: number
Rules: numbers without currency symbols or thousands separators. If a field is not on the page, use null. Never guess."""
«Never guess» (non tirare mai a indovinare) insieme a un null esplicito è la parte che conta di più. Senza, i modelli riempiono i vuoti con valori plausibili, il che è peggio di un campo vuoto perché supera un controllo ingenuo.
Come si ottiene un output strutturato e come lo si valida?
L’output strutturato ha due livelli. La JSON mode garantisce un JSON valido. L’output vincolato a uno schema garantisce anche la forma. La guida di OpenAI lo dice chiaramente: entrambi producono JSON valido, ma solo gli Structured Outputs assicurano l’aderenza allo schema. Il supporto per l’uno o l’altro varia per provider e modello, quindi valida nel codice qualunque cosa prometta l’API:
import json, os
from decimal import Decimal
from pydantic import BaseModel, ValidationError, model_validator
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
class Line(BaseModel):
description: str
quantity: Decimal
unit_price: Decimal
line_total: Decimal
class Invoice(BaseModel):
vendor_name: str
vendor_tax_id: str | None = None
invoice_number: str
invoice_date: str
currency: str
line_items: list[Line]
subtotal: Decimal
tax: Decimal | None = None
total: Decimal
@model_validator(mode="after")
def sums(self):
tol = Decimal("0.02")
if abs(sum(l.line_total for l in self.line_items) - self.subtotal) > tol:
raise ValueError("line_totals do not sum to subtotal")
if abs(self.subtotal + (self.tax or 0) - self.total) > tol:
raise ValueError("subtotal + tax != total")
return self
def extract(image_urls, model="broadnet/qwen3.8-27b"):
content = [{"type": "text", "text": PROMPT}] + [
{"type": "image_url", "image_url": {"url": u}} for u in image_urls]
messages = [{"role": "user", "content": content}]
for attempt in range(2):
r = client.chat.completions.create(model=model, messages=messages, max_tokens=4000, temperature=0)
raw = (r.choices[0].message.content or "").strip().removeprefix("```json").removesuffix("```")
try:
return Invoice.model_validate(json.loads(raw)), r.usage
except (json.JSONDecodeError, ValidationError, ValueError) as e:
messages += [{"role": "assistant", "content": raw},
{"role": "user", "content": f"That failed validation: {e}. Re-read the image and reply with corrected JSON only."}]
return None, r.usage # send to human review
Per gli importi usa Decimal, non float. Tieni max_tokens generoso: Qwen3.8 27B ragiona prima di rispondere, e il ragionamento conta nel limite; un tetto basso restituisce una stringa vuota. Vedi perché i modelli di ragionamento restituiscono risposte vuote.
Quali controlli intercettano più errori?
| Controllo | Cosa intercetta | Costo |
|---|---|---|
| Il JSON si analizza | Testo attorno al JSON, troncamento | Gratis |
| Lo schema è valido | Chiavi mancanti, tipi sbagliati | Gratis |
| Le righe sommano al subtotale | Cifre lette male, righe saltate | Gratis |
| Subtotale + imposta = totale | Totale o imposta letti male | Gratis |
| La data si analizza e non è nel futuro | Giorno e mese invertiti, rumore OCR | Gratis |
| La partita IVA del fornitore è nella tua anagrafica | Fornitore sbagliato, frode | Una ricerca |
| Numero di fattura duplicato per fornitore | Doppio pagamento | Una query |
I controlli aritmetici sono quelli che rendono di più: una sola cifra letta male rompe quasi sempre una somma. Gli scontrini spesso non hanno il dettaglio per riga, quindi controlla ciò che c’è e accetta meno controlli.
Come si misura l’accuratezza prima di andare in produzione?
Etichetta a mano da 50 a 100 documenti reali, esegui la pipeline e valuta per campo, non per documento. Totali e date meritano un’asticella più alta delle descrizioni. Tieni d’occhio tre numeri: accuratezza per campo, quota di documenti che superano la validazione senza retry e quota mandata in revisione. Come progettare quel passaggio di revisione, compresi gli audit casuali sui documenti che hanno superato i controlli, è spiegato in rendere la revisione umana parte del flusso di document AI. Quando provi un altro modello, usa lo stesso insieme; valutare un LLM prima di cambiarlo descrive il metodo.
Quali modelli vision vanno bene su BroadNet Inference?
| Modello | Immagini | Contesto | Note |
|---|---|---|---|
| Qwen3.8 27B | Sì | 262.144 | Tool, output strutturato e ragionamento indicati; testato in arabo da BroadNet |
| Gemma 4 VL 26B | Sì | 32.768 | Il prezzo più basso di BroadNet; funziona con il credito gratuito e con la chiave oraria |
| DeepSeek V4.1 Flash | Sì | 1.048.576 | Immagini incluse nei piani illimitati |
I prezzi per 1M di token sono nella pagina prezzi; moltiplica i token per pagina che hai misurato per il volume mensile nel calcolatore dei costi delle API LLM.
Dove si colloca BroadNet Inference
BroadNet Inference accetta immagini su tre modelli di chat tramite il formato standard dei messaggi OpenAI, e non conserva prompt, immagini né risposte dopo la richiesta, il che conta per fatture piene di nomi, codici fiscali e coordinate bancarie (zero data retention). La sua documentazione indica l’output strutturato per Qwen3.8 27B ma non documenta parametri di schema, quindi affidati al livello di validazione descritto sopra e non all’API per imporre il tuo schema. BroadNet non pubblica un limite di dimensione per le immagini né un prodotto dedicato di document AI, e la sua documentazione descrive l’input di immagini, non l’upload di PDF, quindi converti prima le pagine in immagini. Per esecuzioni ad alto volume con un budget fisso, un piano illimitato DeepSeek V4.1 Flash include le immagini.

