BroadRouter

Estrarre dati da fatture, scontrini e moduli in JSON con un LLM vision

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato

Converti ogni pagina in un’immagine, inviala a un modello vision con un prompt che nomina ogni campo e il suo formato, e chiedi solo JSON. Poi valida nel codice: fai il parsing, controlla lo schema, verifica che le righe sommino al totale e ripeti una volta passando l’errore. Gli errori ripetuti vanno a una persona.

A paper invoice headed "فاتورة" (invoice) with tabs labelled Vendor, Date and Total, and the text "Turn documents into useful data."
Illustrative example.

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?

  1. Prepara ogni pagina: converti i PDF in immagini, correggi la rotazione, ridimensiona.
  2. Estrai: una richiesta per documento con un prompt campo per campo, solo JSON.
  3. Valida: parsing, controllo dello schema, controllo aritmetico.
  4. Ripeti una volta con il messaggio d’errore se la validazione fallisce.
  5. Rivedi: ciò che continua a fallire va a una persona, con l’immagine e la bozza.
  6. 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.

Domande frequenti

Un LLM vision può sostituire l’OCR per le fatture?

Per molti layout, sì. Un modello vision legge l’immagine e associa il testo ai campi in un solo passaggio, senza template per ogni fornitore. A volte però legge male le cifre, quindi tieni la validazione e una coda di revisione.

Come ottengo un JSON affidabile da un modello vision?

Elenca nel prompt chiavi, tipi e formati esatti, chiedi solo JSON e fai il parsing nel codice. Se il modello supporta output vincolato a uno schema, usalo. In ogni caso valida con una libreria di schemi e ripeti una volta passando l’errore.

Come estraggo i dati da una fattura PDF di più pagine?

Converti ogni pagina in un’immagine, poi invia tutte le pagine di una fattura in un’unica richiesta se stanno nel contesto del modello, così i totali dell’ultima pagina si possono confrontare con le righe della prima.

Che risoluzione devono avere le immagini delle fatture?

Abbastanza alta da rendere nitide le cifre più piccole, e non di più. Le immagini più grandi usano più token di input. Un lato lungo di circa 1.500–2.000 pixel è un punto di partenza sensato per una pagina A4; prova sui tuoi documenti.

Come misuro l’accuratezza dell’estrazione?

Etichetta a mano da 50 a 100 documenti reali e valuta campo per campo. Tieni separati totali e date dai campi di testo libero come i nomi dei fornitori, perché i loro errori costano in modo diverso.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity